summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/.cvsignore23
-rw-r--r--doc/BUGS13
-rw-r--r--doc/COPYING340
-rw-r--r--doc/ChangeLog977
-rw-r--r--doc/ChangeLog-guile-doc48
-rw-r--r--doc/Makefile.am51
-rw-r--r--doc/NEWS44
-rw-r--r--doc/README33
-rw-r--r--doc/THANKS19
-rw-r--r--doc/example-smob/COPYING340
-rw-r--r--doc/example-smob/ChangeLog48
-rw-r--r--doc/example-smob/Makefile12
-rw-r--r--doc/example-smob/README6
-rw-r--r--doc/example-smob/image-type.c126
-rw-r--r--doc/example-smob/image-type.h3
-rw-r--r--doc/example-smob/myguile.c37
-rw-r--r--doc/goops/.cvsignore22
-rw-r--r--doc/goops/ChangeLog22
-rw-r--r--doc/goops/Makefile.am43
-rw-r--r--doc/goops/goops-tutorial.texi810
-rw-r--r--doc/goops/goops.texi2803
-rw-r--r--doc/goops/hierarchy.eps127
-rw-r--r--doc/goops/hierarchy.txt14
-rw-r--r--doc/goops/mop.text66
-rw-r--r--doc/groupings.alist176
-rw-r--r--doc/guile-api.alist3219
-rw-r--r--doc/guile.193
-rw-r--r--doc/hacks.el16
-rw-r--r--doc/maint/ChangeLog59
-rw-r--r--doc/maint/README35
-rw-r--r--doc/maint/docstring.el622
-rw-r--r--doc/maint/guile.texi7846
-rw-r--r--doc/mbapi.texi987
-rw-r--r--doc/mltext.texi146
-rw-r--r--doc/oldfmt.c218
-rw-r--r--doc/r5rs/.cvsignore22
-rw-r--r--doc/r5rs/ChangeLog10
-rw-r--r--doc/r5rs/Makefile.am26
-rw-r--r--doc/r5rs/r5rs.texi8538
-rw-r--r--doc/recipe-guidelines.txt80
-rw-r--r--doc/ref/.cvsignore26
-rw-r--r--doc/ref/ChangeLog610
-rw-r--r--doc/ref/ChangeLog-guile-doc-ref890
-rw-r--r--doc/ref/Makefile.am62
-rw-r--r--doc/ref/api.txt185
-rw-r--r--doc/ref/autoconf.texi234
-rw-r--r--doc/ref/data-rep.texi2047
-rw-r--r--doc/ref/debugging.texi115
-rw-r--r--doc/ref/deprecated.texi3
-rw-r--r--doc/ref/expect.texi142
-rw-r--r--doc/ref/extend.texi44
-rw-r--r--doc/ref/gh.texi1170
-rw-r--r--doc/ref/guile.texi389
-rw-r--r--doc/ref/indices.texi52
-rw-r--r--doc/ref/intro.texi1128
-rw-r--r--doc/ref/misc-modules.texi426
-rw-r--r--doc/ref/new-docstrings.texi701
-rw-r--r--doc/ref/posix.texi2490
-rw-r--r--doc/ref/preface.texi200
-rw-r--r--doc/ref/program.texi776
-rw-r--r--doc/ref/repl-modules.texi131
-rw-r--r--doc/ref/scheme-binding.texi279
-rw-r--r--doc/ref/scheme-compound.texi2431
-rw-r--r--doc/ref/scheme-control.texi979
-rwxr-xr-xdoc/ref/scheme-data.texi3086
-rw-r--r--doc/ref/scheme-debug.texi206
-rw-r--r--doc/ref/scheme-evaluation.texi426
-rw-r--r--doc/ref/scheme-ideas.texi1459
-rw-r--r--doc/ref/scheme-indices.texi10
-rw-r--r--doc/ref/scheme-intro.texi36
-rw-r--r--doc/ref/scheme-io.texi1116
-rw-r--r--doc/ref/scheme-memory.texi396
-rw-r--r--doc/ref/scheme-modules.texi909
-rw-r--r--doc/ref/scheme-options.texi651
-rw-r--r--doc/ref/scheme-procedures.texi816
-rw-r--r--doc/ref/scheme-reading.texi27
-rw-r--r--doc/ref/scheme-scheduling.texi453
-rw-r--r--doc/ref/scheme-translation.texi48
-rw-r--r--doc/ref/scheme-utility.texi731
-rw-r--r--doc/ref/scm.texi181
-rw-r--r--doc/ref/script-getopt.texi435
-rw-r--r--doc/ref/scripts.texi225
-rw-r--r--doc/ref/scsh.texi18
-rw-r--r--doc/ref/slib.texi105
-rw-r--r--doc/ref/srfi-modules.texi2399
-rw-r--r--doc/ref/tcltk.texi3
-rw-r--r--doc/ref/tools.texi386
-rw-r--r--doc/sources/.cvsignore20
-rw-r--r--doc/sources/ChangeLog5
-rw-r--r--doc/sources/Makefile.am7
-rw-r--r--doc/sources/contributors.texi80
-rw-r--r--doc/sources/debug-c.texi2
-rw-r--r--doc/sources/debug-scheme.texi2
-rw-r--r--doc/sources/env.texi1165
-rw-r--r--doc/sources/format.texi434
-rw-r--r--doc/sources/guile-slib.texi2
-rw-r--r--doc/sources/jimb-org.texi131
-rw-r--r--doc/sources/libguile-overview.texi30
-rw-r--r--doc/sources/libguile-tools.texi191
-rw-r--r--doc/sources/new-types.texi2
-rw-r--r--doc/sources/old-intro.texi290
-rw-r--r--doc/sources/sample-APIs.texi6
-rw-r--r--doc/sources/scheme-concepts.texi249
-rw-r--r--doc/sources/scm-ref.texi4
-rw-r--r--doc/sources/strings.texi45
-rw-r--r--doc/sources/tk.texi5
-rw-r--r--doc/sources/unix-other.texi132
-rw-r--r--doc/sources/unix.texi622
-rw-r--r--doc/tutorial/.cvsignore22
-rw-r--r--doc/tutorial/ChangeLog34
-rw-r--r--doc/tutorial/ChangeLog-guile-doc-tutorial16
-rw-r--r--doc/tutorial/Makefile.am39
-rw-r--r--doc/tutorial/guile-tut.texi1373
-rw-r--r--doc/use-cases.fig199
-rw-r--r--doc/use-cases.txt22
115 files changed, 0 insertions, 62881 deletions
diff --git a/doc/.cvsignore b/doc/.cvsignore
deleted file mode 100644
index 86d66d588..000000000
--- a/doc/.cvsignore
+++ /dev/null
@@ -1,23 +0,0 @@
-*.aux
-*.cp
-*.cps
-*.dvi
-*.fn
-*.fns
-*.html
-*.info*
-*.ky
-*.log
-*.pg
-*.ps
-*.toc
-*.tp
-*.tps
-*.vr
-*.vrs
-Makefile
-Makefile.in
-stamp-vti
-stamp-vti1
-version-tutorial.texi
-version.texi
diff --git a/doc/BUGS b/doc/BUGS
deleted file mode 100644
index 736edaace..000000000
--- a/doc/BUGS
+++ /dev/null
@@ -1,13 +0,0 @@
-
-Known Guile documentation bugs -*- outline -*-
-
-* The building of HTML docs is dependent on GNU Make
-
-This is because the Makefile.am's for the Guile reference manual and
-tutorial use a $(shell ...) command to list the set of HTML files to
-install.
-
-Probably this will not be fixed until Automake gains proper HTML doc
-support. On the other hand, if we've overlooked a more
-version-independent way of achieving the same thing, please let us
-know.
diff --git a/doc/COPYING b/doc/COPYING
deleted file mode 100644
index eeb586b39..000000000
--- a/doc/COPYING
+++ /dev/null
@@ -1,340 +0,0 @@
- GNU GENERAL PUBLIC LICENSE
- Version 2, June 1991
-
- Copyright (C) 1989, 1991 Free Software Foundation, Inc.
- 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
- Preamble
-
- The licenses for most software are designed to take away your
-freedom to share and change it. By contrast, the GNU General Public
-License is intended to guarantee your freedom to share and change free
-software--to make sure the software is free for all its users. This
-General Public License applies to most of the Free Software
-Foundation's software and to any other program whose authors commit to
-using it. (Some other Free Software Foundation software is covered by
-the GNU Library General Public License instead.) You can apply it to
-your programs, too.
-
- When we speak of free software, we are referring to freedom, not
-price. Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-this service if you wish), that you receive source code or can get it
-if you want it, that you can change the software or use pieces of it
-in new free programs; and that you know you can do these things.
-
- To protect your rights, we need to make restrictions that forbid
-anyone to deny you these rights or to ask you to surrender the rights.
-These restrictions translate to certain responsibilities for you if you
-distribute copies of the software, or if you modify it.
-
- For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must give the recipients all the rights that
-you have. You must make sure that they, too, receive or can get the
-source code. And you must show them these terms so they know their
-rights.
-
- We protect your rights with two steps: (1) copyright the software, and
-(2) offer you this license which gives you legal permission to copy,
-distribute and/or modify the software.
-
- Also, for each author's protection and ours, we want to make certain
-that everyone understands that there is no warranty for this free
-software. If the software is modified by someone else and passed on, we
-want its recipients to know that what they have is not the original, so
-that any problems introduced by others will not reflect on the original
-authors' reputations.
-
- Finally, any free program is threatened constantly by software
-patents. We wish to avoid the danger that redistributors of a free
-program will individually obtain patent licenses, in effect making the
-program proprietary. To prevent this, we have made it clear that any
-patent must be licensed for everyone's free use or not licensed at all.
-
- The precise terms and conditions for copying, distribution and
-modification follow.
-
- GNU GENERAL PUBLIC LICENSE
- TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
- 0. This License applies to any program or other work which contains
-a notice placed by the copyright holder saying it may be distributed
-under the terms of this General Public License. The "Program", below,
-refers to any such program or work, and a "work based on the Program"
-means either the Program or any derivative work under copyright law:
-that is to say, a work containing the Program or a portion of it,
-either verbatim or with modifications and/or translated into another
-language. (Hereinafter, translation is included without limitation in
-the term "modification".) Each licensee is addressed as "you".
-
-Activities other than copying, distribution and modification are not
-covered by this License; they are outside its scope. The act of
-running the Program is not restricted, and the output from the Program
-is covered only if its contents constitute a work based on the
-Program (independent of having been made by running the Program).
-Whether that is true depends on what the Program does.
-
- 1. You may copy and distribute verbatim copies of the Program's
-source code as you receive it, in any medium, provided that you
-conspicuously and appropriately publish on each copy an appropriate
-copyright notice and disclaimer of warranty; keep intact all the
-notices that refer to this License and to the absence of any warranty;
-and give any other recipients of the Program a copy of this License
-along with the Program.
-
-You may charge a fee for the physical act of transferring a copy, and
-you may at your option offer warranty protection in exchange for a fee.
-
- 2. You may modify your copy or copies of the Program or any portion
-of it, thus forming a work based on the Program, and copy and
-distribute such modifications or work under the terms of Section 1
-above, provided that you also meet all of these conditions:
-
- a) You must cause the modified files to carry prominent notices
- stating that you changed the files and the date of any change.
-
- b) You must cause any work that you distribute or publish, that in
- whole or in part contains or is derived from the Program or any
- part thereof, to be licensed as a whole at no charge to all third
- parties under the terms of this License.
-
- c) If the modified program normally reads commands interactively
- when run, you must cause it, when started running for such
- interactive use in the most ordinary way, to print or display an
- announcement including an appropriate copyright notice and a
- notice that there is no warranty (or else, saying that you provide
- a warranty) and that users may redistribute the program under
- these conditions, and telling the user how to view a copy of this
- License. (Exception: if the Program itself is interactive but
- does not normally print such an announcement, your work based on
- the Program is not required to print an announcement.)
-
-These requirements apply to the modified work as a whole. If
-identifiable sections of that work are not derived from the Program,
-and can be reasonably considered independent and separate works in
-themselves, then this License, and its terms, do not apply to those
-sections when you distribute them as separate works. But when you
-distribute the same sections as part of a whole which is a work based
-on the Program, the distribution of the whole must be on the terms of
-this License, whose permissions for other licensees extend to the
-entire whole, and thus to each and every part regardless of who wrote it.
-
-Thus, it is not the intent of this section to claim rights or contest
-your rights to work written entirely by you; rather, the intent is to
-exercise the right to control the distribution of derivative or
-collective works based on the Program.
-
-In addition, mere aggregation of another work not based on the Program
-with the Program (or with a work based on the Program) on a volume of
-a storage or distribution medium does not bring the other work under
-the scope of this License.
-
- 3. You may copy and distribute the Program (or a work based on it,
-under Section 2) in object code or executable form under the terms of
-Sections 1 and 2 above provided that you also do one of the following:
-
- a) Accompany it with the complete corresponding machine-readable
- source code, which must be distributed under the terms of Sections
- 1 and 2 above on a medium customarily used for software interchange; or,
-
- b) Accompany it with a written offer, valid for at least three
- years, to give any third party, for a charge no more than your
- cost of physically performing source distribution, a complete
- machine-readable copy of the corresponding source code, to be
- distributed under the terms of Sections 1 and 2 above on a medium
- customarily used for software interchange; or,
-
- c) Accompany it with the information you received as to the offer
- to distribute corresponding source code. (This alternative is
- allowed only for noncommercial distribution and only if you
- received the program in object code or executable form with such
- an offer, in accord with Subsection b above.)
-
-The source code for a work means the preferred form of the work for
-making modifications to it. For an executable work, complete source
-code means all the source code for all modules it contains, plus any
-associated interface definition files, plus the scripts used to
-control compilation and installation of the executable. However, as a
-special exception, the source code distributed need not include
-anything that is normally distributed (in either source or binary
-form) with the major components (compiler, kernel, and so on) of the
-operating system on which the executable runs, unless that component
-itself accompanies the executable.
-
-If distribution of executable or object code is made by offering
-access to copy from a designated place, then offering equivalent
-access to copy the source code from the same place counts as
-distribution of the source code, even though third parties are not
-compelled to copy the source along with the object code.
-
- 4. You may not copy, modify, sublicense, or distribute the Program
-except as expressly provided under this License. Any attempt
-otherwise to copy, modify, sublicense or distribute the Program is
-void, and will automatically terminate your rights under this License.
-However, parties who have received copies, or rights, from you under
-this License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
- 5. You are not required to accept this License, since you have not
-signed it. However, nothing else grants you permission to modify or
-distribute the Program or its derivative works. These actions are
-prohibited by law if you do not accept this License. Therefore, by
-modifying or distributing the Program (or any work based on the
-Program), you indicate your acceptance of this License to do so, and
-all its terms and conditions for copying, distributing or modifying
-the Program or works based on it.
-
- 6. Each time you redistribute the Program (or any work based on the
-Program), the recipient automatically receives a license from the
-original licensor to copy, distribute or modify the Program subject to
-these terms and conditions. You may not impose any further
-restrictions on the recipients' exercise of the rights granted herein.
-You are not responsible for enforcing compliance by third parties to
-this License.
-
- 7. If, as a consequence of a court judgment or allegation of patent
-infringement or for any other reason (not limited to patent issues),
-conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License. If you cannot
-distribute so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you
-may not distribute the Program at all. For example, if a patent
-license would not permit royalty-free redistribution of the Program by
-all those who receive copies directly or indirectly through you, then
-the only way you could satisfy both it and this License would be to
-refrain entirely from distribution of the Program.
-
-If any portion of this section is held invalid or unenforceable under
-any particular circumstance, the balance of the section is intended to
-apply and the section as a whole is intended to apply in other
-circumstances.
-
-It is not the purpose of this section to induce you to infringe any
-patents or other property right claims or to contest validity of any
-such claims; this section has the sole purpose of protecting the
-integrity of the free software distribution system, which is
-implemented by public license practices. Many people have made
-generous contributions to the wide range of software distributed
-through that system in reliance on consistent application of that
-system; it is up to the author/donor to decide if he or she is willing
-to distribute software through any other system and a licensee cannot
-impose that choice.
-
-This section is intended to make thoroughly clear what is believed to
-be a consequence of the rest of this License.
-
- 8. If the distribution and/or use of the Program is restricted in
-certain countries either by patents or by copyrighted interfaces, the
-original copyright holder who places the Program under this License
-may add an explicit geographical distribution limitation excluding
-those countries, so that distribution is permitted only in or among
-countries not thus excluded. In such case, this License incorporates
-the limitation as if written in the body of this License.
-
- 9. The Free Software Foundation may publish revised and/or new versions
-of the General Public 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.
-
-Each version is given a distinguishing version number. If the Program
-specifies a version number of this License which applies to it and "any
-later version", you have the option of following the terms and conditions
-either of that version or of any later version published by the Free
-Software Foundation. If the Program does not specify a version number of
-this License, you may choose any version ever published by the Free Software
-Foundation.
-
- 10. If you wish to incorporate parts of the Program into other free
-programs whose distribution conditions are different, write to the author
-to ask for permission. For software which is copyrighted by the Free
-Software Foundation, write to the Free Software Foundation; we sometimes
-make exceptions for this. Our decision will be guided by the two goals
-of preserving the free status of all derivatives of our free software and
-of promoting the sharing and reuse of software generally.
-
- NO WARRANTY
-
- 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
-FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
-OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
-PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
-OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
-TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
-PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
-REPAIR OR CORRECTION.
-
- 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
-REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
-INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
-OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
-TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
-YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
-PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGES.
-
- END OF TERMS AND CONDITIONS
-
- How to Apply These Terms to Your New Programs
-
- If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
- To do so, attach the following notices to the program. It is safest
-to attach them to the start of each source file to most effectively
-convey the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
- <one line to give the program's name and a brief idea of what it does.>
- Copyright (C) 19yy <name of author>
-
- This program 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 2 of the License, or
- (at your option) any later version.
-
- This program 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 this program; if not, write to the Free Software
- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-
-
-Also add information on how to contact you by electronic and paper mail.
-
-If the program is interactive, make it output a short notice like this
-when it starts in an interactive mode:
-
- Gnomovision version 69, Copyright (C) 19yy name of author
- Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
- This is free software, and you are welcome to redistribute it
- under certain conditions; type `show c' for details.
-
-The hypothetical commands `show w' and `show c' should show the appropriate
-parts of the General Public License. Of course, the commands you use may
-be called something other than `show w' and `show c'; they could even be
-mouse-clicks or menu items--whatever suits your program.
-
-You should also get your employer (if you work as a programmer) or your
-school, if any, to sign a "copyright disclaimer" for the program, if
-necessary. Here is a sample; alter the names:
-
- Yoyodyne, Inc., hereby disclaims all copyright interest in the program
- `Gnomovision' (which makes passes at compilers) written by James Hacker.
-
- <signature of Ty Coon>, 1 April 1989
- Ty Coon, President of Vice
-
-This General Public License does not permit incorporating your program into
-proprietary programs. If your program is a subroutine library, you may
-consider it more useful to permit linking proprietary applications with the
-library. If this is what you want to do, use the GNU Library General
-Public License instead of this License.
diff --git a/doc/ChangeLog b/doc/ChangeLog
deleted file mode 100644
index 6d496a88e..000000000
--- a/doc/ChangeLog
+++ /dev/null
@@ -1,977 +0,0 @@
-2002-05-13 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * Makefile.am (EXTRA_DIST): New var.
-
-2002-05-11 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * Makefile.am: Include ../am/maintainer-dirs (in MAINTAINER_MODE).
- (guile-api.alist, guile-api.alist-FORCE):
- New rules (in MAINTAINER_MODE).
-
-2002-05-09 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * groupings.alist: Add copyright and commentary.
-
- (favorite): Delete this example composite.
- (embedded-libltdl, gdb, coop, gh, g-fdes, r-fdes, scm, k, POSIX,
- guile-C-API): New groups.
-
-2002-05-08 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * groupings.alist: New file.
-
-2002-04-23 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * guile-api.alist: Update.
-
-2002-04-16 Marius Vollmer <mvo@zagadka.ping.de>
-
- * Makefile.am (dist-hook): Simplified to not use "cd"; now it
- works for relative pathnames in $(distdir).
-
-2002-04-10 Rob Browning <rlb@defaultvalue.org>
-
- * .cvsignore: add version-tutorial.texi, version.texi, and
- stamp-vti1.
-
-2002-03-01 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * guile-api.alist: Update.
-
-2001-08-27 Neil Jerram <neil@ossau.uklinux.net>
-
- * mltext.texi (Guile Character Properties): Fix `hexidecimal'
- spelling errors (merge from stable branch).
-
- * AUTHORS: Removed. Authorship information for each manual is now
- in the top-level Texinfo file for that manual.
-
-2001-08-24 Neil Jerram <neil@ossau.uklinux.net>
-
- * Makefile.am: Split documentation into per-manual subdirectories.
-
-2001-08-22 Mikael Djurfeldt <mdj@linnaeus.mit.edu>
-
- * scheme-options.texi (Evaluator trap options): Splitted
- section "Evaluator options".
-
- * scheme-evaluation.texi (Evaluator Behaviour): Typo "reader
- options" --> "evaluator options".
-
-2001-08-17 Rob Browning <rlb@defaultvalue.org>
-
- * Makefile.am (guile_tut_TEXINFOS): remove guile-tut.texi. It's
- already in info_TEXINFOS.
-
- * .cvsignore: rename stamp-vti1 to stamp-vti.1. Of course this
- only matters once you fix the bug in automake.
-
-2001-08-02 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-debug.texi (Debugging): Improve `make-stack' doc by
- explaining cutting args.
-
-2001-07-19 Rob Browning <rlb@defaultvalue.org>
-
- * posix.texi (Signals): add docs for setitimer and getitimer.
-
-2001-07-11 Gary Houston <ghouston@arglist.com>
-
- * scheme-evaluation.texi: Added `load-from-path'. Corrected `load':
- it doesn't use the load paths.
-
-2001-07-04 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-data.texi (Hook Reference): Removed documentation for
- `make-hook-with-name', which does note exist. Added note about
- unspecified return values to all procedure documentation
-
-2001-07-02 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * srfi-modules.texi (SRFI-1 Fold and Map): Documented extended
- versions of `map' and `for-each'.
-
-2001-06-30 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * preface.texi (Manual Conventions): Added description of
- @result{} and @print{}.
-
- * scheme-data.texi (Hash Table Examples): New subsubsection.
-
-2001-06-30 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-data.texi (Hash Tables): Added docs for
- `make-hash-table'.
-
-2001-06-29 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * misc-modules.texi: New file.
- (Pretty Printing): New chapter.
- (Formatted Output): New chapter.
-
- * Makefile.am (guile_TEXINFOS): Added misc-modules.texi.
-
- * guile.texi (Top): Added inclusion of misc-modules.texi.
-
- * scheme-modules.texi (Included Guile Modules): Added (srfi
- srfi-4) and (ice-9 rw) modules.
- (Module System Quirks): Removed note that `module-export!' must be
- called via gh_eval_str, now that we have scm_c_export.
-
- * repl-modules.texi (Loading Readline Support, Readline Options):
- New nodes.
-
-2001-06-27 Neil Jerram <neil@ossau.uklinux.net>
-
- * posix.texi (Network Sockets and Communication): Grammar fix -
- thanks to Christopher Cramer!
-
-2001-06-27 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * srfi-modules.texi (SRFI-4): Added documentation for the new
- module (srfi srfi-4).
-
-2001-06-26 Neil Jerram <neil@ossau.uklinux.net>
-
- * gh.texi (scm transition summary): Refer to scm_mem2string
- instead of scm_makfromstr.
-
-2001-06-26 Dirk Herrmann <D.Herrmann@tu-bs.de>
-
- * oldfmt.c (scm_oldfmt): Use scm_mem2string instead of
- scm_makfromstr.
-
-2001-06-25 Neil Jerram <neil@ossau.uklinux.net>
-
- * gh.texi (GH deprecation): Remove paragraph about portability.
-
- * extend.texi (Libguile Intro): Updated following Marius'
- suggestions.
-
-2001-06-25 Marius Vollmer <mvo@zagadka.ping.de>
-
- * Makefile.am (version.texi, version-tutorial.texi): Removed
- kluges to build them unconditionally.
-
-2001-06-22 Neil Jerram <neil@ossau.uklinux.net>
-
- * gh.texi (scm transition summary): New node for summary of how to
- transition from GH to scm interface.
- (GH): Link to new node.
- (Calling Scheme procedures from C): Remove doc for gh_set_car and
- gh_set_cdr, which don't actually exist.
- (Data types and constants defined by gh): Correct
- SCM_UNSPECIFIED/SCM_UNDEFINED confusion.
- (Calling Scheme procedures from C): Correct SCM_EOL/SCM_UNDEFINED
- confusion.
-
-2001-06-20 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile.texi (Top): Move GH chapter to end of Part V.
-
- * extend.texi (Libguile Intro), gh.texi (GH deprecation): Explain
- deprecation of GH and broad plan for documentation of scm
- interface.
-
-2001-06-18 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * srfi-modules.texi (SRFI-1): Completed procedure documentation.
-
- * scheme-data.texi (List Constructors): Added make-list.
- Added type index entries for all data types.
-
-2001-06-15 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * srfi-modules.texi (SRFI-1): New section documenting the SRFI-1
- module.
-
-2001-06-14 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-modules.texi (Included Guile Modules): Added reference to
- (srfi srfi-1) module.
-
-2001-06-16 Marius Vollmer <mvo@zagadka.ping.de>
-
- * posix.texi (Conventions): Use `system-error-errno' instead of
- explicit code
-
-2001-06-04 Gary Houston <ghouston@arglist.com>
-
- * scheme-io.texi (Block Reading and Writing): added
- write-string/partial, updated read-string!/partial.
-
-2001-05-30 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * General: A lot of typo, texinfo markup and layout corrections.
-
- * scheme-data.texi (Arithmetic): Clarified docs for - and /.
- (String Modification): Removed docs for C functions
- (scm_substring_move_right_x etc.)
- (Keyword Procedures): New section documenting the keyword
- procedures from boot-9.scm.
- (Vectors): Moved the section before the non-standard data types.
-
- * data-rep.texi (Defining New Types (Smobs)): Adapted description
- of smobs and proocedure creation to new terminology.
- (Describing a New Type): Removed mentioning of
- scm_make_smob_type_mfpe from smob function list and added
- deprecation notice for this function.
- (Creating Instances): Added description and macro docs for smobs
- with 2 or 3 data cells.
- (Garbage Collecting Smobs): Removed old docs for SCM_GCTYP16.
- (Garbage Collecting Simple Smobs): Added some clarification about
- usage and usefulness.
- (Non-immediate Datatypes): Changed R4RS reference to R5RS.
- (Vector Data): Document type-specific accessors.
-
-
-2001-05-23 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * guile.texi: Commented out menu entry and inclusion of Tcl/Tk
- stuff.
-
- * indices.texi: Users are advised to look under C and Scheme
- names, xref to transformation rules added.
-
- * intro.texi, scheme-modules.texi, scheme-ideas.texi,
- scheme-evaluation.texi, scheme-data.texi, scheme-procedures.texi:
- Fixed most REFFIXMEs.
-
- * srfi-modules.texi (About SRFI Usage): New node.
- (SRFI-0): Extended.
- Fixed all REFFIXMEs.
-
-2001-05-19 Neil Jerram <neil@ossau.uklinux.net>
-
- * posix.texi (Networking): Split existing material into new nodes
- `Network Address Conversion' and `Network Databases'.
-
- * scheme-control.texi (Lazy Catch): Update doc for new constraint
- that lazy-catch handlers are not allowed to return.
-
-2001-05-16 Rob Browning <rlb@cs.utexas.edu>
-
- * scheme-options.texi (Install Config): fixed minor-version docs
- and added micro-version docs.
-
-2001-05-16 Neil Jerram <neil@ossau.uklinux.net>
-
- * data-rep.texi, srfi-modules.texi (SRFI-14 Iterating Over
- Character Sets), scheme-io.texi (Block Reading and Writing),
- scheme-control.texi (Lazy Catch), scheme-procedures.texi (Internal
- Macros): Add @bullet to @itemize usages. (Thanks for Masao
- Uebayashi for the bug report!)
-
-2001-05-15 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scripts.texi (Invoking Guile): Added docs for --use-srfi.
-
- * expect.texi, repl-modules.texi: Start the chapters with a new
- page.
-
- * srfi-modules.texi (SRFI-0): Added note about supported feature
- identifiers and an example. Start the chapter with a new page.
-
- * srfi-modules.texi, scheme-data.texi, scheme-control.texi,
- scheme-binding.texi, repl-modules.texi, posix.texi, intro.texi,
- scheme-utility.texi: Change `--' to `-' throughout.
-
-2001-05-14 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * srfi-13-14.texi: Removed.
-
- * srfi-modules.texi (SRFI-13): Merged SRFI-13 docs into SRFI
- chapter.
- (SRFI-14): Merged SRFI-14 too.
-
- * guile.texi (Top): Remove inclusion of obsolete SRFI-13/14 file.
-
- * srfi-modules.texi (SRFI-0): New section.
- (SRFI-16): New section.
-
- Change `--' to `-' throughout.
-
-2001-05-13 Thien-Thi Nguyen <ttn@revel.glug.org>
-
- * intro.texi, scheme-modules.texi, scheme-procedures.texi:
- Fixup some module-related references.
-
- * scheme-modules.texi (Modules): Remove "babbling" fixme.
- (The Guile module system): Rewrite intro.
- (General Information about Modules): Rewrite some parts.
- Move problems to "Module System Quirks".
- (Using Guile Modules): Renamed from "Loading Guile Modules".
- Rewrite most parts.
- Remove reivewme comment.
- (Creating Guile Modules): Review, touch up.
- Remove "Tkintr" comment.
- (Module System Quirks): New node/subsection.
-
-2001-05-06 Thien-Thi Nguyen <ttn@revel.glug.org>
-
- * intro.texi (Using Guile Modules): Review; remove reviewme
- comment. Expand `GUILE_LOAD_PATH' blurb; add small example.
- (Reporting Bugs): Review; remove reviewme comment.
- Reword some phrases; add texi markup.
- Add suggestion to include `guile-config info' output.
- Update gdb invocation; add fixme question.
-
-2001-05-05 Neil Jerram <neil@ossau.uklinux.net>
-
- * AUTHORS: Added Martin Grabmueller.
-
- * scheme-procedures.texi (Macros, Syntax Rules, Internal Macros):
- New material.
- (Syntax Case): New node, but currently empty.
-
- * scheme-data.texi (Booleans, Symbols): Supply cross-references.
-
-2001-05-04 Neil Jerram <neil@ossau.uklinux.net>
-
- * new-docstrings.texi, posix.texi, scheme-control.texi,
- scheme-data.texi, scheme-debug.texi, scheme-evaluation.texi,
- scheme-io.texi, scheme-memory.texi, scheme-procedures.texi:
- Automatic docstring updates (mostly argument name updates and
- blank lines).
-
- * scheme-modules.texi: Change double hyphens to single.
-
- * scheme-control.texi (Lazy Catch): Completed.
-
- * posix.texi (Network Databases and Address Conversion): New
- subsubsection `IPv6 Address Conversion'.
-
-2001-05-04 Thien-Thi Nguyen <ttn@revel.glug.org>
-
- * preface.texi (iff): Use proper texi markup.
- Thanks to Florian Weimer.
-
-2001-05-04 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-io.texi (Block Reading and Writing): Moved the
- documentation for read-string!/partial from the node `Reading'.
-
- * scheme-data.texi (List/String Conversion): Added docstring for
- `string-split'.
-
-2001-05-02 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * srfi-13-14.texi: Added @bullet to various @itemize lists.
-
- * srfi-modules.texi (SRFI Support): New file and chapter.
-
- * Makefile.am (guile_TEXINFOS): Added repl-modules.texi and
- srfi-modules.texi.
-
- * guile.texi (Top): New menu entries for the new chapters.
- (Top): @includes for the new chapters.
- (Top): New menu entry for `SRFI Support', @include for
- `srfi-modules.texi'.
-
- * repl-modules.texi: New file.
- (Readline Support): New chapter for (ice-9 readline).
- (Value History): New chapter for (ice-9 history).
-
-2001-05-02 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-modules.texi (Dynamic Libraries): Renamed from `Dynamic
- Linking from Marius''.
- (The Guile module system): Removed obsolete naming convention.
- (Loading Guile Modules, Creating Guile Modules),
- (More Module Procedures, Included Guile Modules): New nodes, split
- from `The Guile module system'.
- (The Guile module system): Changed references to (ice-9 slib) to
- (ice-9 popen), because note everybody has SLIB installed.
- (Included Guile Modules): Added a bunch of modules shipped with
- Guile.
-
- (Dynamic Libraries): (old version) Removed.
-
- * scheme-io.texi (Block Reading and Writing): Corrected
- capitalization, so it builds again.
-
-2001-05-01 Gary Houston <ghouston@arglist.com>
-
- * scheme-io.texi: Removed obsolete section Binary IO. Added
- new section Block Reading and Writing. Updated section
- Line/Delimited with module usage.
-
-2001-04-29 Neil Jerram <neil@ossau.uklinux.net>
-
- * deprecated.texi (Tags): Removed - deprecation expired.
-
- * scheme-io.texi (Random Access): Removed `fseek' - deprecation
- expired.
-
- * guile.texi (Top): Add menu entry for Manual Conventions node.
-
-2001-04-28 Neil Jerram <neil@ossau.uklinux.net>
-
- * THANKS: Move authorship bit into AUTHORS, simplify structure,
- add Dirk Herrmann.
-
- * AUTHORS, guile.texi, guile-tut.texi, goops.texi, Makefile.am:
- Consolidate authorship information in AUTHORS file, and @include
- AUTHORS from the top level source file for each manual.
-
-2001-04-28 Thien-Thi Nguyen <ttn@revel.glug.org>
-
- * preface.texi (Manual Conventions): New chapter.
-
-2001-04-26 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * srfi-13-14.texi (Reverse/Append): Updated procedure names for
- string-concatenate-reverse[/shared].
- (Reverse/Append): Document the parameter `end' to
- string-concatenate-reverse.
-
-2001-04-26 Neil Jerram <neil@ossau.uklinux.net>
-
- * data-rep.texi (Defining New Types (Smobs)): Use non-deprecated
- smob interface. Thanks to Masao Uebayashi for the patch!
- (Creating Instances): Don't need SCM_NIMP anymore.
-
-2001-04-25 Marius Vollmer <mvo@zagadka.ping.de>
-
- * guile.1: New file, from Robert Merkel and Rob Browning.
- * Makefile.am (man_MANS, EXTRADIST): Added, but still commented
- out: install and distribute the manpage. It is not yet installed
- or distributed since we don't have Robert's papers yet.
-
-2001-04-24 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile-tut.texi: Include version-tutorial.texi rather than
- version.texi.
-
- * Makefile.am ($(srcdir)/version-tutorial.texi): New target, to
- avoid having two files both include version.texi.
-
-2001-04-24 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * Makefile.am (guile_TEXINFOS): Added srfi-13-14.texi.
-
- * srfi-13-14.texi: New file documenting SRFI-13/14.
-
- * guile.texi (Top): Added the SRFI-13/14 menu entry and @include.
-
-2001-04-22 Neil Jerram <neil@ossau.uklinux.net>
-
- * posix.texi (Network Sockets and Communication): Automatic
- docstring updates for `socket' and `connect'. (For IPV6 support.)
-
- * scheme-io.texi: Remove old docstring comments referring to
- r4rs.scm.
-
- * appendices.texi (The Basic Guile Package, Packages not shipped
- with Guile), env.texi (Switching to Environments), format.texi
- (Format Specification), gh.texi
- (Executing Scheme code, Calling Scheme procedures from C),
- guile-tut.texi (How to characterize Guile), scheme-data.texi
- (Symbols, Keywords, Keyword Read Syntax, Append/Reverse),
- scheme-evaluation.texi (Delayed Evaluation), scheme-modules.texi
- (Scheme and modules), scheme-io.texi (Soft Ports): Change R4RS
- references to R5RS.
-
- * r4rs.texi: Removed.
-
- * Makefile.am (info_TEXINFOS): Remove r4rs.
-
- * README: Note removal of r4rs, and provide a reference.
-
- * scheme-control.texi (Exceptions): Extended documentation.
- (Continuations): Correct "except" typo, and fix reference to
- Exceptions node. Plus minor review changes.
-
-2001-04-20 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-control.texi (Exceptions): Reorganized and extended
- existing documentation; more to come.
-
-2001-04-20 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-evaluation.texi (Comments): Document normal comments and
- comment conventions.
- (Block Comments): Documented multiline comments.
- (Case Sensitivity): Documented R5RS and Guile behaviour and how to
- switch it off.
-
- * scheme-control.texi (Continuations): Added some documentation
- for call/cc.
- (Exceptions): Added xref to `Continuations'.
-
- * scheme-binding.texi (Binding Reflection): Typo fix.
-
-2001-04-20 Neil Jerram <neil@ossau.uklinux.net>
-
- * gh.texi (Executing Scheme code): gh_eval_file returns
- SCM_UNSPECIFIED. Thanks to Dirk for the report!
-
- * data-rep.texi (Non-immediate Datatypes, Immediates vs
- Non-immediates): Emphasize current rather than pre-1.4 practice
- when talking about not needing to call SCM_NIMP.
-
- * recipe-guidelines.txt: New file: guidelines for contributions to
- the Guile Recipes manual.
-
-2001-04-20 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * intro.texi (Using Guile Modules): Wrote intro to using modules.
- (Writing New Modules): New intro for writing modules.
- (Reporting Bugs): Added info about what is a bug and what to
- include in a bug report (taken and adapted from the Emacs
- Reference Manual).
-
-2001-04-19 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-control.texi (while do): Added documentation for named
- let.
-
- * scheme-binding.texi (Internal Definitions): New explanation of
- `Internal Definitions'.
- (Top Level): Documented behaviour of top level definitions.
- (Binding Constructs): New introductory text.
- (Local Bindings): Explain concept of local bindings. Document
- let, let* and letrec.
-
-2001-04-18 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-modules.texi (Modules): Added menu descriptions.
- (Scheme and modules, The Guile module system): Some whitespace
- cleanup
- (The Guile module system): Layout fixes, docstring fix for
- `define-module'.
-
-2001-04-17 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-control.texi (Multiple Values): Documented concept of
- multiple values, added docs for `receive'.
- (begin): Documented `begin'.
- (if cond case): Documented `if', `cond' and `case'.
- (and or): Documented `and' and `or'.
- (while do): Documented `do' and `while'.
-
- * scheme-procedures.texi (Optional Arguments): Split the node,
- added introductory text, added menu for subsections.
- (let-optional Reference, let-keywords Reference),
- (lambda* Reference, define* Reference): Added syntax documentation
- for all exported procedures from (ice-9 optargs).
-
-2001-04-17 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-utility.texi (General Conversion): New node, added
- `object->string'.
- (Equality): Added definition and explanation of `sameness'.
-
- * posix.texi (System Identification): Added `gethostname' and
- `sethostname'.
- (Processes): Added `setpriority' and `getpriority'.
- (User Information): Added `cuserid' and `getlogin'.
- (Ports and File Descriptors): Added `flock'.
- (Processes): Added `chroot'.
- (File System): Added `mkstemp!'.
- (Encryption): New node, added `crypt' and `getpass'.
-
- * new-docstrings.texi: Moved several docstrings over to the
- reference manual (see above which).
-
- * scheme-data.texi (Data Types), (Numerical Tower): Add explicit
- @bullet to @itemize to satisfy older `makeinfo'.
-
-2001-04-16 Neil Jerram <neil@ossau.uklinux.net>
-
- * data-rep.texi (Signalling Type Errors): Update SCM_ASSERT doc
- for recent changes to disallow passing a string parameter as the
- `pos'. Thanks to Dirk Herrmann for the patch!
-
-2001-04-13 Neil Jerram <neil@ossau.uklinux.net>
-
- * data-rep.texi (Unpacking the SCM type): New section, taken from
- Dirk Herrmann's description of SCM and scm_bits_t in api.txt.
- (Immediate Datatypes, Non-immediate Datatypes): Remove obsolete
- notes about needing to call SCM_NIMP.
-
-2001-04-11 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-procedures.texi (Procedures with Setters): Fix dvi
- building syntax error. Thanks to Dale P. Smith for the report and
- patch.
-
-2001-04-11 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-scheduling.texi (Arbiters): New explanatory text.
- (Asyncs): New explanations and documentation.
- (Scheduling): Added menu entry descriptions.
- (Fluids): New documentation.
-
-2001-04-11 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-procedures.texi (Lambda): Documented the lambda form.
- (Procedure Properties): Concept and usage explanation added.
- (Procedures with Setters): Explain by example, introduce
- definitions.
-
- * scheme-data.texi (Symbols and Variables): Split and reorganized
- this section.
- (Symbols): New introductory text.
- (Characters): Added char-ci* procedures to rn index.
-
-2001-04-10 Neil Jerram <neil@ossau.uklinux.net>
-
- * scm.texi (Handling Errors): Improve Texinfo markup. Thanks to
- Dale P. Smith for the patch!
-
- * api.txt (Accessing Cell Entries): Fix typo.
-
-2001-04-09 Neil Jerram <neil@ossau.uklinux.net>
-
- * deprecated.texi (Shared And Read Only Strings): New section for
- deprecated string stuff. I've also updated the text a bit to
- reflect current usage of "read only" strings.
-
- * scheme-data.texi (Shared Substrings, Read Only Strings): Moved
- to deprecated.texi.
-
- * deprecated.texi, posix.texi, scheme-binding.texi,
- scheme-control.texi, scheme-data.texi, scheme-debug.texi,
- scheme-evaluation.texi, scheme-io.texi, scheme-memory.texi,
- scheme-modules.texi, scheme-options.texi, scheme-procedures.texi,
- scheme-scheduling.texi, scheme-translation.texi,
- scheme-utility.texi: Remove `@c docstring' comments, since they
- aren't used any more by the docstring tracking utilities.
-
-2001-04-09 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-data.texi (Pairs): New data type and procedure
- description.
- (Lists): Added new subsections for grouping the list procedures.
- (Hooks): Added new nodes for hook subsections.
- (String Syntax): New node, factoring out read syntax.
- (Strings): Some blurb about allowed characters, zero-termination
- etc.
- (Keywords): Added menu descriptions.
-
-2001-04-08 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-indices.texi (R5RS Index): Print index `rn', not `r5'.
-
- * guile.texi: The index formerly known as `r5' is now called `rn'.
-
- * scheme-utility.texi, scheme-procedures.texi, scheme-io.texi,
- scheme-evaluation.texi, scheme-control.texi, scheme-data.texi:
- Changed all @r5index entries to @rnindex.
-
-2001-04-06 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-data.texi (Hooks): Added hook description and
- constraints.
-
-2001-04-06 Thien-Thi Nguyen <ttn@revel.glug.org>
-
- * scheme-scheduling.texi (Higher level thread
- procedures): Replace some instances of `@var' with `@code'.
-
- * scheme-scheduling.texi (Higher level thread
- procedures): Rewrite.
-
-2001-04-04 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-data.texi (Alphabetic Case Mapping),
- (String Comparison): Rearranged function order.
- (Vectors): Reorganized, new introductory text, docs about read
- syntax.
-
-2001-04-03 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-options.texi, scheme-procedures.texi,
- scheme-modules.texi, scheme-memory.texi, scheme-control.texi,
- scheme-utility.texi, scheme-io.texi, scheme-evaluation.texi,
- scheme-data.texi: Removed a lot of ARGFIXME's after tweaking
- docstrings and C source.
-
- * new-docstrings.texi, scheme-io.texi, scheme-data.texi,
- posix.texi, scheme-control.texi, scheme-evaluation.texi,
- scheme-memory.texi, scheme-procedures.texi, scheme-modules.texi,
- scheme-scheduling.texi: Automated docstring merging.
-
-2001-04-02 Neil Jerram <neil@ossau.uklinux.net>
-
- * data-rep.texi (Immediates vs. Non-immediates): Update
- out-of-date documentation. (Thanks to Dirk Herrmann for the
- report!)
- (Immediates vs Non-immediates): Renamed without the dot, since the
- dot causes `info' not to be able to display this node!
-
- * Makefile.am (guile_TEXINFOS): Add in a few more source files
- that had got left out.
-
-2001-03-30 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-reading.texi (Further Reading): Add bullets to further
- reading list.
-
- * gh.texi: Insert page break before chapter. Remove page breaks
- within the chapter.
-
- * Makefile.am: Add script-getopt.texi.
-
- * guile.texi (Top): Include and link to new script-getopt.texi
- chapter.
-
- * script-getopt.texi: New chapter on command line handling.
- (Written and contributed by Martin Grabmueller, revised by me.)
-
- * intro.texi (Modules and Extensions): Fix typo.
-
-2001-03-27 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-data.texi (Strings): Reorganized the whole `Strings'
- section and wrote introductory material for each new subsection.
-
-2001-03-25 Marius Vollmer <mvo@zagadka.ping.de>
-
- * intro.texi (Modules and Extensions): Some short text about
- dynamic libraries and modules.
-
-2001-03-23 Neil Jerram <neil@ossau.uklinux.net>
-
- * intro.texi (Writing Extensions for Guile), scheme-data.texi
- (Lists): Fix typos.
-
- * guile-tut.texi, ChangeLog-guile-doc-tutorial: Added to CVS. It
- seems that I somehow missed these out when I moved everything from
- guile-doc to guile-core.
-
- * posix.texi, scheme-data.texi, scheme-evaluation.texi,
- scheme-io.texi, scheme-memory.texi: Automatic docstring updates.
-
- * new-docstrings.texi: New file. Holds snarfed docstrings that
- have not yet been incorporated into the reference manual.
-
-2001-03-20 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-options.texi (Evaluator options): Added evaluator
- options, corrected docs for evaluator trap options.
-
- * scheme-evaluation.texi (Scheme Read): New docs for read-options,
- read-enable, read-disable and read-set! and cross references to
- option nodes.
- (Evaluator Options): New docs for eval-options, eval-enable,
- eval-disable and eval-set!, traps, trap-enable, trap-disable and
- trap-set! and cross references to option nodes.
- (Evaluator Behaviour): Renamed node from `Evaluator options' to
- avoid name clash.
-
- * scheme-io.texi (String Ports): Added docs for SRFI-6 procedures.
- (Void Ports): Corrected introductory comment.
-
-2001-03-16 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * scheme-data.texi (Arithmetic): Documented the arithmetic
- procedures.
- (Integer Operations): Added documentation.
- (Comparison): Added documentation.
- (Complex): Added documentation.
- (Symbols and Variables): Comment out `builtin-bindings', which is
- removed according to NEWS.
- (Pairs): Added documentation.
-
- * scheme-io.texi: Added R5RS index entries for all R5RS
- procedures.
- (File Ports): New docs for `call-with-input-file',
- `call-with-output-file', `with-input-from-file',
- `with-output-to-file', `with-error-to-file'.
-
- * scheme-control.texi, scheme-utility.texi,
- * scheme-procedures.texi: Added R5RS index entries for all R5RS
- procedures.
-
- * scheme-evaluation.texi (Fly Evaluation): Added documentation for
- `apply'. Added R5RS index entries for all R5RS procedures.
-
- * scheme-data.texi: Added R5RS index entries for all R5RS
- procedures. Removed R5RS index entries for `ass{q,v,occ}-set!'.
- Removed explicit entries into the function entries. They are
- automagic.
- (Vectors): Added documentation for `make-vector', `vector-ref' and
- `vector-set!'.
-
-2001-03-12 Marius Vollmer <mvo@zagadka.ping.de>
-
- * intro.texi: Changed to reflect current practice better. Added
- stuff about writing Guile Extensions (aka dynamically loaded
- shared libraries).
-
-2001-03-09 Mikael Djurfeldt <mdj@linnaeus.mit.edu>
-
- * goops.texi (VERSION): Bumped to version 0.3.
-
- * goops-tutorial.texi, goops.texi: Updated to reflect new
- define-method syntax.
-
-2001-03-09 Neil Jerram <neil@ossau.uklinux.net>
-
- * Makefile.am: Change HTML to HTMLDOC, now that we're part of a
- wider distribution.
-
- Moving documentation files from guile-doc and guile-doc into
- guile-core/doc:
-
- * env.texi, indices.texi, mbapi.texi, mltext.texi, scripts.texi,
- scsh.texi, tcltk.texi, hierarchy.txt, scheme-indices.texi,
- slib.texi, deprecated.texi, scheme-binding.texi, appendices.texi,
- scheme-intro.texi, goops.texi, extend.texi, gh.texi, intro.texi,
- preface.texi, scm.texi, goops-tutorial.texi, hierarchy.eps,
- r4rs.texi, r5rs.texi, texinfo.tex, scheme-reading.texi,
- data-rep.texi, scheme-utility.texi, posix.texi,
- scheme-control.texi, scheme-debug.texi, scheme-evaluation.texi,
- scheme-io.texi, scheme-memory.texi, scheme-modules.texi,
- scheme-options.texi, scheme-procedures.texi,
- scheme-scheduling.texi, scheme-translation.texi, guile.texi,
- scheme-data.texi, scheme-ideas.texi, expect.texi,
- ChangeLog-guile-doc-ref, guile-tut.texi,
- ChangeLog-guile-doc-tutorial, AUTHORS, BUGS, NEWS, THANKS: New
- files.
-
- * .cvsignore, Makefile.am, README: Merged.
-
- * sources: New subdirectory.
-
- Both the following files are about to be replaced by files from
- guile-doc/ref.
-
- * texinfo.tex: Removed.
-
- * data-rep.texi: Removed.
-
-2001-02-15 Neil Jerram <neil@ossau.uklinux.net>
-
- * README: Explain retirement of `data-rep.texi'.
-
- * Makefile.am (info_TEXINFOS, data_rep_TEXINFOS): Removed.
-
- * data-rep.texi: Replace this copy of data-rep.texi with a notice
- indicating that it has been retired. The master copy of
- data-rep.texi is at guile-doc/ref/data-rep.texi.
-
-2001-02-04 Marius Vollmer <mvo@zagadka.ping.de>
-
- * data-rep.texi: Use SCM_SMOB_DATA instead of SCM_CDR. Also
- things like SCM_SMOB_PREDICATE and SCM_NEWSMOB. Thanks to Dale
- P. Smith!
-
-2000-10-25 Mikael Djurfeldt <mdj@linnaeus.mit.edu>
-
- * mop.text: Preliminary documentation of the GOOPS meta object
- protocol.
-
-2000-07-28 Neil Jerram <neil@ossau.uklinux.net>
-
- * data-rep.texi (Garbage Collection): Fix "accomodate" spelling
- mistake.
-
-2000-06-30 Dirk Herrmann <D.Herrmann@tu-bs.de>
-
- * data-rep.tex: Removed documentation for SCM_OUTOFRANGE.
-
-2000-06-20 Mikael Djurfeldt <mdj@thalamus.nada.kth.se>
-
- * data-rep.texi: Center discussion around the standard interface
- for smob type creation (scm_make_smob_type) and warn about the
- ongoing discussion which may result in deprecating
- scm_make_smob_type_mfpe in next release of Guile.
-
-2000-05-15 Dirk Herrmann <D.Herrmann@tu-bs.de>
-
- * data-rep.texi: Updated the macro names for operating on
- characters.
-
-2000-03-22 Dirk Herrmann <D.Herrmann@tu-bs.de>
-
- * api.txt: Added a first attempt for a description of the newly
- designed low level API.
-
-2000-01-31 Marius Vollmer <mvo@zagadka.ping.de>
-
- * Makefile.am (version.texi): Override automake's rule for
- version.texi so that it gets created even in non-maintainer-mode.
-
-Thu Jan 20 13:00:18 2000 Greg J. Badros <gjb@cs.washington.edu>
-
- * version.texi, stamp-vti: Removed -- these are auto-generated.
-
-2000-01-12 Mikael Djurfeldt <mdj@mdj.nada.kth.se>
-
- * Makefile.am (dist-hook): Updated to include oldfmt.c in
- distribution archive.
-
- * README: Updated with note about oldfmt.c.
-
- * oldfmt.c: New file: Used by application writers to adapt to
- new-style error format strings.
-
-1999-12-06 Gary Houston <ghouston@freewire.co.uk>
-
- * data-rep.texi: change dircategory to match change in guile-doc
- and scm.
-
-1999-10-05 Jim Blandy <jimb@savonarola.red-bean.com>
-
- * Makefile.in: Deleted from CVS repository. Run the autogen.sh
- script to create generated files like this one.
-
-1999-09-11 Jim Blandy <jimb@savonarola.red-bean.com>
-
- * Makefile.in: Regenerated.
-
-Fri Jun 25 22:21:43 1999 Greg Badros <gjb@cs.washington.edu>
-
- * data-rep.texi: Updated SMOB docs to talk about
- scm_make_smob_type_mfpe, SCM_RETURN_NEWSMOB, SCM_NEWSMOB function
- and macros.
-
-1999-04-17 Jim Blandy <jimb@savonarola.red-bean.com>
-
- * Makefile.in: Regenerated.
-
-1998-10-19 Jim Blandy <jimb@zwingli.cygnus.com>
-
- * COPYING: New file.
- * Makefile.in: Regenerated.
-
- * Makefile.am (EXAMPLE_SMOB_FILES): List example-smob/COPYING.
- * Makefile.in: Regenerated.
-
-1998-10-16 Jim Blandy <jimb@zwingli.cygnus.com>
-
- * Makefile.in: Regenerated, after change to qthreads.m4.
-
-1998-10-15 Jim Blandy <jimb@zwingli.cygnus.com>
-
- * stamp-vti: Regenerated.
-
- * hacks.el: Some handy helper functions for working on the manual.
-
- * data-rep.texi: Extended to accomodate a full running example,
- provided with the manual.
- * example-smob: A new subdirectory, containing example files for
- the manual chapter on smobs.
- * Makefile.am (EXAMPLE_SMOB_FILES, dist-hook): New variable and
- target, to get the example-smob directory into the distribution.
- * Makefile.in: Regenerated.
-
-1998-10-08 Jim Blandy <jimb@zwingli.cygnus.com>
-
- * .cvsignore: New file, containing data-rep.info. I'm not sure
- whether we want to check this file into CVS, because it's
- generated; if you find compelling reasons it should be, let me
- know.
-
-1998-10-07 Jim Blandy <jimb@zwingli.cygnus.com>
-
- * New directory for documentation.
- * README: New file.
- * data-rep.texi: It's not a real manual, but it's better than
- nothing.
- * Makefile.am, Makefile.in, data-rep.info, data-rep.texi,
- mdate-sh, stamp-vti, texinfo.tex, version.texi: The usual support
- files.
diff --git a/doc/ChangeLog-guile-doc b/doc/ChangeLog-guile-doc
deleted file mode 100644
index 74ce49b55..000000000
--- a/doc/ChangeLog-guile-doc
+++ /dev/null
@@ -1,48 +0,0 @@
-2001-02-15 Neil Jerram <neil@ossau.uklinux.net>
-
- * sources/data-rep.texi: Removed. (ref/data-rep.texi is now the
- current version of this essay.)
-
-2001-01-26 Neil Jerram <neil@ossau.uklinux.net>
-
- * configure.in: Only check for `texi2html' program if HTML is
- enabled, and explain where to get `texi2html' from if the check
- fails.
-
- * configure.in, Makefile.am, ref/Makefile.am,
- tutorial/Makefile.am: Clean up Makefile.am's and support
- (configurable) building of HTML documentation in addition to
- Info. Thanks to Steve Tell for the patch on which these changes
- were based.
-
-2000-10-14 Neil Jerram <neil@ossau.uklinux.net>
-
- * sources/data-rep.texi: Merged a lot of changes from
- guile-core/doc/data-rep.texi.
-
-2000-08-07 Neil Jerram <neil@ossau.uklinux.net>
-
- * configure.in, configure: Advance version number to 1.4.
-
-2000-07-28 Neil Jerram <neil@ossau.uklinux.net>
-
- * sources/data-rep.texi (Garbage Collection): Fix "accomodate"
- spelling mistake.
-
-1998-07-27 Mark Galassi <rosalia@cygnus.com>
-
- * simple test
-
-1998-04-13 Marius Vollmer <mvo@zagadka.ping.de>
-
- Have "make dist" include the sources directory:
- * Makefile.am: Added "sources" directory to SUBDIRS.
- * sources/Makefile.am: New file.
- * configure.in: Added "sources/Makefile" to AC_OUTPUT.
-
-Sun Jun 22 18:38:28 1997 Tim Pierce <twp@twp.tezcat.com>
-
- New documentation module.
-
-
-
diff --git a/doc/Makefile.am b/doc/Makefile.am
deleted file mode 100644
index 708899fe0..000000000
--- a/doc/Makefile.am
+++ /dev/null
@@ -1,51 +0,0 @@
-## Process this file with Automake to create Makefile.in
-##
-## Copyright (C) 1998 Free Software Foundation, Inc.
-##
-## This file is part of GUILE.
-##
-## GUILE 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 2, or
-## (at your option) any later version.
-##
-## GUILE 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 GUILE; see the file COPYING. If not, write
-## to the Free Software Foundation, Inc., 59 Temple Place, Suite
-## 330, Boston, MA 02111-1307 USA
-
-AUTOMAKE_OPTIONS = gnu
-
-SUBDIRS = ref tutorial goops r5rs
-
-# pending the papers from Robert Merkel
-# man_MANS = guile.1
-
-EXAMPLE_SMOB_FILES = \
- ChangeLog Makefile README COPYING image-type.c image-type.h myguile.c
-
-OLDFMT = oldfmt.c
-
-dist-hook:
- cp $(srcdir)/$(OLDFMT) $(distdir)/
- mkdir $(distdir)/example-smob
- for f in $(EXAMPLE_SMOB_FILES); do \
- cp $(srcdir)/example-smob/$$f $(distdir)/example-smob/; \
- done
-
-EXTRA_DIST = groupings.alist guile-api.alist
-
-# pending the papers from Robert Merkel
-# EXTRA_DIST = guile.1
-
-if MAINTAINER_MODE
-include $(top_srcdir)/am/maintainer-dirs
-guile-api.alist: guile-api.alist-FORCE
- ( cd $(top_builddir) ; $(mscripts)/update-guile-api.alist )
-guile-api.alist-FORCE:
-endif
diff --git a/doc/NEWS b/doc/NEWS
deleted file mode 100644
index 2624f28d3..000000000
--- a/doc/NEWS
+++ /dev/null
@@ -1,44 +0,0 @@
-Guile-doc NEWS --- history of user-visible changes. -*- text -*-
-Copyright (C) 1997, 2001 Free Software Foundation, Inc.
-See the end for copying conditions.
-
-
-Changes since Guile 1.3.4:
-
-* It's now possible to build HTML documentation as well as Info
-
-The guile-doc distribution now supports building HTML versions of the
-Guile tutorial and reference manual, in addition to the standard Info
-documentation. To enable this, include the `--enable-html' option
-when you run `./configure':
-
- ./configure --enable-html
-
-HTML documentation is installed in $(prefix)/html/guile-$(VERSION).
-
-
-Changes since Guile 1.0 (Sun 5 Jan 1997):
-
-* The current documentation approach, recommended by Jim Blandy, is to
-have: (*) a tutorial with the pedagogical style of guile-user, and a
-non-dry reference manual in the style of the most excellent GNU libc
-reference manual: the reference manual should be complete, but at the
-same time it should have an introductory screen for each major topic,
-which can be referenced if the user goes "up" a level in the info
-documentation.
-
-
-Copyright information:
-
-Copyright (C) 1996,1997 Free Software Foundation, Inc.
-
- Permission is granted to anyone to make or distribute verbatim copies
- of this document as received, in any medium, provided that the
- copyright notice and this permission notice are preserved,
- thus giving the recipient permission to redistribute in turn.
-
- Permission is granted to distribute modified versions
- of this document, or of portions of it,
- under the above conditions, provided also that they
- carry prominent notices stating who last changed them.
-
diff --git a/doc/README b/doc/README
deleted file mode 100644
index 3ecd329b4..000000000
--- a/doc/README
+++ /dev/null
@@ -1,33 +0,0 @@
-This directory contains documentation on the Guile core. -*-text-*-
-
-The documentation consists of the following manuals.
-
-- The Guile Tutorial (guile-tut.texi) contains a tutorial introduction
- to using Guile.
-
-- The Guile Reference Manual (guile.texi) contains (or is intended to
- contain) reference documentation on all aspects of Guile.
-
-- The GOOPS Manual (goops.texi) contains both tutorial-style and
- reference documentation for using GOOPS, Guile's Object Oriented
- Programming System.
-
-- The Revised^5 Report on the Algorithmic Language Scheme (r5rs.texi).
-
-Please be aware that this is all very much work in progress (apart
-from the Revised^5 Report). Bug reports and contributions are
-welcome!
-
-The file `oldfmt.c' contains a function which can be used by
-application writers to support both old-style and new-style error
-format strings.
-
-The `sources' directory includes some stuff relevant to the Guile
-reference manual, and which may eventually be folded in to it. It's
-not immediately relevant, however, which is why it's not in this
-directory.
-
-The Revised^4 Report (r4rs.texi) is no longer in this distribution, as
-it is completely superseded by the Revised^5 Report. If you need to
-consult R4RS, it is still widely available, for example at
-http://www-swiss.ai.mit.edu/projects/info/SchemeDocs/r4rs/.
diff --git a/doc/THANKS b/doc/THANKS
deleted file mode 100644
index 53cff29f4..000000000
--- a/doc/THANKS
+++ /dev/null
@@ -1,19 +0,0 @@
-Many thanks to the following people for contributing to the Guile
-manuals!
-
-Proofreading, bug reports and patches from:
- Chris Bitmead
-Christopher Cramer
- Marcus Daniels
- Dirk Herrmann
- Dale P. Smith
- Steve Tell
- Lee Thomas
- Masao Uebayashi
- Joel Weber
- Keith Wright
-
-New entries from:
- Per Bothner
- Martin Grabmueller
- Thien Thi Nguyen
diff --git a/doc/example-smob/COPYING b/doc/example-smob/COPYING
deleted file mode 100644
index eeb586b39..000000000
--- a/doc/example-smob/COPYING
+++ /dev/null
@@ -1,340 +0,0 @@
- GNU GENERAL PUBLIC LICENSE
- Version 2, June 1991
-
- Copyright (C) 1989, 1991 Free Software Foundation, Inc.
- 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
- Preamble
-
- The licenses for most software are designed to take away your
-freedom to share and change it. By contrast, the GNU General Public
-License is intended to guarantee your freedom to share and change free
-software--to make sure the software is free for all its users. This
-General Public License applies to most of the Free Software
-Foundation's software and to any other program whose authors commit to
-using it. (Some other Free Software Foundation software is covered by
-the GNU Library General Public License instead.) You can apply it to
-your programs, too.
-
- When we speak of free software, we are referring to freedom, not
-price. Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-this service if you wish), that you receive source code or can get it
-if you want it, that you can change the software or use pieces of it
-in new free programs; and that you know you can do these things.
-
- To protect your rights, we need to make restrictions that forbid
-anyone to deny you these rights or to ask you to surrender the rights.
-These restrictions translate to certain responsibilities for you if you
-distribute copies of the software, or if you modify it.
-
- For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must give the recipients all the rights that
-you have. You must make sure that they, too, receive or can get the
-source code. And you must show them these terms so they know their
-rights.
-
- We protect your rights with two steps: (1) copyright the software, and
-(2) offer you this license which gives you legal permission to copy,
-distribute and/or modify the software.
-
- Also, for each author's protection and ours, we want to make certain
-that everyone understands that there is no warranty for this free
-software. If the software is modified by someone else and passed on, we
-want its recipients to know that what they have is not the original, so
-that any problems introduced by others will not reflect on the original
-authors' reputations.
-
- Finally, any free program is threatened constantly by software
-patents. We wish to avoid the danger that redistributors of a free
-program will individually obtain patent licenses, in effect making the
-program proprietary. To prevent this, we have made it clear that any
-patent must be licensed for everyone's free use or not licensed at all.
-
- The precise terms and conditions for copying, distribution and
-modification follow.
-
- GNU GENERAL PUBLIC LICENSE
- TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
- 0. This License applies to any program or other work which contains
-a notice placed by the copyright holder saying it may be distributed
-under the terms of this General Public License. The "Program", below,
-refers to any such program or work, and a "work based on the Program"
-means either the Program or any derivative work under copyright law:
-that is to say, a work containing the Program or a portion of it,
-either verbatim or with modifications and/or translated into another
-language. (Hereinafter, translation is included without limitation in
-the term "modification".) Each licensee is addressed as "you".
-
-Activities other than copying, distribution and modification are not
-covered by this License; they are outside its scope. The act of
-running the Program is not restricted, and the output from the Program
-is covered only if its contents constitute a work based on the
-Program (independent of having been made by running the Program).
-Whether that is true depends on what the Program does.
-
- 1. You may copy and distribute verbatim copies of the Program's
-source code as you receive it, in any medium, provided that you
-conspicuously and appropriately publish on each copy an appropriate
-copyright notice and disclaimer of warranty; keep intact all the
-notices that refer to this License and to the absence of any warranty;
-and give any other recipients of the Program a copy of this License
-along with the Program.
-
-You may charge a fee for the physical act of transferring a copy, and
-you may at your option offer warranty protection in exchange for a fee.
-
- 2. You may modify your copy or copies of the Program or any portion
-of it, thus forming a work based on the Program, and copy and
-distribute such modifications or work under the terms of Section 1
-above, provided that you also meet all of these conditions:
-
- a) You must cause the modified files to carry prominent notices
- stating that you changed the files and the date of any change.
-
- b) You must cause any work that you distribute or publish, that in
- whole or in part contains or is derived from the Program or any
- part thereof, to be licensed as a whole at no charge to all third
- parties under the terms of this License.
-
- c) If the modified program normally reads commands interactively
- when run, you must cause it, when started running for such
- interactive use in the most ordinary way, to print or display an
- announcement including an appropriate copyright notice and a
- notice that there is no warranty (or else, saying that you provide
- a warranty) and that users may redistribute the program under
- these conditions, and telling the user how to view a copy of this
- License. (Exception: if the Program itself is interactive but
- does not normally print such an announcement, your work based on
- the Program is not required to print an announcement.)
-
-These requirements apply to the modified work as a whole. If
-identifiable sections of that work are not derived from the Program,
-and can be reasonably considered independent and separate works in
-themselves, then this License, and its terms, do not apply to those
-sections when you distribute them as separate works. But when you
-distribute the same sections as part of a whole which is a work based
-on the Program, the distribution of the whole must be on the terms of
-this License, whose permissions for other licensees extend to the
-entire whole, and thus to each and every part regardless of who wrote it.
-
-Thus, it is not the intent of this section to claim rights or contest
-your rights to work written entirely by you; rather, the intent is to
-exercise the right to control the distribution of derivative or
-collective works based on the Program.
-
-In addition, mere aggregation of another work not based on the Program
-with the Program (or with a work based on the Program) on a volume of
-a storage or distribution medium does not bring the other work under
-the scope of this License.
-
- 3. You may copy and distribute the Program (or a work based on it,
-under Section 2) in object code or executable form under the terms of
-Sections 1 and 2 above provided that you also do one of the following:
-
- a) Accompany it with the complete corresponding machine-readable
- source code, which must be distributed under the terms of Sections
- 1 and 2 above on a medium customarily used for software interchange; or,
-
- b) Accompany it with a written offer, valid for at least three
- years, to give any third party, for a charge no more than your
- cost of physically performing source distribution, a complete
- machine-readable copy of the corresponding source code, to be
- distributed under the terms of Sections 1 and 2 above on a medium
- customarily used for software interchange; or,
-
- c) Accompany it with the information you received as to the offer
- to distribute corresponding source code. (This alternative is
- allowed only for noncommercial distribution and only if you
- received the program in object code or executable form with such
- an offer, in accord with Subsection b above.)
-
-The source code for a work means the preferred form of the work for
-making modifications to it. For an executable work, complete source
-code means all the source code for all modules it contains, plus any
-associated interface definition files, plus the scripts used to
-control compilation and installation of the executable. However, as a
-special exception, the source code distributed need not include
-anything that is normally distributed (in either source or binary
-form) with the major components (compiler, kernel, and so on) of the
-operating system on which the executable runs, unless that component
-itself accompanies the executable.
-
-If distribution of executable or object code is made by offering
-access to copy from a designated place, then offering equivalent
-access to copy the source code from the same place counts as
-distribution of the source code, even though third parties are not
-compelled to copy the source along with the object code.
-
- 4. You may not copy, modify, sublicense, or distribute the Program
-except as expressly provided under this License. Any attempt
-otherwise to copy, modify, sublicense or distribute the Program is
-void, and will automatically terminate your rights under this License.
-However, parties who have received copies, or rights, from you under
-this License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
- 5. You are not required to accept this License, since you have not
-signed it. However, nothing else grants you permission to modify or
-distribute the Program or its derivative works. These actions are
-prohibited by law if you do not accept this License. Therefore, by
-modifying or distributing the Program (or any work based on the
-Program), you indicate your acceptance of this License to do so, and
-all its terms and conditions for copying, distributing or modifying
-the Program or works based on it.
-
- 6. Each time you redistribute the Program (or any work based on the
-Program), the recipient automatically receives a license from the
-original licensor to copy, distribute or modify the Program subject to
-these terms and conditions. You may not impose any further
-restrictions on the recipients' exercise of the rights granted herein.
-You are not responsible for enforcing compliance by third parties to
-this License.
-
- 7. If, as a consequence of a court judgment or allegation of patent
-infringement or for any other reason (not limited to patent issues),
-conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License. If you cannot
-distribute so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you
-may not distribute the Program at all. For example, if a patent
-license would not permit royalty-free redistribution of the Program by
-all those who receive copies directly or indirectly through you, then
-the only way you could satisfy both it and this License would be to
-refrain entirely from distribution of the Program.
-
-If any portion of this section is held invalid or unenforceable under
-any particular circumstance, the balance of the section is intended to
-apply and the section as a whole is intended to apply in other
-circumstances.
-
-It is not the purpose of this section to induce you to infringe any
-patents or other property right claims or to contest validity of any
-such claims; this section has the sole purpose of protecting the
-integrity of the free software distribution system, which is
-implemented by public license practices. Many people have made
-generous contributions to the wide range of software distributed
-through that system in reliance on consistent application of that
-system; it is up to the author/donor to decide if he or she is willing
-to distribute software through any other system and a licensee cannot
-impose that choice.
-
-This section is intended to make thoroughly clear what is believed to
-be a consequence of the rest of this License.
-
- 8. If the distribution and/or use of the Program is restricted in
-certain countries either by patents or by copyrighted interfaces, the
-original copyright holder who places the Program under this License
-may add an explicit geographical distribution limitation excluding
-those countries, so that distribution is permitted only in or among
-countries not thus excluded. In such case, this License incorporates
-the limitation as if written in the body of this License.
-
- 9. The Free Software Foundation may publish revised and/or new versions
-of the General Public 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.
-
-Each version is given a distinguishing version number. If the Program
-specifies a version number of this License which applies to it and "any
-later version", you have the option of following the terms and conditions
-either of that version or of any later version published by the Free
-Software Foundation. If the Program does not specify a version number of
-this License, you may choose any version ever published by the Free Software
-Foundation.
-
- 10. If you wish to incorporate parts of the Program into other free
-programs whose distribution conditions are different, write to the author
-to ask for permission. For software which is copyrighted by the Free
-Software Foundation, write to the Free Software Foundation; we sometimes
-make exceptions for this. Our decision will be guided by the two goals
-of preserving the free status of all derivatives of our free software and
-of promoting the sharing and reuse of software generally.
-
- NO WARRANTY
-
- 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
-FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
-OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
-PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
-OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
-TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
-PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
-REPAIR OR CORRECTION.
-
- 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
-REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
-INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
-OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
-TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
-YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
-PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGES.
-
- END OF TERMS AND CONDITIONS
-
- How to Apply These Terms to Your New Programs
-
- If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
- To do so, attach the following notices to the program. It is safest
-to attach them to the start of each source file to most effectively
-convey the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
- <one line to give the program's name and a brief idea of what it does.>
- Copyright (C) 19yy <name of author>
-
- This program 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 2 of the License, or
- (at your option) any later version.
-
- This program 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 this program; if not, write to the Free Software
- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-
-
-Also add information on how to contact you by electronic and paper mail.
-
-If the program is interactive, make it output a short notice like this
-when it starts in an interactive mode:
-
- Gnomovision version 69, Copyright (C) 19yy name of author
- Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
- This is free software, and you are welcome to redistribute it
- under certain conditions; type `show c' for details.
-
-The hypothetical commands `show w' and `show c' should show the appropriate
-parts of the General Public License. Of course, the commands you use may
-be called something other than `show w' and `show c'; they could even be
-mouse-clicks or menu items--whatever suits your program.
-
-You should also get your employer (if you work as a programmer) or your
-school, if any, to sign a "copyright disclaimer" for the program, if
-necessary. Here is a sample; alter the names:
-
- Yoyodyne, Inc., hereby disclaims all copyright interest in the program
- `Gnomovision' (which makes passes at compilers) written by James Hacker.
-
- <signature of Ty Coon>, 1 April 1989
- Ty Coon, President of Vice
-
-This General Public License does not permit incorporating your program into
-proprietary programs. If your program is a subroutine library, you may
-consider it more useful to permit linking proprietary applications with the
-library. If this is what you want to do, use the GNU Library General
-Public License instead of this License.
diff --git a/doc/example-smob/ChangeLog b/doc/example-smob/ChangeLog
deleted file mode 100644
index 5e0ea0cfa..000000000
--- a/doc/example-smob/ChangeLog
+++ /dev/null
@@ -1,48 +0,0 @@
-2002-02-28 Marius Vollmer <mvo@zagadka.ping.de>
-
- * image-type.c (image_tag): Changed type to scm_t_bits.
- (make_image): Use scm_gc_malloc instead of scm_must_malloc.
- (free_image): Use scm_gc_free instead of free. Return zero.
-
-2001-05-30 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * image-type.c: Adapted to new typing and naming convention.
-
-2001-04-26 Neil Jerram <neil@ossau.uklinux.net>
-
- * image-type.c (make_image): Don't need to use SCM_NIMP before
- SCM_STRINGP.
- (clear_image): Use SCM_SMOB_PREDICATE.
- (clear_image, mark_image, free_image, print_image): Use
- SCM_SMOB_DATA rather than SCM_CDR.
-
-2000-06-20 Mikael Djurfeldt <mdj@thalamus.nada.kth.se>
-
- * image-type.c: Removed unused scm_smobfuns structure.
- (init_image_type): Use standard smob type interface.
-
-Fri Jun 25 22:21:04 1999 Greg Badros <gjb@cs.washington.edu>
-
- * image-type.c: Updated example to use scm_make_smob_type_mfpe,
- SCM_RETURN_NEWSMOB, SCM_NEWSMOB function and macros.
-
-1998-10-19 Jim Blandy <jimb@zwingli.cygnus.com>
-
- * image-type.c, myguile.c: Terminate copyright comments.
-
- * COPYING: New file.
- * image-type.c myguile.c: Add copyright notice.
-
-1998-10-16 Jim Blandy <jimb@zwingli.cygnus.com>
-
- * Makefile (myguile): Fix link command, to put the Guile libraries
- after the object files. The old command worked on my machine, but
- I don't see how.
-
-1998-10-15 Jim Blandy <jimb@zwingli.cygnus.com>
-
- Created this directory for the Guile 1.3 release. Thanks to Jay
- Glascoe for suggesting that we provide a complete, buildable
- example!
- * ChangeLog, Makefile, README, image-type.c, image-type.h,
- myguile: New files.
diff --git a/doc/example-smob/Makefile b/doc/example-smob/Makefile
deleted file mode 100644
index 548c5ed83..000000000
--- a/doc/example-smob/Makefile
+++ /dev/null
@@ -1,12 +0,0 @@
-CFLAGS=`guile-config compile`
-LIBS=`guile-config link`
-
-O_FILES=image-type.o myguile.o
-
-all: myguile
-
-myguile: $(O_FILES)
- $(CC) $(O_FILES) $(LIBS) -o myguile
-
-clean:
- -rm -rf myguile $(O_FILES)
diff --git a/doc/example-smob/README b/doc/example-smob/README
deleted file mode 100644
index 1380db123..000000000
--- a/doc/example-smob/README
+++ /dev/null
@@ -1,6 +0,0 @@
-This is the example code for the ``Defining New Types (Smobs)''
-chapter of the Guile manual.
-
-When you try to execute the code, if the system complains that it
-can't find libguile.so, you need to add the directory containing the
-installed Guile libraries to your LD_LIBRARY_PATH environment variable.
diff --git a/doc/example-smob/image-type.c b/doc/example-smob/image-type.c
deleted file mode 100644
index 1a03c9ce2..000000000
--- a/doc/example-smob/image-type.c
+++ /dev/null
@@ -1,126 +0,0 @@
-/* image-type.c
- *
- * Copyright (C) 1998, 2000 Free Software Foundation, Inc.
- *
- * This program 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 2, or (at your option)
- * any later version.
- *
- * This program 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 this software; see the file COPYING. If not, write to
- * the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- * Boston, MA 02111-1307 USA
- */
-
-#include <stdlib.h>
-#include <libguile.h>
-
-static scm_t_bits image_tag;
-
-struct image {
- int width, height;
- char *pixels;
-
- /* The name of this image */
- SCM name;
-
- /* A function to call when this image is
- modified, e.g., to update the screen,
- or SCM_BOOL_F if no action necessary */
- SCM update_func;
-};
-
-static SCM
-make_image (SCM name, SCM s_width, SCM s_height)
-{
- struct image *image;
- int width, height;
-
- SCM_ASSERT (SCM_STRINGP (name), name, SCM_ARG1, "make-image");
- SCM_ASSERT (SCM_INUMP (s_width), s_width, SCM_ARG2, "make-image");
- SCM_ASSERT (SCM_INUMP (s_height), s_height, SCM_ARG3, "make-image");
-
- width = SCM_INUM (s_width);
- height = SCM_INUM (s_height);
-
- image = (struct image *) scm_gc_malloc (sizeof (struct image), "image");
- image->width = width;
- image->height = height;
- image->pixels = scm_gc_malloc (width * height, "image pixels");
- image->name = name;
- image->update_func = SCM_BOOL_F;
-
- SCM_RETURN_NEWSMOB (image_tag, image);
-}
-
-static SCM
-clear_image (SCM image_smob)
-{
- int area;
- struct image *image;
-
- SCM_ASSERT (SCM_SMOB_PREDICATE (image_tag, image_smob),
- image_smob, SCM_ARG1, "clear-image");
-
- image = (struct image *) SCM_SMOB_DATA (image_smob);
- area = image->width * image->height;
- memset (image->pixels, 0, area);
-
- /* Invoke the image's update function. */
- if (image->update_func != SCM_BOOL_F)
- scm_apply (image->update_func, SCM_EOL, SCM_EOL);
-
- return SCM_UNSPECIFIED;
-}
-
-static SCM
-mark_image (SCM image_smob)
-{
- /* Mark the image's name and update function. */
- struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
-
- scm_gc_mark (image->name);
- return image->update_func;
-}
-
-static size_t
-free_image (SCM image_smob)
-{
- struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
-
- scm_gc_free (image->pixels, image->width * image->height, "image pixels");
- scm_gc_free (image, sizeof (struct image), "image");
-
- return 0;
-}
-
-static int
-print_image (SCM image_smob, SCM port, scm_print_state *pstate)
-{
- struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
-
- scm_puts ("#<image ", port);
- scm_display (image->name, port);
- scm_puts (">", port);
-
- /* non-zero means success */
- return 1;
-}
-
-void
-init_image_type (void)
-{
- image_tag = scm_make_smob_type ("image", sizeof (struct image));
- scm_set_smob_mark (image_tag, mark_image);
- scm_set_smob_free (image_tag, free_image);
- scm_set_smob_print (image_tag, print_image);
-
- scm_c_define_gsubr ("clear-image", 1, 0, 0, clear_image);
- scm_c_define_gsubr ("make-image", 3, 0, 0, make_image);
-}
diff --git a/doc/example-smob/image-type.h b/doc/example-smob/image-type.h
deleted file mode 100644
index 38fcf74c4..000000000
--- a/doc/example-smob/image-type.h
+++ /dev/null
@@ -1,3 +0,0 @@
-/* file "image-type.h" */
-
-void init_image_type (void);
diff --git a/doc/example-smob/myguile.c b/doc/example-smob/myguile.c
deleted file mode 100644
index 95bff27fd..000000000
--- a/doc/example-smob/myguile.c
+++ /dev/null
@@ -1,37 +0,0 @@
-/* myguile.c
- *
- * Copyright (C) 1998 Free Software Foundation, Inc.
- *
- * This program 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 2, or (at your option)
- * any later version.
- *
- * This program 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 this software; see the file COPYING. If not, write to
- * the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- * Boston, MA 02111-1307 USA
- */
-
-#include <libguile.h>
-#include "image-type.h"
-
-static void
-inner_main (void *closure, int argc, char **argv)
-{
- /* module initializations would go here */
- init_image_type();
- scm_shell (argc, argv);
-}
-
-int
-main (int argc, char **argv)
-{
- scm_boot_guile (argc, argv, inner_main, 0);
- return 0; /* never reached */
-}
diff --git a/doc/goops/.cvsignore b/doc/goops/.cvsignore
deleted file mode 100644
index 896c69f47..000000000
--- a/doc/goops/.cvsignore
+++ /dev/null
@@ -1,22 +0,0 @@
-Makefile
-Makefile.in
-stamp-vti
-stamp-vti.1
-*.log
-*.dvi
-*.aux
-*.toc
-*.cp
-*.fn
-*.vr
-*.tp
-*.ky
-*.pg
-*.cps
-*.fns
-*.tps
-*.vrs
-*.ps
-*.info*
-*.html
-goops.tmp
diff --git a/doc/goops/ChangeLog b/doc/goops/ChangeLog
deleted file mode 100644
index 9c3cd22a9..000000000
--- a/doc/goops/ChangeLog
+++ /dev/null
@@ -1,22 +0,0 @@
-2002-04-17 Marius Vollmer <mvo@zagadka.ping.de>
-
- * Makefile.am (CLEANFILES): Added goops.tmp, goops.cps.
-
-2001-12-03 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * goops.texi: Grammar fix.
-
-2001-08-27 Neil Jerram <neil@ossau.uklinux.net>
-
- * Makefile.am (goops_TEXINFOS): Remove ../AUTHORS.
- (TEXINFO_TEX): Added; avoids shipping multiple copies of
- texinfo.tex in a single distribution.
-
- * goops.texi: Incorporate text previously in separate AUTHORS
- file.
-
-2001-08-27 Neil Jerram <neil@ossau.uklinux.net>
-
- The change log for files in this directory continues backwards
- from 2001-08-27 in ../ChangeLog, as all the Guile documentation
- prior to this date was contained in a single directory.
diff --git a/doc/goops/Makefile.am b/doc/goops/Makefile.am
deleted file mode 100644
index 3a58df577..000000000
--- a/doc/goops/Makefile.am
+++ /dev/null
@@ -1,43 +0,0 @@
-## Process this file with Automake to create Makefile.in
-##
-## Copyright (C) 1998 Free Software Foundation, Inc.
-##
-## This file is part of GUILE.
-##
-## GUILE 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 2, or
-## (at your option) any later version.
-##
-## GUILE 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 GUILE; see the file COPYING. If not, write
-## to the Free Software Foundation, Inc., 59 Temple Place, Suite
-## 330, Boston, MA 02111-1307 USA
-
-AUTOMAKE_OPTIONS = gnu
-
-info_TEXINFOS = goops.texi
-
-goops_TEXINFOS = goops-tutorial.texi hierarchy.eps hierarchy.txt
-
-TEXINFO_TEX = ../ref/texinfo.tex
-
-# Optionally support building an HTML version of the manual.
-
-if HTMLDOC
-
-htmldir = $(prefix)/html/guile-$(VERSION)
-
-html_DATA = goops_toc.html $(shell ls goops_*.html 2>/dev/null)
-
-goops_toc.html: goops.texi $(goops_TEXINFOS)
- $(TEXI2HTML) -split_chapter goops.texi
-
-endif
-
-CLEANFILES = goops.tmp goops.cps
diff --git a/doc/goops/goops-tutorial.texi b/doc/goops/goops-tutorial.texi
deleted file mode 100644
index 7ab6ebcf0..000000000
--- a/doc/goops/goops-tutorial.texi
+++ /dev/null
@@ -1,810 +0,0 @@
-@c Original attribution:
-
-@c
-@c STk Reference manual (Appendix: An Introduction to STklos)
-@c
-@c Copyright © 1993-1999 Erick Gallesio - I3S-CNRS/ESSI <eg@unice.fr>
-@c Permission to use, copy, modify, distribute,and license this
-@c software and its documentation for any purpose is hereby granted,
-@c provided that existing copyright notices are retained in all
-@c copies and that this notice is included verbatim in any
-@c distributions. No written agreement, license, or royalty fee is
-@c required for any of the authorized uses.
-@c This software is provided ``AS IS'' without express or implied
-@c warranty.
-@c
-
-@c Adapted for use in Guile with the authors permission
-
-@c @macro goops @c was {\stklos}
-@c GOOPS
-@c @end macro
-
-@c @macro guile @c was {\stk}
-@c Guile
-@c @end macro
-
-This is chapter was originally written by Erick Gallesio as an appendix
-for the STk reference manual, and subsequently adapted to @goops{}.
-
-@menu
-* Copyright::
-* Intro::
-* Class definition and instantiation::
-* Inheritance::
-* Generic functions::
-@end menu
-
-@node Copyright, Intro, Tutorial, Tutorial
-@section Copyright
-
-Original attribution:
-
-STk Reference manual (Appendix: An Introduction to STklos)
-
-Copyright © 1993-1999 Erick Gallesio - I3S-CNRS/ESSI <eg@@unice.fr>
-Permission to use, copy, modify, distribute,and license this
-software and its documentation for any purpose is hereby granted,
-provided that existing copyright notices are retained in all
-copies and that this notice is included verbatim in any
-distributions. No written agreement, license, or royalty fee is
-required for any of the authorized uses.
-This software is provided ``AS IS'' without express or implied
-warranty.
-
-Adapted for use in Guile with the authors permission
-
-@node Intro, Class definition and instantiation, Copyright, Tutorial
-@section Introduction
-
-@goops{} is the object oriented extension to @guile{}. Its
-implementation is derived from @w{STk-3.99.3} by Erick Gallesio and
-version 1.3 of the Gregor Kiczales @cite{Tiny-Clos}. It is very close
-to CLOS, the Common Lisp Object System (@cite{CLtL2}) but is adapted for
-the Scheme language.
-
-Briefly stated, the @goops{} extension gives the user a full object
-oriented system with multiple inheritance and generic functions with
-multi-method dispatch. Furthermore, the implementation relies on a true
-meta object protocol, in the spirit of the one defined for CLOS
-(@cite{Gregor Kiczales: A Metaobject Protocol}).
-
-The purpose of this tutorial is to introduce briefly the @goops{}
-package and in no case will it replace the @goops{} reference manual
-(which needs to be urgently written now@ @dots{}).
-
-Note that the operations described in this tutorial resides in modules
-that may need to be imported before being available. The main module is
-imported by evaluating:
-
-@lisp
-(use-modules (oop goops))
-@end lisp
-@findex (oop goops)
-@cindex main module
-@cindex loading
-@cindex preparing
-
-@node Class definition and instantiation, Inheritance, Intro, Tutorial
-@section Class definition and instantiation
-
-@menu
-* Class definition::
-@end menu
-
-@node Class definition, , Class definition and instantiation, Class definition and instantiation
-@subsection Class definition
-
-A new class is defined with the @code{define-class}@footnote{Don't
-forget to import the @code{(oop goops)} module} macro. The syntax of
-@code{define-class} is close to CLOS @code{defclass}:
-
-@findex define-class
-@cindex class
-@lisp
-(define-class @var{class} (@var{superclass} @dots{})
- @var{slot-description} @dots{}
- @var{class-option} @dots{})
-@end lisp
-
-Class options will not be discussed in this tutorial. The list of
-@var{superclass}es specifies which classes to inherit properties from
-@var{class} (see @ref{Inheritance} for more details). A
-@var{slot-description} gives the name of a slot and, eventually, some
-``properties'' of this slot (such as its initial value, the function
-which permit to access its value, @dots{}). Slot descriptions will be
-discussed in @ref{Slot description}.
-@cindex slot
-
-As an example, let us define a type for representation of complex
-numbers in terms of real numbers. This can be done with the following
-class definition:
-
-@lisp
-(define-class <complex> (<number>)
- r i)
-@end lisp
-
-This binds the variable @code{<complex>}@footnote{@code{<complex>} is in
-fact a builtin class in GOOPS. Because of this, GOOPS will create a new
-class. The old class will still serve as the type for Guile's native
-complex numbers.} to a new class whose instances contain two
-slots. These slots are called @code{r} an @code{i} and we suppose here
-that they contain respectively the real part and the imaginary part of a
-complex number. Note that this class inherits from @code{<number>} which
-is a pre-defined class. (@code{<number>} is the direct super class of
-the pre-defined class @code{<complex>} which, in turn, is the super
-class of @code{<real>} which is the super of
-@code{<integer>}.)@footnote{With the new definition of @code{<complex>},
-a @code{<real>} is not a @code{<complex>} since @code{<real>} inherits
-from @code{ <number>} rather than @code{<complex>}. In practice,
-inheritance could be modified @emph{a posteriori}, if needed. However,
-this necessitates some knowledge of the meta object protocol and it will
-not be shown in this document}.
-
-@node Inheritance, Generic functions, Class definition and instantiation, Tutorial
-@section Inheritance
-@c \label{inheritance}
-
-@menu
-* Class hierarchy and inheritance of slots::
-* Instance creation and slot access::
-* Slot description::
-* Class precedence list::
-@end menu
-
-@node Class hierarchy and inheritance of slots, Instance creation and slot access, Inheritance, Inheritance
-@subsection Class hierarchy and inheritance of slots
-Inheritance is specified upon class definition. As said in the
-introduction, @goops{} supports multiple inheritance. Here are some
-class definitions:
-
-@lisp
-(define-class A () a)
-(define-class B () b)
-(define-class C () c)
-(define-class D (A B) d a)
-(define-class E (A C) e c)
-(define-class F (D E) f)
-@end lisp
-
-@code{A}, @code{B}, @code{C} have a null list of super classes. In this
-case, the system will replace it by the list which only contains
-@code{<object>}, the root of all the classes defined by
-@code{define-class}. @code{D}, @code{E}, @code{F} use multiple
-inheritance: each class inherits from two previously defined classes.
-Those class definitions define a hierarchy which is shown in Figure@ 1.
-In this figure, the class @code{<top>} is also shown; this class is the
-super class of all Scheme objects. In particular, @code{<top>} is the
-super class of all standard Scheme types.
-
-@example
-@group
-@image{hierarchy}
-@center @emph{Fig 1: A class hierarchy}
-@iftex
-@emph{(@code{<complex>} which is the direct subclass of @code{<number>}
-and the direct superclass of @code{<real>} has been omitted in this
-figure.)}
-@end iftex
-@end group
-@end example
-
-The set of slots of a given class is calculated by taking the union of the
-slots of all its super class. For instance, each instance of the class
-D, defined before will have three slots (@code{a}, @code{b} and
-@code{d}). The slots of a class can be obtained by the @code{class-slots}
-primitive. For instance,
-
-@lisp
-(class-slots A) @result{} ((a))
-(class-slots E) @result{} ((a) (e) (c))
-(class-slots F) @result{} ((e) (c) (b) (d) (a) (f))
-@c used to be ((d) (a) (b) (c) (f))
-@end lisp
-
-@emph{Note: } The order of slots is not significant.
-
-@node Instance creation and slot access, Slot description, Class hierarchy and inheritance of slots, Inheritance
-@subsection Instance creation and slot access
-
-Creation of an instance of a previously defined
-class can be done with the @code{make} procedure. This
-procedure takes one mandatory parameter which is the class of the
-instance which must be created and a list of optional
-arguments. Optional arguments are generally used to initialize some
-slots of the newly created instance. For instance, the following form
-
-@findex make
-@cindex instance
-@lisp
-(define c (make <complex>))
-@end lisp
-
-will create a new @code{<complex>} object and will bind it to the @code{c}
-Scheme variable.
-
-Accessing the slots of the new complex number can be done with the
-@code{slot-ref} and the @code{slot-set!} primitives. @code{Slot-set!}
-primitive permits to set the value of an object slot and @code{slot-ref}
-permits to get its value.
-
-@findex slot-set!
-@findex slot-ref
-@lisp
-@group
-(slot-set! c 'r 10)
-(slot-set! c 'i 3)
-(slot-ref c 'r) @result{} 10
-(slot-ref c 'i) @result{} 3
-@end group
-@end lisp
-
-Using the @code{describe} function is a simple way to see all the
-slots of an object at one time: this function prints all the slots of an
-object on the standard output.
-
-First load the module @code{(oop goops describe)}:
-
-@example
-@code{(use-modules (oop goops describe))}
-@end example
-
-The expression
-
-@smalllisp
-(describe c)
-@end smalllisp
-
-will now print the following information on the standard output:
-
-@lisp
-#<<complex> 401d8638> is an instance of class <complex>
-Slots are:
- r = 10
- i = 3
-@end lisp
-
-@node Slot description, Class precedence list, Instance creation and slot access, Inheritance
-@subsection Slot description
-@c \label{slot-description}
-
-When specifying a slot, a set of options can be given to the
-system. Each option is specified with a keyword. The list of authorized
-keywords is given below:
-
-@cindex keyword
-@itemize @bullet
-@item
-@code{#:init-value} permits to supply a default value for the slot. This
-default value is obtained by evaluating the form given after the
-@code{#:init-form} in the global environment, at class definition time.
-@cindex default slot value
-@findex #:init-value
-@cindex top level environment
-
-@item
-@code{#:init-thunk} permits to supply a thunk that will provide a
-default value for the slot. The value is obtained by evaluating the
-thunk a instance creation time.
-@c CHECKME: in the global environment?
-@findex default slot value
-@findex #:init-thunk
-@cindex top level environment
-
-@item
-@code{#:init-keyword} permits to specify the keyword for initializing a
-slot. The init-keyword may be provided during instance creation (i.e. in
-the @code{make} optional parameter list). Specifying such a keyword
-during instance initialization will supersede the default slot
-initialization possibly given with @code{#:init-form}.
-@findex #:init-keyword
-
-@item
-@code{#:getter} permits to supply the name for the
-slot getter. The name binding is done in the
-environment of the @code{define-class} macro.
-@findex #:getter
-@cindex top level environment
-@cindex getter
-
-@item
-@code{#:setter} permits to supply the name for the
-slot setter. The name binding is done in the
-environment of the @code{define-class} macro.
-@findex #:setter
-@cindex top level environment
-@cindex setter
-
-@item
-@code{#:accessor} permits to supply the name for the
-slot accessor. The name binding is done in the global
-environment. An accessor permits to get and
-set the value of a slot. Setting the value of a slot is done with the extended
-version of @code{set!}.
-@findex set!
-@findex #:accessor
-@cindex top level environment
-@cindex accessor
-
-@item
-@code{#:allocation} permits to specify how storage for
-the slot is allocated. Three kinds of allocation are provided.
-They are described below:
-
-@itemize @minus
-@item
-@code{#:instance} indicates that each instance gets its own storage for
-the slot. This is the default.
-@item
-@code{#:class} indicates that there is one storage location used by all
-the direct and indirect instances of the class. This permits to define a
-kind of global variable which can be accessed only by (in)direct
-instances of the class which defines this slot.
-@item
-@code{#:each-subclass} indicates that there is one storage location used
-by all the direct instances of the class. In other words, if two classes
-are not siblings in the class hierarchy, they will not see the same
-value.
-@item
-@code{#:virtual} indicates that no storage will be allocated for this
-slot. It is up to the user to define a getter and a setter function for
-this slot. Those functions must be defined with the @code{#:slot-ref}
-and @code{#:slot-set!} options. See the example below.
-@findex #:slot-set!
-@findex #:slot-ref
-@findex #:virtual
-@findex #:class
-@findex #:each-subclass
-@findex #:instance
-@findex #:allocation
-@end itemize
-@end itemize
-
-To illustrate slot description, we shall redefine the @code{<complex>} class
-seen before. A definition could be:
-
-@lisp
-(define-class <complex> (<number>)
- (r #:init-value 0 #:getter get-r #:setter set-r! #:init-keyword #:r)
- (i #:init-value 0 #:getter get-i #:setter set-i! #:init-keyword #:i))
-@end lisp
-
-With this definition, the @code{r} and @code{i} slot are set to 0 by
-default. Value of a slot can also be specified by calling @code{make}
-with the @code{#:r} and @code{#:i} keywords. Furthermore, the generic
-functions @code{get-r} and @code{set-r!} (resp. @code{get-i} and
-@code{set-i!}) are automatically defined by the system to read and write
-the @code{r} (resp. @code{i}) slot.
-
-@lisp
-(define c1 (make <complex> #:r 1 #:i 2))
-(get-r c1) @result{} 1
-(set-r! c1 12)
-(get-r c1) @result{} 12
-(define c2 (make <complex> #:r 2))
-(get-r c2) @result{} 2
-(get-i c2) @result{} 0
-@end lisp
-
-Accessors provide an uniform access for reading and writing an object
-slot. Writing a slot is done with an extended form of @code{set!}
-which is close to the Common Lisp @code{setf} macro. So, another
-definition of the previous @code{<complex>} class, using the
-@code{#:accessor} option, could be:
-
-@findex set!
-@lisp
-(define-class <complex> (<number>)
- (r #:init-value 0 #:accessor real-part #:init-keyword #:r)
- (i #:init-value 0 #:accessor imag-part #:init-keyword #:i))
-@end lisp
-
-Using this class definition, reading the real part of the @code{c}
-complex can be done with:
-@lisp
-(real-part c)
-@end lisp
-and setting it to the value contained in the @code{new-value} variable
-can be done using the extended form of @code{set!}.
-@lisp
-(set! (real-part c) new-value)
-@end lisp
-
-Suppose now that we have to manipulate complex numbers with rectangular
-coordinates as well as with polar coordinates. One solution could be to
-have a definition of complex numbers which uses one particular
-representation and some conversion functions to pass from one
-representation to the other. A better solution uses virtual slots. A
-complete definition of the @code{<complex>} class using virtual slots is
-given in Figure@ 2.
-
-@example
-@group
-@lisp
-(define-class <complex> (<number>)
- ;; True slots use rectangular coordinates
- (r #:init-value 0 #:accessor real-part #:init-keyword #:r)
- (i #:init-value 0 #:accessor imag-part #:init-keyword #:i)
- ;; Virtual slots access do the conversion
- (m #:accessor magnitude #:init-keyword #:magn
- #:allocation #:virtual
- #:slot-ref (lambda (o)
- (let ((r (slot-ref o 'r)) (i (slot-ref o 'i)))
- (sqrt (+ (* r r) (* i i)))))
- #:slot-set! (lambda (o m)
- (let ((a (slot-ref o 'a)))
- (slot-set! o 'r (* m (cos a)))
- (slot-set! o 'i (* m (sin a))))))
- (a #:accessor angle #:init-keyword #:angle
- #:allocation #:virtual
- #:slot-ref (lambda (o)
- (atan (slot-ref o 'i) (slot-ref o 'r)))
- #:slot-set! (lambda(o a)
- (let ((m (slot-ref o 'm)))
- (slot-set! o 'r (* m (cos a)))
- (slot-set! o 'i (* m (sin a)))))))
-
-@end lisp
-@center @emph{Fig 2: A @code{<complex>} number class definition using virtual slots}
-@end group
-@end example
-
-@sp 3
-This class definition implements two real slots (@code{r} and
-@code{i}). Values of the @code{m} and @code{a} virtual slots are
-calculated from real slot values. Reading a virtual slot leads to the
-application of the function defined in the @code{#:slot-ref}
-option. Writing such a slot leads to the application of the function
-defined in the @code{#:slot-set!} option. For instance, the following
-expression
-
-@findex #:slot-set!
-@findex #:slot-ref
-@lisp
-(slot-set! c 'a 3)
-@end lisp
-
-permits to set the angle of the @code{c} complex number. This expression
-conducts, in fact, to the evaluation of the following expression
-
-@lisp
-((lambda o m)
- (let ((m (slot-ref o 'm)))
- (slot-set! o 'r (* m (cos a)))
- (slot-set! o 'i (* m (sin a))))
- c 3)
-@end lisp
-
-A more complete example is given below:
-
-@example
-@group
-@lisp
-(define c (make <complex> #:r 12 #:i 20))
-(real-part c) @result{} 12
-(angle c) @result{} 1.03037682652431
-(slot-set! c 'i 10)
-(set! (real-part c) 1)
-(describe c) @result{}
- #<<complex> 401e9b58> is an instance of class <complex>
- Slots are:
- r = 1
- i = 10
- m = 10.0498756211209
- a = 1.47112767430373
-@end lisp
-@end group
-@end example
-
-Since initialization keywords have been defined for the four slots, we
-can now define the @code{make-rectangular} and @code{make-polar} standard
-Scheme primitives.
-
-@lisp
-(define make-rectangular
- (lambda (x y) (make <complex> #:r x #:i y)))
-
-(define make-polar
- (lambda (x y) (make <complex> #:magn x #:angle y)))
-@end lisp
-
-@node Class precedence list, , Slot description, Inheritance
-@subsection Class precedence list
-
-A class may have more than one superclass. @footnote{This section is an
-adaptation of Jeff Dalton's (J.Dalton@@ed.ac.uk) @cite{Brief
-introduction to CLOS}} With single inheritance (one superclass), it is
-easy to order the super classes from most to least specific. This is the
-rule:
-
-@display
-@cartouche
-Rule 1: Each class is more specific than its superclasses.@c was \bf
-@end cartouche
-@end display
-
-With multiple inheritance, ordering is harder. Suppose we have
-
-@lisp
-(define-class X ()
- (x #:init-value 1))
-
-(define-class Y ()
- (x #:init-value 2))
-
-(define-class Z (X Y)
- (@dots{}))
-@end lisp
-
-In this case, the @code{Z} class is more specific than the @code{X} or
-@code{Y} class for instances of @code{Z}. However, the @code{#:init-value}
-specified in @code{X} and @code{Y} leads to a problem: which one
-overrides the other? The rule in @goops{}, as in CLOS, is that the
-superclasses listed earlier are more specific than those listed later.
-So:
-
-@display
-@cartouche
-Rule 2: For a given class, superclasses listed earlier are more
- specific than those listed later.
-@end cartouche
-@end display
-
-These rules are used to compute a linear order for a class and all its
-superclasses, from most specific to least specific. This order is
-called the ``class precedence list'' of the class. Given these two
-rules, we can claim that the initial form for the @code{x} slot of
-previous example is 1 since the class @code{X} is placed before @code{Y}
-in class precedence list of @code{Z}.
-
-These two rules are not always enough to determine a unique order,
-however, but they give an idea of how things work. Taking the @code{F}
-class shown in Figure@ 1, the class precedence list is
-
-@example
-(f d e a c b <object> <top>)
-@end example
-
-However, it is usually considered a bad idea for programmers to rely on
-exactly what the order is. If the order for some superclasses is important,
-it can be expressed directly in the class definition.
-
-The precedence list of a class can be obtained by the function
-@code{class-precedence-list}. This function returns a ordered
-list whose first element is the most specific class. For instance,
-
-@lisp
-(class-precedence-list B) @result{} (#<<class> B 401b97c8>
- #<<class> <object> 401e4a10>
- #<<class> <top> 4026a9d8>)
-@end lisp
-
-However, this result is not too much readable; using the function
-@code{class-name} yields a clearer result:
-
-@lisp
-(map class-name (class-precedence-list B)) @result{} (B <object> <top>)
-@end lisp
-
-@node Generic functions, , Inheritance, Tutorial
-@section Generic functions
-
-@menu
-* Generic functions and methods::
-* Next-method::
-* Example::
-@end menu
-
-@node Generic functions and methods, Next-method, Generic functions, Generic functions
-@subsection Generic functions and methods
-
-@c \label{gf-n-methods}
-Neither @goops{} nor CLOS use the message mechanism for methods as most
-Object Oriented language do. Instead, they use the notion of
-@dfn{generic functions}. A generic function can be seen as a methods
-``tanker''. When the evaluator requested the application of a generic
-function, all the methods of this generic function will be grabbed and
-the most specific among them will be applied. We say that a method
-@var{M} is @emph{more specific} than a method @var{M'} if the class of
-its parameters are more specific than the @var{M'} ones. To be more
-precise, when a generic function must be ``called'' the system will:
-
-@cindex generic function
-@enumerate
-@item
-search among all the generic function those which are applicable
-@item
-sort the list of applicable methods in the ``most specific'' order
-@item
-call the most specific method of this list (i.e. the first method of
-the sorted methods list).
-@end enumerate
-
-The definition of a generic function is done with the
-@code{define-generic} macro. Definition of a new method is done with the
-@code{define-method} macro. Note that @code{define-method} automatically
-defines the generic function if it has not been defined
-before. Consequently, most of the time, the @code{define-generic} needs
-not be used.
-@findex define-generic
-@findex define-method
-Consider the following definitions:
-
-@lisp
-(define-generic G)
-(define-method (G (a <integer>) b) 'integer)
-(define-method (G (a <real>) b) 'real)
-(define-method (G a b) 'top)
-@end lisp
-
-The @code{define-generic} call defines @var{G} as a generic
-function. Note that the signature of the generic function is not given
-upon definition, contrarily to CLOS. This will permit methods with
-different signatures for a given generic function, as we shall see
-later. The three next lines define methods for the @var{G} generic
-function. Each method uses a sequence of @dfn{parameter specializers}
-that specify when the given method is applicable. A specializer permits
-to indicate the class a parameter must belong to (directly or
-indirectly) to be applicable. If no specializer is given, the system
-defaults it to @code{<top>}. Thus, the first method definition is
-equivalent to
-
-@cindex parameter specializers
-@lisp
-(define-method (G (a <integer>) (b <top>)) 'integer)
-@end lisp
-
-Now, let us look at some possible calls to generic function @var{G}:
-
-@lisp
-(G 2 3) @result{} integer
-(G 2 #t) @result{} integer
-(G 1.2 'a) @result{} real
-@c (G #3 'a) @result{} real @c was {\sharpsign}
-(G #t #f) @result{} top
-(G 1 2 3) @result{} error (since no method exists for 3 parameters)
-@end lisp
-
-The preceding methods use only one specializer per parameter list. Of
-course, each parameter can use a specializer. In this case, the
-parameter list is scanned from left to right to determine the
-applicability of a method. Suppose we declare now
-
-@lisp
-(define-method (G (a <integer>) (b <number>)) 'integer-number)
-(define-method (G (a <integer>) (b <real>)) 'integer-real)
-(define-method (G (a <integer>) (b <integer>)) 'integer-integer)
-(define-method (G a (b <number>)) 'top-number)
-@end lisp
-
-In this case,
-
-@lisp
-(G 1 2) @result{} integer-integer
-(G 1 1.0) @result{} integer-real
-(G 1 #t) @result{} integer
-(G 'a 1) @result{} top-number
-@end lisp
-
-@node Next-method, Example, Generic functions and methods, Generic functions
-@subsection Next-method
-
-When a generic function is called, the list of applicable methods is
-built. As mentioned before, the most specific method of this list is
-applied (see@ @ref{Generic functions and methods}). This method may call
-the next method in the list of applicable methods. This is done by using
-the special form @code{next-method}. Consider the following definitions
-
-@lisp
-(define-method (Test (a <integer>)) (cons 'integer (next-method)))
-(define-method (Test (a <number>)) (cons 'number (next-method)))
-(define-method (Test a) (list 'top))
-@end lisp
-
-With those definitions,
-
-@lisp
-(Test 1) @result{} (integer number top)
-(Test 1.0) @result{} (number top)
-(Test #t) @result{} (top)
-@end lisp
-
-@node Example, , Next-method, Generic functions
-@subsection Example
-
-In this section we shall continue to define operations on the @code{<complex>}
-class defined in Figure@ 2. Suppose that we want to use it to implement
-complex numbers completely. For instance a definition for the addition of
-two complexes could be
-
-@lisp
-(define-method (new-+ (a <complex>) (b <complex>))
- (make-rectangular (+ (real-part a) (real-part b))
- (+ (imag-part a) (imag-part b))))
-@end lisp
-
-To be sure that the @code{+} used in the method @code{new-+} is the standard
-addition we can do:
-
-@lisp
-(define-generic new-+)
-
-(let ((+ +))
- (define-method (new-+ (a <complex>) (b <complex>))
- (make-rectangular (+ (real-part a) (real-part b))
- (+ (imag-part a) (imag-part b)))))
-@end lisp
-
-The @code{define-generic} ensures here that @code{new-+} will be defined
-in the global environment. Once this is done, we can add methods to the
-generic function @code{new-+} which make a closure on the @code{+}
-symbol. A complete writing of the @code{new-+} methods is shown in
-Figure@ 3.
-
-@example
-@group
-@lisp
-(define-generic new-+)
-
-(let ((+ +))
-
- (define-method (new-+ (a <real>) (b <real>)) (+ a b))
-
- (define-method (new-+ (a <real>) (b <complex>))
- (make-rectangular (+ a (real-part b)) (imag-part b)))
-
- (define-method (new-+ (a <complex>) (b <real>))
- (make-rectangular (+ (real-part a) b) (imag-part a)))
-
- (define-method (new-+ (a <complex>) (b <complex>))
- (make-rectangular (+ (real-part a) (real-part b))
- (+ (imag-part a) (imag-part b))))
-
- (define-method (new-+ (a <number>)) a)
-
- (define-method (new-+) 0)
-
- (define-method (new-+ . args)
- (new-+ (car args)
- (apply new-+ (cdr args)))))
-
-(set! + new-+)
-@end lisp
-
-@center @emph{Fig 3: Extending @code{+} for dealing with complex numbers}
-@end group
-@end example
-
-@sp 3
-We use here the fact that generic function are not obliged to have the
-same number of parameters, contrarily to CLOS. The four first methods
-implement the dyadic addition. The fifth method says that the addition
-of a single element is this element itself. The sixth method says that
-using the addition with no parameter always return 0. The last method
-takes an arbitrary number of parameters@footnote{The parameter list for
-a @code{define-method} follows the conventions used for Scheme
-procedures. In particular it can use the dot notation or a symbol to
-denote an arbitrary number of parameters}. This method acts as a kind
-of @code{reduce}: it calls the dyadic addition on the @emph{car} of the
-list and on the result of applying it on its rest. To finish, the
-@code{set!} permits to redefine the @code{+} symbol to our extended
-addition.
-
-@sp 3
-To terminate our implementation (integration?) of complex numbers, we can
-redefine standard Scheme predicates in the following manner:
-
-@lisp
-(define-method (complex? c <complex>) #t)
-(define-method (complex? c) #f)
-
-(define-method (number? n <number>) #t)
-(define-method (number? n) #f)
-@dots{}
-@dots{}
-@end lisp
-
-Standard primitives in which complex numbers are involved could also be
-redefined in the same manner.
-
diff --git a/doc/goops/goops.texi b/doc/goops/goops.texi
deleted file mode 100644
index 230bd3eb2..000000000
--- a/doc/goops/goops.texi
+++ /dev/null
@@ -1,2803 +0,0 @@
-\input texinfo
-@c -*-texinfo-*-
-@c %**start of header
-@setfilename goops.info
-@settitle Goops Manual
-@set goops
-@setchapternewpage odd
-@paragraphindent 0
-@c %**end of header
-
-@set VERSION 0.3
-
-@dircategory The Algorithmic Language Scheme
-@direntry
-* GOOPS: (goops). The GOOPS reference manual.
-@end direntry
-
-@macro goops
-GOOPS
-@end macro
-
-@macro guile
-Guile
-@end macro
-
-@ifinfo
-This file documents GOOPS, an object oriented extension for Guile.
-
-Copyright (C) 1999, 2000, 2001 Free Software Foundation
-
-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.
-
-@end ifinfo
-
-@c This title page illustrates only one of the
-@c two methods of forming a title page.
-
-@titlepage
-@title Goops Manual
-@subtitle For use with GOOPS @value{VERSION}
-
-@c AUTHORS
-
-@c The GOOPS tutorial was written by Christian Lynbech and Mikael
-@c Djurfeldt, who also wrote GOOPS itself. The GOOPS reference manual
-@c and MOP documentation were written by Neil Jerram and reviewed by
-@c Mikael Djurfeldt.
-
-@author Christian Lynbech
-@author @email{chl@@tbit.dk}
-@author
-@author Mikael Djurfeldt
-@author @email{djurfeldt@@nada.kth.se}
-@author
-@author Neil Jerram
-@author @email{neil@@ossau.uklinux.net}
-
-@c The following two commands
-@c start the copyright page.
-@page
-@vskip 0pt plus 1filll
-Copyright @copyright{} 1999 Free Software Foundation
-
-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.
-
-@end titlepage
-
-@node Top, Introduction, (dir), (dir)
-
-@menu
-[When the manual is completed, this will be a flat index in the style of
- the Emacs manual. More nodes will turn up under parts I-III.]
-
-Part I: Preliminaries
-
-* Introduction::
-* Getting Started::
-
-Part II: Reference Manual
-
-* Reference Manual::
-
-Part III: GOOPS Meta Object Protocol
-
-* MOP Specification::
-
-The GOOPS tutorial
-
-* Tutorial::
-
-* Index::
-* Concept Index::
-* Function and Variable Index::
-@end menu
-
-@iftex
-@chapter Preliminaries
-@end iftex
-
-@node Introduction, Getting Started, Top, Top
-@section Introduction
-
-@goops{} is the object oriented extension to @guile{}. Its
-implementation is derived from @w{STk-3.99.3} by Erick Gallesio and
-version 1.3 of Gregor Kiczales @cite{Tiny-Clos}. It is very close in
-spirit to CLOS, the Common Lisp Object System (@cite{CLtL2}) but is
-adapted for the Scheme language. While GOOPS is not compatible with any
-of these systems, GOOPS contains a compatibility module which allows for
-execution of STKlos programs.
-
-Briefly stated, the @goops{} extension gives the user a full object
-oriented system with multiple inheritance and generic functions with
-multi-method dispatch. Furthermore, the implementation relies on a true
-meta object protocol, in the spirit of the one defined for CLOS
-(@cite{Gregor Kiczales: A Metaobject Protocol}).
-
-@node Getting Started, Reference Manual, Introduction, Top
-@section Getting Started
-
-@menu
-* Running GOOPS::
-
-Examples of some basic GOOPS functionality.
-
-* Methods::
-* User-defined types::
-* Asking for the type of an object::
-
-See further in the GOOPS tutorial available in this distribution in
-info (goops.info) and texinfo format.
-@end menu
-
-@node Running GOOPS, Methods, Getting Started, Getting Started
-@subsection Running GOOPS
-
-@enumerate
-@item
-Type
-
-@smalllisp
-guile-oops
-@end smalllisp
-
-You should now be at the Guile prompt ("guile> ").
-
-@item
-Type
-
-@smalllisp
-(use-modules (oop goops))
-@end smalllisp
-
-to load GOOPS. (If your system supports dynamic loading, you
-should be able to do this not only from `guile-oops' but from an
-arbitrary Guile interpreter.)
-@end enumerate
-
-We're now ready to try some basic GOOPS functionality.
-
-@node Methods, User-defined types, Running GOOPS, Getting Started
-@subsection Methods
-
-@smalllisp
-@group
-(define-method (+ (x <string>) (y <string>))
- (string-append x y))
-
-(+ 1 2) --> 3
-(+ "abc" "de") --> "abcde"
-@end group
-@end smalllisp
-
-@node User-defined types, Asking for the type of an object, Methods, Getting Started
-@subsection User-defined types
-
-@smalllisp
-(define-class <2D-vector> ()
- (x #:init-value 0 #:accessor x-component #:init-keyword #:x)
- (y #:init-value 0 #:accessor y-component #:init-keyword #:y))
-
-@group
-(use-modules (ice-9 format))
-
-(define-method (write (obj <2D-vector>) port)
- (display (format #f "<~S, ~S>" (x-component obj) (y-component obj))
- port))
-
-(define v (make <2D-vector> #:x 3 #:y 4))
-
-v --> <3, 4>
-@end group
-
-@group
-(define-method (+ (x <2D-vector>) (y <2D-vector>))
- (make <2D-vector>
- #:x (+ (x-component x) (x-component y))
- #:y (+ (y-component x) (y-component y))))
-
-(+ v v) --> <6, 8>
-@end group
-@end smalllisp
-
-@node Asking for the type of an object, , User-defined types, Getting Started
-@subsection Types
-
-@example
-(class-of v) --> #<<class> <2D-vector> 40241ac0>
-<2D-vector> --> #<<class> <2D-vector> 40241ac0>
-(class-of 1) --> #<<class> <integer> 401b2a98>
-<integer> --> #<<class> <integer> 401b2a98>
-
-(is-a? v <2D-vector>) --> #t
-@end example
-
-@node Reference Manual, MOP Specification, Getting Started, Top
-@chapter Reference Manual
-
-This chapter is the GOOPS reference manual. It aims to describe all the
-syntax, procedures, options and associated concepts that a typical
-application author would need to understand in order to use GOOPS
-effectively in their application. It also describes what is meant by
-the GOOPS ``metaobject protocol'' (aka ``MOP''), and indicates how
-authors can use the metaobject protocol to customize the behaviour of
-GOOPS itself.
-
-For a detailed specification of the GOOPS metaobject protocol, see
-@ref{MOP Specification}.
-
-@menu
-* Introductory Remarks::
-* Defining New Classes::
-* Creating Instances::
-* Accessing Slots::
-* Creating Generic Functions::
-* Adding Methods to Generic Functions::
-* Invoking Generic Functions::
-* Redefining a Class::
-* Changing the Class of an Instance::
-* Introspection::
-* Miscellaneous Functions::
-@end menu
-
-@node Introductory Remarks
-@section Introductory Remarks
-
-GOOPS is an object-oriented programming system based on a ``metaobject
-protocol'' derived from the ones used in CLOS (the Common Lisp Object
-System), tiny-clos (a small Scheme implementation of a subset of CLOS
-functionality) and STKlos.
-
-GOOPS can be used by application authors at a basic level without any
-need to understand what the metaobject protocol (aka ``MOP'') is and how
-it works. On the other hand, the MOP underlies even the customizations
-that application authors are likely to make use of very quickly --- such
-as defining an @code{initialize} method to customize the initialization
-of instances of an application-defined class --- and an understanding of
-the MOP makes it much easier to explain such customizations in a precise
-way. And in the long run, understanding the MOP is the key both to
-understanding GOOPS at a deeper level and to taking full advantage of
-GOOPS' power, by customizing the behaviour of GOOPS itself.
-
-Each of the following sections of the reference manual is arranged
-such that the most basic usage is introduced first, and then subsequent
-subsections discuss the related internal functions and metaobject
-protocols, finishing with a description of how to customize that area of
-functionality.
-
-These introductory remarks continue with a few words about metaobjects
-and the MOP. Readers who do not want to be bothered yet with the MOP
-and customization could safely skip this subsection on a first reading,
-and should correspondingly skip subsequent subsections that are
-concerned with internals and customization.
-
-In general, this reference manual assumes familiarity with standard
-object oriented concepts and terminology. However, some of the terms
-used in GOOPS are less well known, so the Terminology subsection
-provides definitions for these terms.
-
-@menu
-* Metaobjects and the Metaobject Protocol::
-* Terminology::
-@end menu
-
-@node Metaobjects and the Metaobject Protocol
-@subsection Metaobjects and the Metaobject Protocol
-
-The conceptual building blocks of GOOPS are classes, slot definitions,
-instances, generic functions and methods. A class is a grouping of
-inheritance relations and slot definitions. An instance is an object
-with slots that are allocated following the rules implied by its class's
-superclasses and slot definitions. A generic function is a collection
-of methods and rules for determining which of those methods to apply
-when the generic function is invoked. A method is a procedure and a set
-of specializers that specify the type of arguments to which the
-procedure is applicable.
-
-Of these entities, GOOPS represents classes, generic functions and
-methods as ``metaobjects''. In other words, the values in a GOOPS
-program that describe classes, generic functions and methods, are
-themselves instances (or ``objects'') of special GOOPS classes that
-encapsulate the behaviour, respectively, of classes, generic functions,
-and methods.
-
-(The other two entities are slot definitions and instances. Slot
-definitions are not strictly instances, but every slot definition is
-associated with a GOOPS class that specifies the behaviour of the slot
-as regards accessibility and protection from garbage collection.
-Instances are of course objects in the usual sense, and there is no
-benefit from thinking of them as metaobjects.)
-
-The ``metaobject protocol'' (aka ``MOP'') is the specification of the
-generic functions which determine the behaviour of these metaobjects and
-the circumstances in which these generic functions are invoked.
-
-For a concrete example of what this means, consider how GOOPS calculates
-the set of slots for a class that is being defined using
-@code{define-class}. The desired set of slots is the union of the new
-class's direct slots and the slots of all its superclasses. But
-@code{define-class} itself does not perform this calculation. Instead,
-there is a method of the @code{initialize} generic function that is
-specialized for instances of type @code{<class>}, and it is this method
-that performs the slot calculation.
-
-@code{initialize} is a generic function which GOOPS calls whenever a new
-instance is created, immediately after allocating memory for a new
-instance, in order to initialize the new instance's slots. The sequence
-of steps is as follows.
-
-@itemize @bullet
-@item
-@code{define-class} uses @code{make} to make a new instance of the
-@code{<class>}, passing as initialization arguments the superclasses,
-slot definitions and class options that were specified in the
-@code{define-class} form.
-
-@item
-@code{make} allocates memory for the new instance, and then invokes the
-@code{initialize} generic function to initialize the new instance's
-slots.
-
-@item
-The @code{initialize} generic function applies the method that is
-specialized for instances of type @code{<class>}, and this method
-performs the slot calculation.
-@end itemize
-
-In other words, rather than being hardcoded in @code{define-class}, the
-behaviour of class definition is encapsulated by generic function
-methods that are specialized for the class @code{<class>}.
-
-It is possible to create a new class that inherits from @code{<class>},
-which is called a ``metaclass'', and to write a new @code{initialize}
-method that is specialized for instances of the new metaclass. Then, if
-the @code{define-class} form includes a @code{#:metaclass} class option
-whose value is the new metaclass, the class that is defined by the
-@code{define-class} form will be an instance of the new metaclass rather
-than of the default @code{<class>}, and will be defined in accordance
-with the new @code{initialize} method. Thus the default slot
-calculation, as well as any other aspect of the new class's relationship
-with its superclasses, can be modified or overridden.
-
-In a similar way, the behaviour of generic functions can be modified or
-overridden by creating a new class that inherits from the standard
-generic function class @code{<generic>}, writing appropriate methods
-that are specialized to the new class, and creating new generic
-functions that are instances of the new class.
-
-The same is true for method metaobjects. And the same basic mechanism
-allows the application class author to write an @code{initialize} method
-that is specialized to their application class, to initialize instances
-of that class.
-
-Such is the power of the MOP. Note that @code{initialize} is just one
-of a large number of generic functions that can be customized to modify
-the behaviour of application objects and classes and of GOOPS itself.
-Each subsequent section of the reference manual covers a particular area
-of GOOPS functionality, and describes the generic functions that are
-relevant for customization of that area.
-
-We conclude this subsection by emphasizing a point that may seem
-obvious, but contrasts with the corresponding situation in some other
-MOP implementations, such as CLOS. The point is simply that an
-identifier which represents a GOOPS class or generic function is a
-variable with a first-class value, the value being an instance of class
-@code{<class>} or @code{<generic>}. (In CLOS, on the other hand, a
-class identifier is a symbol that indexes the corresponding class
-metaobject in a separate namespace for classes.) This is, of course,
-simply an extension of the tendency in Scheme to avoid the unnecessary
-use of, on the one hand, syntactic forms that require unevaluated
-arguments and, on the other, separate identifier namespaces (e.g. for
-class names), but it is worth noting that GOOPS conforms fully to this
-Schemely principle.
-
-@node Terminology
-@subsection Terminology
-
-It is assumed that the reader is already familiar with standard object
-orientation concepts such as classes, objects/instances,
-inheritance/subclassing, generic functions and methods, encapsulation
-and polymorphism.
-
-This section explains some of the less well known concepts and
-terminology that GOOPS uses, which are assumed by the following sections
-of the reference manual.
-
-@menu
-* Metaclass::
-* Class Precedence List::
-* Accessor::
-@end menu
-
-@node Metaclass
-@subsubsection Metaclass
-
-A @dfn{metaclass} is the class of an object which represents a GOOPS
-class. Put more succinctly, a metaclass is a class's class.
-
-Most GOOPS classes have the metaclass @code{<class>} and, by default,
-any new class that is created using @code{define-class} has the
-metaclass @code{<class>}.
-
-But what does this really mean? To find out, let's look in more detail
-at what happens when a new class is created using @code{define-class}:
-
-@example
-(define-class <my-class> (<object>) . slots)
-@end example
-
-GOOPS actually expands the @code{define-class} form to something like
-this
-
-@example
-(define <my-class> (class (<object>) . slots))
-@end example
-
-and thence to
-
-@example
-(define <my-class>
- (make <class> #:supers (list <object>) #:slots slots))
-@end example
-
-In other words, the value of @code{<my-class>} is in fact an instance of
-the class @code{<class>} with slot values specifying the superclasses
-and slot definitions for the class @code{<my-class>}. (@code{#:supers}
-and @code{#:slots} are initialization keywords for the @code{dsupers}
-and @code{dslots} slots of the @code{<class>} class.)
-
-In order to take advantage of the full power of the GOOPS metaobject
-protocol (@pxref{MOP Specification}), it is sometimes desirable to
-create a new class with a metaclass other than the default
-@code{<class>}. This is done by writing:
-
-@example
-(define-class <my-class2> (<object>)
- slot @dots{}
- #:metaclass <my-metaclass>)
-@end example
-
-GOOPS expands this to something like:
-
-@example
-(define <my-class2>
- (make <my-metaclass> #:supers (list <object>) #:slots slots))
-@end example
-
-In this case, the value of @code{<my-class2>} is an instance of the more
-specialized class @code{<my-metaclass>}. Note that
-@code{<my-metaclass>} itself must previously have been defined as a
-subclass of @code{<class>}. For a full discussion of when and how it is
-useful to define new metaclasses, see @ref{MOP Specification}.
-
-Now let's make an instance of @code{<my-class2>}:
-
-@example
-(define my-object (make <my-class2> ...))
-@end example
-
-All of the following statements are correct expressions of the
-relationships between @code{my-object}, @code{<my-class2>},
-@code{<my-metaclass>} and @code{<class>}.
-
-@itemize @bullet
-@item
-@code{my-object} is an instance of the class @code{<my-class2>}.
-
-@item
-@code{<my-class2>} is an instance of the class @code{<my-metaclass>}.
-
-@item
-@code{<my-metaclass>} is an instance of the class @code{<class>}.
-
-@item
-The class of @code{my-object} is @code{<my-class2>}.
-
-@item
-The metaclass of @code{my-object} is @code{<my-metaclass>}.
-
-@item
-The class of @code{<my-class2>} is @code{<my-metaclass>}.
-
-@item
-The metaclass of @code{<my-class2>} is @code{<class>}.
-
-@item
-The class of @code{<my-metaclass>} is @code{<class>}.
-
-@item
-The metaclass of @code{<my-metaclass>} is @code{<class>}.
-
-@item
-@code{<my-class2>} is not a metaclass, since it is does not inherit from
-@code{<class>}.
-
-@item
-@code{<my-metaclass>} is a metaclass, since it inherits from
-@code{<class>}.
-@end itemize
-
-@node Class Precedence List
-@subsubsection Class Precedence List
-
-The @dfn{class precedence list} of a class is the list of all direct and
-indirect superclasses of that class, including the class itself.
-
-In the absence of multiple inheritance, the class precedence list is
-ordered straightforwardly, beginning with the class itself and ending
-with @code{<top>}.
-
-For example, given this inheritance hierarchy:
-
-@example
-(define-class <invertebrate> (<object>) @dots{})
-(define-class <echinoderm> (<invertebrate>) @dots{})
-(define-class <starfish> (<echinoderm>) @dots{})
-@end example
-
-the class precedence list of <starfish> would be
-
-@example
-(<starfish> <echinoderm> <invertebrate> <object> <top>)
-@end example
-
-With multiple inheritance, the algorithm is a little more complicated.
-A full description is provided by the GOOPS Tutorial: see @ref{Class
-precedence list}.
-
-``Class precedence list'' is often abbreviated, in documentation and
-Scheme variable names, to @dfn{cpl}.
-
-@node Accessor
-@subsubsection Accessor
-
-An @dfn{accessor} is a generic function with both reference and setter
-methods.
-
-@example
-(define-accessor perimeter)
-@end example
-
-Reference methods for an accessor are defined in the same way as generic
-function methods.
-
-@example
-(define-method (perimeter (s <square>))
- (* 4 (side-length s)))
-@end example
-
-Setter methods for an accessor are defined by specifying ``(setter
-<accessor-name>)'' as the first parameter of the @code{define-method}
-call.
-
-@example
-(define-method ((setter perimeter) (s <square>) (n <number>))
- (set! (side-length s) (/ n 4)))
-@end example
-
-Once an appropriate setter method has been defined in this way, it can
-be invoked using the generalized @code{set!} syntax, as in:
-
-@example
-(set! (perimeter s1) 18.3)
-@end example
-
-@node Defining New Classes
-@section Defining New Classes
-
-[ *fixme* Somewhere in this manual there needs to be an introductory
-discussion about GOOPS classes, generic functions and methods, covering
-
-@itemize @bullet
-@item
-how classes encapsulate related items of data in @dfn{slots}
-
-@item
-why it is that, unlike in C++ and Java, a class does not encapsulate the
-methods that act upon the class (at least not in the C++/Java sense)
-
-@item
-how generic functions provide a more general solution that provides for
-dispatch on all argument types, and avoids idiosyncracies like C++'s
-friend classes
-
-@item
-how encapsulation in the sense of data- and code-hiding, or of
-distinguishing interface from implementation, is treated in Guile as an
-orthogonal concept to object orientation, and is the responsibility of
-the module system.
-@end itemize
-
-Some of this is covered in the Tutorial chapter, in @ref{Generic
-functions and methods} - perhaps the best solution would be to expand
-the discussion there. ]
-
-@menu
-* Basic Class Definition::
-* Class Options::
-* Slot Options::
-* Class Definition Internals::
-* Customizing Class Definition::
-* STKlos Compatibility::
-@end menu
-
-@node Basic Class Definition
-@subsection Basic Class Definition
-
-New classes are defined using the @code{define-class} syntax, with
-arguments that specify the classes that the new class should inherit
-from, the direct slots of the new class, and any required class options.
-
-@deffn syntax define-class name (super @dots{}) slot-definition @dots{} . options
-Define a class called @var{name} that inherits from @var{super}s, with
-direct slots defined by @var{slot-definition}s and class options
-@var{options}. The newly created class is bound to the variable name
-@var{name} in the current environment.
-
-Each @var{slot-definition} is either a symbol that names the slot or a
-list,
-
-@example
-(@var{slot-name-symbol} . @var{slot-options})
-@end example
-
-where @var{slot-name-symbol} is a symbol and @var{slot-options} is a
-list with an even number of elements. The even-numbered elements of
-@var{slot-options} (counting from zero) are slot option keywords; the
-odd-numbered elements are the corresponding values for those keywords.
-
-@var{options} is a similarly structured list containing class option
-keywords and corresponding values.
-@end deffn
-
-The standard GOOPS class and slot options are described in the following
-subsections: see @ref{Class Options} and @ref{Slot Options}.
-
-Example 1. Define a class that combines two pre-existing classes by
-inheritance but adds no new slots.
-
-@example
-(define-class <combined> (<tree> <bicycle>))
-@end example
-
-Example 2. Define a @code{regular-polygon} class with slots for side
-length and number of sides that have default values and can be accessed
-via the generic functions @code{side-length} and @code{num-sides}.
-
-@example
-(define-class <regular-polygon> ()
- (sl #:init-value 1 #:accessor side-length)
- (ns #:init-value 5 #:accessor num-sides))
-@end example
-
-Example 3. Define a class whose behavior (and that of its instances) is
-customized via an application-defined metaclass.
-
-@example
-(define-class <tcpip-fsm> ()
- (s #:init-value #f #:accessor state)
- ...
- #:metaclass <finite-state-class>)
-@end example
-
-@node Class Options
-@subsection Class Options
-
-@deffn {class option} #:metaclass metaclass
-The @code{#:metaclass} class option specifies the metaclass of the class
-being defined. @var{metaclass} must be a class that inherits from
-@code{<class>}. For an introduction to the use of metaclasses, see
-@ref{Metaobjects and the Metaobject Protocol} and @ref{Metaclass}.
-
-If the @code{#:metaclass} option is absent, GOOPS reuses or constructs a
-metaclass for the new class by calling @code{ensure-metaclass}
-(@pxref{Class Definition Internals,, ensure-metaclass}).
-@end deffn
-
-@deffn {class option} #:name name
-The @code{#:name} class option specifies the new class's name. This
-name is used to identify the class whenever related objects - the class
-itself, its instances and its subclasses - are printed.
-
-If the @code{#:name} option is absent, GOOPS uses the first argument to
-@code{define-class} as the class name.
-@end deffn
-
-@deffn {class option} #:environment environment
-*fixme* Not sure about this one, but I think that the
-@code{#:environment} option specifies the environment in which the
-class's getters and setters are computed and evaluated.
-
-If the @code{#:environment} option is not specified, the class's
-environment defaults to the top-level environment in which the
-@code{define-class} form appears.
-@end deffn
-
-@node Slot Options
-@subsection Slot Options
-
-@deffn {slot option} #:allocation allocation
-The @code{#:allocation} option tells GOOPS how to allocate storage for
-the slot. Possible values for @var{allocation} are
-
-@itemize @bullet
-@item @code{#:instance}
-
-Indicates that GOOPS should create separate storage for this slot in
-each new instance of the containing class (and its subclasses).
-
-@item @code{#:class}
-
-Indicates that GOOPS should create storage for this slot that is shared
-by all instances of the containing class (and its subclasses). In other
-words, a slot in class @var{C} with allocation @code{#:class} is shared
-by all @var{instance}s for which @code{(is-a? @var{instance} @var{c})}.
-
-@item @code{#:each-subclass}
-
-Indicates that GOOPS should create storage for this slot that is shared
-by all @emph{direct} instances of the containing class, and that
-whenever a subclass of the containing class is defined, GOOPS should
-create a new storage for the slot that is shared by all @emph{direct}
-instances of the subclass. In other words, a slot with allocation
-@code{#:each-subclass} is shared by all instances with the same
-@code{class-of}.
-
-@item @code{#:virtual}
-
-Indicates that GOOPS should not allocate storage for this slot. The
-slot definition must also include the @code{#:slot-ref} and
-@code{#:slot-set!} options to specify how to reference and set the value
-for this slot.
-@end itemize
-
-The default value is @code{#:instance}.
-
-Slot allocation options are processed when defining a new class by the
-generic function @code{compute-get-n-set}, which is specialized by the
-class's metaclass. Hence new types of slot allocation can be
-implemented by defining a new metaclass and a method for
-@code{compute-get-n-set} that is specialized for the new metaclass. For
-an example of how to do this, see @ref{Customizing Class Definition}.
-@end deffn
-
-@deffn {slot option} #:slot-ref getter
-@deffnx {slot option} #:slot-set! setter
-The @code{#:slot-ref} and @code{#:slot-set!} options must be specified
-if the slot allocation is @code{#:virtual}, and are ignored otherwise.
-
-@var{getter} should be a closure taking a single @var{instance} parameter
-that returns the current slot value. @var{setter} should be a closure
-taking two parameters - @var{instance} and @var{new-val} - that sets the
-slot value to @var{new-val}.
-@end deffn
-
-@deffn {slot option} #:getter getter
-@deffnx {slot option} #:setter setter
-@deffnx {slot option} #:accessor accessor
-These options, if present, tell GOOPS to create generic function and
-method definitions that can be used to get and set the slot value more
-conveniently than by using @code{slot-ref} and @code{slot-set!}.
-
-@var{getter} specifies a generic function to which GOOPS will add a
-method for getting the slot value. @var{setter} specifies a generic
-function to which GOOPS will add a method for setting the slot value.
-@var{accessor} specifies an accessor to which GOOPS will add methods for
-both getting and setting the slot value.
-
-So if a class includes a slot definition like this:
-
-@example
-(c #:getter get-count #:setter set-count #:accessor count)
-@end example
-
-GOOPS defines generic function methods such that the slot value can be
-referenced using either the getter or the accessor -
-
-@example
-(let ((current-count (get-count obj))) @dots{})
-(let ((current-count (count obj))) @dots{})
-@end example
-
-- and set using either the setter or the accessor -
-
-@example
-(set-count obj (+ 1 current-count))
-(set! (count obj) (+ 1 current-count))
-@end example
-
-Note that
-
-@itemize @bullet
-@item
-with an accessor, the slot value is set using the generalized
-@code{set!} syntax
-
-@item
-in practice, it is unusual for a slot to use all three of these options:
-read-only, write-only and read-write slots would typically use only
-@code{#:getter}, @code{#:setter} and @code{#:accessor} options
-respectively.
-@end itemize
-
-If the specified names are already bound in the top-level environment to
-values that cannot be upgraded to generic functions, those values are
-overwritten during evaluation of the @code{define-class} that contains
-the slot definition. For details, see @ref{Generic Function Internals,,
-ensure-generic}.
-@end deffn
-
-@deffn {slot option} #:init-value init-value
-@deffnx {slot option} #:init-form init-form
-@deffnx {slot option} #:init-thunk init-thunk
-@deffnx {slot option} #:init-keyword init-keyword
-These options provide various ways to specify how to initialize the
-slot's value at instance creation time. @var{init-value} is a fixed
-value. @var{init-thunk} is a procedure of no arguments that is called
-when a new instance is created and should return the desired initial
-slot value. @var{init-form} is an unevaluated expression that gets
-evaluated when a new instance is created and should return the desired
-initial slot value. @var{init-keyword} is a keyword that can be used to
-pass an initial slot value to @code{make} when creating a new instance.
-
-If more than one of these options is specified for the same slot, the
-order of precedence, highest first is
-
-@itemize @bullet
-@item
-@code{#:init-keyword}, if @var{init-keyword} is present in the options
-passed to @code{make}
-
-@item
-@code{#:init-thunk}, @code{#:init-form} or @code{#:init-value}.
-@end itemize
-
-If the slot definition contains more than one initialization option of
-the same precedence, the later ones are ignored. If a slot is not
-initialized at all, its value is unbound.
-
-In general, slots that are shared between more than one instance are
-only initialized at new instance creation time if the slot value is
-unbound at that time. However, if the new instance creation specifies
-a valid init keyword and value for a shared slot, the slot is
-re-initialized regardless of its previous value.
-
-Note, however, that the power of GOOPS' metaobject protocol means that
-everything written here may be customized or overridden for particular
-classes! The slot initializations described here are performed by the least
-specialized method of the generic function @code{initialize}, whose
-signature is
-
-@example
-(define-method (initialize (object <object>) initargs) ...)
-@end example
-
-The initialization of instances of any given class can be customized by
-defining a @code{initialize} method that is specialized for that class,
-and the author of the specialized method may decide to call
-@code{next-method} - which will result in a call to the next less
-specialized @code{initialize} method - at any point within the
-specialized code, or maybe not at all. In general, therefore, the
-initialization mechanisms described here may be modified or overridden by
-more specialized code, or may not be supported at all for particular
-classes.
-@end deffn
-
-@node Class Definition Internals
-@subsection Class Definition Internals
-
-Implementation notes: @code{define-class} expands to an expression which
-
-@itemize @bullet
-@item
-checks that it is being evaluated only at top level
-
-@item
-defines any accessors that are implied by the @var{slot-definition}s
-
-@item
-uses @code{class} to create the new class (@pxref{Class Definition
-Internals,, class})
-
-@item
-checks for a previous class definition for @var{name} and, if found,
-handles the redefinition by invoking @code{class-redefinition}
-(@pxref{Redefining a Class}).
-@end itemize
-
-@deffn syntax class name (super @dots{}) slot-definition @dots{} . options
-Return a newly created class that inherits from @var{super}s, with
-direct slots defined by @var{slot-definition}s and class options
-@var{options}. For the format of @var{slot-definition}s and
-@var{options}, see @ref{Basic Class Definition,, define-class}.
-@end deffn
-
-Implementation notes: @code{class} expands to an expression which
-
-@itemize @bullet
-@item
-processes the class and slot definition options to check that they are
-well-formed, to convert the @code{#:init-form} option to an
-@code{#:init-thunk} option, to supply a default environment parameter
-(the current top-level environment) and to evaluate all the bits that
-need to be evaluated
-
-@item
-calls @code{make-class} to create the class with the processed and
-evaluated parameters.
-@end itemize
-
-@deffn procedure make-class supers slots . options
-Return a newly created class that inherits from @var{supers}, with
-direct slots defined by @var{slots} and class options @var{options}.
-For the format of @var{slots} and @var{options}, see @ref{Basic Class
-Definition,, define-class}, except note that for @code{make-class},
-@var{slots} and @var{options} are separate list parameters: @var{slots}
-here is a list of slot definitions.
-@end deffn
-
-Implementation notes: @code{make-class}
-
-@itemize @bullet
-@item
-adds @code{<object>} to the @var{supers} list if @var{supers} is empty
-or if none of the classes in @var{supers} have @code{<object>} in their
-class precedence list
-
-@item
-defaults the @code{#:environment}, @code{#:name} and @code{#:metaclass}
-options, if they are not specified by @var{options}, to the current
-top-level environment, the unbound value, and @code{(ensure-metaclass
-@var{supers})} respectively (@pxref{Class Definition Internals,,
-ensure-metaclass})
-
-@item
-checks for duplicate classes in @var{supers} and duplicate slot names in
-@var{slots}, and signals an error if there are any duplicates
-
-@item
-calls @code{make}, passing the metaclass as the first parameter and all
-other parameters as option keywords with values.
-@end itemize
-
-@deffn procedure ensure-metaclass supers env
-Return a metaclass suitable for a class that inherits from the list of
-classes in @var{supers}. The returned metaclass is the union by
-inheritance of the metaclasses of the classes in @var{supers}.
-
-In the simplest case, where all the @var{supers} are straightforward
-classes with metaclass @code{<class>}, the returned metaclass is just
-@code{<class>}.
-
-For a more complex example, suppose that @var{supers} contained one
-class with metaclass @code{<operator-class>} and one with metaclass
-@code{<foreign-object-class>}. Then the returned metaclass would be a
-class that inherits from both @code{<operator-class>} and
-@code{<foreign-object-class>}.
-
-If @var{supers} is the empty list, @code{ensure-metaclass} returns the
-default GOOPS metaclass @code{<class>}.
-
-GOOPS keeps a list of the metaclasses created by
-@code{ensure-metaclass}, so that each required type of metaclass only
-has to be created once.
-
-The @code{env} parameter is ignored.
-@end deffn
-
-@deffn procedure ensure-metaclass-with-supers meta-supers
-@code{ensure-metaclass-with-supers} is an internal procedure used by
-@code{ensure-metaclass} (@pxref{Class Definition Internals,,
-ensure-metaclass}). It returns a metaclass that is the union by
-inheritance of the metaclasses in @var{meta-supers}.
-@end deffn
-
-The internals of @code{make}, which is ultimately used to create the new
-class object, are described in @ref{Customizing Instance Creation},
-which covers the creation and initialization of instances in general.
-
-@node Customizing Class Definition
-@subsection Customizing Class Definition
-
-During the initialization of a new class, GOOPS calls a number of generic
-functions with the newly allocated class instance as the first
-argument. Specifically, GOOPS calls the generic function
-
-@itemize @bullet
-@item
-(initialize @var{class} @dots{})
-@end itemize
-
-where @var{class} is the newly allocated class instance, and the default
-@code{initialize} method for arguments of type @code{<class>} calls the
-generic functions
-
-@itemize @bullet
-@item
-(compute-cpl @var{class})
-
-@item
-(compute-slots @var{class})
-
-@item
-(compute-get-n-set @var{class} @var{slot-def}), for each of the slot
-definitions returned by @code{compute-slots}
-
-@item
-(compute-getter-method @var{class} @var{slot-def}), for each of the
-slot definitions returned by @code{compute-slots} that includes a
-@code{#:getter} or @code{#:accessor} slot option
-
-@item
-(compute-setter-method @var{class} @var{slot-def}), for each of the
-slot definitions returned by @code{compute-slots} that includes a
-@code{#:setter} or @code{#:accessor} slot option.
-@end itemize
-
-If the metaclass of the new class is something more specialized than the
-default @code{<class>}, then the type of @var{class} in the calls above
-is more specialized than @code{<class>}, and hence it becomes possible
-to define generic function methods, specialized for the new class's
-metaclass, that can modify or override the default behaviour of
-@code{initialize}, @code{compute-cpl} or @code{compute-get-n-set}.
-
-@code{compute-cpl} computes the class precedence list (``CPL'') for the
-new class (@pxref{Class precedence list}), and returns it as a list of
-class objects. The CPL is important because it defines a superclass
-ordering that is used, when a generic function is invoked upon an
-instance of the class, to decide which of the available generic function
-methods is the most specific. Hence @code{compute-cpl} could be
-customized in order to modify the CPL ordering algorithm for all classes
-with a special metaclass.
-
-The default CPL algorithm is encapsulated by the @code{compute-std-cpl}
-procedure, which is in turn called by the default @code{compute-cpl}
-method.
-
-@deffn procedure compute-std-cpl class
-Compute and return the class precedence list for @var{class} according
-to the algorithm described in @ref{Class precedence list}.
-@end deffn
-
-@code{compute-slots} computes and returns a list of all slot definitions
-for the new class. By default, this list includes the direct slot
-definitions from the @code{define-class} form, plus the slot definitions
-that are inherited from the new class's superclasses. The default
-@code{compute-slots} method uses the CPL computed by @code{compute-cpl}
-to calculate this union of slot definitions, with the rule that slots
-inherited from superclasses are shadowed by direct slots with the same
-name. One possible reason for customizing @code{compute-slots} would be
-to implement an alternative resolution strategy for slot name conflicts.
-
-@code{compute-get-n-set} computes the low-level closures that will be
-used to get and set the value of a particular slot, and returns them in
-a list with two elements.
-
-The closures returned depend on how storage for that slot is allocated.
-The standard @code{compute-get-n-set} method, specialized for classes of
-type @code{<class>}, handles the standard GOOPS values for the
-@code{#:allocation} slot option (@pxref{Slot Options,, allocation}). By
-defining a new @code{compute-get-n-set} method for a more specialized
-metaclass, it is possible to support new types of slot allocation.
-
-Suppose you wanted to create a large number of instances of some class
-with a slot that should be shared between some but not all instances of
-that class - say every 10 instances should share the same slot storage.
-The following example shows how to implement and use a new type of slot
-allocation to do this.
-
-@example
-(define-class <batched-allocation-metaclass> (<class>))
-
-(let ((batch-allocation-count 0)
- (batch-get-n-set #f))
- (define-method (compute-get-n-set (class <batched-allocation-metaclass>) s)
- (case (slot-definition-allocation s)
- ((#:batched)
- ;; If we've already used the same slot storage for 10 instances,
- ;; reset variables.
- (if (= batch-allocation-count 10)
- (begin
- (set! batch-allocation-count 0)
- (set! batch-get-n-set #f)))
- ;; If we don't have a current pair of get and set closures,
- ;; create one. make-closure-variable returns a pair of closures
- ;; around a single Scheme variable - see goops.scm for details.
- (or batch-get-n-set
- (set! batch-get-n-set (make-closure-variable)))
- ;; Increment the batch allocation count.
- (set! batch-allocation-count (+ batch-allocation-count 1))
- batch-get-n-set)
-
- ;; Call next-method to handle standard allocation types.
- (else (next-method)))))
-
-(define-class <class-using-batched-slot> ()
- ...
- (c #:allocation #:batched)
- ...
- #:metaclass <batched-allocation-metaclass>)
-@end example
-
-The usage of @code{compute-getter-method} and @code{compute-setter-method}
-is described in @ref{MOP Specification}.
-
-@code{compute-cpl} and @code{compute-get-n-set} are called by the
-standard @code{initialize} method for classes whose metaclass is
-@code{<class>}. But @code{initialize} itself can also be modified, by
-defining an @code{initialize} method specialized to the new class's
-metaclass. Such a method could complete override the standard
-behaviour, by not calling @code{(next-method)} at all, but more
-typically it would perform additional class initialization steps before
-and/or after calling @code{(next-method)} for the standard behaviour.
-
-@node STKlos Compatibility
-@subsection STKlos Compatibility
-
-If the STKlos compatibility module is loaded, @code{define-class} is
-overwritten by a STKlos-specific definition; the standard GOOPS
-definition of @code{define-class} remains available in
-@code{standard-define-class}.
-
-@deffn syntax standard-define-class name (super @dots{}) slot-definition @dots{} . options
-@code{standard-define-class} is equivalent to the standard GOOPS
-@code{define-class}.
-@end deffn
-
-@node Creating Instances
-@section Creating Instances
-
-@menu
-* Basic Instance Creation::
-* Customizing Instance Creation::
-@end menu
-
-@node Basic Instance Creation
-@subsection Basic Instance Creation
-
-To create a new instance of any GOOPS class, use the generic function
-@code{make} or @code{make-instance}, passing the required class and any
-appropriate instance initialization arguments as keyword and value
-pairs. Note that @code{make} and @code{make-instances} are aliases for
-each other - their behaviour is identical.
-
-@deffn generic make
-@deffnx method make (class <class>) . initargs
-Create and return a new instance of class @var{class}, initialized using
-@var{initargs}.
-
-In theory, @var{initargs} can have any structure that is understood by
-whatever methods get applied when the @code{initialize} generic function
-is applied to the newly allocated instance.
-
-In practice, specialized @code{initialize} methods would normally call
-@code{(next-method)}, and so eventually the standard GOOPS
-@code{initialize} methods are applied. These methods expect
-@var{initargs} to be a list with an even number of elements, where
-even-numbered elements (counting from zero) are keywords and
-odd-numbered elements are the corresponding values.
-
-GOOPS processes initialization argument keywords automatically for slots
-whose definition includes the @code{#:init-keyword} option (@pxref{Slot
-Options,, init-keyword}). Other keyword value pairs can only be
-processed by an @code{initialize} method that is specialized for the new
-instance's class. Any unprocessed keyword value pairs are ignored.
-@end deffn
-
-@deffn generic make-instance
-@deffnx method make-instance (class <class>) . initargs
-@code{make-instance} is an alias for @code{make}.
-@end deffn
-
-@node Customizing Instance Creation
-@subsection Customizing Instance Creation
-
-@code{make} itself is a generic function. Hence the @code{make}
-invocation itself can be customized in the case where the new instance's
-metaclass is more specialized than the default @code{<class>}, by
-defining a @code{make} method that is specialized to that metaclass.
-
-Normally, however, the method for classes with metaclass @code{<class>}
-will be applied. This method calls two generic functions:
-
-@itemize @bullet
-@item
-(allocate-instance @var{class} . @var{initargs})
-
-@item
-(initialize @var{instance} . @var{initargs})
-@end itemize
-
-@code{allocate-instance} allocates storage for and returns the new
-instance, uninitialized. You might customize @code{allocate-instance},
-for example, if you wanted to provide a GOOPS wrapper around some other
-object programming system.
-
-To do this, you would create a specialized metaclass, which would act as
-the metaclass for all classes and instances from the other system. Then
-define an @code{allocate-instance} method, specialized to that
-metaclass, which calls a Guile primitive C function, which in turn
-allocates the new instance using the interface of the other object
-system.
-
-In this case, for a complete system, you would also need to customize a
-number of other generic functions like @code{make} and
-@code{initialize}, so that GOOPS knows how to make classes from the
-other system, access instance slots, and so on.
-
-@code{initialize} initializes the instance that is returned by
-@code{allocate-instance}. The standard GOOPS methods perform
-initializations appropriate to the instance class.
-
-@itemize @bullet
-@item
-At the least specialized level, the method for instances of type
-@code{<object>} performs internal GOOPS instance initialization, and
-initializes the instance's slots according to the slot definitions and
-any slot initialization keywords that appear in @var{initargs}.
-
-@item
-The method for instances of type @code{<class>} calls
-@code{(next-method)}, then performs the class initializations described
-in @ref{Customizing Class Definition}.
-
-@item
-and so on for generic functions, method, operator classes @dots{}
-@end itemize
-
-Similarly, you can customize the initialization of instances of any
-application-defined class by defining an @code{initialize} method
-specialized to that class.
-
-Imagine a class whose instances' slots need to be initialized at
-instance creation time by querying a database. Although it might be
-possible to achieve this a combination of @code{#:init-thunk} keywords
-and closures in the slot definitions, it is neater to write an
-@code{initialize} method for the class that queries the database once
-and initializes all the dependent slot values according to the results.
-
-@node Accessing Slots
-@section Accessing Slots
-
-The definition of a slot contains at the very least a slot name, and may
-also contain various slot options, including getter, setter and/or
-accessor functions for the slot.
-
-It is always possible to access slots by name, using the various
-``slot-ref'' and ``slot-set!'' procedures described in the following
-subsections. For example,
-
-@example
-(define-class <my-class> () ;; Define a class with slots
- (count #:init-value 0) ;; named "count" and "cache".
- (cache #:init-value '())
- @dots{})
-
-(define inst (make <my-class>)) ;; Make an instance of this class.
-
-(slot-set! inst 'count 5) ;; Set the value of the "count"
- ;; slot to 5.
-
-(slot-set! inst 'cache ;; Modify the value of the
- (cons (cons "^it" "It") ;; "cache" slot.
- (slot-ref inst 'cache)))
-@end example
-
-If a slot definition includes a getter, setter or accessor function,
-these can be used instead of @code{slot-ref} and @code{slot-set!} to
-access the slot.
-
-@example
-(define-class <adv-class> () ;; Define a new class whose slots
- (count #:setter set-count) ;; use a getter, a setter and
- (cache #:accessor cache) ;; an accessor.
- (csize #:getter cache-size)
- @dots{})
-
-(define inst (make <adv-class>)) ;; Make an instance of this class.
-
-(set-count inst 5) ;; Set the value of the "count"
- ;; slot to 5.
-
-(set! (cache inst) ;; Modify the value of the
- (cons (cons "^it" "It") ;; "cache" slot.
- (cache inst)))
-
-(let ((size (cache-size inst))) ;; Get the value of the "csize"
- @dots{}) ;; slot.
-@end example
-
-Whichever of these methods is used to access slots, GOOPS always calls
-the low-level @dfn{getter} and @dfn{setter} closures for the slot to get
-and set its value. These closures make sure that the slot behaves
-according to the @code{#:allocation} type that was specified in the slot
-definition (@pxref{Slot Options,, allocation}). (For more about these
-closures, see @ref{Customizing Class Definition,, compute-get-n-set}.)
-
-@menu
-* Instance Slots::
-* Class Slots::
-* Handling Slot Access Errors::
-@end menu
-
-@node Instance Slots
-@subsection Instance Slots
-
-Any slot, regardless of its allocation, can be queried, referenced and
-set using the following four primitive procedures.
-
-@deffn {primitive procedure} slot-exists? obj slot-name
-Return @code{#t} if @var{obj} has a slot with name @var{slot-name},
-otherwise @code{#f}.
-@end deffn
-
-@deffn {primitive procedure} slot-bound? obj slot-name
-Return @code{#t} if the slot named @var{slot-name} in @var{obj} has a
-value, otherwise @code{#f}.
-
-@code{slot-bound?} calls the generic function @code{slot-missing} if
-@var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
-Slot Access Errors, slot-missing}).
-@end deffn
-
-@deffn {primitive procedure} slot-ref obj slot-name
-Return the value of the slot named @var{slot-name} in @var{obj}.
-
-@code{slot-ref} calls the generic function @code{slot-missing} if
-@var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
-Slot Access Errors, slot-missing}).
-
-@code{slot-ref} calls the generic function @code{slot-unbound} if the
-named slot in @var{obj} does not have a value (@pxref{Handling Slot
-Access Errors, slot-unbound}).
-@end deffn
-
-@deffn {primitive procedure} slot-set! obj slot-name value
-Set the value of the slot named @var{slot-name} in @var{obj} to @var{value}.
-
-@code{slot-set!} calls the generic function @code{slot-missing} if
-@var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
-Slot Access Errors, slot-missing}).
-@end deffn
-
-GOOPS stores information about slots in class metaobjects. Internally,
-all of these procedures work by looking up the slot definition for the
-slot named @var{slot-name} in the class metaobject for @code{(class-of
-@var{obj})}, and then using the slot definition's ``getter'' and
-``setter'' closures to get and set the slot value.
-
-The next four procedures differ from the previous ones in that they take
-the class metaobject as an explicit argument, rather than assuming
-@code{(class-of @var{obj})}. Therefore they allow you to apply the
-``getter'' and ``setter'' closures of a slot definition in one class to
-an instance of a different class.
-
-[ *fixme* I have no idea why this is useful! Perhaps when a slot in
-@code{(class-of @var{obj})} shadows a slot with the same name in one of
-its superclasses? There should be an enlightening example here. ]
-
-@deffn {primitive procedure} slot-exists-using-class? class obj slot-name
-Return @code{#t} if the class metaobject @var{class} has a slot
-definition for a slot with name @var{slot-name}, otherwise @code{#f}.
-@end deffn
-
-@deffn {primitive procedure} slot-bound-using-class? class obj slot-name
-Return @code{#t} if applying @code{slot-ref-using-class} to the same
-arguments would call the generic function @code{slot-unbound}, otherwise
-@code{#f}.
-
-@code{slot-bound-using-class?} calls the generic function
-@code{slot-missing} if @var{class} does not have a slot definition for a
-slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
-slot-missing}).
-@end deffn
-
-@deffn {primitive procedure} slot-ref-using-class class obj slot-name
-Apply the ``getter'' closure for the slot named @var{slot-name} in
-@var{class} to @var{obj}, and return its result.
-
-@code{slot-ref-using-class} calls the generic function
-@code{slot-missing} if @var{class} does not have a slot definition for a
-slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
-slot-missing}).
-
-@code{slot-ref-using-class} calls the generic function
-@code{slot-unbound} if the application of the ``getter'' closure to
-@var{obj} returns an unbound value (@pxref{Handling Slot Access Errors,
-slot-unbound}).
-@end deffn
-
-@deffn {primitive procedure} slot-set-using-class! class obj slot-name value
-Apply the ``setter'' closure for the slot named @var{slot-name} in
-@var{class} to @var{obj} and @var{value}.
-
-@code{slot-set-using-class!} calls the generic function
-@code{slot-missing} if @var{class} does not have a slot definition for a
-slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
-slot-missing}).
-@end deffn
-
-@node Class Slots
-@subsection Class Slots
-
-Slots whose allocation is per-class rather than per-instance can be
-referenced and set without needing to specify any particular instance.
-
-@deffn procedure class-slot-ref class slot-name
-Return the value of the slot named @var{slot-name} in class @var{class}.
-The named slot must have @code{#:class} or @code{#:each-subclass}
-allocation (@pxref{Slot Options,, allocation}).
-
-If there is no such slot with @code{#:class} or @code{#:each-subclass}
-allocation, @code{class-slot-ref} calls the @code{slot-missing} generic
-function with arguments @var{class} and @var{slot-name}. Otherwise, if
-the slot value is unbound, @code{class-slot-ref} calls the
-@code{slot-missing} generic function, with the same arguments.
-@end deffn
-
-@deffn procedure class-slot-set! class slot-name value
-Set the value of the slot named @var{slot-name} in class @var{class} to
-@var{value}. The named slot must have @code{#:class} or
-@code{#:each-subclass} allocation (@pxref{Slot Options,, allocation}).
-
-If there is no such slot with @code{#:class} or @code{#:each-subclass}
-allocation, @code{class-slot-ref} calls the @code{slot-missing} generic
-function with arguments @var{class} and @var{slot-name}.
-@end deffn
-
-@node Handling Slot Access Errors
-@subsection Handling Slot Access Errors
-
-GOOPS calls one of the following generic functions when a ``slot-ref''
-or ``slot-set!'' call specifies a non-existent slot name, or tries to
-reference a slot whose value is unbound.
-
-@deffn generic slot-missing
-@deffnx method slot-missing (class <class>) slot-name
-@deffnx method slot-missing (class <class>) (object <object>) slot-name
-@deffnx method slot-missing (class <class>) (object <object>) slot-name value
-When an application attempts to reference or set a class or instance
-slot by name, and the slot name is invalid for the specified @var{class}
-or @var{object}, GOOPS calls the @code{slot-missing} generic function.
-
-The default methods all call @code{goops-error} with an appropriate
-message.
-@end deffn
-
-@deffn generic slot-unbound
-@deffnx method slot-unbound (object <object>)
-@deffnx method slot-unbound (class <class>) slot-name
-@deffnx method slot-unbound (class <class>) (object <object>) slot-name
-When an application attempts to reference a class or instance slot, and
-the slot's value is unbound, GOOPS calls the @code{slot-unbound} generic
-function.
-
-The default methods all call @code{goops-error} with an appropriate
-message.
-@end deffn
-
-@node Creating Generic Functions
-@section Creating Generic Functions
-
-A generic function is a collection of methods, with rules for
-determining which of the methods should be applied for any given
-invocation of the generic function.
-
-GOOPS represents generic functions as metaobjects of the class
-@code{<generic>} (or one of its subclasses).
-
-@menu
-* Basic Generic Function Creation::
-* Generic Function Internals::
-* Extending Guiles Primitives::
-@end menu
-
-@node Basic Generic Function Creation
-@subsection Basic Generic Function Creation
-
-The following forms may be used to bind a variable to a generic
-function. Depending on that variable's pre-existing value, the generic
-function may be created empty - with no methods - or it may contain
-methods that are inferred from the pre-existing value.
-
-It is not, in general, necessary to use @code{define-generic} or
-@code{define-accessor} before defining methods for the generic function
-using @code{define-method}, since @code{define-method} will
-automatically interpolate a @code{define-generic} call, or upgrade an
-existing generic to an accessor, if that is implied by the
-@code{define-method} call. Note in particular that,
-if the specified variable already has a @emph{generic function} value,
-@code{define-generic} and @code{define-accessor} will @emph{discard} it!
-Obviously it is application-dependent whether this is desirable or not.
-
-If, for example, you wanted to extend @code{+} for a class representing
-a new numerical type, you probably want to inherit any existing methods
-for @code{+} and so should not use @code{define-generic}. If, on the
-other hand, you do not want to risk inheriting methods whose behaviour
-might surprise you, you can use @code{define-generic} or
-@code{define-accessor} to wipe the slate clean.
-
-@deffn syntax define-generic symbol
-Create a generic function with name @var{symbol} and bind it to the
-variable @var{symbol}.
-
-If the variable @var{symbol} was previously bound to a Scheme procedure
-(or procedure-with-setter), the old procedure (and setter) is
-incorporated into the new generic function as its default procedure (and
-setter). Any other previous value that was bound to @var{symbol},
-including an existing generic function, is overwritten by the new
-generic function.
-@end deffn
-
-@deffn syntax define-accessor symbol
-Create an accessor with name @var{symbol} and bind it to the variable
-@var{symbol}.
-
-If the variable @var{symbol} was previously bound to a Scheme procedure
-(or procedure-with-setter), the old procedure (and setter) is
-incorporated into the new accessor as its default procedure (and
-setter). Any other previous value that was bound to @var{symbol},
-including an existing generic function or accessor, is overwritten by
-the new definition.
-@end deffn
-
-@node Generic Function Internals
-@subsection Generic Function Internals
-
-@code{define-generic} calls @code{ensure-generic} to upgrade a
-pre-existing procedure value, or @code{make} with metaclass
-@code{<generic>} to create a new generic function.
-
-@code{define-accessor} calls @code{ensure-accessor} to upgrade a
-pre-existing procedure value, or @code{make-accessor} to create a new
-accessor.
-
-@deffn procedure ensure-generic old-definition [name]
-Return a generic function with name @var{name}, if possible by using or
-upgrading @var{old-definition}. If unspecified, @var{name} defaults to
-@code{#f}.
-
-If @var{old-definition} is already a generic function, it is returned
-unchanged.
-
-If @var{old-definition} is a Scheme procedure or procedure-with-setter,
-@code{ensure-generic} returns a new generic function that uses
-@var{old-definition} for its default procedure and setter.
-
-Otherwise @code{ensure-generic} returns a new generic function with no
-defaults and no methods.
-@end deffn
-
-@deffn procedure make-generic [name]
-Return a new generic function with name @code{(car @var{name})}. If
-unspecified, @var{name} defaults to @code{#f}.
-@end deffn
-
-@code{ensure-generic} calls @code{make} with metaclasses
-@code{<generic>} and @code{<generic-with-setter>}, depending on the
-previous value of the variable that it is trying to upgrade.
-
-@code{make-generic} is a simple wrapper for @code{make} with metaclass
-@code{<generic>}.
-
-@deffn procedure ensure-accessor proc [name]
-Return an accessor with name @var{name}, if possible by using or
-upgrading @var{proc}. If unspecified, @var{name} defaults to @code{#f}.
-
-If @var{proc} is already an accessor, it is returned unchanged.
-
-If @var{proc} is a Scheme procedure, procedure-with-setter or generic
-function, @code{ensure-accessor} returns an accessor that reuses the
-reusable elements of @var{proc}.
-
-Otherwise @code{ensure-accessor} returns a new accessor with no defaults
-and no methods.
-@end deffn
-
-@deffn procedure make-accessor [name]
-Return a new accessor with name @code{(car @var{name})}. If
-unspecified, @var{name} defaults to @code{#f}.
-@end deffn
-
-@code{ensure-accessor} calls @code{make} with
-metaclass @code{<generic-with-setter>}, as well as calls to
-@code{ensure-generic}, @code{make-accessor} and (tail recursively)
-@code{ensure-accessor}.
-
-@code{make-accessor} calls @code{make} twice, first
-with metaclass @code{<generic>} to create a generic function for the
-setter, then with metaclass @code{<generic-with-setter>} to create the
-accessor, passing the setter generic function as the value of the
-@code{#:setter} keyword.
-
-@node Extending Guiles Primitives
-@subsection Extending Guile's Primitives
-
-When GOOPS is loaded, many of Guile's primitive procedures can be
-extended by giving them a generic function definition that operates
-in conjunction with their normal C-coded implementation. For
-primitives that are extended in this way, the result from the user-
-or application-level point of view is that the extended primitive
-behaves exactly like a generic function with the C-coded implementation
-as its default method.
-
-The @code{generic-capability?} predicate should be used to determine
-whether a particular primitive is extensible in this way.
-
-@deffn {primitive procedure} generic-capability? primitive
-Return @code{#t} if @var{primitive} can be extended by giving it a
-generic function definition, otherwise @code{#f}.
-@end deffn
-
-Even when a primitive procedure is extensible like this, its generic
-function definition is not created until it is needed by a call to
-@code{define-method}, or until the application explicitly requests it
-by calling @code{enable-primitive-generic!}.
-
-@deffn {primitive procedure} enable-primitive-generic! primitive
-Force the creation of a generic function definition for
-@var{primitive}.
-@end deffn
-
-Once the generic function definition for a primitive has been created,
-it can be retrieved using @code{primitive-generic-generic}.
-
-@deffn {primitive procedure} primitive-generic-generic primitive
-Return the generic function definition of @var{primitive}.
-
-@code{primitive-generic-generic} raises an error if @var{primitive}
-is not a primitive with generic capability, or if its generic capability
-has not yet been enabled, whether implicitly (by @code{define-method})
-or explicitly (by @code{enable-primitive-generic!}).
-@end deffn
-
-Note that the distinction between, on the one hand, primitives with
-additional generic function definitions and, on the other hand, generic
-functions with a default method, may disappear when GOOPS is fully
-integrated into the core of Guile. Consequently, the
-procedures described in this section may disappear as well.
-
-@node Adding Methods to Generic Functions
-@section Adding Methods to Generic Functions
-
-@menu
-* Basic Method Definition::
-* Method Definition Internals::
-@end menu
-
-@node Basic Method Definition
-@subsection Basic Method Definition
-
-To add a method to a generic function, use the @code{define-method} form.
-
-@deffn syntax define-method (generic parameter @dots{}) . body
-Define a method for the generic function or accessor @var{generic} with
-parameters @var{parameter}s and body @var{body}.
-
-@var{generic} is a generic function. If @var{generic} is a variable
-which is not yet bound to a generic function object, the expansion of
-@code{define-method} will include a call to @code{define-generic}. If
-@var{generic} is @code{(setter @var{generic-with-setter})}, where
-@var{generic-with-setter} is a variable which is not yet bound to a
-generic-with-setter object, the expansion will include a call to
-@code{define-accessor}.
-
-Each @var{parameter} must be either a symbol or a two-element list
-@code{(@var{symbol} @var{class})}. The symbols refer to variables in
-the @var{body} that will be bound to the parameters supplied by the
-caller when calling this method. The @var{class}es, if present,
-specify the possible combinations of parameters to which this method
-can be applied.
-
-@var{body} is the body of the method definition.
-@end deffn
-
-@code{define-method} expressions look a little like normal Scheme
-procedure definitions of the form
-
-@example
-(define (name formals @dots{}) . body)
-@end example
-
-The most important difference is that each formal parameter, apart from the
-possible ``rest'' argument, can be qualified by a class name:
-@code{@var{formal}} becomes @code{(@var{formal} @var{class})}. The
-meaning of this qualification is that the method being defined
-will only be applicable in a particular generic function invocation if
-the corresponding argument is an instance of @code{@var{class}} (or one of
-its subclasses). If more than one of the formal parameters is qualified
-in this way, then the method will only be applicable if each of the
-corresponding arguments is an instance of its respective qualifying class.
-
-Note that unqualified formal parameters act as though they are qualified
-by the class @code{<top>}, which GOOPS uses to mean the superclass of
-all valid Scheme types, including both primitive types and GOOPS classes.
-
-For example, if a generic function method is defined with
-@var{parameter}s @code{((s1 <square>) (n <number>))}, that method is
-only applicable to invocations of its generic function that have two
-parameters where the first parameter is an instance of the
-@code{<square>} class and the second parameter is a number.
-
-If a generic function is invoked with a combination of parameters for which
-there is no applicable method, GOOPS raises an error. For more about
-invocation error handling, and generic function invocation in general,
-see @ref{Invoking Generic Functions}.
-
-@node Method Definition Internals
-@subsection Method Definition Internals
-
-@code{define-method}
-
-@itemize @bullet
-@item
-checks the form of the first parameter, and applies the following steps
-to the accessor's setter if it has the @code{(setter @dots{})} form
-
-@item
-interpolates a call to @code{define-generic} or @code{define-accessor}
-if a generic function is not already defined with the supplied name
-
-@item
-calls @code{method} with the @var{parameter}s and @var{body}, to make a
-new method instance
-
-@item
-calls @code{add-method!} to add this method to the relevant generic
-function.
-@end itemize
-
-@deffn syntax method (parameter @dots{}) . body
-Make a method whose specializers are defined by the classes in
-@var{parameter}s and whose procedure definition is constructed from the
-@var{parameter} symbols and @var{body} forms.
-
-The @var{parameter} and @var{body} parameters should be as for
-@code{define-method} (@pxref{Basic Method Definition,, define-method}).
-@end deffn
-
-@code{method}
-
-@itemize @bullet
-@item
-extracts formals and specializing classes from the @var{parameter}s,
-defaulting the class for unspecialized parameters to @code{<top>}
-
-@item
-creates a closure using the formals and the @var{body} forms
-
-@item
-calls @code{make} with metaclass @code{<method>} and the specializers
-and closure using the @code{#:specializers} and @code{#:procedure}
-keywords.
-@end itemize
-
-@deffn procedure make-method specializers procedure
-Make a method using @var{specializers} and @var{procedure}.
-
-@var{specializers} should be a list of classes that specifies the
-parameter combinations to which this method will be applicable.
-
-@var{procedure} should be the closure that will applied to the generic
-function parameters when this method is invoked.
-@end deffn
-
-@code{make-method} is a simple wrapper around @code{make} with metaclass
-@code{<method>}.
-
-@deffn generic add-method! target method
-Generic function for adding method @var{method} to @var{target}.
-@end deffn
-
-@deffn method add-method! (generic <generic>) (method <method>)
-Add method @var{method} to the generic function @var{generic}.
-@end deffn
-
-@deffn method add-method! (proc <procedure>) (method <method>)
-If @var{proc} is a procedure with generic capability (@pxref{Extending
-Guiles Primitives,, generic-capability?}), upgrade it to a
-primitive generic and add @var{method} to its generic function
-definition.
-@end deffn
-
-@deffn method add-method! (pg <primitive-generic>) (method <method>)
-Add method @var{method} to the generic function definition of @var{pg}.
-
-Implementation: @code{(add-method! (primitive-generic-generic pg) method)}.
-@end deffn
-
-@deffn method add-method! (whatever <top>) (method <method>)
-Raise an error indicating that @var{whatever} is not a valid generic
-function.
-@end deffn
-
-@node Invoking Generic Functions
-@section Invoking Generic Functions
-
-When a variable with a generic function definition appears as the first
-element of a list that is being evaluated, the Guile evaluator tries
-to apply the generic function to the arguments obtained by evaluating
-the remaining elements of the list. [ *fixme* How do I put this in a
-more Schemely and less Lispy way? ]
-
-Usually a generic function contains several method definitions, with
-varying degrees of formal parameter specialization (@pxref{Basic
-Method Definition,, define-method}). So it is necessary to sort these
-methods by specificity with respect to the supplied arguments, and then
-apply the most specific method definition. Less specific methods
-may be applied subsequently if a method that is being applied calls
-@code{next-method}.
-
-@menu
-* Determining Which Methods to Apply::
-* Handling Invocation Errors::
-@end menu
-
-@node Determining Which Methods to Apply
-@subsection Determining Which Methods to Apply
-
-[ *fixme* Sorry - this is the area of GOOPS that I understand least of
-all, so I'm afraid I have to pass on this section. Would some other
-kind person consider filling it in? ]
-
-@deffn generic apply-generic
-@deffnx method apply-generic (gf <generic>) args
-@end deffn
-
-@deffn generic compute-applicable-methods
-@deffnx method compute-applicable-methods (gf <generic>) args
-@end deffn
-
-@deffn generic sort-applicable-methods
-@deffnx method sort-applicable-methods (gf <generic>) methods args
-@end deffn
-
-@deffn generic method-more-specific?
-@deffnx method method-more-specific? (m1 <method>) (m2 <method>) args
-@end deffn
-
-@deffn generic apply-method
-@deffnx method apply-method (gf <generic>) methods build-next args
-@end deffn
-
-@deffn generic apply-methods
-@deffnx method apply-methods (gf <generic>) (l <list>) args
-@end deffn
-
-@node Handling Invocation Errors
-@subsection Handling Invocation Errors
-
-@deffn generic no-method
-@deffnx method no-method (gf <generic>) args
-When an application invokes a generic function, and no methods at all
-have been defined for that generic function, GOOPS calls the
-@code{no-method} generic function. The default method calls
-@code{goops-error} with an appropriate message.
-@end deffn
-
-@deffn generic no-applicable-method
-@deffnx method no-applicable-method (gf <generic>) args
-When an application applies a generic function to a set of arguments,
-and no methods have been defined for those argument types, GOOPS calls
-the @code{no-applicable-method} generic function. The default method
-calls @code{goops-error} with an appropriate message.
-@end deffn
-
-@deffn generic no-next-method
-@deffnx method no-next-method (gf <generic>) args
-When a generic function method calls @code{(next-method)} to invoke the
-next less specialized method for that generic function, and no less
-specialized methods have been defined for the current generic function
-arguments, GOOPS calls the @code{no-next-method} generic function. The
-default method calls @code{goops-error} with an appropriate message.
-@end deffn
-
-@node Redefining a Class
-@section Redefining a Class
-
-Suppose that a class @code{<my-class>} is defined using @code{define-class}
-(@pxref{Basic Class Definition,, define-class}), with slots that have
-accessor functions, and that an application has created several instances
-of @code{<my-class>} using @code{make} (@pxref{Basic Instance Creation,,
-make}). What then happens if @code{<my-class>} is redefined by calling
-@code{define-class} again?
-
-@menu
-* Default Class Redefinition Behaviour::
-* Customizing Class Redefinition::
-@end menu
-
-@node Default Class Redefinition Behaviour
-@subsection Default Class Redefinition Behaviour
-
-GOOPS' default answer to this question is as follows.
-
-@itemize @bullet
-@item
-All existing direct instances of @code{<my-class>} are converted to be
-instances of the new class. This is achieved by preserving the values
-of slots that exist in both the old and new definitions, and initializing the
-values of new slots in the usual way (@pxref{Basic Instance Creation,,
-make}).
-
-@item
-All existing subclasses of @code{<my-class>} are redefined, as though
-the @code{define-class} expressions that defined them were re-evaluated
-following the redefinition of @code{<my-class>}, and the class
-redefinition process described here is applied recursively to the
-redefined subclasses.
-
-@item
-Once all of its instances and subclasses have been updated, the class
-metaobject previously bound to the variable @code{<my-class>} is no
-longer needed and so can be allowed to be garbage collected.
-@end itemize
-
-To keep things tidy, GOOPS also needs to do a little housekeeping on
-methods that are associated with the redefined class.
-
-@itemize @bullet
-@item
-Slot accessor methods for slots in the old definition should be removed
-from their generic functions. They will be replaced by accessor methods
-for the slots of the new class definition.
-
-@item
-Any generic function method that uses the old @code{<my-class>} metaobject
-as one of its formal parameter specializers must be updated to refer to
-the new @code{<my-class>} metaobject. (Whenever a new generic function
-method is defined, @code{define-method} adds the method to a list stored
-in the class metaobject for each class used as a formal parameter
-specializer, so it is easy to identify all the methods that must be
-updated when a class is redefined.)
-@end itemize
-
-If this class redefinition strategy strikes you as rather counter-intuitive,
-bear in mind that it is derived from similar behaviour in other object
-systems such as CLOS, and that experience in those systems has shown it to be
-very useful in practice.
-
-Also bear in mind that, like most of GOOPS' default behaviour, it can
-be customized@dots{}
-
-@node Customizing Class Redefinition
-@subsection Customizing Class Redefinition
-
-When @code{define-class} notices that a class is being redefined,
-it constructs the new class metaobject as usual, and then invokes the
-@code{class-redefinition} generic function with the old and new classes
-as arguments. Therefore, if the old or new classes have metaclasses
-other than the default @code{<class>}, class redefinition behaviour can
-be customized by defining a @code{class-redefinition} method that is
-specialized for the relevant metaclasses.
-
-@deffn generic class-redefinition
-Handle the class redefinition from @var{old-class} to @var{new-class},
-and return the new class metaobject that should be bound to the
-variable specified by @code{define-class}'s first argument.
-@end deffn
-
-@deffn method class-redefinition (old-class <class>) (new-class <class>)
-Implements GOOPS' default class redefinition behaviour, as described in
-@ref{Default Class Redefinition Behaviour}. Returns the metaobject
-for the new class definition.
-@end deffn
-
-An alternative class redefinition strategy could be to leave all
-existing instances as instances of the old class, but accepting that the
-old class is now ``nameless'', since its name has been taken over by the
-new definition. In this strategy, any existing subclasses could also
-be left as they are, on the understanding that they inherit from a nameless
-superclass.
-
-This strategy is easily implemented in GOOPS, by defining a new metaclass,
-that will be used as the metaclass for all classes to which the strategy
-should apply, and then defining a @code{class-redefinition} method that
-is specialized for this metaclass:
-
-@example
-(define-class <can-be-nameless> (<class>))
-
-(define-method (class-redefinition (old <can-be-nameless>) (new <class>))
- new)
-@end example
-
-When customization can be as easy as this, aren't you glad that GOOPS
-implements the far more difficult strategy as its default!
-
-Finally, note that, if @code{class-redefinition} itself is not customized,
-the default @code{class-redefinition} method invokes three further
-generic functions that could be individually customized:
-
-@itemize @bullet
-@item
-(remove-class-accessors! @var{old-class})
-
-@item
-(update-direct-method! @var{method} @var{old-class} @var{new-class})
-
-@item
-(update-direct-subclass! @var{subclass} @var{old-class} @var{new-class})
-@end itemize
-
-and the default methods for these generic functions invoke further
-generic functions, and so on@dots{} The detailed protocol for all of these
-is described in @ref{MOP Specification}.
-
-@node Changing the Class of an Instance
-@section Changing the Class of an Instance
-
-You can change the class of an existing instance by invoking the
-generic function @code{change-class} with two arguments: the instance
-and the new class.
-
-@deffn generic change-class
-@end deffn
-
-The default method for @code{change-class} decides how to implement the
-change of class by looking at the slot definitions for the instance's
-existing class and for the new class. If the new class has slots with
-the same name as slots in the existing class, the values for those slots
-are preserved. Slots that are present only in the existing class are
-discarded. Slots that are present only in the new class are initialized
-using the corresponding slot definition's init function (@pxref{Classes,,
-slot-init-function}).
-
-@deffn {method} change-class (obj <object>) (new <class>)
-Modify instance @var{obj} to make it an instance of class @var{new}.
-
-The value of each of @var{obj}'s slots is preserved only if a similarly named
-slot exists in @var{new}; any other slot values are discarded.
-
-The slots in @var{new} that do not correspond to any of @var{obj}'s
-pre-existing slots are initialized according to @var{new}'s slot definitions'
-init functions.
-@end deffn
-
-Customized change of class behaviour can be implemented by defining
-@code{change-class} methods that are specialized either by the class
-of the instances to be modified or by the metaclass of the new class.
-
-When a class is redefined (@pxref{Redefining a Class}), and the default
-class redefinition behaviour is not overridden, GOOPS (eventually)
-invokes the @code{change-class} generic function for each existing
-instance of the redefined class.
-
-@node Introspection
-@section Introspection
-
-@dfn{Introspection}, also known as @dfn{reflection}, is the name given
-to the ability to obtain information dynamically about GOOPS metaobjects.
-It is perhaps best illustrated by considering an object oriented language
-that does not provide any introspection, namely C++.
-
-Nothing in C++ allows a running program to obtain answers to the following
-types of question:
-
-@itemize @bullet
-@item
-What are the data members of this object or class?
-
-@item
-What classes does this class inherit from?
-
-@item
-Is this method call virtual or non-virtual?
-
-@item
-If I invoke @code{Employee::adjustHoliday()}, what class contains the
-@code{adjustHoliday()} method that will be applied?
-@end itemize
-
-In C++, answers to such questions can only be determined by looking at
-the source code, if you have access to it. GOOPS, on the other hand,
-includes procedures that allow answers to these questions --- or their
-GOOPS equivalents --- to be obtained dynamically, at run time.
-
-@menu
-* Classes::
-* Slots::
-* Instances::
-* Generic Functions::
-* Generic Function Methods::
-@end menu
-
-@node Classes
-@subsection Classes
-
-@deffn {primitive procedure} class-name class
-Return the name of class @var{class}.
-This is the value of the @var{class} metaobject's @code{name} slot.
-@end deffn
-
-@deffn {primitive procedure} class-direct-supers class
-Return a list containing the direct superclasses of @var{class}.
-This is the value of the @var{class} metaobject's
-@code{direct-supers} slot.
-@end deffn
-
-@deffn {primitive procedure} class-direct-slots class
-Return a list containing the slot definitions of the direct slots of
-@var{class}.
-This is the value of the @var{class} metaobject's @code{direct-slots}
-slot.
-@end deffn
-
-@deffn {primitive procedure} class-direct-subclasses class
-Return a list containing the direct subclasses of @var{class}.
-This is the value of the @var{class} metaobject's
-@code{direct-subclasses} slot.
-@end deffn
-
-@deffn {primitive procedure} class-direct-methods class
-Return a list of all the generic function methods that use @var{class}
-as a formal parameter specializer.
-This is the value of the @var{class} metaobject's @code{direct-methods}
-slot.
-@end deffn
-
-@deffn {primitive procedure} class-precedence-list class
-Return the class precedence list for class @var{class} (@pxref{Class
-precedence list}).
-This is the value of the @var{class} metaobject's @code{cpl} slot.
-@end deffn
-
-@deffn {primitive procedure} class-slots class
-Return a list containing the slot definitions for all @var{class}'s slots,
-including any slots that are inherited from superclasses.
-This is the value of the @var{class} metaobject's @code{slots} slot.
-@end deffn
-
-@deffn {primitive procedure} class-environment class
-Return the value of @var{class}'s @code{environment} slot.
-[ *fixme* I don't know what this value is used for. ]
-@end deffn
-
-@deffn procedure class-subclasses class
-Return a list of all subclasses of @var{class}.
-@end deffn
-
-@deffn procedure class-methods class
-Return a list of all methods that use @var{class} or a subclass of
-@var{class} as one of its formal parameter specializers.
-@end deffn
-
-@node Slots
-@subsection Slots
-
-@deffn procedure class-slot-definition class slot-name
-Return the slot definition for the slot named @var{slot-name} in class
-@var{class}. @var{slot-name} should be a symbol.
-@end deffn
-
-@deffn procedure slot-definition-name slot-def
-Extract and return the slot name from @var{slot-def}.
-@end deffn
-
-@deffn procedure slot-definition-options slot-def
-Extract and return the slot options from @var{slot-def}.
-@end deffn
-
-@deffn procedure slot-definition-allocation slot-def
-Extract and return the slot allocation option from @var{slot-def}. This
-is the value of the @code{#:allocation} keyword (@pxref{Slot Options,,
-allocation}), or @code{#:instance} if the @code{#:allocation} keyword is
-absent.
-@end deffn
-
-@deffn procedure slot-definition-getter slot-def
-Extract and return the slot getter option from @var{slot-def}. This is
-the value of the @code{#:getter} keyword (@pxref{Slot Options,,
-getter}), or @code{#f} if the @code{#:getter} keyword is absent.
-@end deffn
-
-@deffn procedure slot-definition-setter slot-def
-Extract and return the slot setter option from @var{slot-def}. This is
-the value of the @code{#:setter} keyword (@pxref{Slot Options,,
-setter}), or @code{#f} if the @code{#:setter} keyword is absent.
-@end deffn
-
-@deffn procedure slot-definition-accessor slot-def
-Extract and return the slot accessor option from @var{slot-def}. This
-is the value of the @code{#:accessor} keyword (@pxref{Slot Options,,
-accessor}), or @code{#f} if the @code{#:accessor} keyword is absent.
-@end deffn
-
-@deffn procedure slot-definition-init-value slot-def
-Extract and return the slot init-value option from @var{slot-def}. This
-is the value of the @code{#:init-value} keyword (@pxref{Slot Options,,
-init-value}), or the unbound value if the @code{#:init-value} keyword is
-absent.
-@end deffn
-
-@deffn procedure slot-definition-init-form slot-def
-Extract and return the slot init-form option from @var{slot-def}. This
-is the value of the @code{#:init-form} keyword (@pxref{Slot Options,,
-init-form}), or the unbound value if the @code{#:init-form} keyword is
-absent.
-@end deffn
-
-@deffn procedure slot-definition-init-thunk slot-def
-Extract and return the slot init-thunk option from @var{slot-def}. This
-is the value of the @code{#:init-thunk} keyword (@pxref{Slot Options,,
-init-thunk}), or @code{#f} if the @code{#:init-thunk} keyword is absent.
-@end deffn
-
-@deffn procedure slot-definition-init-keyword slot-def
-Extract and return the slot init-keyword option from @var{slot-def}.
-This is the value of the @code{#:init-keyword} keyword (@pxref{Slot
-Options,, init-keyword}), or @code{#f} if the @code{#:init-keyword}
-keyword is absent.
-@end deffn
-
-@deffn procedure slot-init-function class slot-name
-Return the initialization function for the slot named @var{slot-name} in
-class @var{class}. @var{slot-name} should be a symbol.
-
-The returned initialization function incorporates the effects of the
-standard @code{#:init-thunk}, @code{#:init-form} and @code{#:init-value}
-slot options. These initializations can be overridden by the
-@code{#:init-keyword} slot option or by a specialized @code{initialize}
-method, so, in general, the function returned by
-@code{slot-init-function} may be irrelevant. For a fuller discussion,
-see @ref{Slot Options,, init-value}.
-@end deffn
-
-@node Instances
-@subsection Instances
-
-@deffn {primitive procedure} class-of value
-Return the GOOPS class of any Scheme @var{value}.
-@end deffn
-
-@deffn {primitive procedure} instance? object
-Return @code{#t} if @var{object} is any GOOPS instance, otherwise
-@code{#f}.
-@end deffn
-
-@deffn procedure is-a? object class
-Return @code{#t} if @var{object} is an instance of @var{class} or one of
-its subclasses.
-@end deffn
-
-Implementation notes: @code{is-a?} uses @code{class-of} and
-@code{class-precedence-list} to obtain the class precedence list for
-@var{object}.
-
-@node Generic Functions
-@subsection Generic Functions
-
-@deffn {primitive procedure} generic-function-name gf
-Return the name of generic function @var{gf}.
-@end deffn
-
-@deffn {primitive procedure} generic-function-methods gf
-Return a list of the methods of generic function @var{gf}.
-This is the value of the @var{gf} metaobject's @code{methods} slot.
-@end deffn
-
-@node Generic Function Methods
-@subsection Generic Function Methods
-
-@deffn {primitive procedure} method-generic-function method
-Return the generic function that @var{method} belongs to.
-This is the value of the @var{method} metaobject's
-@code{generic-function} slot.
-@end deffn
-
-@deffn {primitive procedure} method-specializers method
-Return a list of @var{method}'s formal parameter specializers .
-This is the value of the @var{method} metaobject's
-@code{specializers} slot.
-@end deffn
-
-@deffn {primitive procedure} method-procedure method
-Return the procedure that implements @var{method}.
-This is the value of the @var{method} metaobject's
-@code{procedure} slot.
-@end deffn
-
-@deffn generic method-source
-@deffnx method method-source (m <method>)
-Return an expression that prints to show the definition of method
-@var{m}.
-
-@example
-(define-generic cube)
-
-(define-method (cube (n <number>))
- (* n n n))
-
-(map method-source (generic-function-methods cube))
-@result{}
-((method ((n <number>)) (* n n n)))
-@end example
-@end deffn
-
-@node Miscellaneous Functions
-@section Miscellaneous Functions
-
-@menu
-* Administrative Functions::
-* Error Handling::
-* Object Comparisons::
-* Cloning Objects::
-* Write and Display::
-@end menu
-
-@node Administrative Functions
-@subsection Administration Functions
-
-This section describes administrative, non-technical GOOPS functions.
-
-@deffn primitive goops-version
-Return the current GOOPS version as a string, for example ``0.2''.
-@end deffn
-
-@node Error Handling
-@subsection Error Handling
-
-The procedure @code{goops-error} is called to raise an appropriate error
-by the default methods of the following generic functions:
-
-@itemize @bullet
-@item
-@code{slot-missing} (@pxref{Handling Slot Access Errors,, slot-missing})
-
-@item
-@code{slot-unbound} (@pxref{Handling Slot Access Errors,, slot-unbound})
-
-@item
-@code{no-method} (@pxref{Handling Invocation Errors,, no-method})
-
-@item
-@code{no-applicable-method} (@pxref{Handling Invocation Errors,,
-no-applicable-method})
-
-@item
-@code{no-next-method} (@pxref{Handling Invocation Errors,,
-no-next-method})
-@end itemize
-
-If you customize these functions for particular classes or metaclasses,
-you may still want to use @code{goops-error} to signal any error
-conditions that you detect.
-
-@deffn procedure goops-error format-string . args
-Raise an error with key @code{goops-error} and error message constructed
-from @var{format-string} and @var{args}. Error message formatting is
-as done by @code{scm-error}.
-@end deffn
-
-@node Object Comparisons
-@subsection Object Comparisons
-
-@deffn generic object-eqv?
-@deffnx method object-eqv? ((x <top>) (y <top>))
-@deffnx generic object-equal?
-@deffnx method object-equal? ((x <top>) (y <top>))
-Generic functions and default (unspecialized) methods for comparing two
-GOOPS objects.
-
-The default methods always return @code{#f}. Application class authors
-may wish to define specialized methods for @code{object-eqv?} and
-@code{object-equal?} that compare instances of the same class for
-equality in whatever sense is useful to the application.
-@end deffn
-
-@node Cloning Objects
-@subsection Cloning Objects
-
-@deffn generic shallow-clone
-@deffnx method shallow-clone (self <object>)
-Return a ``shallow'' clone of @var{self}. The default method makes a
-shallow clone by allocating a new instance and copying slot values from
-self to the new instance. Each slot value is copied either as an
-immediate value or by reference.
-@end deffn
-
-@deffn generic deep-clone
-@deffnx method deep-clone (self <object>)
-Return a ``deep'' clone of @var{self}. The default method makes a deep
-clone by allocating a new instance and copying or cloning slot values
-from self to the new instance. If a slot value is an instance
-(satisfies @code{instance?}), it is cloned by calling @code{deep-clone}
-on that value. Other slot values are copied either as immediate values
-or by reference.
-@end deffn
-
-@node Write and Display
-@subsection Write and Display
-
-@deffn {primitive generic} write object port
-@deffnx {primitive generic} display object port
-When GOOPS is loaded, @code{write} and @code{display} become generic
-functions with special methods for printing
-
-@itemize @bullet
-@item
-objects - instances of the class @code{<object>}
-
-@item
-foreign objects - instances of the class @code{<foreign-object>}
-
-@item
-classes - instances of the class @code{<class>}
-
-@item
-generic functions - instances of the class @code{<generic>}
-
-@item
-methods - instances of the class @code{<method>}.
-@end itemize
-
-@code{write} and @code{display} print non-GOOPS values in the same way
-as the Guile primitive @code{write} and @code{display} functions.
-@end deffn
-
-@node MOP Specification, Tutorial, Reference Manual, Top
-@chapter MOP Specification
-
-For an introduction to metaobjects and the metaobject protocol,
-see @ref{Metaobjects and the Metaobject Protocol}.
-
-The aim of the MOP specification in this chapter is to specify all the
-customizable generic function invocations that can be made by the standard
-GOOPS syntax, procedures and methods, and to explain the protocol for
-customizing such invocations.
-
-A generic function invocation is customizable if the types of the arguments
-to which it is applied are not all determined by the lexical context in
-which the invocation appears. For example,
-
-@itemize @bullet
-@item
-the @code{(initialize @var{instance} @var{initargs})} invocation in the
-default @code{make-instance} method is customizable, because the type of the
-@code{@var{instance}} argument is determined by the class that was passed to
-@code{make-instance}.
-
-@item
-the @code{(make <generic> #:name ',name)} invocation in @code{define-generic}
-is not customizable, because all of its arguments have lexically determined
-types.
-@end itemize
-
-When using this rule to decide whether a given generic function invocation
-is customizable, we ignore arguments that are expected to be handled in
-method definitions as a single ``rest'' list argument.
-
-For each customizable generic function invocation, the @dfn{invocation
-protocol} is explained by specifying
-
-@itemize @bullet
-@item
-what, conceptually, the applied method is intended to do
-
-@item
-what assumptions, if any, the caller makes about the applied method's side
-effects
-
-@item
-what the caller expects to get as the applied method's return value.
-@end itemize
-
-@menu
-* Class Definition::
-* Instance Creation::
-* Class Redefinition::
-* Method Definition::
-* Generic Function Invocation::
-@end menu
-
-@node Class Definition
-@section Class Definition
-
-@code{define-class} (syntax)
-
-@itemize @bullet
-@item
-@code{class} (syntax)
-
-@itemize @bullet
-@item
-@code{make-class} (procedure)
-
-@itemize @bullet
-@item
-@code{make @var{metaclass} @dots{}} (generic)
-
-@var{metaclass} is the metaclass of the class being defined, either
-taken from the @code{#:metaclass} class option or computed by
-@code{ensure-metaclass}. The applied method must create and return the
-fully initialized class metaobject for the new class definition.
-@end itemize
-
-@end itemize
-
-@item
-@code{class-redefinition @var{old-class} @var{new-class}} (generic)
-
-@code{define-class} calls @code{class-redefinition} if the variable
-specified by its first argument already held a GOOPS class definition.
-@var{old-class} and @var{new-class} are the old and new class metaobjects.
-The applied method should perform whatever is necessary to handle the
-redefinition, and should return the class metaobject that is to be bound
-to @code{define-class}'s variable. The default class redefinition
-protocol is described in @ref{Class Redefinition}.
-@end itemize
-
-The @code{(make @var{metaclass} @dots{})} invocation above will create
-an class metaobject with metaclass @var{metaclass}. By default, this
-metaobject will be initialized by the @code{initialize} method that is
-specialized for instances of type @code{<class>}.
-
-@code{initialize <class> @var{initargs}} (method)
-
-@itemize @bullet
-@item
-@code{compute-cpl @var{class}} (generic)
-
-The applied method should compute and return the class precedence list
-for @var{class} as a list of class metaobjects. When @code{compute-cpl}
-is called, the following @var{class} metaobject slots have all been
-initialized: @code{name}, @code{direct-supers}, @code{direct-slots},
-@code{direct-subclasses} (empty), @code{direct-methods}. The value
-returned by @code{compute-cpl} will be stored in the @code{cpl} slot.
-
-@item
-@code{compute-slots @var{class}} (generic)
-
-The applied method should compute and return the slots (union of direct
-and inherited) for @var{class} as a list of slot definitions. When
-@code{compute-slots} is called, all the @var{class} metaobject slots
-mentioned for @code{compute-cpl} have been initialized, plus the
-following: @code{cpl}, @code{redefined} (@code{#f}), @code{environment}.
-The value returned by @code{compute-slots} will be stored in the
-@code{slots} slot.
-
-@item
-@code{compute-get-n-set @var{class} @var{slot-def}} (generic)
-
-@code{initialize} calls @code{compute-get-n-set} for each slot computed
-by @code{compute-slots}. The applied method should compute and return a
-pair of closures that, respectively, get and set the value of the specified
-slot. The get closure should have arity 1 and expect a single argument
-that is the instance whose slot value is to be retrieved. The set closure
-should have arity 2 and expect two arguments, where the first argument is
-the instance whose slot value is to be set and the second argument is the
-new value for that slot. The closures should be returned in a two element
-list: @code{(list @var{get} @var{set})}.
-
-The closures returned by @code{compute-get-n-set} are stored as part of
-the value of the @var{class} metaobject's @code{getters-n-setters} slot.
-Specifically, the value of this slot is a list with the same number of
-elements as there are slots in the class, and each element looks either like
-
-@example
-@code{(@var{slot-name-symbol} @var{init-function} . @var{index})}
-@end example
-
-or like
-
-@example
-@code{(@var{slot-name-symbol} @var{init-function} @var{get} @var{set})}
-@end example
-
-Where the get and set closures are replaced by @var{index}, the slot is
-an instance slot and @var{index} is the slot's index in the underlying
-structure: GOOPS knows how to get and set the value of such slots and so
-does not need specially constructed get and set closures. Otherwise,
-@var{get} and @var{set} are the closures returned by @code{compute-get-n-set}.
-
-The structure of the @code{getters-n-setters} slot value is important when
-understanding the next customizable generic functions that @code{initialize}
-calls@dots{}
-
-@item
-@code{compute-getter-method @var{class} @var{gns}} (generic)
-
-@code{initialize} calls @code{compute-getter-method} for each of the class's
-slots (as determined by @code{compute-slots}) that includes a
-@code{#:getter} or @code{#:accessor} slot option. @var{gns} is the
-element of the @var{class} metaobject's @code{getters-n-setters} slot that
-specifies how the slot in question is referenced and set, as described
-above under @code{compute-get-n-set}. The applied method should create
-and return a method that is specialized for instances of type @var{class}
-and uses the get closure to retrieve the slot's value. [ *fixme Need
-to insert something here about checking that the value is not unbound. ]
-@code{initialize} uses @code{add-method!} to add the returned method to
-the generic function named by the slot definition's @code{#:getter} or
-@code{#:accessor} option.
-
-@item
-@code{compute-setter-method @var{class} @var{gns}} (generic)
-
-@code{compute-setter-method} is invoked with the same arguments as
-@code{compute-getter-method}, for each of the class's slots that includes
-a @code{#:setter} or @code{#:accessor} slot option. The applied method
-should create and return a method that is specialized for instances of
-type @var{class} and uses the set closure to set the slot's value.
-@code{initialize} then uses @code{add-method!} to add the returned method
-to the generic function named by the slot definition's @code{#:setter}
-or @code{#:accessor} option.
-@end itemize
-
-@node Instance Creation
-@section Instance Creation
-
-@code{make <class> . @var{initargs}} (method)
-
-@itemize @bullet
-@item
-@code{allocate-instance @var{class} @var{initargs}} (generic)
-
-The applied @code{allocate-instance} method should allocate storage for
-a new instance of class @var{class} and return the uninitialized instance.
-
-@item
-@code{initialize @var{instance} @var{initargs}} (generic)
-
-@var{instance} is the uninitialized instance returned by
-@code{allocate-instance}. The applied method should initialize the new
-instance in whatever sense is appropriate for its class. The method's
-return value is ignored.
-@end itemize
-
-@node Class Redefinition
-@section Class Redefinition
-
-The default @code{class-redefinition} method, specialized for classes
-with the default metaclass @code{<class>}, has the following internal
-protocol.
-
-[ *fixme* I'm not sure that I understand this sufficiently to explain
-it. Also, the internals of the default class redefinition method are
-extremely implementation-specific, and I'm not sure that there is that
-much point trying to describe the internal protocol such that it could
-be customized without going to look at the source code. ]
-
-@code{class-redefinition @var{(old <class>)} @var{(new <class>)}}
-(method)
-
-@itemize @bullet
-@item
-@code{remove-class-accessors! @var{old}} (generic)
-
-@item
-@code{update-direct-method! @var{method} @var{old} @var{new}} (generic)
-
-@item
-@code{update-direct-subclass! @var{subclass} @var{old} @var{new}} (generic)
-@end itemize
-
-The default @code{update-direct-subclass!} method invokes
-@code{class-redefinition} recursively to handle the redefinition of the
-subclass.
-
-When a class is redefined, any existing instance of the redefined class
-will be modified for the new class definition before the next time that
-any of the instance's slot is referenced or set. GOOPS modifies each
-instance by calling the generic function @code{change-class}. [ *fixme*
-Actually it sometimes calls @code{change-class} and sometimes
-@code{change-object-class}, and I don't understand why. ]
-
-The default @code{change-class} method copies slot values from the old
-to the modified instance, and initializes new slots, as described in
-@ref{Changing the Class of an Instance}. After doing so, it makes a
-generic function invocation that can be used to customize the instance
-update algorithm.
-
-@code{change-class @var{(old-instance <object>)} @var{(new <class>)}} (method)
-
-@itemize @bullet
-@item
-@code{update-instance-for-different-class @var{old-instance} @var{new-instance}} (generic)
-
-@code{change-class} invokes @code{update-instance-for-different-class}
-as the last thing that it does before returning. The applied method can
-make any further adjustments to @var{new-instance} that are required to
-complete or modify the change of class. The return value from the
-applied method is ignored.
-
-The default @code{update-instance-for-different-class} method does
-nothing.
-@end itemize
-
-@node Method Definition
-@section Method Definition
-
-@code{define-method} (syntax)
-
-@itemize @bullet
-@item
-@code{add-method! @var{target} @var{method}} (generic)
-
-@code{define-method} invokes the @code{add-method!} generic function to
-handle adding the new method to a variety of possible targets. GOOPS
-includes methods to handle @var{target} as
-
-@itemize @bullet
-@item
-a generic function (the most common case)
-
-@item
-a procedure
-
-@item
-a primitive generic (@pxref{Extending Guiles Primitives})
-@end itemize
-
-By defining further methods for @code{add-method!}, you can
-theoretically handle adding methods to further types of target.
-@end itemize
-
-@node Generic Function Invocation
-@section Generic Function Invocation
-
-[ *fixme* Description required here. ]
-
-@code{apply-generic}
-
-@itemize @bullet
-@item
-@code{no-method}
-
-@item
-@code{compute-applicable-methods}
-
-@item
-@code{sort-applicable-methods}
-
-@item
-@code{apply-methods}
-
-@item
-@code{no-applicable-method}
-@end itemize
-
-@code{sort-applicable-methods}
-
-@itemize @bullet
-@item
-@code{method-more-specific?}
-@end itemize
-
-@code{apply-methods}
-
-@itemize @bullet
-@item
-@code{apply-method}
-@end itemize
-
-@code{next-method}
-
-@itemize @bullet
-@item
-@code{no-next-method}
-@end itemize
-
-@node Tutorial, Index, MOP Specification, Top
-@chapter Tutorial
-@include goops-tutorial.texi
-
-@node Index, Concept Index, Tutorial, Top
-@chapter Index
-@page
-@node Concept Index, Function and Variable Index, Index, Top
-@unnumberedsec Concept Index
-
-@printindex cp
-
-@node Function and Variable Index, , Concept Index, Top
-@unnumberedsec Function and Variable Index
-
-@printindex fn
-
-@summarycontents
-@contents
-@bye
diff --git a/doc/goops/hierarchy.eps b/doc/goops/hierarchy.eps
deleted file mode 100644
index 7b1a98605..000000000
--- a/doc/goops/hierarchy.eps
+++ /dev/null
@@ -1,127 +0,0 @@
-%!PS-Adobe-2.0 EPSF
-%%Title: /tmp/xfig-fig016295
-%%Creator: fig2dev
-%%CreationDate: Fri Jun 10 23:18:16 1994
-%%For: eg@kaolin (Erick Gallesio)
-%%BoundingBox: 0 0 361 217
-%%Pages: 0
-%%EndComments
-/$F2psDict 200 dict def
-$F2psDict begin
-$F2psDict /mtrx matrix put
-/l {lineto} bind def
-/m {moveto} bind def
-/s {stroke} bind def
-/n {newpath} bind def
-/gs {gsave} bind def
-/gr {grestore} bind def
-/clp {closepath} bind def
-/graycol {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
-4 -2 roll mul setrgbcolor} bind def
-/col-1 {} def
-/col0 {0 0 0 setrgbcolor} bind def
-/col1 {0 0 1 setrgbcolor} bind def
-/col2 {0 1 0 setrgbcolor} bind def
-/col3 {0 1 1 setrgbcolor} bind def
-/col4 {1 0 0 setrgbcolor} bind def
-/col5 {1 0 1 setrgbcolor} bind def
-/col6 {1 1 0 setrgbcolor} bind def
-/col7 {1 1 1 setrgbcolor} bind def
- end
-/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
-/$F2psEnd {$F2psEnteredState restore end} def
-%%EndProlog
-
-$F2psBegin
-0 setlinecap 0 setlinejoin
--216.0 288.0 translate 0.900 -0.900 scale
-0.500 setlinewidth
-n 309 159 m 309 159 l gs col-1 s gr
-n 246.401 216.889 m 244.000 209.000 l 249.831 214.831 l gs 2 setlinejoin col-1 s gr
-% Polyline
-n 244 209 m 274 259 l gs col-1 s gr
-n 298.169 214.831 m 304.000 209.000 l 301.599 216.889 l gs 2 setlinejoin col-1 s gr
-% Polyline
-n 304 209 m 274 259 l gs col-1 s gr
-n 255.721 213.778 m 249.000 209.000 l 257.179 210.053 l gs 2 setlinejoin col-1 s gr
-% Polyline
-n 249 209 m 364 254 l gs col-1 s gr
-n 370.312 216.376 m 374.000 209.000 l 374.217 217.243 l gs 2 setlinejoin col-1 s gr
-% Polyline
-n 374 209 m 364 254 l gs col-1 s gr
-n 283.772 280.725 m 279.000 274.000 l 286.376 277.688 l gs 2 setlinejoin col-1 s gr
-% Polyline
-n 279 274 m 314 304 l gs col-1 s gr
-n 351.457 272.333 m 359.000 269.000 l 353.913 275.490 l gs 2 setlinejoin col-1 s gr
-% Polyline
-n 359 269 m 314 304 l gs col-1 s gr
-n 300.950 165.789 m 309.000 164.000 l 302.739 169.367 l gs 2 setlinejoin col-1 s gr
-% Polyline
-n 309 164 m 249 194 l gs col-1 s gr
-n 307.000 172.000 m 309.000 164.000 l 311.000 172.000 l gs 2 setlinejoin col-1 s gr
-% Polyline
-n 309 164 m 309 199 l gs col-1 s gr
-n 315.261 169.367 m 309.000 164.000 l 317.050 165.789 l gs 2 setlinejoin col-1 s gr
-% Polyline
-n 309 164 m 379 199 l gs col-1 s gr
-n 406.949 101.701 m 404.000 94.000 l 410.226 99.407 l gs 2 setlinejoin col-1 s gr
-% Polyline
-n 404 94 m 439 144 l gs col-1 s gr
-n 410.363 99.245 m 404.000 94.000 l 412.083 95.634 l gs 2 setlinejoin col-1 s gr
-% Polyline
-n 404 94 m 509 144 l gs col-1 s gr
-n 411.173 98.068 m 404.000 94.000 l 412.243 94.214 l gs 2 setlinejoin col-1 s gr
-% Polyline
-n 404 94 m 584 144 l gs col-1 s gr
-n 396.075 96.277 m 404.000 94.000 l 398.079 99.739 l gs 2 setlinejoin col-1 s gr
-% Polyline
-n 404 94 m 309 149 l gs col-1 s gr
-% Polyline
-n 584 229 m 584 204 l gs col-1 s gr
-n 582.000 212.000 m 584.000 204.000 l 586.000 212.000 l gs 2 setlinejoin col-1 s gr
-% Polyline
-n 584 189 m 584 159 l gs col-1 s gr
-n 582.000 167.000 m 584.000 159.000 l 586.000 167.000 l gs 2 setlinejoin col-1 s gr
-/Times-Bold findfont 12.00 scalefont setfont
-239 209 m
-gs 1 -1 scale (A) col-1 show gr
-/Times-Bold findfont 12.00 scalefont setfont
-274 274 m
-gs 1 -1 scale (D) col-1 show gr
-/Times-Bold findfont 12.00 scalefont setfont
-359 269 m
-gs 1 -1 scale (E) col-1 show gr
-/Times-Bold findfont 12.00 scalefont setfont
-304 209 m
-gs 1 -1 scale (B) col-1 show gr
-/Times-Bold findfont 12.00 scalefont setfont
-374 209 m
-gs 1 -1 scale (C) col-1 show gr
-/Times-Bold findfont 12.00 scalefont setfont
-314 319 m
-gs 1 -1 scale (F) col-1 show gr
-/Times-Bold findfont 12.00 scalefont setfont
-289 159 m
-gs 1 -1 scale (<object>) col-1 show gr
-/Times-Bold findfont 12.00 scalefont setfont
-389 89 m
-gs 1 -1 scale (<top>) col-1 show gr
-/Times-Bold findfont 12.00 scalefont setfont
-424 154 m
-gs 1 -1 scale (<pair>) col-1 show gr
-/Times-Bold findfont 12.00 scalefont setfont
-474 154 m
-gs 1 -1 scale (<procedure>) col-1 show gr
-/Times-Bold findfont 12.00 scalefont setfont
-559 154 m
-gs 1 -1 scale (<number>) col-1 show gr
-/Times-Bold findfont 12.00 scalefont setfont
-629 154 m
-gs 1 -1 scale (...) col-1 show gr
-/Times-Bold findfont 12.00 scalefont setfont
-569 199 m
-gs 1 -1 scale (<real>) col-1 show gr
-/Times-Bold findfont 12.00 scalefont setfont
-559 239 m
-gs 1 -1 scale (<integer>) col-1 show gr
-$F2psEnd
diff --git a/doc/goops/hierarchy.txt b/doc/goops/hierarchy.txt
deleted file mode 100644
index c7992df7b..000000000
--- a/doc/goops/hierarchy.txt
+++ /dev/null
@@ -1,14 +0,0 @@
- <top>
- / \\\_____________________
- / \\___________ \
- / \ \ \
- <object> <pair> <procedure> <number>
- / | \ |
- / | \ |
- A B C <complex>
- |\__/__ | |
- \ / \ / |
- D E <real>
- \ / |
- F |
- <integer>
diff --git a/doc/goops/mop.text b/doc/goops/mop.text
deleted file mode 100644
index 0180f2c1e..000000000
--- a/doc/goops/mop.text
+++ /dev/null
@@ -1,66 +0,0 @@
-*** NOTE: This information needs updating! ***
-
-P - procedure
-L - local procedure
-S - syntax
-G - generic
-M - method
-
-define-class (S)
- make-class (S)
- ensure-metaclass (P)
- ensure-metaclass-with-supers (P)
- make (G)
- ensure-class (P)
- make (G)
- class-redefinition (G)
- remove-class-accessors (G)
- update-direct-method (G)
- update-direct-subclass (G)
-
-define-generic (S)
- make-generic-function (S)
- ensure-generic-function (P)
- make (G)
-
-define-method (S)
- ensure-method (P)
- ensure-generic-function (P)
- make (G)
- make (G)
- add-method (P)
-
-method (S)
- ensure-method (P)
-
-initialize (class) (M)
- compute-cpl (P)
- compute-slots (G)
- compute-getters-n-setters (P)
- compute-slot-init-function (L)
- compute-get-n-set (G)
- compute-slot-accessors (P)
- ensure-method (P)
- %inherit-magic! (P)
- %prep-layout! (P)
-
-initialize (generic) (M)
- make (G)
-
-change-class (G)
- change-object-class (P)
- update-instance-for-different-class (G)
-
-make = make-instance (G)
- allocate-instance (G)
- %allocate-instance (P)
- initialize (G)
- %initialize-object (P)
-
-apply-generic (G)
- compute-applicable-methods (G)
- find-method (P)
- sort-applicable-methods (G)
- sort (P)
- apply-methods (G)
- apply-method (G)
diff --git a/doc/groupings.alist b/doc/groupings.alist
deleted file mode 100644
index df198631c..000000000
--- a/doc/groupings.alist
+++ /dev/null
@@ -1,176 +0,0 @@
-;;; groupings.alist -*-scheme-*-
-
-;; Copyright (C) 2002 Free Software Foundation, Inc.
-;;
-;; This program 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 2, or
-;; (at your option) any later version.
-;;
-;; This program 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 this software; see the file COPYING. If not, write to
-;; the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
-;; Boston, MA 02111-1307 USA
-
-;;; Commentary:
-
-;; This file describes interface element groupings.
-;; See (scripts scan-api) commentary for more info.
-;; NOTE: Order matters; put simple ones first, composites after.
-;;
-;; TODO: Add goops, add math, etc etc.
-;; Group `guile-C-API' needs much more serious thought.
-
-;;; Code:
-
-(
-
- ;; Integrity checks
-
- (C+scheme
- (description "in both groups `scheme' and `C' -- should be empty!")
- (grok () (lambda (x)
- (and (in-group? x 'Scheme)
- (in-group? x 'C)))))
-
- ;; Embedded foreign libraries
-
- (embedded-libltdl
- (description "begins with lt_ -- should become empty over time")
- (grok () (lambda (x)
- (name-prefix? x "lt_"))))
-
- ;; By name
-
- (libguile-internal
- (description "begins with scm_i_")
- (grok () (lambda (x)
- (name-prefix? x "scm_i_"))))
-
- (gdb
- (description "begins with gdb_")
- (grok () (lambda (x)
- (name-prefix? x "gdb_"))))
-
- (coop
- (description "begins with coop_")
- (grok () (lambda (x)
- (name-prefix? x "coop_"))))
-
- (gh
- (description "begins with gh_")
- (grok () (lambda (x)
- (name-prefix? x "gh_"))))
-
- (g-fdes
- (description "begins with g and ends with fds")
- (grok () (lambda (x)
- (name-prefix? x "g.+fds$"))))
-
- (r-fdes
- (description "begins with r and ends with fds")
- (grok () (lambda (x)
- (name-prefix? x "r.+fds$"))))
-
- (scm
- (description "begins with scm_")
- (grok () (lambda (x)
- (name-prefix? x "scm_"))))
-
- (k
- (description "constants")
- (grok () (lambda (x)
- (name-prefix? x "[_A-Z0-9]+$"))))
-
- (POSIX
- (description "POSIX support")
- (members ; from docs
-
- ;; ports and file descriptors
- port-revealed set-port-revealed! fileno port->fdes fdopen fdes->ports
- fdes->inport fdes->outport primitive-move->fdes move->fdes
- release-port-handle fsync open open-fdes close close-fdes unread-char
- unread-string pipe dup->fdes dup->inport dup->outport dup dup->port
- duplicate-port redirect-port dup2 port-mode close-all-ports-except
- port-for-each setvbuf fcntl flock select
- O_RDONLY O_WRONLY O_RDWR O_APPEND O_CREAT _IONBF _IOLBF _IOFBF
- F_DUPFD F_GETFD F_SETFD F_GETFL F_SETFL F_GETOWN F_SETOWN FD_CLOEXEC
- LOCK_SH LOCK_EX LOCK_UN LOCK_NB
-
- ;; file system
- access? stat lstat readlink chown chmod utime delete-file copy-file
- rename-file link symlink mkdir rmdir opendir directory-stream? readdir
- rewinddir closedir sync mknod tmpnam mkstemp! dirname basename
- R_OK W_OK X_OK F_OK
- stat:perms stat:type stat:blocks stat:blksize stat:ctime stat:mtime
- stat:atime stat:size stat:rdev stat:gid stat:uid stat:nlink stat:mode
- stat:ino stat:dev
-
- ;; user information
- passwd:name passwd:passwd passwd:uid passwd:gid passwd:gecos passwd:dir
- passwd:shell group:name group:passwd group:gid group:mem
- getpwuid getpwnam name setpwent getpwent endpwent setpw getpw getgrgid
- getgrnam setgrent getgrent endgrent setgr getgr cuserid getlogin
-
- ;; time
- tm:sec set-tm:sec tm:min set-tm:min tm:hour set-tm:hour tm:mday set-tm:mday
- tm:mon set-tm:mon tm:year set-tm:year tm:wday set-tm:wday tm:yday
- set-tm:yday tm:isdst set-tm:isdst tm:gmtoff set-tm:gmtoff tm:zone
- set-tm:zone tms:clock tms:utime tms:stime tms:cutime tms:cstime
- current-time gettimeofday localtime gmtime mktime tzset strftime strptime
- times get-internal-real-time get-internal-run-time
-
- ;; runtime environment
- program-arguments command-line getenv setenv environ putenv
-
- ;; proceses
- chdir getcwd umask chroot getpid getgroups getppid getuid getgid geteuid
- getegid setuid setgid seteuid setegid getpgrp setpgid setsid waitpid
- status:exit-val status:term-sig status:stop-sig system primitive-exit execl
- execlp execle primitive-fork nice setpriority getpriority
- WNOHANG WUNTRACED
-
- ;; signals
- kill raise sigaction restore-signals alarm pause sleep usleep setitimer
- getitimer SIGHUP SIGINT
-
- ;; terminals and ptys
- isatty? ttyname ctermid tcgetpgrp tcsetpgrp
-
- ;; pipes -- not included because they are in (ice-9 popen)
-
- ;; system identification
- utsname:sysname utsname:nodename utsname:release utsname:version
- utsname:machine uname gethostname sethostname software-type
-
- ;; locales
- setlocale
- LC_ALL LC_COLLATE LC_CTYPE LC_MESSAGES LC_MONETARY LC_NUMERIC LC_TIME
-
- ;; encryption
- crypt getpass))
-
- (math
- (description "math functions")
- (members $abs $acos $acosh $asin $asinh $atan $atan2 $atanh $cos $cosh
- $exp $expt $log $sin $sinh $sqrt $tan $tanh))
-
- ;; By composition (these must be AFTER their constituent groupings)
-
- (guile-C-API
- (description "the official guile API available to C programs")
- (grok () (lambda (x)
- (and (in-group? x 'C)
- (or (in-group? x 'gh)
- (in-group? x 'coop)
- (in-group? x 'gdb))))))
-
- ;; Add new grouping descriptions here.
- )
-
-;;; groupings.alist ends here
diff --git a/doc/guile-api.alist b/doc/guile-api.alist
deleted file mode 100644
index 5f73cae3a..000000000
--- a/doc/guile-api.alist
+++ /dev/null
@@ -1,3219 +0,0 @@
-;;; generated 2002-05-12 05:25:39 UTC by scan-api -- do not edit!
-
-(
-(meta
- (GUILE_LOAD_PATH . "")
- (LTDL_LIBRARY_PATH . "")
- (guile . "pre-inst-guile")
- (libguileinterface . "15:0:0")
- (sofile . "libguile/.libs/libguile.so.15.0.0")
- (groups C+scheme embedded-libltdl libguile-internal gdb coop gh g-fdes r-fdes scm k POSIX math guile-C-API Scheme C)
-) ;; end of meta
-(interface
-($abs (groups math Scheme) (scan-data "#<primitive-procedure $abs>"))
-($acos (groups math Scheme) (scan-data "#<primitive-procedure $acos>"))
-($acosh (groups math Scheme) (scan-data "#<primitive-procedure $acosh>"))
-($asin (groups math Scheme) (scan-data "#<primitive-procedure $asin>"))
-($asinh (groups math Scheme) (scan-data "#<primitive-procedure $asinh>"))
-($atan (groups math Scheme) (scan-data "#<primitive-procedure $atan>"))
-($atan2 (groups math Scheme) (scan-data "#<primitive-procedure $atan2>"))
-($atanh (groups math Scheme) (scan-data "#<primitive-procedure $atanh>"))
-($cos (groups math Scheme) (scan-data "#<primitive-procedure $cos>"))
-($cosh (groups math Scheme) (scan-data "#<primitive-procedure $cosh>"))
-($exp (groups math Scheme) (scan-data "#<primitive-procedure $exp>"))
-($expt (groups math Scheme) (scan-data "#<primitive-procedure $expt>"))
-($log (groups math Scheme) (scan-data "#<primitive-procedure $log>"))
-($sin (groups math Scheme) (scan-data "#<primitive-procedure $sin>"))
-($sinh (groups math Scheme) (scan-data "#<primitive-procedure $sinh>"))
-($sqrt (groups math Scheme) (scan-data "#<primitive-procedure $sqrt>"))
-($tan (groups math Scheme) (scan-data "#<primitive-procedure $tan>"))
-($tanh (groups math Scheme) (scan-data "#<primitive-procedure $tanh>"))
-(%cond-expand-features (groups Scheme) (scan-data ""))
-(%cond-expand-table (groups Scheme) (scan-data ""))
-(%deliver-signals (groups Scheme) (scan-data "#<primitive-procedure %deliver-signals>"))
-(%get-pre-modules-obarray (groups Scheme) (scan-data "#<primitive-procedure %get-pre-modules-obarray>"))
-(%guile-build-info (groups Scheme) (scan-data ""))
-(%init-goops-builtins (groups Scheme) (scan-data "#<primitive-procedure %init-goops-builtins>"))
-(%init-rdelim-builtins (groups Scheme) (scan-data "#<primitive-procedure %init-rdelim-builtins>"))
-(%init-rw-builtins (groups Scheme) (scan-data "#<primitive-procedure %init-rw-builtins>"))
-(%library-dir (groups Scheme) (scan-data "#<primitive-procedure %library-dir>"))
-(%load-announce (groups Scheme) (scan-data "#<procedure %load-announce (file)>"))
-(%load-extensions (groups Scheme) (scan-data ""))
-(%load-hook (groups Scheme) (scan-data "#<procedure %load-announce (file)>"))
-(%load-path (groups Scheme) (scan-data ""))
-(%load-verbosely (groups Scheme) (scan-data ""))
-(%make-void-port (groups Scheme) (scan-data "#<primitive-procedure %make-void-port>"))
-(%module-public-interface (groups Scheme) (scan-data ""))
-(%nil (groups Scheme) (scan-data ""))
-(%package-data-dir (groups Scheme) (scan-data "#<primitive-procedure %package-data-dir>"))
-(%print-module (groups Scheme) (scan-data "#<procedure %print-module (mod port)>"))
-(%print-values (groups Scheme) (scan-data "#<primitive-procedure %print-values>"))
-(%search-load-path (groups Scheme) (scan-data "#<primitive-procedure %search-load-path>"))
-(%site-dir (groups Scheme) (scan-data "#<primitive-procedure %site-dir>"))
-(* (groups Scheme) (scan-data "#<primitive-procedure *>"))
-(*features* (groups Scheme) (scan-data ""))
-(*null-device* (groups Scheme) (scan-data ""))
-(*random-state* (groups Scheme) (scan-data ""))
-(*unspecified* (groups Scheme) (scan-data ""))
-(+ (groups Scheme) (scan-data "#<primitive-procedure +>"))
-(- (groups Scheme) (scan-data "#<primitive-procedure ->"))
-(->bool (groups Scheme) (scan-data "#<procedure ->bool (x)>"))
-(/ (groups Scheme) (scan-data "#<primitive-procedure />"))
-(1+ (groups Scheme) (scan-data "#<procedure 1+ (n)>"))
-(1- (groups Scheme) (scan-data "#<procedure 1- (n)>"))
-(< (groups Scheme) (scan-data "#<primitive-procedure <>"))
-(<= (groups Scheme) (scan-data "#<primitive-procedure <=>"))
-(<class> (groups Scheme) (scan-data ""))
-(<entity> (groups Scheme) (scan-data ""))
-(<operator-class> (groups Scheme) (scan-data ""))
-(= (groups Scheme) (scan-data "#<primitive-procedure =>"))
-(> (groups Scheme) (scan-data "#<primitive-procedure >>"))
-(>= (groups Scheme) (scan-data "#<primitive-procedure >=>"))
-(@apply (groups Scheme) (scan-data ""))
-(@bind (groups Scheme) (scan-data ""))
-(@call-with-current-continuation (groups Scheme) (scan-data ""))
-(@call-with-values (groups Scheme) (scan-data ""))
-(@fop (groups Scheme) (scan-data ""))
-(AF_INET (groups k Scheme) (scan-data ""))
-(AF_INET6 (groups k Scheme) (scan-data ""))
-(AF_UNIX (groups k Scheme) (scan-data ""))
-(AF_UNSPEC (groups k Scheme) (scan-data ""))
-(E2BIG (groups k Scheme) (scan-data ""))
-(EACCES (groups k Scheme) (scan-data ""))
-(EADDRINUSE (groups k Scheme) (scan-data ""))
-(EADDRNOTAVAIL (groups k Scheme) (scan-data ""))
-(EADV (groups k Scheme) (scan-data ""))
-(EAFNOSUPPORT (groups k Scheme) (scan-data ""))
-(EAGAIN (groups k Scheme) (scan-data ""))
-(EALREADY (groups k Scheme) (scan-data ""))
-(EBADE (groups k Scheme) (scan-data ""))
-(EBADF (groups k Scheme) (scan-data ""))
-(EBADFD (groups k Scheme) (scan-data ""))
-(EBADMSG (groups k Scheme) (scan-data ""))
-(EBADR (groups k Scheme) (scan-data ""))
-(EBADRQC (groups k Scheme) (scan-data ""))
-(EBADSLT (groups k Scheme) (scan-data ""))
-(EBFONT (groups k Scheme) (scan-data ""))
-(EBUSY (groups k Scheme) (scan-data ""))
-(ECHILD (groups k Scheme) (scan-data ""))
-(ECHRNG (groups k Scheme) (scan-data ""))
-(ECOMM (groups k Scheme) (scan-data ""))
-(ECONNABORTED (groups k Scheme) (scan-data ""))
-(ECONNREFUSED (groups k Scheme) (scan-data ""))
-(ECONNRESET (groups k Scheme) (scan-data ""))
-(EDEADLK (groups k Scheme) (scan-data ""))
-(EDEADLOCK (groups k Scheme) (scan-data ""))
-(EDESTADDRREQ (groups k Scheme) (scan-data ""))
-(EDOM (groups k Scheme) (scan-data ""))
-(EDOTDOT (groups k Scheme) (scan-data ""))
-(EDQUOT (groups k Scheme) (scan-data ""))
-(EEXIST (groups k Scheme) (scan-data ""))
-(EFAULT (groups k Scheme) (scan-data ""))
-(EFBIG (groups k Scheme) (scan-data ""))
-(EHOSTDOWN (groups k Scheme) (scan-data ""))
-(EHOSTUNREACH (groups k Scheme) (scan-data ""))
-(EIDRM (groups k Scheme) (scan-data ""))
-(EILSEQ (groups k Scheme) (scan-data ""))
-(EINPROGRESS (groups k Scheme) (scan-data ""))
-(EINTR (groups k Scheme) (scan-data ""))
-(EINVAL (groups k Scheme) (scan-data ""))
-(EIO (groups k Scheme) (scan-data ""))
-(EISCONN (groups k Scheme) (scan-data ""))
-(EISDIR (groups k Scheme) (scan-data ""))
-(EISNAM (groups k Scheme) (scan-data ""))
-(EL2HLT (groups k Scheme) (scan-data ""))
-(EL2NSYNC (groups k Scheme) (scan-data ""))
-(EL3HLT (groups k Scheme) (scan-data ""))
-(EL3RST (groups k Scheme) (scan-data ""))
-(ELIBACC (groups k Scheme) (scan-data ""))
-(ELIBBAD (groups k Scheme) (scan-data ""))
-(ELIBEXEC (groups k Scheme) (scan-data ""))
-(ELIBMAX (groups k Scheme) (scan-data ""))
-(ELIBSCN (groups k Scheme) (scan-data ""))
-(ELNRNG (groups k Scheme) (scan-data ""))
-(ELOOP (groups k Scheme) (scan-data ""))
-(EMFILE (groups k Scheme) (scan-data ""))
-(EMLINK (groups k Scheme) (scan-data ""))
-(EMSGSIZE (groups k Scheme) (scan-data ""))
-(EMULTIHOP (groups k Scheme) (scan-data ""))
-(ENAMETOOLONG (groups k Scheme) (scan-data ""))
-(ENAVAIL (groups k Scheme) (scan-data ""))
-(ENETDOWN (groups k Scheme) (scan-data ""))
-(ENETRESET (groups k Scheme) (scan-data ""))
-(ENETUNREACH (groups k Scheme) (scan-data ""))
-(ENFILE (groups k Scheme) (scan-data ""))
-(ENOANO (groups k Scheme) (scan-data ""))
-(ENOBUFS (groups k Scheme) (scan-data ""))
-(ENOCSI (groups k Scheme) (scan-data ""))
-(ENODATA (groups k Scheme) (scan-data ""))
-(ENODEV (groups k Scheme) (scan-data ""))
-(ENOENT (groups k Scheme) (scan-data ""))
-(ENOEXEC (groups k Scheme) (scan-data ""))
-(ENOLCK (groups k Scheme) (scan-data ""))
-(ENOLINK (groups k Scheme) (scan-data ""))
-(ENOMEM (groups k Scheme) (scan-data ""))
-(ENOMSG (groups k Scheme) (scan-data ""))
-(ENONET (groups k Scheme) (scan-data ""))
-(ENOPKG (groups k Scheme) (scan-data ""))
-(ENOPROTOOPT (groups k Scheme) (scan-data ""))
-(ENOSPC (groups k Scheme) (scan-data ""))
-(ENOSR (groups k Scheme) (scan-data ""))
-(ENOSTR (groups k Scheme) (scan-data ""))
-(ENOSYS (groups k Scheme) (scan-data ""))
-(ENOTBLK (groups k Scheme) (scan-data ""))
-(ENOTCONN (groups k Scheme) (scan-data ""))
-(ENOTDIR (groups k Scheme) (scan-data ""))
-(ENOTEMPTY (groups k Scheme) (scan-data ""))
-(ENOTNAM (groups k Scheme) (scan-data ""))
-(ENOTSOCK (groups k Scheme) (scan-data ""))
-(ENOTTY (groups k Scheme) (scan-data ""))
-(ENOTUNIQ (groups k Scheme) (scan-data ""))
-(ENXIO (groups k Scheme) (scan-data ""))
-(EOPNOTSUPP (groups k Scheme) (scan-data ""))
-(EOVERFLOW (groups k Scheme) (scan-data ""))
-(EPERM (groups k Scheme) (scan-data ""))
-(EPFNOSUPPORT (groups k Scheme) (scan-data ""))
-(EPIPE (groups k Scheme) (scan-data ""))
-(EPROTO (groups k Scheme) (scan-data ""))
-(EPROTONOSUPPORT (groups k Scheme) (scan-data ""))
-(EPROTOTYPE (groups k Scheme) (scan-data ""))
-(ERANGE (groups k Scheme) (scan-data ""))
-(EREMCHG (groups k Scheme) (scan-data ""))
-(EREMOTE (groups k Scheme) (scan-data ""))
-(EREMOTEIO (groups k Scheme) (scan-data ""))
-(ERESTART (groups k Scheme) (scan-data ""))
-(EROFS (groups k Scheme) (scan-data ""))
-(ESHUTDOWN (groups k Scheme) (scan-data ""))
-(ESOCKTNOSUPPORT (groups k Scheme) (scan-data ""))
-(ESPIPE (groups k Scheme) (scan-data ""))
-(ESRCH (groups k Scheme) (scan-data ""))
-(ESRMNT (groups k Scheme) (scan-data ""))
-(ESTALE (groups k Scheme) (scan-data ""))
-(ESTRPIPE (groups k Scheme) (scan-data ""))
-(ETIME (groups k Scheme) (scan-data ""))
-(ETIMEDOUT (groups k Scheme) (scan-data ""))
-(ETOOMANYREFS (groups k Scheme) (scan-data ""))
-(ETXTBSY (groups k Scheme) (scan-data ""))
-(EUCLEAN (groups k Scheme) (scan-data ""))
-(EUNATCH (groups k Scheme) (scan-data ""))
-(EUSERS (groups k Scheme) (scan-data ""))
-(EWOULDBLOCK (groups k Scheme) (scan-data ""))
-(EXDEV (groups k Scheme) (scan-data ""))
-(EXFULL (groups k Scheme) (scan-data ""))
-(FD_CLOEXEC (groups POSIX k Scheme) (scan-data ""))
-(F_DUPFD (groups POSIX k Scheme) (scan-data ""))
-(F_GETFD (groups POSIX k Scheme) (scan-data ""))
-(F_GETFL (groups POSIX k Scheme) (scan-data ""))
-(F_GETOWN (groups POSIX k Scheme) (scan-data ""))
-(F_OK (groups POSIX k Scheme) (scan-data ""))
-(F_SETFD (groups POSIX k Scheme) (scan-data ""))
-(F_SETFL (groups POSIX k Scheme) (scan-data ""))
-(F_SETOWN (groups POSIX k Scheme) (scan-data ""))
-(INADDR_ANY (groups k Scheme) (scan-data ""))
-(INADDR_BROADCAST (groups k Scheme) (scan-data ""))
-(INADDR_LOOPBACK (groups k Scheme) (scan-data ""))
-(INADDR_NONE (groups k Scheme) (scan-data ""))
-(ITIMER_PROF (groups k Scheme) (scan-data ""))
-(ITIMER_REAL (groups k Scheme) (scan-data ""))
-(ITIMER_VIRTUAL (groups k Scheme) (scan-data ""))
-(LC_ALL (groups POSIX k Scheme) (scan-data ""))
-(LC_COLLATE (groups POSIX k Scheme) (scan-data ""))
-(LC_CTYPE (groups POSIX k Scheme) (scan-data ""))
-(LC_MESSAGES (groups POSIX k Scheme) (scan-data ""))
-(LC_MONETARY (groups POSIX k Scheme) (scan-data ""))
-(LC_NUMERIC (groups POSIX k Scheme) (scan-data ""))
-(LC_TIME (groups POSIX k Scheme) (scan-data ""))
-(LOCK_EX (groups POSIX k Scheme) (scan-data ""))
-(LOCK_NB (groups POSIX k Scheme) (scan-data ""))
-(LOCK_SH (groups POSIX k Scheme) (scan-data ""))
-(LOCK_UN (groups POSIX k Scheme) (scan-data ""))
-(MSG_DONTROUTE (groups k Scheme) (scan-data ""))
-(MSG_OOB (groups k Scheme) (scan-data ""))
-(MSG_PEEK (groups k Scheme) (scan-data ""))
-(NSIG (groups k Scheme) (scan-data ""))
-(OPEN_BOTH (groups k Scheme) (scan-data ""))
-(OPEN_READ (groups k Scheme) (scan-data ""))
-(OPEN_WRITE (groups k Scheme) (scan-data ""))
-(O_APPEND (groups POSIX k Scheme) (scan-data ""))
-(O_CREAT (groups POSIX k Scheme) (scan-data ""))
-(O_EXCL (groups k Scheme) (scan-data ""))
-(O_NDELAY (groups k Scheme) (scan-data ""))
-(O_NOCTTY (groups k Scheme) (scan-data ""))
-(O_NONBLOCK (groups k Scheme) (scan-data ""))
-(O_RDONLY (groups POSIX k Scheme) (scan-data ""))
-(O_RDWR (groups POSIX k Scheme) (scan-data ""))
-(O_SYNC (groups k Scheme) (scan-data ""))
-(O_TRUNC (groups k Scheme) (scan-data ""))
-(O_WRONLY (groups POSIX k Scheme) (scan-data ""))
-(PF_INET (groups k Scheme) (scan-data ""))
-(PF_INET6 (groups k Scheme) (scan-data ""))
-(PF_UNIX (groups k Scheme) (scan-data ""))
-(PF_UNSPEC (groups k Scheme) (scan-data ""))
-(PIPE_BUF (groups k Scheme) (scan-data ""))
-(PRIO_PGRP (groups k Scheme) (scan-data ""))
-(PRIO_PROCESS (groups k Scheme) (scan-data ""))
-(PRIO_USER (groups k Scheme) (scan-data ""))
-(R_OK (groups POSIX k Scheme) (scan-data ""))
-(SA_NOCLDSTOP (groups k Scheme) (scan-data ""))
-(SA_RESTART (groups k Scheme) (scan-data ""))
-(SEEK_CUR (groups k Scheme) (scan-data ""))
-(SEEK_END (groups k Scheme) (scan-data ""))
-(SEEK_SET (groups k Scheme) (scan-data ""))
-(SIGABRT (groups k Scheme) (scan-data ""))
-(SIGALRM (groups k Scheme) (scan-data ""))
-(SIGBUS (groups k Scheme) (scan-data ""))
-(SIGCHLD (groups k Scheme) (scan-data ""))
-(SIGCLD (groups k Scheme) (scan-data ""))
-(SIGCONT (groups k Scheme) (scan-data ""))
-(SIGFPE (groups k Scheme) (scan-data ""))
-(SIGHUP (groups POSIX k Scheme) (scan-data ""))
-(SIGILL (groups k Scheme) (scan-data ""))
-(SIGINT (groups POSIX k Scheme) (scan-data ""))
-(SIGIO (groups k Scheme) (scan-data ""))
-(SIGIOT (groups k Scheme) (scan-data ""))
-(SIGKILL (groups k Scheme) (scan-data ""))
-(SIGPIPE (groups k Scheme) (scan-data ""))
-(SIGPOLL (groups k Scheme) (scan-data ""))
-(SIGPROF (groups k Scheme) (scan-data ""))
-(SIGPWR (groups k Scheme) (scan-data ""))
-(SIGQUIT (groups k Scheme) (scan-data ""))
-(SIGSEGV (groups k Scheme) (scan-data ""))
-(SIGSTKFLT (groups k Scheme) (scan-data ""))
-(SIGSTOP (groups k Scheme) (scan-data ""))
-(SIGTERM (groups k Scheme) (scan-data ""))
-(SIGTRAP (groups k Scheme) (scan-data ""))
-(SIGTSTP (groups k Scheme) (scan-data ""))
-(SIGTTIN (groups k Scheme) (scan-data ""))
-(SIGTTOU (groups k Scheme) (scan-data ""))
-(SIGUNUSED (groups k Scheme) (scan-data ""))
-(SIGURG (groups k Scheme) (scan-data ""))
-(SIGUSR1 (groups k Scheme) (scan-data ""))
-(SIGUSR2 (groups k Scheme) (scan-data ""))
-(SIGVTALRM (groups k Scheme) (scan-data ""))
-(SIGWINCH (groups k Scheme) (scan-data ""))
-(SIGXCPU (groups k Scheme) (scan-data ""))
-(SIGXFSZ (groups k Scheme) (scan-data ""))
-(SIG_DFL (groups k Scheme) (scan-data ""))
-(SIG_IGN (groups k Scheme) (scan-data ""))
-(SOCK_DGRAM (groups k Scheme) (scan-data ""))
-(SOCK_RAW (groups k Scheme) (scan-data ""))
-(SOCK_STREAM (groups k Scheme) (scan-data ""))
-(SOL_IP (groups k Scheme) (scan-data ""))
-(SOL_SOCKET (groups k Scheme) (scan-data ""))
-(SO_BROADCAST (groups k Scheme) (scan-data ""))
-(SO_DEBUG (groups k Scheme) (scan-data ""))
-(SO_DONTROUTE (groups k Scheme) (scan-data ""))
-(SO_ERROR (groups k Scheme) (scan-data ""))
-(SO_KEEPALIVE (groups k Scheme) (scan-data ""))
-(SO_LINGER (groups k Scheme) (scan-data ""))
-(SO_NO_CHECK (groups k Scheme) (scan-data ""))
-(SO_OOBINLINE (groups k Scheme) (scan-data ""))
-(SO_PRIORITY (groups k Scheme) (scan-data ""))
-(SO_RCVBUF (groups k Scheme) (scan-data ""))
-(SO_REUSEADDR (groups k Scheme) (scan-data ""))
-(SO_SNDBUF (groups k Scheme) (scan-data ""))
-(SO_TYPE (groups k Scheme) (scan-data ""))
-(WAIT_ANY (groups k Scheme) (scan-data ""))
-(WAIT_MYPGRP (groups k Scheme) (scan-data ""))
-(WNOHANG (groups POSIX k Scheme) (scan-data ""))
-(WUNTRACED (groups POSIX k Scheme) (scan-data ""))
-(W_OK (groups POSIX k Scheme) (scan-data ""))
-(X_OK (groups POSIX k Scheme) (scan-data ""))
-(_IOFBF (groups POSIX k Scheme) (scan-data ""))
-(_IOLBF (groups POSIX k Scheme) (scan-data ""))
-(_IONBF (groups POSIX k Scheme) (scan-data ""))
-(_fini (groups C) (scan-data T))
-(_init (groups C) (scan-data T))
-(abort-hook (groups Scheme) (scan-data ""))
-(abs (groups Scheme) (scan-data "#<primitive-procedure abs>"))
-(accept (groups Scheme) (scan-data "#<primitive-procedure accept>"))
-(access? (groups POSIX Scheme) (scan-data "#<primitive-procedure access?>"))
-(acons (groups Scheme) (scan-data "#<primitive-procedure acons>"))
-(acos (groups Scheme) (scan-data "#<procedure acos (z)>"))
-(acosh (groups Scheme) (scan-data "#<procedure acosh (z)>"))
-(add-hook! (groups Scheme) (scan-data "#<primitive-procedure add-hook!>"))
-(after-backtrace-hook (groups Scheme) (scan-data ""))
-(after-error-hook (groups Scheme) (scan-data ""))
-(after-eval-hook (groups Scheme) (scan-data ""))
-(after-gc-hook (groups Scheme) (scan-data ""))
-(after-print-hook (groups Scheme) (scan-data ""))
-(after-read-hook (groups Scheme) (scan-data ""))
-(alarm (groups POSIX Scheme) (scan-data "#<primitive-procedure alarm>"))
-(and (groups Scheme) (scan-data ""))
-(and-map (groups Scheme) (scan-data "#<procedure and-map (f lst)>"))
-(and=> (groups Scheme) (scan-data "#<procedure and=> (value procedure)>"))
-(angle (groups Scheme) (scan-data "#<primitive-procedure angle>"))
-(app (groups Scheme) (scan-data ""))
-(append (groups Scheme) (scan-data "#<primitive-procedure append>"))
-(append! (groups Scheme) (scan-data "#<primitive-procedure append!>"))
-(apply (groups Scheme) (scan-data "#<procedure apply (fun . args)>"))
-(apply-to-args (groups Scheme) (scan-data "#<procedure apply-to-args (args fn)>"))
-(apply:nconc2last (groups Scheme) (scan-data "#<primitive-procedure apply:nconc2last>"))
-(array->list (groups Scheme) (scan-data "#<primitive-procedure array->list>"))
-(array-contents (groups Scheme) (scan-data "#<primitive-procedure array-contents>"))
-(array-copy! (groups Scheme) (scan-data "#<primitive-procedure array-copy!>"))
-(array-copy-in-order! (groups Scheme) (scan-data "#<primitive-procedure array-copy-in-order!>"))
-(array-dimensions (groups Scheme) (scan-data "#<primitive-procedure array-dimensions>"))
-(array-equal? (groups Scheme) (scan-data "#<primitive-procedure array-equal?>"))
-(array-fill! (groups Scheme) (scan-data "#<primitive-procedure array-fill!>"))
-(array-for-each (groups Scheme) (scan-data "#<primitive-procedure array-for-each>"))
-(array-in-bounds? (groups Scheme) (scan-data "#<primitive-procedure array-in-bounds?>"))
-(array-index-map! (groups Scheme) (scan-data "#<primitive-procedure array-index-map!>"))
-(array-map! (groups Scheme) (scan-data "#<primitive-procedure array-map!>"))
-(array-map-in-order! (groups Scheme) (scan-data "#<primitive-procedure array-map-in-order!>"))
-(array-prototype (groups Scheme) (scan-data "#<primitive-procedure array-prototype>"))
-(array-rank (groups Scheme) (scan-data "#<primitive-procedure array-rank>"))
-(array-ref (groups Scheme) (scan-data "#<primitive-procedure array-ref>"))
-(array-set! (groups Scheme) (scan-data "#<primitive-procedure array-set!>"))
-(array-shape (groups Scheme) (scan-data "#<procedure array-shape (a)>"))
-(array? (groups Scheme) (scan-data "#<primitive-procedure array?>"))
-(ash (groups Scheme) (scan-data "#<primitive-procedure ash>"))
-(asin (groups Scheme) (scan-data "#<procedure asin (z)>"))
-(asinh (groups Scheme) (scan-data "#<procedure asinh (z)>"))
-(assert-defmacro?! (groups Scheme) (scan-data "#<procedure assert-defmacro?! (m)>"))
-(assert-load-verbosity (groups Scheme) (scan-data "#<procedure assert-load-verbosity (v)>"))
-(assert-repl-print-unspecified (groups Scheme) (scan-data "#<procedure assert-repl-print-unspecified (v)>"))
-(assert-repl-silence (groups Scheme) (scan-data "#<procedure assert-repl-silence (v)>"))
-(assert-repl-verbosity (groups Scheme) (scan-data "#<procedure assert-repl-verbosity (v)>"))
-(assoc (groups Scheme) (scan-data "#<primitive-procedure assoc>"))
-(assoc-ref (groups Scheme) (scan-data "#<primitive-procedure assoc-ref>"))
-(assoc-remove! (groups Scheme) (scan-data "#<primitive-procedure assoc-remove!>"))
-(assoc-set! (groups Scheme) (scan-data "#<primitive-procedure assoc-set!>"))
-(assq (groups Scheme) (scan-data "#<primitive-procedure assq>"))
-(assq-ref (groups Scheme) (scan-data "#<primitive-procedure assq-ref>"))
-(assq-remove! (groups Scheme) (scan-data "#<primitive-procedure assq-remove!>"))
-(assq-set! (groups Scheme) (scan-data "#<primitive-procedure assq-set!>"))
-(assv (groups Scheme) (scan-data "#<primitive-procedure assv>"))
-(assv-ref (groups Scheme) (scan-data "#<primitive-procedure assv-ref>"))
-(assv-remove! (groups Scheme) (scan-data "#<primitive-procedure assv-remove!>"))
-(assv-set! (groups Scheme) (scan-data "#<primitive-procedure assv-set!>"))
-(async (groups Scheme) (scan-data "#<primitive-procedure async>"))
-(async-mark (groups Scheme) (scan-data "#<primitive-procedure async-mark>"))
-(atan (groups Scheme) (scan-data "#<procedure atan (z . y)>"))
-(atanh (groups Scheme) (scan-data "#<procedure atanh (z)>"))
-(autoload-done! (groups Scheme) (scan-data "#<procedure autoload-done! (p m)>"))
-(autoload-done-or-in-progress? (groups Scheme) (scan-data "#<procedure autoload-done-or-in-progress? (p m)>"))
-(autoload-in-progress! (groups Scheme) (scan-data "#<procedure autoload-in-progress! (p m)>"))
-(autoloads-done (groups Scheme) (scan-data ""))
-(autoloads-in-progress (groups Scheme) (scan-data ""))
-(backtrace (groups Scheme) (scan-data "#<primitive-procedure backtrace>"))
-(bad-throw (groups Scheme) (scan-data "#<procedure bad-throw (key . args)>"))
-(basename (groups POSIX Scheme) (scan-data "#<primitive-procedure basename>"))
-(basic-load (groups Scheme) (scan-data "#<procedure load (name)>"))
-(batch-mode? (groups Scheme) (scan-data "#<procedure batch-mode? ()>"))
-(beautify-user-module! (groups Scheme) (scan-data "#<procedure beautify-user-module! (module)>"))
-(before-backtrace-hook (groups Scheme) (scan-data ""))
-(before-error-hook (groups Scheme) (scan-data ""))
-(before-eval-hook (groups Scheme) (scan-data ""))
-(before-print-hook (groups Scheme) (scan-data ""))
-(before-read-hook (groups Scheme) (scan-data ""))
-(before-signal-stack (groups Scheme) (scan-data ""))
-(begin (groups Scheme) (scan-data ""))
-(begin-deprecated (groups Scheme) (scan-data ""))
-(bind (groups Scheme) (scan-data "#<primitive-procedure bind>"))
-(bit-count (groups Scheme) (scan-data "#<primitive-procedure bit-count>"))
-(bit-count* (groups Scheme) (scan-data "#<primitive-procedure bit-count*>"))
-(bit-extract (groups Scheme) (scan-data "#<primitive-procedure bit-extract>"))
-(bit-invert! (groups Scheme) (scan-data "#<primitive-procedure bit-invert!>"))
-(bit-position (groups Scheme) (scan-data "#<primitive-procedure bit-position>"))
-(bit-set*! (groups Scheme) (scan-data "#<primitive-procedure bit-set*!>"))
-(boolean? (groups Scheme) (scan-data "#<primitive-procedure boolean?>"))
-(caaaar (groups Scheme) (scan-data "#<primitive-procedure caaaar>"))
-(caaadr (groups Scheme) (scan-data "#<primitive-procedure caaadr>"))
-(caaar (groups Scheme) (scan-data "#<primitive-procedure caaar>"))
-(caadar (groups Scheme) (scan-data "#<primitive-procedure caadar>"))
-(caaddr (groups Scheme) (scan-data "#<primitive-procedure caaddr>"))
-(caadr (groups Scheme) (scan-data "#<primitive-procedure caadr>"))
-(caar (groups Scheme) (scan-data "#<primitive-procedure caar>"))
-(cadaar (groups Scheme) (scan-data "#<primitive-procedure cadaar>"))
-(cadadr (groups Scheme) (scan-data "#<primitive-procedure cadadr>"))
-(cadar (groups Scheme) (scan-data "#<primitive-procedure cadar>"))
-(caddar (groups Scheme) (scan-data "#<primitive-procedure caddar>"))
-(cadddr (groups Scheme) (scan-data "#<primitive-procedure cadddr>"))
-(caddr (groups Scheme) (scan-data "#<primitive-procedure caddr>"))
-(cadr (groups Scheme) (scan-data "#<primitive-procedure cadr>"))
-(call-with-current-continuation (groups Scheme) (scan-data "#<procedure call-with-current-continuation (proc)>"))
-(call-with-dynamic-root (groups Scheme) (scan-data "#<primitive-procedure call-with-dynamic-root>"))
-(call-with-input-file (groups Scheme) (scan-data "#<procedure call-with-input-file (str proc)>"))
-(call-with-input-string (groups Scheme) (scan-data "#<primitive-procedure call-with-input-string>"))
-(call-with-new-thread (groups Scheme) (scan-data "#<primitive-procedure call-with-new-thread>"))
-(call-with-output-file (groups Scheme) (scan-data "#<procedure call-with-output-file (str proc)>"))
-(call-with-output-string (groups Scheme) (scan-data "#<primitive-procedure call-with-output-string>"))
-(call-with-values (groups Scheme) (scan-data "#<procedure call-with-values (producer consumer)>"))
-(car (groups Scheme) (scan-data "#<primitive-procedure car>"))
-(case (groups Scheme) (scan-data ""))
-(catch (groups Scheme) (scan-data "#<primitive-procedure catch>"))
-(cdaaar (groups Scheme) (scan-data "#<primitive-procedure cdaaar>"))
-(cdaadr (groups Scheme) (scan-data "#<primitive-procedure cdaadr>"))
-(cdaar (groups Scheme) (scan-data "#<primitive-procedure cdaar>"))
-(cdadar (groups Scheme) (scan-data "#<primitive-procedure cdadar>"))
-(cdaddr (groups Scheme) (scan-data "#<primitive-procedure cdaddr>"))
-(cdadr (groups Scheme) (scan-data "#<primitive-procedure cdadr>"))
-(cdar (groups Scheme) (scan-data "#<primitive-procedure cdar>"))
-(cddaar (groups Scheme) (scan-data "#<primitive-procedure cddaar>"))
-(cddadr (groups Scheme) (scan-data "#<primitive-procedure cddadr>"))
-(cddar (groups Scheme) (scan-data "#<primitive-procedure cddar>"))
-(cdddar (groups Scheme) (scan-data "#<primitive-procedure cdddar>"))
-(cddddr (groups Scheme) (scan-data "#<primitive-procedure cddddr>"))
-(cdddr (groups Scheme) (scan-data "#<primitive-procedure cdddr>"))
-(cddr (groups Scheme) (scan-data "#<primitive-procedure cddr>"))
-(cdr (groups Scheme) (scan-data "#<primitive-procedure cdr>"))
-(ceiling (groups Scheme) (scan-data "#<primitive-procedure ceiling>"))
-(char->integer (groups Scheme) (scan-data "#<primitive-procedure char->integer>"))
-(char-alphabetic? (groups Scheme) (scan-data "#<primitive-procedure char-alphabetic?>"))
-(char-ci<=? (groups Scheme) (scan-data "#<primitive-procedure char-ci<=?>"))
-(char-ci<? (groups Scheme) (scan-data "#<primitive-procedure char-ci<?>"))
-(char-ci=? (groups Scheme) (scan-data "#<primitive-procedure char-ci=?>"))
-(char-ci>=? (groups Scheme) (scan-data "#<primitive-procedure char-ci>=?>"))
-(char-ci>? (groups Scheme) (scan-data "#<primitive-procedure char-ci>?>"))
-(char-code-limit (groups Scheme) (scan-data ""))
-(char-downcase (groups Scheme) (scan-data "#<primitive-procedure char-downcase>"))
-(char-is-both? (groups Scheme) (scan-data "#<primitive-procedure char-is-both?>"))
-(char-lower-case? (groups Scheme) (scan-data "#<primitive-procedure char-lower-case?>"))
-(char-numeric? (groups Scheme) (scan-data "#<primitive-procedure char-numeric?>"))
-(char-ready? (groups Scheme) (scan-data "#<primitive-procedure char-ready?>"))
-(char-upcase (groups Scheme) (scan-data "#<primitive-procedure char-upcase>"))
-(char-upper-case? (groups Scheme) (scan-data "#<primitive-procedure char-upper-case?>"))
-(char-whitespace? (groups Scheme) (scan-data "#<primitive-procedure char-whitespace?>"))
-(char<=? (groups Scheme) (scan-data "#<primitive-procedure char<=?>"))
-(char<? (groups Scheme) (scan-data "#<primitive-procedure char<?>"))
-(char=? (groups Scheme) (scan-data "#<primitive-procedure char=?>"))
-(char>=? (groups Scheme) (scan-data "#<primitive-procedure char>=?>"))
-(char>? (groups Scheme) (scan-data "#<primitive-procedure char>?>"))
-(char? (groups Scheme) (scan-data "#<primitive-procedure char?>"))
-(chdir (groups POSIX Scheme) (scan-data "#<primitive-procedure chdir>"))
-(chmod (groups POSIX Scheme) (scan-data "#<primitive-procedure chmod>"))
-(chown (groups POSIX Scheme) (scan-data "#<primitive-procedure chown>"))
-(chroot (groups POSIX Scheme) (scan-data "#<primitive-procedure chroot>"))
-(class-of (groups Scheme) (scan-data "#<primitive-procedure class-of>"))
-(close (groups POSIX Scheme) (scan-data "#<primitive-procedure close>"))
-(close-fdes (groups POSIX Scheme) (scan-data "#<primitive-procedure close-fdes>"))
-(close-input-port (groups Scheme) (scan-data "#<primitive-procedure close-input-port>"))
-(close-io-port (groups Scheme) (scan-data "#<primitive-procedure close-port>"))
-(close-output-port (groups Scheme) (scan-data "#<primitive-procedure close-output-port>"))
-(close-port (groups Scheme) (scan-data "#<primitive-procedure close-port>"))
-(closedir (groups POSIX Scheme) (scan-data "#<primitive-procedure closedir>"))
-(closure? (groups Scheme) (scan-data "#<primitive-procedure closure?>"))
-(collect (groups Scheme) (scan-data ""))
-(command-line (groups POSIX Scheme) (scan-data "#<procedure command-line ()>"))
-(compile-define-module-args (groups Scheme) (scan-data "#<procedure compile-define-module-args (args)>"))
-(compile-interface-spec (groups Scheme) (scan-data "#<procedure compile-interface-spec (spec)>"))
-(complex? (groups Scheme) (scan-data "#<primitive-procedure complex?>"))
-(cond (groups Scheme) (scan-data ""))
-(cond-expand (groups Scheme) (scan-data ""))
-(cond-expand-provide (groups Scheme) (scan-data "#<procedure cond-expand-provide (module features)>"))
-(connect (groups Scheme) (scan-data "#<primitive-procedure connect>"))
-(cons (groups Scheme) (scan-data "#<primitive-procedure cons>"))
-(cons* (groups Scheme) (scan-data "#<primitive-procedure cons*>"))
-(cons-source (groups Scheme) (scan-data "#<primitive-procedure cons-source>"))
-(coop_abort (groups guile-C-API coop C) (scan-data T))
-(coop_condition_variable_destroy (groups guile-C-API coop C) (scan-data T))
-(coop_condition_variable_init (groups guile-C-API coop C) (scan-data T))
-(coop_condition_variable_signal (groups guile-C-API coop C) (scan-data T))
-(coop_condition_variable_timed_wait_mutex (groups guile-C-API coop C) (scan-data T))
-(coop_condition_variable_wait_mutex (groups guile-C-API coop C) (scan-data T))
-(coop_create (groups guile-C-API coop C) (scan-data T))
-(coop_getspecific (groups guile-C-API coop C) (scan-data T))
-(coop_global_allq (groups guile-C-API coop C) (scan-data B))
-(coop_global_curr (groups guile-C-API coop C) (scan-data B))
-(coop_global_runq (groups guile-C-API coop C) (scan-data B))
-(coop_global_sleepq (groups guile-C-API coop C) (scan-data B))
-(coop_init (groups guile-C-API coop C) (scan-data T))
-(coop_join (groups guile-C-API coop C) (scan-data T))
-(coop_key_create (groups guile-C-API coop C) (scan-data T))
-(coop_key_delete (groups guile-C-API coop C) (scan-data T))
-(coop_mutex_destroy (groups guile-C-API coop C) (scan-data T))
-(coop_mutex_init (groups guile-C-API coop C) (scan-data T))
-(coop_mutex_lock (groups guile-C-API coop C) (scan-data T))
-(coop_mutex_trylock (groups guile-C-API coop C) (scan-data T))
-(coop_mutex_unlock (groups guile-C-API coop C) (scan-data T))
-(coop_new_condition_variable_init (groups guile-C-API coop C) (scan-data T))
-(coop_new_mutex_init (groups guile-C-API coop C) (scan-data T))
-(coop_next_runnable_thread (groups guile-C-API coop C) (scan-data T))
-(coop_qget (groups guile-C-API coop C) (scan-data T))
-(coop_qput (groups guile-C-API coop C) (scan-data T))
-(coop_setspecific (groups guile-C-API coop C) (scan-data T))
-(coop_sleephelp (groups guile-C-API coop C) (scan-data T))
-(coop_start (groups guile-C-API coop C) (scan-data T))
-(coop_timeout_qinsert (groups guile-C-API coop C) (scan-data T))
-(coop_tmp_queue (groups guile-C-API coop C) (scan-data B))
-(coop_wait_for_runnable_thread (groups guile-C-API coop C) (scan-data T))
-(coop_wait_for_runnable_thread_now (groups guile-C-API coop C) (scan-data T))
-(coop_yield (groups guile-C-API coop C) (scan-data T))
-(copy-file (groups POSIX Scheme) (scan-data "#<primitive-procedure copy-file>"))
-(copy-random-state (groups Scheme) (scan-data "#<primitive-procedure copy-random-state>"))
-(copy-tree (groups Scheme) (scan-data "#<primitive-procedure copy-tree>"))
-(cos (groups Scheme) (scan-data "#<procedure cos (z)>"))
-(cosh (groups Scheme) (scan-data "#<procedure cosh (z)>"))
-(crypt (groups POSIX Scheme) (scan-data "#<primitive-procedure crypt>"))
-(ctermid (groups POSIX Scheme) (scan-data "#<primitive-procedure ctermid>"))
-(current-error-port (groups Scheme) (scan-data "#<primitive-procedure current-error-port>"))
-(current-input-port (groups Scheme) (scan-data "#<primitive-procedure current-input-port>"))
-(current-load-port (groups Scheme) (scan-data "#<primitive-procedure current-load-port>"))
-(current-module (groups Scheme) (scan-data "#<primitive-procedure current-module>"))
-(current-output-port (groups Scheme) (scan-data "#<primitive-procedure current-output-port>"))
-(current-time (groups POSIX Scheme) (scan-data "#<primitive-procedure current-time>"))
-(cuserid (groups POSIX Scheme) (scan-data "#<primitive-procedure cuserid>"))
-(debug-disable (groups Scheme) (scan-data "#<procedure debug-disable flags>"))
-(debug-enable (groups Scheme) (scan-data "#<procedure debug-enable flags>"))
-(debug-object? (groups Scheme) (scan-data "#<primitive-procedure debug-object?>"))
-(debug-options (groups Scheme) (scan-data "#<procedure debug-options args>"))
-(debug-options-interface (groups Scheme) (scan-data "#<primitive-procedure debug-options-interface>"))
-(debug-set! (groups Scheme) (scan-data ""))
-(default-lazy-handler (groups Scheme) (scan-data "#<procedure default-lazy-handler (key . args)>"))
-(define (groups Scheme) (scan-data ""))
-(define-macro (groups Scheme) (scan-data ""))
-(define-module (groups Scheme) (scan-data ""))
-(define-option-interface (groups Scheme) (scan-data ""))
-(define-private (groups Scheme) (scan-data ""))
-(define-public (groups Scheme) (scan-data ""))
-(define-syntax-macro (groups Scheme) (scan-data ""))
-(defined? (groups Scheme) (scan-data "#<primitive-procedure defined?>"))
-(defmacro (groups Scheme) (scan-data ""))
-(defmacro-public (groups Scheme) (scan-data ""))
-(defmacro-transformer (groups Scheme) (scan-data "#<procedure defmacro-transformer (m)>"))
-(defmacro:syntax-transformer (groups Scheme) (scan-data "#<procedure defmacro:syntax-transformer (f)>"))
-(defmacro:transformer (groups Scheme) (scan-data "#<procedure defmacro:transformer (f)>"))
-(defmacro? (groups Scheme) (scan-data "#<procedure defmacro? (m)>"))
-(delay (groups Scheme) (scan-data ""))
-(delete (groups Scheme) (scan-data "#<primitive-procedure delete>"))
-(delete! (groups Scheme) (scan-data "#<primitive-procedure delete!>"))
-(delete-file (groups POSIX Scheme) (scan-data "#<primitive-procedure delete-file>"))
-(delete1! (groups Scheme) (scan-data "#<primitive-procedure delete1!>"))
-(delq (groups Scheme) (scan-data "#<primitive-procedure delq>"))
-(delq! (groups Scheme) (scan-data "#<primitive-procedure delq!>"))
-(delq1! (groups Scheme) (scan-data "#<primitive-procedure delq1!>"))
-(delv (groups Scheme) (scan-data "#<primitive-procedure delv>"))
-(delv! (groups Scheme) (scan-data "#<primitive-procedure delv!>"))
-(delv1! (groups Scheme) (scan-data "#<primitive-procedure delv1!>"))
-(destroy-guardian! (groups Scheme) (scan-data "#<primitive-procedure destroy-guardian!>"))
-(dimensions->uniform-array (groups Scheme) (scan-data "#<primitive-procedure dimensions->uniform-array>"))
-(directory-stream? (groups POSIX Scheme) (scan-data "#<primitive-procedure directory-stream?>"))
-(dirname (groups POSIX Scheme) (scan-data "#<primitive-procedure dirname>"))
-(display (groups Scheme) (scan-data "#<primitive-procedure display>"))
-(display-application (groups Scheme) (scan-data "#<primitive-procedure display-application>"))
-(display-backtrace (groups Scheme) (scan-data "#<primitive-procedure display-backtrace>"))
-(display-error (groups Scheme) (scan-data "#<primitive-procedure display-error>"))
-(display-usage-report (groups Scheme) (scan-data "#<procedure display-usage-report (kw-desc)>"))
-(do (groups Scheme) (scan-data ""))
-(doubly-weak-hash-table? (groups Scheme) (scan-data "#<primitive-procedure doubly-weak-hash-table?>"))
-(drain-input (groups Scheme) (scan-data "#<primitive-procedure drain-input>"))
-(dup (groups POSIX Scheme) (scan-data "#<procedure dup (port/fd . maybe-fd)>"))
-(dup->fdes (groups POSIX Scheme) (scan-data "#<primitive-procedure dup->fdes>"))
-(dup->inport (groups POSIX Scheme) (scan-data "#<procedure dup->inport (port/fd . maybe-fd)>"))
-(dup->outport (groups POSIX Scheme) (scan-data "#<procedure dup->outport (port/fd . maybe-fd)>"))
-(dup->port (groups POSIX Scheme) (scan-data "#<procedure dup->port (port/fd mode . maybe-fd)>"))
-(dup2 (groups POSIX Scheme) (scan-data "#<primitive-procedure dup2>"))
-(duplicate-port (groups POSIX Scheme) (scan-data "#<procedure duplicate-port (port modes)>"))
-(dynamic-args-call (groups Scheme) (scan-data "#<primitive-procedure dynamic-args-call>"))
-(dynamic-call (groups Scheme) (scan-data "#<primitive-procedure dynamic-call>"))
-(dynamic-func (groups Scheme) (scan-data "#<primitive-procedure dynamic-func>"))
-(dynamic-link (groups Scheme) (scan-data "#<primitive-procedure dynamic-link>"))
-(dynamic-object? (groups Scheme) (scan-data "#<primitive-procedure dynamic-object?>"))
-(dynamic-root (groups Scheme) (scan-data "#<primitive-procedure dynamic-root>"))
-(dynamic-unlink (groups Scheme) (scan-data "#<primitive-procedure dynamic-unlink>"))
-(dynamic-wind (groups Scheme) (scan-data "#<primitive-procedure dynamic-wind>"))
-(enclose-array (groups Scheme) (scan-data "#<primitive-procedure enclose-array>"))
-(endgrent (groups POSIX Scheme) (scan-data "#<procedure endgrent ()>"))
-(endhostent (groups Scheme) (scan-data "#<procedure endhostent ()>"))
-(endnetent (groups Scheme) (scan-data "#<procedure endnetent ()>"))
-(endprotoent (groups Scheme) (scan-data "#<procedure endprotoent ()>"))
-(endpwent (groups POSIX Scheme) (scan-data "#<procedure endpwent ()>"))
-(endservent (groups Scheme) (scan-data "#<procedure endservent ()>"))
-(entity? (groups Scheme) (scan-data "#<primitive-procedure entity?>"))
-(env-module (groups Scheme) (scan-data "#<primitive-procedure env-module>"))
-(environ (groups POSIX Scheme) (scan-data "#<primitive-procedure environ>"))
-(environment-bound? (groups Scheme) (scan-data "#<primitive-procedure environment-bound?>"))
-(environment-cell (groups Scheme) (scan-data "#<primitive-procedure environment-cell>"))
-(environment-define (groups Scheme) (scan-data "#<primitive-procedure environment-define>"))
-(environment-fold (groups Scheme) (scan-data "#<primitive-procedure environment-fold>"))
-(environment-module (groups Scheme) (scan-data "#<procedure environment-module (env)>"))
-(environment-observe (groups Scheme) (scan-data "#<primitive-procedure environment-observe>"))
-(environment-observe-weak (groups Scheme) (scan-data "#<primitive-procedure environment-observe-weak>"))
-(environment-ref (groups Scheme) (scan-data "#<primitive-procedure environment-ref>"))
-(environment-set! (groups Scheme) (scan-data "#<primitive-procedure environment-set!>"))
-(environment-undefine (groups Scheme) (scan-data "#<primitive-procedure environment-undefine>"))
-(environment-unobserve (groups Scheme) (scan-data "#<primitive-procedure environment-unobserve>"))
-(environment? (groups Scheme) (scan-data "#<primitive-procedure environment?>"))
-(eof-object? (groups Scheme) (scan-data "#<primitive-procedure eof-object?>"))
-(eq? (groups Scheme) (scan-data "#<primitive-procedure eq?>"))
-(equal? (groups Scheme) (scan-data "#<primitive-procedure equal?>"))
-(eqv? (groups Scheme) (scan-data "#<primitive-procedure eqv?>"))
-(error (groups Scheme) (scan-data "#<procedure error args>"))
-(error-catching-loop (groups Scheme) (scan-data "#<procedure error-catching-loop (thunk)>"))
-(error-catching-repl (groups Scheme) (scan-data "#<procedure error-catching-repl (r e p)>"))
-(eval (groups Scheme) (scan-data "#<primitive-procedure eval>"))
-(eval-case (groups Scheme) (scan-data ""))
-(eval-disable (groups Scheme) (scan-data "#<procedure eval-disable flags>"))
-(eval-enable (groups Scheme) (scan-data "#<procedure eval-enable flags>"))
-(eval-environment-imported (groups Scheme) (scan-data "#<primitive-procedure eval-environment-imported>"))
-(eval-environment-local (groups Scheme) (scan-data "#<primitive-procedure eval-environment-local>"))
-(eval-environment-set-imported! (groups Scheme) (scan-data "#<primitive-procedure eval-environment-set-imported!>"))
-(eval-environment-set-local! (groups Scheme) (scan-data "#<primitive-procedure eval-environment-set-local!>"))
-(eval-environment? (groups Scheme) (scan-data "#<primitive-procedure eval-environment?>"))
-(eval-options (groups Scheme) (scan-data "#<procedure eval-options args>"))
-(eval-options-interface (groups Scheme) (scan-data "#<primitive-procedure eval-options-interface>"))
-(eval-set! (groups Scheme) (scan-data ""))
-(eval-string (groups Scheme) (scan-data "#<primitive-procedure eval-string>"))
-(evaluator-traps-interface (groups Scheme) (scan-data "#<primitive-procedure evaluator-traps-interface>"))
-(even? (groups Scheme) (scan-data "#<primitive-procedure even?>"))
-(exact->inexact (groups Scheme) (scan-data "#<primitive-procedure exact->inexact>"))
-(exact? (groups Scheme) (scan-data "#<primitive-procedure exact?>"))
-(execl (groups POSIX Scheme) (scan-data "#<primitive-procedure execl>"))
-(execle (groups POSIX Scheme) (scan-data "#<primitive-procedure execle>"))
-(execlp (groups POSIX Scheme) (scan-data "#<primitive-procedure execlp>"))
-(exit (groups Scheme) (scan-data "#<procedure quit args>"))
-(exit-hook (groups Scheme) (scan-data ""))
-(exp (groups Scheme) (scan-data "#<procedure exp (z)>"))
-(export (groups Scheme) (scan-data ""))
-(export-environment-private (groups Scheme) (scan-data "#<primitive-procedure export-environment-private>"))
-(export-environment-set-private! (groups Scheme) (scan-data "#<primitive-procedure export-environment-set-private!>"))
-(export-environment-set-signature! (groups Scheme) (scan-data "#<primitive-procedure export-environment-set-signature!>"))
-(export-environment-signature (groups Scheme) (scan-data "#<primitive-procedure export-environment-signature>"))
-(export-environment? (groups Scheme) (scan-data "#<primitive-procedure export-environment?>"))
-(export-syntax (groups Scheme) (scan-data ""))
-(expt (groups Scheme) (scan-data "#<procedure expt (z1 z2)>"))
-(false-if-exception (groups Scheme) (scan-data ""))
-(fcntl (groups POSIX Scheme) (scan-data "#<primitive-procedure fcntl>"))
-(fdes->inport (groups POSIX Scheme) (scan-data "#<procedure fdes->inport (fdes)>"))
-(fdes->outport (groups POSIX Scheme) (scan-data "#<procedure fdes->outport (fdes)>"))
-(fdes->ports (groups POSIX Scheme) (scan-data "#<primitive-procedure fdes->ports>"))
-(fdopen (groups POSIX Scheme) (scan-data "#<primitive-procedure fdopen>"))
-(feature? (groups Scheme) (scan-data "#<procedure provided? (feature)>"))
-(file-exists? (groups Scheme) (scan-data "#<procedure file-exists? (str)>"))
-(file-is-directory? (groups Scheme) (scan-data "#<procedure file-is-directory? (str)>"))
-(file-port? (groups Scheme) (scan-data "#<primitive-procedure file-port?>"))
-(file-position (groups Scheme) (scan-data "#<procedure file-position args>"))
-(file-set-position (groups Scheme) (scan-data "#<procedure file-set-position args>"))
-(fileno (groups POSIX Scheme) (scan-data "#<primitive-procedure fileno>"))
-(flock (groups POSIX Scheme) (scan-data "#<primitive-procedure flock>"))
-(floor (groups Scheme) (scan-data "#<primitive-procedure floor>"))
-(fluid-ref (groups Scheme) (scan-data "#<primitive-procedure fluid-ref>"))
-(fluid-set! (groups Scheme) (scan-data "#<primitive-procedure fluid-set!>"))
-(fluid? (groups Scheme) (scan-data "#<primitive-procedure fluid?>"))
-(flush-all-ports (groups Scheme) (scan-data "#<primitive-procedure flush-all-ports>"))
-(for-each (groups Scheme) (scan-data "#<primitive-procedure for-each>"))
-(for-next-option (groups Scheme) (scan-data "#<procedure for-next-option (proc argv kw-opts kw-args)>"))
-(force (groups Scheme) (scan-data "#<primitive-procedure force>"))
-(force-output (groups Scheme) (scan-data "#<primitive-procedure force-output>"))
-(format (groups Scheme) (scan-data "#<primitive-procedure simple-format>"))
-(frame-arguments (groups Scheme) (scan-data "#<primitive-procedure frame-arguments>"))
-(frame-evaluating-args? (groups Scheme) (scan-data "#<primitive-procedure frame-evaluating-args?>"))
-(frame-next (groups Scheme) (scan-data "#<primitive-procedure frame-next>"))
-(frame-number (groups Scheme) (scan-data "#<primitive-procedure frame-number>"))
-(frame-overflow? (groups Scheme) (scan-data "#<primitive-procedure frame-overflow?>"))
-(frame-previous (groups Scheme) (scan-data "#<primitive-procedure frame-previous>"))
-(frame-procedure (groups Scheme) (scan-data "#<primitive-procedure frame-procedure>"))
-(frame-procedure? (groups Scheme) (scan-data "#<primitive-procedure frame-procedure?>"))
-(frame-real? (groups Scheme) (scan-data "#<primitive-procedure frame-real?>"))
-(frame-source (groups Scheme) (scan-data "#<primitive-procedure frame-source>"))
-(frame? (groups Scheme) (scan-data "#<primitive-procedure frame?>"))
-(fsync (groups POSIX Scheme) (scan-data "#<primitive-procedure fsync>"))
-(ftell (groups Scheme) (scan-data "#<primitive-procedure ftell>"))
-(gc (groups Scheme) (scan-data "#<primitive-procedure gc>"))
-(gc-run-time (groups Scheme) (scan-data "#<procedure gc-run-time ()>"))
-(gc-stats (groups Scheme) (scan-data "#<primitive-procedure gc-stats>"))
-(gcd (groups Scheme) (scan-data "#<primitive-procedure gcd>"))
-(gdb_binding (groups guile-C-API gdb C) (scan-data T))
-(gdb_eval (groups guile-C-API gdb C) (scan-data T))
-(gdb_language (groups guile-C-API gdb C) (scan-data D))
-(gdb_maybe_valid_type_p (groups guile-C-API gdb C) (scan-data T))
-(gdb_options (groups guile-C-API gdb C) (scan-data D))
-(gdb_output (groups guile-C-API gdb C) (scan-data B))
-(gdb_output_length (groups guile-C-API gdb C) (scan-data B))
-(gdb_print (groups guile-C-API gdb C) (scan-data T))
-(gdb_read (groups guile-C-API gdb C) (scan-data T))
-(gdb_result (groups guile-C-API gdb C) (scan-data B))
-(gensym (groups Scheme) (scan-data "#<primitive-procedure gensym>"))
-(get-internal-real-time (groups POSIX Scheme) (scan-data "#<primitive-procedure get-internal-real-time>"))
-(get-internal-run-time (groups POSIX Scheme) (scan-data "#<primitive-procedure get-internal-run-time>"))
-(get-option (groups Scheme) (scan-data "#<procedure get-option (argv kw-opts kw-args return)>"))
-(get-output-string (groups Scheme) (scan-data "#<primitive-procedure get-output-string>"))
-(get-print-state (groups Scheme) (scan-data "#<primitive-procedure get-print-state>"))
-(getcwd (groups POSIX Scheme) (scan-data "#<primitive-procedure getcwd>"))
-(getegid (groups POSIX Scheme) (scan-data "#<primitive-procedure getegid>"))
-(getenv (groups POSIX Scheme) (scan-data "#<primitive-procedure getenv>"))
-(geteuid (groups POSIX Scheme) (scan-data "#<primitive-procedure geteuid>"))
-(getgid (groups POSIX Scheme) (scan-data "#<primitive-procedure getgid>"))
-(getgr (groups POSIX Scheme) (scan-data "#<primitive-procedure getgr>"))
-(getgrent (groups POSIX Scheme) (scan-data "#<procedure getgrent ()>"))
-(getgrgid (groups POSIX Scheme) (scan-data "#<procedure getgrgid (id)>"))
-(getgrnam (groups POSIX Scheme) (scan-data "#<procedure getgrnam (name)>"))
-(getgroups (groups POSIX Scheme) (scan-data "#<primitive-procedure getgroups>"))
-(gethost (groups Scheme) (scan-data "#<primitive-procedure gethost>"))
-(gethostbyaddr (groups Scheme) (scan-data "#<procedure gethostbyaddr (addr)>"))
-(gethostbyname (groups Scheme) (scan-data "#<procedure gethostbyname (name)>"))
-(gethostent (groups Scheme) (scan-data "#<procedure gethostent ()>"))
-(gethostname (groups POSIX Scheme) (scan-data "#<primitive-procedure gethostname>"))
-(getitimer (groups POSIX Scheme) (scan-data "#<primitive-procedure getitimer>"))
-(getlogin (groups POSIX Scheme) (scan-data "#<primitive-procedure getlogin>"))
-(getnet (groups Scheme) (scan-data "#<primitive-procedure getnet>"))
-(getnetbyaddr (groups Scheme) (scan-data "#<procedure getnetbyaddr (addr)>"))
-(getnetbyname (groups Scheme) (scan-data "#<procedure getnetbyname (name)>"))
-(getnetent (groups Scheme) (scan-data "#<procedure getnetent ()>"))
-(getpass (groups POSIX Scheme) (scan-data "#<primitive-procedure getpass>"))
-(getpeername (groups Scheme) (scan-data "#<primitive-procedure getpeername>"))
-(getpgrp (groups POSIX Scheme) (scan-data "#<primitive-procedure getpgrp>"))
-(getpid (groups POSIX Scheme) (scan-data "#<primitive-procedure getpid>"))
-(getppid (groups POSIX Scheme) (scan-data "#<primitive-procedure getppid>"))
-(getpriority (groups POSIX Scheme) (scan-data "#<primitive-procedure getpriority>"))
-(getproto (groups Scheme) (scan-data "#<primitive-procedure getproto>"))
-(getprotobyname (groups Scheme) (scan-data "#<procedure getprotobyname (name)>"))
-(getprotobynumber (groups Scheme) (scan-data "#<procedure getprotobynumber (addr)>"))
-(getprotoent (groups Scheme) (scan-data "#<procedure getprotoent ()>"))
-(getpw (groups POSIX Scheme) (scan-data "#<primitive-procedure getpw>"))
-(getpwent (groups POSIX Scheme) (scan-data "#<procedure getpwent ()>"))
-(getpwnam (groups POSIX Scheme) (scan-data "#<procedure getpwnam (name)>"))
-(getpwuid (groups POSIX Scheme) (scan-data "#<procedure getpwuid (uid)>"))
-(getserv (groups Scheme) (scan-data "#<primitive-procedure getserv>"))
-(getservbyname (groups Scheme) (scan-data "#<procedure getservbyname (name proto)>"))
-(getservbyport (groups Scheme) (scan-data "#<procedure getservbyport (port proto)>"))
-(getservent (groups Scheme) (scan-data "#<procedure getservent ()>"))
-(getsockname (groups Scheme) (scan-data "#<primitive-procedure getsockname>"))
-(getsockopt (groups Scheme) (scan-data "#<primitive-procedure getsockopt>"))
-(gettimeofday (groups POSIX Scheme) (scan-data "#<primitive-procedure gettimeofday>"))
-(getuid (groups POSIX Scheme) (scan-data "#<primitive-procedure getuid>"))
-(gh_append (groups guile-C-API gh C) (scan-data T))
-(gh_append2 (groups guile-C-API gh C) (scan-data T))
-(gh_append3 (groups guile-C-API gh C) (scan-data T))
-(gh_append4 (groups guile-C-API gh C) (scan-data T))
-(gh_apply (groups guile-C-API gh C) (scan-data T))
-(gh_bool2scm (groups guile-C-API gh C) (scan-data T))
-(gh_boolean_p (groups guile-C-API gh C) (scan-data T))
-(gh_caaar (groups guile-C-API gh C) (scan-data T))
-(gh_caadr (groups guile-C-API gh C) (scan-data T))
-(gh_caar (groups guile-C-API gh C) (scan-data T))
-(gh_cadar (groups guile-C-API gh C) (scan-data T))
-(gh_caddr (groups guile-C-API gh C) (scan-data T))
-(gh_cadr (groups guile-C-API gh C) (scan-data T))
-(gh_call0 (groups guile-C-API gh C) (scan-data T))
-(gh_call1 (groups guile-C-API gh C) (scan-data T))
-(gh_call2 (groups guile-C-API gh C) (scan-data T))
-(gh_call3 (groups guile-C-API gh C) (scan-data T))
-(gh_car (groups guile-C-API gh C) (scan-data T))
-(gh_catch (groups guile-C-API gh C) (scan-data T))
-(gh_cdaar (groups guile-C-API gh C) (scan-data T))
-(gh_cdadr (groups guile-C-API gh C) (scan-data T))
-(gh_cdar (groups guile-C-API gh C) (scan-data T))
-(gh_cddar (groups guile-C-API gh C) (scan-data T))
-(gh_cdddr (groups guile-C-API gh C) (scan-data T))
-(gh_cddr (groups guile-C-API gh C) (scan-data T))
-(gh_cdr (groups guile-C-API gh C) (scan-data T))
-(gh_char2scm (groups guile-C-API gh C) (scan-data T))
-(gh_char_p (groups guile-C-API gh C) (scan-data T))
-(gh_chars2byvect (groups guile-C-API gh C) (scan-data T))
-(gh_cons (groups guile-C-API gh C) (scan-data T))
-(gh_define (groups guile-C-API gh C) (scan-data T))
-(gh_display (groups guile-C-API gh C) (scan-data T))
-(gh_double2scm (groups guile-C-API gh C) (scan-data T))
-(gh_doubles2dvect (groups guile-C-API gh C) (scan-data T))
-(gh_doubles2scm (groups guile-C-API gh C) (scan-data T))
-(gh_enter (groups guile-C-API gh C) (scan-data T))
-(gh_eq_p (groups guile-C-API gh C) (scan-data T))
-(gh_equal_p (groups guile-C-API gh C) (scan-data T))
-(gh_eqv_p (groups guile-C-API gh C) (scan-data T))
-(gh_eval_file (groups guile-C-API gh C) (scan-data T))
-(gh_eval_file_with_catch (groups guile-C-API gh C) (scan-data T))
-(gh_eval_file_with_standard_handler (groups guile-C-API gh C) (scan-data T))
-(gh_eval_str (groups guile-C-API gh C) (scan-data T))
-(gh_eval_str_with_catch (groups guile-C-API gh C) (scan-data T))
-(gh_eval_str_with_stack_saving_handler (groups guile-C-API gh C) (scan-data T))
-(gh_eval_str_with_standard_handler (groups guile-C-API gh C) (scan-data T))
-(gh_exact_p (groups guile-C-API gh C) (scan-data T))
-(gh_floats2fvect (groups guile-C-API gh C) (scan-data T))
-(gh_get_substr (groups guile-C-API gh C) (scan-data T))
-(gh_inexact_p (groups guile-C-API gh C) (scan-data T))
-(gh_int2scm (groups guile-C-API gh C) (scan-data T))
-(gh_ints2scm (groups guile-C-API gh C) (scan-data T))
-(gh_length (groups guile-C-API gh C) (scan-data T))
-(gh_list_p (groups guile-C-API gh C) (scan-data T))
-(gh_long2scm (groups guile-C-API gh C) (scan-data T))
-(gh_longs2ivect (groups guile-C-API gh C) (scan-data T))
-(gh_lookup (groups guile-C-API gh C) (scan-data T))
-(gh_make_vector (groups guile-C-API gh C) (scan-data T))
-(gh_module_lookup (groups guile-C-API gh C) (scan-data T))
-(gh_new_procedure (groups guile-C-API gh C) (scan-data T))
-(gh_new_procedure0_0 (groups guile-C-API gh C) (scan-data T))
-(gh_new_procedure0_1 (groups guile-C-API gh C) (scan-data T))
-(gh_new_procedure0_2 (groups guile-C-API gh C) (scan-data T))
-(gh_new_procedure1_0 (groups guile-C-API gh C) (scan-data T))
-(gh_new_procedure1_1 (groups guile-C-API gh C) (scan-data T))
-(gh_new_procedure1_2 (groups guile-C-API gh C) (scan-data T))
-(gh_new_procedure2_0 (groups guile-C-API gh C) (scan-data T))
-(gh_new_procedure2_1 (groups guile-C-API gh C) (scan-data T))
-(gh_new_procedure2_2 (groups guile-C-API gh C) (scan-data T))
-(gh_new_procedure3_0 (groups guile-C-API gh C) (scan-data T))
-(gh_new_procedure4_0 (groups guile-C-API gh C) (scan-data T))
-(gh_new_procedure5_0 (groups guile-C-API gh C) (scan-data T))
-(gh_newline (groups guile-C-API gh C) (scan-data T))
-(gh_null_p (groups guile-C-API gh C) (scan-data T))
-(gh_number_p (groups guile-C-API gh C) (scan-data T))
-(gh_pair_p (groups guile-C-API gh C) (scan-data T))
-(gh_procedure_p (groups guile-C-API gh C) (scan-data T))
-(gh_repl (groups guile-C-API gh C) (scan-data T))
-(gh_scm2bool (groups guile-C-API gh C) (scan-data T))
-(gh_scm2char (groups guile-C-API gh C) (scan-data T))
-(gh_scm2chars (groups guile-C-API gh C) (scan-data T))
-(gh_scm2double (groups guile-C-API gh C) (scan-data T))
-(gh_scm2doubles (groups guile-C-API gh C) (scan-data T))
-(gh_scm2floats (groups guile-C-API gh C) (scan-data T))
-(gh_scm2int (groups guile-C-API gh C) (scan-data T))
-(gh_scm2long (groups guile-C-API gh C) (scan-data T))
-(gh_scm2longs (groups guile-C-API gh C) (scan-data T))
-(gh_scm2newstr (groups guile-C-API gh C) (scan-data T))
-(gh_scm2shorts (groups guile-C-API gh C) (scan-data T))
-(gh_scm2ulong (groups guile-C-API gh C) (scan-data T))
-(gh_set_car_x (groups guile-C-API gh C) (scan-data T))
-(gh_set_cdr_x (groups guile-C-API gh C) (scan-data T))
-(gh_set_substr (groups guile-C-API gh C) (scan-data T))
-(gh_shorts2svect (groups guile-C-API gh C) (scan-data T))
-(gh_standard_handler (groups guile-C-API gh C) (scan-data T))
-(gh_str02scm (groups guile-C-API gh C) (scan-data T))
-(gh_str2scm (groups guile-C-API gh C) (scan-data T))
-(gh_string_equal_p (groups guile-C-API gh C) (scan-data T))
-(gh_string_p (groups guile-C-API gh C) (scan-data T))
-(gh_symbol2newstr (groups guile-C-API gh C) (scan-data T))
-(gh_symbol2scm (groups guile-C-API gh C) (scan-data T))
-(gh_symbol_p (groups guile-C-API gh C) (scan-data T))
-(gh_ulong2scm (groups guile-C-API gh C) (scan-data T))
-(gh_ulongs2uvect (groups guile-C-API gh C) (scan-data T))
-(gh_uniform_vector_length (groups guile-C-API gh C) (scan-data T))
-(gh_uniform_vector_ref (groups guile-C-API gh C) (scan-data T))
-(gh_vector_length (groups guile-C-API gh C) (scan-data T))
-(gh_vector_p (groups guile-C-API gh C) (scan-data T))
-(gh_vector_ref (groups guile-C-API gh C) (scan-data T))
-(gh_vector_set_x (groups guile-C-API gh C) (scan-data T))
-(gh_write (groups guile-C-API gh C) (scan-data T))
-(gmtime (groups POSIX Scheme) (scan-data "#<primitive-procedure gmtime>"))
-(group:gid (groups POSIX Scheme) (scan-data "#<procedure group:gid (obj)>"))
-(group:mem (groups POSIX Scheme) (scan-data "#<procedure group:mem (obj)>"))
-(group:name (groups POSIX Scheme) (scan-data "#<procedure group:name (obj)>"))
-(group:passwd (groups POSIX Scheme) (scan-data "#<procedure group:passwd (obj)>"))
-(guardian-destroyed? (groups Scheme) (scan-data "#<primitive-procedure guardian-destroyed?>"))
-(guardian-greedy? (groups Scheme) (scan-data "#<primitive-procedure guardian-greedy?>"))
-(handle-system-error (groups Scheme) (scan-data "#<procedure handle-system-error (key . args)>"))
-(has-shown-backtrace-hint? (groups Scheme) (scan-data ""))
-(has-shown-debugger-hint? (groups Scheme) (scan-data ""))
-(has-suffix? (groups Scheme) (scan-data "#<procedure has-suffix? (str suffix)>"))
-(hash (groups Scheme) (scan-data "#<primitive-procedure hash>"))
-(hash-create-handle! (groups Scheme) (scan-data "#<primitive-procedure hash-create-handle!>"))
-(hash-fold (groups Scheme) (scan-data "#<primitive-procedure hash-fold>"))
-(hash-get-handle (groups Scheme) (scan-data "#<primitive-procedure hash-get-handle>"))
-(hash-ref (groups Scheme) (scan-data "#<primitive-procedure hash-ref>"))
-(hash-remove! (groups Scheme) (scan-data "#<primitive-procedure hash-remove!>"))
-(hash-set! (groups Scheme) (scan-data "#<primitive-procedure hash-set!>"))
-(hashq (groups Scheme) (scan-data "#<primitive-procedure hashq>"))
-(hashq-create-handle! (groups Scheme) (scan-data "#<primitive-procedure hashq-create-handle!>"))
-(hashq-get-handle (groups Scheme) (scan-data "#<primitive-procedure hashq-get-handle>"))
-(hashq-ref (groups Scheme) (scan-data "#<primitive-procedure hashq-ref>"))
-(hashq-remove! (groups Scheme) (scan-data "#<primitive-procedure hashq-remove!>"))
-(hashq-set! (groups Scheme) (scan-data "#<primitive-procedure hashq-set!>"))
-(hashv (groups Scheme) (scan-data "#<primitive-procedure hashv>"))
-(hashv-create-handle! (groups Scheme) (scan-data "#<primitive-procedure hashv-create-handle!>"))
-(hashv-get-handle (groups Scheme) (scan-data "#<primitive-procedure hashv-get-handle>"))
-(hashv-ref (groups Scheme) (scan-data "#<primitive-procedure hashv-ref>"))
-(hashv-remove! (groups Scheme) (scan-data "#<primitive-procedure hashv-remove!>"))
-(hashv-set! (groups Scheme) (scan-data "#<primitive-procedure hashv-set!>"))
-(hashx-create-handle! (groups Scheme) (scan-data "#<primitive-procedure hashx-create-handle!>"))
-(hashx-get-handle (groups Scheme) (scan-data "#<primitive-procedure hashx-get-handle>"))
-(hashx-ref (groups Scheme) (scan-data "#<primitive-procedure hashx-ref>"))
-(hashx-set! (groups Scheme) (scan-data "#<primitive-procedure hashx-set!>"))
-(hook->list (groups Scheme) (scan-data "#<primitive-procedure hook->list>"))
-(hook-empty? (groups Scheme) (scan-data "#<primitive-procedure hook-empty?>"))
-(hook? (groups Scheme) (scan-data "#<primitive-procedure hook?>"))
-(hostent:addr-list (groups Scheme) (scan-data "#<procedure hostent:addr-list (obj)>"))
-(hostent:addrtype (groups Scheme) (scan-data "#<procedure hostent:addrtype (obj)>"))
-(hostent:aliases (groups Scheme) (scan-data "#<procedure hostent:aliases (obj)>"))
-(hostent:length (groups Scheme) (scan-data "#<procedure hostent:length (obj)>"))
-(hostent:name (groups Scheme) (scan-data "#<procedure hostent:name (obj)>"))
-(htonl (groups Scheme) (scan-data "#<primitive-procedure htonl>"))
-(htons (groups Scheme) (scan-data "#<primitive-procedure htons>"))
-(identity (groups Scheme) (scan-data "#<procedure identity (x)>"))
-(if (groups Scheme) (scan-data ""))
-(imag-part (groups Scheme) (scan-data "#<primitive-procedure imag-part>"))
-(import-environment-imports (groups Scheme) (scan-data "#<primitive-procedure import-environment-imports>"))
-(import-environment-set-imports! (groups Scheme) (scan-data "#<primitive-procedure import-environment-set-imports!>"))
-(import-environment? (groups Scheme) (scan-data "#<primitive-procedure import-environment?>"))
-(in-vicinity (groups Scheme) (scan-data "#<procedure in-vicinity (vicinity file)>"))
-(include-deprecated-features (groups Scheme) (scan-data "#<primitive-procedure include-deprecated-features>"))
-(inet-aton (groups Scheme) (scan-data "#<primitive-procedure inet-aton>"))
-(inet-lnaof (groups Scheme) (scan-data "#<primitive-procedure inet-lnaof>"))
-(inet-makeaddr (groups Scheme) (scan-data "#<primitive-procedure inet-makeaddr>"))
-(inet-netof (groups Scheme) (scan-data "#<primitive-procedure inet-netof>"))
-(inet-ntoa (groups Scheme) (scan-data "#<primitive-procedure inet-ntoa>"))
-(inet-ntop (groups Scheme) (scan-data "#<primitive-procedure inet-ntop>"))
-(inet-pton (groups Scheme) (scan-data "#<primitive-procedure inet-pton>"))
-(inexact->exact (groups Scheme) (scan-data "#<primitive-procedure inexact->exact>"))
-(inexact? (groups Scheme) (scan-data "#<primitive-procedure inexact?>"))
-(inf (groups Scheme) (scan-data "#<primitive-procedure inf>"))
-(inf? (groups Scheme) (scan-data "#<primitive-procedure inf?>"))
-(inherit-print-state (groups Scheme) (scan-data "#<procedure inherit-print-state (old-port new-port)>"))
-(input-port? (groups Scheme) (scan-data "#<primitive-procedure input-port?>"))
-(integer->char (groups Scheme) (scan-data "#<primitive-procedure integer->char>"))
-(integer-expt (groups Scheme) (scan-data "#<primitive-procedure integer-expt>"))
-(integer-length (groups Scheme) (scan-data "#<primitive-procedure integer-length>"))
-(integer? (groups Scheme) (scan-data "#<primitive-procedure integer?>"))
-(interaction-environment (groups Scheme) (scan-data "#<primitive-procedure interaction-environment>"))
-(internal-time-units-per-second (groups Scheme) (scan-data ""))
-(iota (groups Scheme) (scan-data "#<procedure iota (n)>"))
-(ipow-by-squaring (groups Scheme) (scan-data "#<procedure ipow-by-squaring (x k acc proc)>"))
-(isatty? (groups POSIX Scheme) (scan-data "#<primitive-procedure isatty?>"))
-(issue-deprecation-warning (groups Scheme) (scan-data "#<primitive-procedure issue-deprecation-warning>"))
-(join-thread (groups Scheme) (scan-data "#<primitive-procedure join-thread>"))
-(keyword->symbol (groups Scheme) (scan-data "#<procedure keyword->symbol (kw)>"))
-(keyword-dash-symbol (groups Scheme) (scan-data "#<primitive-procedure keyword-dash-symbol>"))
-(keyword-like-symbol->keyword (groups Scheme) (scan-data "#<procedure keyword-like-symbol->keyword (sym)>"))
-(keyword? (groups Scheme) (scan-data "#<primitive-procedure keyword?>"))
-(kill (groups POSIX Scheme) (scan-data "#<primitive-procedure kill>"))
-(kw-arg-ref (groups Scheme) (scan-data "#<procedure kw-arg-ref (args kw)>"))
-(lambda (groups Scheme) (scan-data ""))
-(last-pair (groups Scheme) (scan-data "#<primitive-procedure last-pair>"))
-(last-stack-frame (groups Scheme) (scan-data "#<primitive-procedure last-stack-frame>"))
-(lazy-catch (groups Scheme) (scan-data "#<primitive-procedure lazy-catch>"))
-(lazy-handler-dispatch (groups Scheme) (scan-data "#<procedure lazy-handler-dispatch (key . args)>"))
-(lcm (groups Scheme) (scan-data "#<primitive-procedure lcm>"))
-(leaf-environment? (groups Scheme) (scan-data "#<primitive-procedure leaf-environment?>"))
-(length (groups Scheme) (scan-data "#<primitive-procedure length>"))
-(let (groups Scheme) (scan-data ""))
-(let* (groups Scheme) (scan-data ""))
-(letrec (groups Scheme) (scan-data ""))
-(link (groups POSIX Scheme) (scan-data "#<primitive-procedure link>"))
-(list (groups Scheme) (scan-data "#<primitive-procedure list>"))
-(list->array (groups Scheme) (scan-data "#<procedure list->array (ndim lst)>"))
-(list->string (groups Scheme) (scan-data "#<primitive-procedure list->string>"))
-(list->symbol (groups Scheme) (scan-data "#<procedure list->symbol args>"))
-(list->uniform-array (groups Scheme) (scan-data "#<primitive-procedure list->uniform-array>"))
-(list->uniform-vector (groups Scheme) (scan-data "#<procedure list->uniform-vector (prot lst)>"))
-(list->vector (groups Scheme) (scan-data "#<primitive-procedure list->vector>"))
-(list->weak-vector (groups Scheme) (scan-data "#<primitive-procedure list->weak-vector>"))
-(list-cdr-ref (groups Scheme) (scan-data "#<primitive-procedure list-cdr-ref>"))
-(list-cdr-set! (groups Scheme) (scan-data "#<primitive-procedure list-cdr-set!>"))
-(list-copy (groups Scheme) (scan-data "#<primitive-procedure list-copy>"))
-(list-head (groups Scheme) (scan-data "#<primitive-procedure list-head>"))
-(list-index (groups Scheme) (scan-data "#<procedure list-index (l k)>"))
-(list-ref (groups Scheme) (scan-data "#<primitive-procedure list-ref>"))
-(list-set! (groups Scheme) (scan-data "#<primitive-procedure list-set!>"))
-(list-tail (groups Scheme) (scan-data "#<primitive-procedure list-tail>"))
-(list? (groups Scheme) (scan-data "#<primitive-procedure list?>"))
-(listen (groups Scheme) (scan-data "#<primitive-procedure listen>"))
-(load (groups Scheme) (scan-data "#<procedure load-module (filename)>"))
-(load-compiled (groups Scheme) (scan-data ""))
-(load-emacs-interface (groups Scheme) (scan-data "#<procedure load-emacs-interface ()>"))
-(load-extension (groups Scheme) (scan-data "#<primitive-procedure load-extension>"))
-(load-from-path (groups Scheme) (scan-data "#<procedure load-from-path (name)>"))
-(load-module (groups Scheme) (scan-data "#<procedure load-module (filename)>"))
-(load-user-init (groups Scheme) (scan-data "#<procedure load-user-init ()>"))
-(local-define (groups Scheme) (scan-data "#<procedure local-define (names val)>"))
-(local-eval (groups Scheme) (scan-data "#<primitive-procedure local-eval>"))
-(local-ref (groups Scheme) (scan-data "#<procedure local-ref (names)>"))
-(local-remove (groups Scheme) (scan-data "#<procedure local-remove (names)>"))
-(local-set! (groups Scheme) (scan-data "#<procedure local-set! (names val)>"))
-(localtime (groups POSIX Scheme) (scan-data "#<primitive-procedure localtime>"))
-(lock-mutex (groups Scheme) (scan-data "#<primitive-procedure lock-mutex>"))
-(log (groups Scheme) (scan-data "#<procedure log (z)>"))
-(log10 (groups Scheme) (scan-data "#<procedure log10 (arg)>"))
-(logand (groups Scheme) (scan-data "#<primitive-procedure logand>"))
-(logbit? (groups Scheme) (scan-data "#<primitive-procedure logbit?>"))
-(logcount (groups Scheme) (scan-data "#<primitive-procedure logcount>"))
-(logior (groups Scheme) (scan-data "#<primitive-procedure logior>"))
-(lognot (groups Scheme) (scan-data "#<primitive-procedure lognot>"))
-(logtest (groups Scheme) (scan-data "#<primitive-procedure logtest>"))
-(logxor (groups Scheme) (scan-data "#<primitive-procedure logxor>"))
-(lstat (groups POSIX Scheme) (scan-data "#<primitive-procedure lstat>"))
-(macro-name (groups Scheme) (scan-data "#<primitive-procedure macro-name>"))
-(macro-table (groups Scheme) (scan-data ""))
-(macro-transformer (groups Scheme) (scan-data "#<primitive-procedure macro-transformer>"))
-(macro-type (groups Scheme) (scan-data "#<primitive-procedure macro-type>"))
-(macro? (groups Scheme) (scan-data "#<primitive-procedure macro?>"))
-(macroexpand (groups Scheme) (scan-data "#<procedure macroexpand (e)>"))
-(macroexpand-1 (groups Scheme) (scan-data "#<procedure macroexpand-1 (e)>"))
-(magnitude (groups Scheme) (scan-data "#<primitive-procedure magnitude>"))
-(major-version (groups Scheme) (scan-data "#<primitive-procedure major-version>"))
-(make-arbiter (groups Scheme) (scan-data "#<primitive-procedure make-arbiter>"))
-(make-array (groups Scheme) (scan-data "#<procedure make-array (fill . args)>"))
-(make-autoload-interface (groups Scheme) (scan-data "#<procedure make-autoload-interface (module name bindings)>"))
-(make-class-object (groups Scheme) (scan-data "#<primitive-procedure make-class-object>"))
-(make-condition-variable (groups Scheme) (scan-data "#<primitive-procedure make-condition-variable>"))
-(make-doubly-weak-hash-table (groups Scheme) (scan-data "#<primitive-procedure make-doubly-weak-hash-table>"))
-(make-eval-environment (groups Scheme) (scan-data "#<primitive-procedure make-eval-environment>"))
-(make-export-environment (groups Scheme) (scan-data "#<primitive-procedure make-export-environment>"))
-(make-fluid (groups Scheme) (scan-data "#<primitive-procedure make-fluid>"))
-(make-guardian (groups Scheme) (scan-data "#<primitive-procedure make-guardian>"))
-(make-hash-table (groups Scheme) (scan-data "#<procedure make-hash-table (k)>"))
-(make-hook (groups Scheme) (scan-data "#<primitive-procedure make-hook>"))
-(make-import-environment (groups Scheme) (scan-data "#<primitive-procedure make-import-environment>"))
-(make-keyword-from-dash-symbol (groups Scheme) (scan-data "#<primitive-procedure make-keyword-from-dash-symbol>"))
-(make-leaf-environment (groups Scheme) (scan-data "#<primitive-procedure make-leaf-environment>"))
-(make-list (groups Scheme) (scan-data "#<procedure make-list (n . init)>"))
-(make-module (groups Scheme) (scan-data "#<procedure make-module args>"))
-(make-modules-in (groups Scheme) (scan-data "#<procedure make-modules-in (module name)>"))
-(make-mutex (groups Scheme) (scan-data "#<primitive-procedure make-mutex>"))
-(make-object-property (groups Scheme) (scan-data "#<procedure make-object-property ()>"))
-(make-polar (groups Scheme) (scan-data "#<primitive-procedure make-polar>"))
-(make-procedure-with-setter (groups Scheme) (scan-data "#<primitive-procedure make-procedure-with-setter>"))
-(make-record-type (groups Scheme) (scan-data "#<procedure make-record-type (type-name fields . opt)>"))
-(make-rectangular (groups Scheme) (scan-data "#<primitive-procedure make-rectangular>"))
-(make-regexp (groups Scheme) (scan-data "#<primitive-procedure make-regexp>"))
-(make-root-module (groups Scheme) (scan-data "#<procedure make-root-module ()>"))
-(make-scm-module (groups Scheme) (scan-data "#<procedure make-scm-module ()>"))
-(make-shared-array (groups Scheme) (scan-data "#<primitive-procedure make-shared-array>"))
-(make-soft-port (groups Scheme) (scan-data "#<primitive-procedure make-soft-port>"))
-(make-stack (groups Scheme) (scan-data "#<primitive-procedure make-stack>"))
-(make-string (groups Scheme) (scan-data "#<primitive-procedure make-string>"))
-(make-struct (groups Scheme) (scan-data "#<primitive-procedure make-struct>"))
-(make-struct-layout (groups Scheme) (scan-data "#<primitive-procedure make-struct-layout>"))
-(make-subclass-object (groups Scheme) (scan-data "#<primitive-procedure make-subclass-object>"))
-(make-symbol (groups Scheme) (scan-data "#<primitive-procedure make-symbol>"))
-(make-undefined-variable (groups Scheme) (scan-data "#<primitive-procedure make-undefined-variable>"))
-(make-uniform-array (groups Scheme) (scan-data "#<procedure make-uniform-array (prot . args)>"))
-(make-uniform-vector (groups Scheme) (scan-data "#<primitive-procedure dimensions->uniform-array>"))
-(make-variable (groups Scheme) (scan-data "#<primitive-procedure make-variable>"))
-(make-vector (groups Scheme) (scan-data "#<primitive-procedure make-vector>"))
-(make-vtable-vtable (groups Scheme) (scan-data "#<primitive-procedure make-vtable-vtable>"))
-(make-weak-key-hash-table (groups Scheme) (scan-data "#<primitive-procedure make-weak-key-hash-table>"))
-(make-weak-value-hash-table (groups Scheme) (scan-data "#<primitive-procedure make-weak-value-hash-table>"))
-(make-weak-vector (groups Scheme) (scan-data "#<primitive-procedure make-weak-vector>"))
-(map (groups Scheme) (scan-data "#<primitive-procedure map>"))
-(map-in-order (groups Scheme) (scan-data "#<primitive-procedure map-in-order>"))
-(mask-signals (groups Scheme) (scan-data "#<primitive-procedure mask-signals>"))
-(max (groups Scheme) (scan-data "#<primitive-procedure max>"))
-(member (groups Scheme) (scan-data "#<primitive-procedure member>"))
-(memoized-environment (groups Scheme) (scan-data "#<primitive-procedure memoized-environment>"))
-(memoized? (groups Scheme) (scan-data "#<primitive-procedure memoized?>"))
-(memq (groups Scheme) (scan-data "#<primitive-procedure memq>"))
-(memv (groups Scheme) (scan-data "#<primitive-procedure memv>"))
-(merge (groups Scheme) (scan-data "#<primitive-procedure merge>"))
-(merge! (groups Scheme) (scan-data "#<primitive-procedure merge!>"))
-(micro-version (groups Scheme) (scan-data "#<primitive-procedure micro-version>"))
-(min (groups Scheme) (scan-data "#<primitive-procedure min>"))
-(minor-version (groups Scheme) (scan-data "#<primitive-procedure minor-version>"))
-(mkdir (groups POSIX Scheme) (scan-data "#<primitive-procedure mkdir>"))
-(mknod (groups POSIX Scheme) (scan-data "#<primitive-procedure mknod>"))
-(mkstemp! (groups POSIX Scheme) (scan-data "#<primitive-procedure mkstemp!>"))
-(mktime (groups POSIX Scheme) (scan-data "#<primitive-procedure mktime>"))
-(module-add! (groups Scheme) (scan-data "#<procedure module-add! (m v var)>"))
-(module-binder (groups Scheme) (scan-data "#<procedure module-binder (obj)>"))
-(module-bound? (groups Scheme) (scan-data "#<procedure module-bound? (m v)>"))
-(module-clear! (groups Scheme) (scan-data "#<procedure module-clear! (m)>"))
-(module-constructor (groups Scheme) (scan-data "#<procedure module-constructor (obarray uses binder eval-closure transformer name kind observers weak-observers observer-id)>"))
-(module-define! (groups Scheme) (scan-data "#<procedure module-define! (module name value)>"))
-(module-defined? (groups Scheme) (scan-data "#<procedure module-defined? (module name)>"))
-(module-ensure-local-variable! (groups Scheme) (scan-data "#<procedure module-ensure-local-variable! (module symbol)>"))
-(module-eval-closure (groups Scheme) (scan-data "#<procedure module-eval-closure (obj)>"))
-(module-export! (groups Scheme) (scan-data "#<procedure module-export! (m names)>"))
-(module-for-each (groups Scheme) (scan-data "#<procedure module-for-each (proc module)>"))
-(module-kind (groups Scheme) (scan-data "#<procedure module-kind (obj)>"))
-(module-local-variable (groups Scheme) (scan-data "#<procedure module-local-variable (m v)>"))
-(module-locally-bound? (groups Scheme) (scan-data "#<procedure module-locally-bound? (m v)>"))
-(module-make-local-var! (groups Scheme) (scan-data "#<procedure module-make-local-var! (m v)>"))
-(module-map (groups Scheme) (scan-data "#<procedure module-map (proc module)>"))
-(module-modified (groups Scheme) (scan-data "#<procedure module-modified (m)>"))
-(module-name (groups Scheme) (scan-data "#<procedure module-name (obj)>"))
-(module-obarray (groups Scheme) (scan-data "#<procedure module-obarray (obj)>"))
-(module-obarray-get-handle (groups Scheme) (scan-data "#<procedure module-obarray-get-handle (ob key)>"))
-(module-obarray-ref (groups Scheme) (scan-data "#<procedure module-obarray-ref (ob key)>"))
-(module-obarray-remove! (groups Scheme) (scan-data "#<procedure module-obarray-remove! (ob key)>"))
-(module-obarray-set! (groups Scheme) (scan-data "#<procedure module-obarray-set! (ob key val)>"))
-(module-observe (groups Scheme) (scan-data "#<procedure module-observe (module proc)>"))
-(module-observe-weak (groups Scheme) (scan-data "#<procedure module-observe-weak (module proc)>"))
-(module-observer-id (groups Scheme) (scan-data "#<procedure module-observer-id (obj)>"))
-(module-observers (groups Scheme) (scan-data "#<procedure module-observers (obj)>"))
-(module-public-interface (groups Scheme) (scan-data "#<procedure module-public-interface (m)>"))
-(module-re-export! (groups Scheme) (scan-data "#<procedure module-re-export! (m names)>"))
-(module-ref (groups Scheme) (scan-data "#<procedure module-ref (module name . rest)>"))
-(module-remove! (groups Scheme) (scan-data "#<procedure module-remove! (m v)>"))
-(module-search (groups Scheme) (scan-data "#<procedure module-search (fn m v)>"))
-(module-set! (groups Scheme) (scan-data "#<procedure module-set! (module name value)>"))
-(module-symbol-binding (groups Scheme) (scan-data "#<procedure module-symbol-binding (m v . opt-val)>"))
-(module-symbol-interned? (groups Scheme) (scan-data "#<procedure module-symbol-interned? (m v)>"))
-(module-symbol-local-binding (groups Scheme) (scan-data "#<procedure module-symbol-local-binding (m v . opt-val)>"))
-(module-symbol-locally-interned? (groups Scheme) (scan-data "#<procedure module-symbol-locally-interned? (m v)>"))
-(module-transformer (groups Scheme) (scan-data "#<procedure module-transformer (obj)>"))
-(module-type (groups Scheme) (scan-data ""))
-(module-unobserve (groups Scheme) (scan-data "#<procedure module-unobserve (token)>"))
-(module-use! (groups Scheme) (scan-data "#<procedure module-use! (module interface)>"))
-(module-uses (groups Scheme) (scan-data "#<procedure module-uses (obj)>"))
-(module-variable (groups Scheme) (scan-data "#<procedure module-variable (m v)>"))
-(module-weak-observers (groups Scheme) (scan-data "#<procedure module-weak-observers (obj)>"))
-(module? (groups Scheme) (scan-data "#<procedure module? (obj)>"))
-(modulo (groups Scheme) (scan-data "#<primitive-procedure modulo>"))
-(most-negative-fixnum (groups Scheme) (scan-data ""))
-(most-positive-fixnum (groups Scheme) (scan-data ""))
-(move->fdes (groups POSIX Scheme) (scan-data "#<procedure move->fdes (fd/port fd)>"))
-(named-module-use! (groups Scheme) (scan-data "#<procedure named-module-use! (user usee)>"))
-(nan (groups Scheme) (scan-data "#<primitive-procedure nan>"))
-(nan? (groups Scheme) (scan-data "#<primitive-procedure nan?>"))
-(negative? (groups Scheme) (scan-data "#<primitive-procedure negative?>"))
-(nested-define! (groups Scheme) (scan-data "#<procedure nested-define! (root names val)>"))
-(nested-ref (groups Scheme) (scan-data "#<procedure nested-ref (root names)>"))
-(nested-remove! (groups Scheme) (scan-data "#<procedure nested-remove! (root names)>"))
-(nested-set! (groups Scheme) (scan-data "#<procedure nested-set! (root names val)>"))
-(netent:addrtype (groups Scheme) (scan-data "#<procedure netent:addrtype (obj)>"))
-(netent:aliases (groups Scheme) (scan-data "#<procedure netent:aliases (obj)>"))
-(netent:name (groups Scheme) (scan-data "#<procedure netent:name (obj)>"))
-(netent:net (groups Scheme) (scan-data "#<procedure netent:net (obj)>"))
-(newline (groups Scheme) (scan-data "#<primitive-procedure newline>"))
-(nice (groups POSIX Scheme) (scan-data "#<primitive-procedure nice>"))
-(nil-cond (groups Scheme) (scan-data ""))
-(noop (groups Scheme) (scan-data "#<primitive-procedure noop>"))
-(not (groups Scheme) (scan-data "#<primitive-procedure not>"))
-(ntohl (groups Scheme) (scan-data "#<primitive-procedure ntohl>"))
-(ntohs (groups Scheme) (scan-data "#<primitive-procedure ntohs>"))
-(null? (groups Scheme) (scan-data "#<primitive-procedure null?>"))
-(number->string (groups Scheme) (scan-data "#<primitive-procedure number->string>"))
-(number? (groups Scheme) (scan-data "#<primitive-procedure number?>"))
-(object->string (groups Scheme) (scan-data "#<primitive-procedure object->string>"))
-(object-address (groups Scheme) (scan-data "#<primitive-procedure object-address>"))
-(object-properties (groups Scheme) (scan-data "#<primitive-procedure object-properties>"))
-(object-property (groups Scheme) (scan-data "#<primitive-procedure object-property>"))
-(odd? (groups Scheme) (scan-data "#<primitive-procedure odd?>"))
-(open (groups POSIX Scheme) (scan-data "#<primitive-procedure open>"))
-(open-fdes (groups POSIX Scheme) (scan-data "#<primitive-procedure open-fdes>"))
-(open-file (groups Scheme) (scan-data "#<primitive-procedure open-file>"))
-(open-input-file (groups Scheme) (scan-data "#<procedure open-input-file (str)>"))
-(open-input-string (groups Scheme) (scan-data "#<primitive-procedure open-input-string>"))
-(open-io-file (groups Scheme) (scan-data "#<procedure open-io-file (str)>"))
-(open-output-file (groups Scheme) (scan-data "#<procedure open-output-file (str)>"))
-(open-output-string (groups Scheme) (scan-data "#<primitive-procedure open-output-string>"))
-(opendir (groups POSIX Scheme) (scan-data "#<primitive-procedure opendir>"))
-(operator? (groups Scheme) (scan-data "#<primitive-procedure operator?>"))
-(or (groups Scheme) (scan-data ""))
-(or-map (groups Scheme) (scan-data "#<procedure or-map (f lst)>"))
-(output-port? (groups Scheme) (scan-data "#<primitive-procedure output-port?>"))
-(pair? (groups Scheme) (scan-data "#<primitive-procedure pair?>"))
-(parse-path (groups Scheme) (scan-data "#<primitive-procedure parse-path>"))
-(passwd:dir (groups POSIX Scheme) (scan-data "#<procedure passwd:dir (obj)>"))
-(passwd:gecos (groups POSIX Scheme) (scan-data "#<procedure passwd:gecos (obj)>"))
-(passwd:gid (groups POSIX Scheme) (scan-data "#<procedure passwd:gid (obj)>"))
-(passwd:name (groups POSIX Scheme) (scan-data "#<procedure passwd:name (obj)>"))
-(passwd:passwd (groups POSIX Scheme) (scan-data "#<procedure passwd:passwd (obj)>"))
-(passwd:shell (groups POSIX Scheme) (scan-data "#<procedure passwd:shell (obj)>"))
-(passwd:uid (groups POSIX Scheme) (scan-data "#<procedure passwd:uid (obj)>"))
-(pause (groups POSIX Scheme) (scan-data "#<primitive-procedure pause>"))
-(peek (groups Scheme) (scan-data "#<procedure peek stuff>"))
-(peek-char (groups Scheme) (scan-data "#<primitive-procedure peek-char>"))
-(pipe (groups POSIX Scheme) (scan-data "#<primitive-procedure pipe>"))
-(pk (groups Scheme) (scan-data "#<procedure peek stuff>"))
-(port->fdes (groups POSIX Scheme) (scan-data "#<procedure port->fdes (port)>"))
-(port-closed? (groups Scheme) (scan-data "#<primitive-procedure port-closed?>"))
-(port-column (groups Scheme) (scan-data "#<primitive-procedure port-column>"))
-(port-filename (groups Scheme) (scan-data "#<primitive-procedure port-filename>"))
-(port-for-each (groups POSIX Scheme) (scan-data "#<primitive-procedure port-for-each>"))
-(port-line (groups Scheme) (scan-data "#<primitive-procedure port-line>"))
-(port-mode (groups POSIX Scheme) (scan-data "#<primitive-procedure port-mode>"))
-(port-revealed (groups POSIX Scheme) (scan-data "#<primitive-procedure port-revealed>"))
-(port-with-print-state (groups Scheme) (scan-data "#<primitive-procedure port-with-print-state>"))
-(port? (groups Scheme) (scan-data "#<primitive-procedure port?>"))
-(positive? (groups Scheme) (scan-data "#<primitive-procedure positive?>"))
-(primitive-eval (groups Scheme) (scan-data "#<primitive-procedure primitive-eval>"))
-(primitive-exit (groups POSIX Scheme) (scan-data "#<primitive-procedure primitive-exit>"))
-(primitive-fork (groups POSIX Scheme) (scan-data "#<primitive-procedure primitive-fork>"))
-(primitive-load (groups Scheme) (scan-data "#<primitive-procedure primitive-load>"))
-(primitive-load-path (groups Scheme) (scan-data "#<primitive-procedure primitive-load-path>"))
-(primitive-macro? (groups Scheme) (scan-data "#<procedure primitive-macro? (m)>"))
-(primitive-make-property (groups Scheme) (scan-data "#<primitive-procedure primitive-make-property>"))
-(primitive-move->fdes (groups POSIX Scheme) (scan-data "#<primitive-procedure primitive-move->fdes>"))
-(primitive-property-del! (groups Scheme) (scan-data "#<primitive-procedure primitive-property-del!>"))
-(primitive-property-ref (groups Scheme) (scan-data "#<primitive-procedure primitive-property-ref>"))
-(primitive-property-set! (groups Scheme) (scan-data "#<primitive-procedure primitive-property-set!>"))
-(print-disable (groups Scheme) (scan-data "#<procedure print-disable flags>"))
-(print-enable (groups Scheme) (scan-data "#<procedure print-enable flags>"))
-(print-options (groups Scheme) (scan-data "#<procedure print-options args>"))
-(print-options-interface (groups Scheme) (scan-data "#<primitive-procedure print-options-interface>"))
-(print-set! (groups Scheme) (scan-data ""))
-(procedure (groups Scheme) (scan-data "#<primitive-procedure procedure>"))
-(procedure->macro (groups Scheme) (scan-data "#<primitive-procedure procedure->macro>"))
-(procedure->memoizing-macro (groups Scheme) (scan-data "#<primitive-procedure procedure->memoizing-macro>"))
-(procedure->syntax (groups Scheme) (scan-data "#<primitive-procedure procedure->syntax>"))
-(procedure-documentation (groups Scheme) (scan-data "#<primitive-procedure procedure-documentation>"))
-(procedure-environment (groups Scheme) (scan-data "#<primitive-procedure procedure-environment>"))
-(procedure-name (groups Scheme) (scan-data "#<primitive-procedure procedure-name>"))
-(procedure-properties (groups Scheme) (scan-data "#<primitive-procedure procedure-properties>"))
-(procedure-property (groups Scheme) (scan-data "#<primitive-procedure procedure-property>"))
-(procedure-source (groups Scheme) (scan-data "#<primitive-procedure procedure-source>"))
-(procedure-with-setter? (groups Scheme) (scan-data "#<primitive-procedure procedure-with-setter?>"))
-(procedure? (groups Scheme) (scan-data "#<primitive-procedure procedure?>"))
-(process-define-module (groups Scheme) (scan-data "#<procedure process-define-module (args)>"))
-(process-use-modules (groups Scheme) (scan-data "#<procedure process-use-modules (module-interface-args)>"))
-(program-arguments (groups POSIX Scheme) (scan-data "#<primitive-procedure program-arguments>"))
-(promise? (groups Scheme) (scan-data "#<primitive-procedure promise?>"))
-(protoent:aliases (groups Scheme) (scan-data "#<procedure protoent:aliases (obj)>"))
-(protoent:name (groups Scheme) (scan-data "#<procedure protoent:name (obj)>"))
-(protoent:proto (groups Scheme) (scan-data "#<procedure protoent:proto (obj)>"))
-(provide (groups Scheme) (scan-data "#<procedure provide (sym)>"))
-(provided? (groups Scheme) (scan-data "#<procedure provided? (feature)>"))
-(purify-module! (groups Scheme) (scan-data "#<procedure purify-module! (module)>"))
-(putenv (groups POSIX Scheme) (scan-data "#<primitive-procedure putenv>"))
-(quasiquote (groups Scheme) (scan-data ""))
-(quit (groups Scheme) (scan-data "#<procedure quit args>"))
-(quote (groups Scheme) (scan-data ""))
-(quotient (groups Scheme) (scan-data "#<primitive-procedure quotient>"))
-(raise (groups POSIX Scheme) (scan-data "#<primitive-procedure raise>"))
-(random (groups Scheme) (scan-data "#<primitive-procedure random>"))
-(random:exp (groups Scheme) (scan-data "#<primitive-procedure random:exp>"))
-(random:hollow-sphere! (groups Scheme) (scan-data "#<primitive-procedure random:hollow-sphere!>"))
-(random:normal (groups Scheme) (scan-data "#<primitive-procedure random:normal>"))
-(random:normal-vector! (groups Scheme) (scan-data "#<primitive-procedure random:normal-vector!>"))
-(random:solid-sphere! (groups Scheme) (scan-data "#<primitive-procedure random:solid-sphere!>"))
-(random:uniform (groups Scheme) (scan-data "#<primitive-procedure random:uniform>"))
-(rational? (groups Scheme) (scan-data "#<primitive-procedure rational?>"))
-(re-export (groups Scheme) (scan-data ""))
-(re-export-syntax (groups Scheme) (scan-data ""))
-(read (groups Scheme) (scan-data "#<primitive-procedure read>"))
-(read-char (groups Scheme) (scan-data "#<primitive-procedure read-char>"))
-(read-disable (groups Scheme) (scan-data "#<procedure read-disable flags>"))
-(read-enable (groups Scheme) (scan-data "#<procedure read-enable flags>"))
-(read-eval? (groups Scheme) (scan-data ""))
-(read-hash-extend (groups Scheme) (scan-data "#<primitive-procedure read-hash-extend>"))
-(read-hash-procedures (groups Scheme) (scan-data ""))
-(read-options (groups Scheme) (scan-data "#<procedure read-options args>"))
-(read-options-interface (groups Scheme) (scan-data "#<primitive-procedure read-options-interface>"))
-(read-set! (groups Scheme) (scan-data ""))
-(read:array (groups Scheme) (scan-data "#<procedure read:array (digit port)>"))
-(read:uniform-vector (groups Scheme) (scan-data "#<procedure read:uniform-vector (proto port)>"))
-(readdir (groups POSIX Scheme) (scan-data "#<primitive-procedure readdir>"))
-(readlink (groups POSIX Scheme) (scan-data "#<primitive-procedure readlink>"))
-(real-part (groups Scheme) (scan-data "#<primitive-procedure real-part>"))
-(real? (groups Scheme) (scan-data "#<primitive-procedure real?>"))
-(record-accessor (groups Scheme) (scan-data "#<procedure record-accessor (rtd field-name)>"))
-(record-constructor (groups Scheme) (scan-data "#<procedure record-constructor (rtd . opt)>"))
-(record-modifier (groups Scheme) (scan-data "#<procedure record-modifier (rtd field-name)>"))
-(record-predicate (groups Scheme) (scan-data "#<procedure record-predicate (rtd)>"))
-(record-type-descriptor (groups Scheme) (scan-data "#<procedure record-type-descriptor (obj)>"))
-(record-type-fields (groups Scheme) (scan-data "#<procedure record-type-fields (obj)>"))
-(record-type-name (groups Scheme) (scan-data "#<procedure record-type-name (obj)>"))
-(record-type-vtable (groups Scheme) (scan-data ""))
-(record-type? (groups Scheme) (scan-data "#<procedure record-type? (obj)>"))
-(record? (groups Scheme) (scan-data "#<procedure record? (obj)>"))
-(recv! (groups Scheme) (scan-data "#<primitive-procedure recv!>"))
-(recvfrom! (groups Scheme) (scan-data "#<primitive-procedure recvfrom!>"))
-(redirect-port (groups POSIX Scheme) (scan-data "#<primitive-procedure redirect-port>"))
-(regexp-exec (groups Scheme) (scan-data "#<primitive-procedure regexp-exec>"))
-(regexp/basic (groups Scheme) (scan-data ""))
-(regexp/extended (groups Scheme) (scan-data ""))
-(regexp/icase (groups Scheme) (scan-data ""))
-(regexp/newline (groups Scheme) (scan-data ""))
-(regexp/notbol (groups Scheme) (scan-data ""))
-(regexp/noteol (groups Scheme) (scan-data ""))
-(regexp? (groups Scheme) (scan-data "#<primitive-procedure regexp?>"))
-(release-arbiter (groups Scheme) (scan-data "#<primitive-procedure release-arbiter>"))
-(release-port-handle (groups POSIX Scheme) (scan-data "#<procedure release-port-handle (port)>"))
-(remainder (groups Scheme) (scan-data "#<primitive-procedure remainder>"))
-(remove-hook! (groups Scheme) (scan-data "#<primitive-procedure remove-hook!>"))
-(rename-file (groups POSIX Scheme) (scan-data "#<primitive-procedure rename-file>"))
-(repl (groups Scheme) (scan-data "#<procedure repl (read evaler print)>"))
-(repl-reader (groups Scheme) (scan-data "#<procedure repl-reader (prompt)>"))
-(reset-hook! (groups Scheme) (scan-data "#<primitive-procedure reset-hook!>"))
-(resolve-interface (groups Scheme) (scan-data "#<procedure resolve-interface (name . args)>"))
-(resolve-module (groups Scheme) (scan-data "#<procedure resolve-module (name . maybe-autoload)>"))
-(restore-signals (groups POSIX Scheme) (scan-data "#<primitive-procedure restore-signals>"))
-(restricted-vector-sort! (groups Scheme) (scan-data "#<primitive-procedure restricted-vector-sort!>"))
-(reverse (groups Scheme) (scan-data "#<primitive-procedure reverse>"))
-(reverse! (groups Scheme) (scan-data "#<primitive-procedure reverse!>"))
-(rewinddir (groups POSIX Scheme) (scan-data "#<primitive-procedure rewinddir>"))
-(rmdir (groups POSIX Scheme) (scan-data "#<primitive-procedure rmdir>"))
-(round (groups Scheme) (scan-data "#<primitive-procedure round>"))
-(run-asyncs (groups Scheme) (scan-data "#<primitive-procedure run-asyncs>"))
-(run-hook (groups Scheme) (scan-data "#<primitive-procedure run-hook>"))
-(save-module-excursion (groups Scheme) (scan-data "#<procedure save-module-excursion (thunk)>"))
-(save-stack (groups Scheme) (scan-data "#<procedure save-stack narrowing>"))
-(scheme-file-suffix (groups Scheme) (scan-data "#<procedure scheme-file-suffix ()>"))
-(scm-error (groups Scheme) (scan-data "#<primitive-procedure scm-error>"))
-(scm-repl-print-unspecified (groups Scheme) (scan-data ""))
-(scm-repl-prompt (groups Scheme) (scan-data ""))
-(scm-repl-silent (groups Scheme) (scan-data ""))
-(scm-repl-verbose (groups Scheme) (scan-data ""))
-(scm-style-repl (groups Scheme) (scan-data "#<procedure scm-style-repl ()>"))
-(scm_I_am_dead (groups scm C) (scan-data B))
-(scm_abs (groups scm C) (scan-data T))
-(scm_accept (groups scm C) (scan-data T))
-(scm_access (groups scm C) (scan-data T))
-(scm_accessor_method_slot_definition (groups scm C) (scan-data T))
-(scm_acons (groups scm C) (scan-data T))
-(scm_acosh (groups scm C) (scan-data T))
-(scm_add_feature (groups scm C) (scan-data T))
-(scm_add_hook_x (groups scm C) (scan-data T))
-(scm_add_method (groups scm C) (scan-data T))
-(scm_add_slot (groups scm C) (scan-data T))
-(scm_add_to_port_table (groups scm C) (scan-data T))
-(scm_addbig (groups scm C) (scan-data T))
-(scm_after_gc_c_hook (groups scm C) (scan-data B))
-(scm_after_gc_hook (groups scm C) (scan-data B))
-(scm_after_sweep_c_hook (groups scm C) (scan-data B))
-(scm_aind (groups scm C) (scan-data T))
-(scm_alarm (groups scm C) (scan-data T))
-(scm_alloc_struct (groups scm C) (scan-data T))
-(scm_allocate_string (groups scm C) (scan-data T))
-(scm_angle (groups scm C) (scan-data T))
-(scm_append (groups scm C) (scan-data T))
-(scm_append_x (groups scm C) (scan-data T))
-(scm_apply (groups scm C) (scan-data T))
-(scm_apply_0 (groups scm C) (scan-data T))
-(scm_apply_1 (groups scm C) (scan-data T))
-(scm_apply_2 (groups scm C) (scan-data T))
-(scm_apply_3 (groups scm C) (scan-data T))
-(scm_apply_generic (groups scm C) (scan-data T))
-(scm_apply_with_dynamic_root (groups scm C) (scan-data T))
-(scm_arg_type_key (groups scm C) (scan-data B))
-(scm_args_number_key (groups scm C) (scan-data B))
-(scm_array_contents (groups scm C) (scan-data T))
-(scm_array_copy_x (groups scm C) (scan-data T))
-(scm_array_dimensions (groups scm C) (scan-data T))
-(scm_array_equal_p (groups scm C) (scan-data T))
-(scm_array_fill_int (groups scm C) (scan-data T))
-(scm_array_fill_x (groups scm C) (scan-data T))
-(scm_array_for_each (groups scm C) (scan-data T))
-(scm_array_identity (groups scm C) (scan-data T))
-(scm_array_in_bounds_p (groups scm C) (scan-data T))
-(scm_array_index_map_x (groups scm C) (scan-data T))
-(scm_array_map_x (groups scm C) (scan-data T))
-(scm_array_p (groups scm C) (scan-data T))
-(scm_array_prototype (groups scm C) (scan-data T))
-(scm_array_rank (groups scm C) (scan-data T))
-(scm_array_set_x (groups scm C) (scan-data T))
-(scm_array_to_list (groups scm C) (scan-data T))
-(scm_ash (groups scm C) (scan-data T))
-(scm_asinh (groups scm C) (scan-data T))
-(scm_assoc (groups scm C) (scan-data T))
-(scm_assoc_ref (groups scm C) (scan-data T))
-(scm_assoc_remove_x (groups scm C) (scan-data T))
-(scm_assoc_set_x (groups scm C) (scan-data T))
-(scm_assq (groups scm C) (scan-data T))
-(scm_assq_ref (groups scm C) (scan-data T))
-(scm_assq_remove_x (groups scm C) (scan-data T))
-(scm_assq_set_x (groups scm C) (scan-data T))
-(scm_assv (groups scm C) (scan-data T))
-(scm_assv_ref (groups scm C) (scan-data T))
-(scm_assv_remove_x (groups scm C) (scan-data T))
-(scm_assv_set_x (groups scm C) (scan-data T))
-(scm_async (groups scm C) (scan-data T))
-(scm_async_click (groups scm C) (scan-data T))
-(scm_async_mark (groups scm C) (scan-data T))
-(scm_asyncs_pending_p (groups scm C) (scan-data D))
-(scm_atanh (groups scm C) (scan-data T))
-(scm_backtrace (groups scm C) (scan-data T))
-(scm_badargsp (groups scm C) (scan-data T))
-(scm_basename (groups scm C) (scan-data T))
-(scm_basic_basic_make_class (groups scm C) (scan-data T))
-(scm_basic_make_class (groups scm C) (scan-data T))
-(scm_before_gc_c_hook (groups scm C) (scan-data B))
-(scm_before_mark_c_hook (groups scm C) (scan-data B))
-(scm_before_sweep_c_hook (groups scm C) (scan-data B))
-(scm_big_and (groups scm C) (scan-data T))
-(scm_big_ior (groups scm C) (scan-data T))
-(scm_big_test (groups scm C) (scan-data T))
-(scm_big_xor (groups scm C) (scan-data T))
-(scm_bigcomp (groups scm C) (scan-data T))
-(scm_bigequal (groups scm C) (scan-data T))
-(scm_bigprint (groups scm C) (scan-data T))
-(scm_bind (groups scm C) (scan-data T))
-(scm_bit_count (groups scm C) (scan-data T))
-(scm_bit_count_star (groups scm C) (scan-data T))
-(scm_bit_extract (groups scm C) (scan-data T))
-(scm_bit_invert_x (groups scm C) (scan-data T))
-(scm_bit_position (groups scm C) (scan-data T))
-(scm_bit_set_star_x (groups scm C) (scan-data T))
-(scm_block_gc (groups scm C) (scan-data D))
-(scm_body_thunk (groups scm C) (scan-data T))
-(scm_boolean_p (groups scm C) (scan-data T))
-(scm_boot_guile (groups scm C) (scan-data T))
-(scm_boot_guile_1_live (groups scm C) (scan-data D))
-(scm_c_call_with_current_module (groups scm C) (scan-data T))
-(scm_c_chars2byvect (groups scm C) (scan-data T))
-(scm_c_chars2scm (groups scm C) (scan-data T))
-(scm_c_default_rstate (groups scm C) (scan-data T))
-(scm_c_define (groups scm C) (scan-data T))
-(scm_c_define_gsubr (groups scm C) (scan-data T))
-(scm_c_define_gsubr_with_generic (groups scm C) (scan-data T))
-(scm_c_define_module (groups scm C) (scan-data T))
-(scm_c_define_subr (groups scm C) (scan-data T))
-(scm_c_define_subr_with_generic (groups scm C) (scan-data T))
-(scm_c_doubles2dvect (groups scm C) (scan-data T))
-(scm_c_doubles2scm (groups scm C) (scan-data T))
-(scm_c_environment_cell (groups scm C) (scan-data T))
-(scm_c_environment_fold (groups scm C) (scan-data T))
-(scm_c_environment_observe (groups scm C) (scan-data T))
-(scm_c_environment_ref (groups scm C) (scan-data T))
-(scm_c_eval_string (groups scm C) (scan-data T))
-(scm_c_exp1 (groups scm C) (scan-data T))
-(scm_c_export (groups scm C) (scan-data T))
-(scm_c_floats2fvect (groups scm C) (scan-data T))
-(scm_c_floats2scm (groups scm C) (scan-data T))
-(scm_c_get_internal_run_time (groups scm C) (scan-data T))
-(scm_c_hook_add (groups scm C) (scan-data T))
-(scm_c_hook_init (groups scm C) (scan-data T))
-(scm_c_hook_remove (groups scm C) (scan-data T))
-(scm_c_hook_run (groups scm C) (scan-data T))
-(scm_c_ints2ivect (groups scm C) (scan-data T))
-(scm_c_ints2scm (groups scm C) (scan-data T))
-(scm_c_issue_deprecation_warning (groups scm C) (scan-data T))
-(scm_c_issue_deprecation_warning_fmt (groups scm C) (scan-data T))
-(scm_c_load_extension (groups scm C) (scan-data T))
-(scm_c_longs2ivect (groups scm C) (scan-data T))
-(scm_c_longs2scm (groups scm C) (scan-data T))
-(scm_c_lookup (groups scm C) (scan-data T))
-(scm_c_make_gsubr (groups scm C) (scan-data T))
-(scm_c_make_gsubr_with_generic (groups scm C) (scan-data T))
-(scm_c_make_hash_table (groups scm C) (scan-data T))
-(scm_c_make_keyword (groups scm C) (scan-data T))
-(scm_c_make_rstate (groups scm C) (scan-data T))
-(scm_c_make_subr (groups scm C) (scan-data T))
-(scm_c_make_subr_with_generic (groups scm C) (scan-data T))
-(scm_c_make_vector (groups scm C) (scan-data T))
-(scm_c_memq (groups scm C) (scan-data T))
-(scm_c_module_define (groups scm C) (scan-data T))
-(scm_c_module_lookup (groups scm C) (scan-data T))
-(scm_c_normal01 (groups scm C) (scan-data T))
-(scm_c_primitive_load (groups scm C) (scan-data T))
-(scm_c_primitive_load_path (groups scm C) (scan-data T))
-(scm_c_random (groups scm C) (scan-data T))
-(scm_c_random_bignum (groups scm C) (scan-data T))
-(scm_c_read (groups scm C) (scan-data T))
-(scm_c_read_string (groups scm C) (scan-data T))
-(scm_c_register_extension (groups scm C) (scan-data T))
-(scm_c_resolve_module (groups scm C) (scan-data T))
-(scm_c_run_hook (groups scm C) (scan-data T))
-(scm_c_scm2chars (groups scm C) (scan-data T))
-(scm_c_scm2doubles (groups scm C) (scan-data T))
-(scm_c_scm2floats (groups scm C) (scan-data T))
-(scm_c_scm2ints (groups scm C) (scan-data T))
-(scm_c_scm2longs (groups scm C) (scan-data T))
-(scm_c_scm2shorts (groups scm C) (scan-data T))
-(scm_c_shorts2scm (groups scm C) (scan-data T))
-(scm_c_shorts2svect (groups scm C) (scan-data T))
-(scm_c_source_property_breakpoint_p (groups scm C) (scan-data T))
-(scm_c_string2str (groups scm C) (scan-data T))
-(scm_c_substring2str (groups scm C) (scan-data T))
-(scm_c_symbol2str (groups scm C) (scan-data T))
-(scm_c_uints2uvect (groups scm C) (scan-data T))
-(scm_c_ulongs2uvect (groups scm C) (scan-data T))
-(scm_c_uniform01 (groups scm C) (scan-data T))
-(scm_c_use_module (groups scm C) (scan-data T))
-(scm_c_with_fluid (groups scm C) (scan-data T))
-(scm_c_with_fluids (groups scm C) (scan-data T))
-(scm_c_write (groups scm C) (scan-data T))
-(scm_call_0 (groups scm C) (scan-data T))
-(scm_call_1 (groups scm C) (scan-data T))
-(scm_call_2 (groups scm C) (scan-data T))
-(scm_call_3 (groups scm C) (scan-data T))
-(scm_call_4 (groups scm C) (scan-data T))
-(scm_call_generic_0 (groups scm C) (scan-data T))
-(scm_call_generic_1 (groups scm C) (scan-data T))
-(scm_call_generic_2 (groups scm C) (scan-data T))
-(scm_call_generic_3 (groups scm C) (scan-data T))
-(scm_call_with_dynamic_root (groups scm C) (scan-data T))
-(scm_call_with_input_string (groups scm C) (scan-data T))
-(scm_call_with_new_thread (groups scm C) (scan-data T))
-(scm_call_with_output_string (groups scm C) (scan-data T))
-(scm_casei_streq (groups scm C) (scan-data T))
-(scm_catch (groups scm C) (scan-data T))
-(scm_cellp (groups scm C) (scan-data T))
-(scm_cells_allocated (groups scm C) (scan-data D))
-(scm_ceval (groups scm C) (scan-data T))
-(scm_ceval_ptr (groups scm C) (scan-data B))
-(scm_change_object_class (groups scm C) (scan-data T))
-(scm_char_alphabetic_p (groups scm C) (scan-data T))
-(scm_char_ci_eq_p (groups scm C) (scan-data T))
-(scm_char_ci_geq_p (groups scm C) (scan-data T))
-(scm_char_ci_gr_p (groups scm C) (scan-data T))
-(scm_char_ci_leq_p (groups scm C) (scan-data T))
-(scm_char_ci_less_p (groups scm C) (scan-data T))
-(scm_char_downcase (groups scm C) (scan-data T))
-(scm_char_eq_p (groups scm C) (scan-data T))
-(scm_char_geq_p (groups scm C) (scan-data T))
-(scm_char_gr_p (groups scm C) (scan-data T))
-(scm_char_is_both_p (groups scm C) (scan-data T))
-(scm_char_leq_p (groups scm C) (scan-data T))
-(scm_char_less_p (groups scm C) (scan-data T))
-(scm_char_lower_case_p (groups scm C) (scan-data T))
-(scm_char_numeric_p (groups scm C) (scan-data T))
-(scm_char_p (groups scm C) (scan-data T))
-(scm_char_ready_p (groups scm C) (scan-data T))
-(scm_char_to_integer (groups scm C) (scan-data T))
-(scm_char_upcase (groups scm C) (scan-data T))
-(scm_char_upper_case_p (groups scm C) (scan-data T))
-(scm_char_whitespace_p (groups scm C) (scan-data T))
-(scm_charnames (groups scm C) (scan-data D))
-(scm_charnums (groups scm C) (scan-data R))
-(scm_chdir (groups scm C) (scan-data T))
-(scm_check_apply_p (groups scm C) (scan-data B))
-(scm_check_entry_p (groups scm C) (scan-data B))
-(scm_check_exit_p (groups scm C) (scan-data B))
-(scm_chmod (groups scm C) (scan-data T))
-(scm_chown (groups scm C) (scan-data T))
-(scm_chroot (groups scm C) (scan-data T))
-(scm_class_accessor (groups scm C) (scan-data B))
-(scm_class_boolean (groups scm C) (scan-data B))
-(scm_class_char (groups scm C) (scan-data B))
-(scm_class_class (groups scm C) (scan-data B))
-(scm_class_complex (groups scm C) (scan-data B))
-(scm_class_direct_methods (groups scm C) (scan-data T))
-(scm_class_direct_slots (groups scm C) (scan-data T))
-(scm_class_direct_subclasses (groups scm C) (scan-data T))
-(scm_class_direct_supers (groups scm C) (scan-data T))
-(scm_class_double (groups scm C) (scan-data B))
-(scm_class_entity (groups scm C) (scan-data B))
-(scm_class_entity_class (groups scm C) (scan-data B))
-(scm_class_entity_with_setter (groups scm C) (scan-data B))
-(scm_class_environment (groups scm C) (scan-data T))
-(scm_class_float (groups scm C) (scan-data B))
-(scm_class_foreign_class (groups scm C) (scan-data B))
-(scm_class_foreign_object (groups scm C) (scan-data B))
-(scm_class_foreign_slot (groups scm C) (scan-data B))
-(scm_class_generic (groups scm C) (scan-data B))
-(scm_class_generic_with_setter (groups scm C) (scan-data B))
-(scm_class_input_output_port (groups scm C) (scan-data B))
-(scm_class_input_port (groups scm C) (scan-data B))
-(scm_class_int (groups scm C) (scan-data B))
-(scm_class_integer (groups scm C) (scan-data B))
-(scm_class_keyword (groups scm C) (scan-data B))
-(scm_class_list (groups scm C) (scan-data B))
-(scm_class_method (groups scm C) (scan-data B))
-(scm_class_name (groups scm C) (scan-data T))
-(scm_class_null (groups scm C) (scan-data B))
-(scm_class_number (groups scm C) (scan-data B))
-(scm_class_object (groups scm C) (scan-data B))
-(scm_class_of (groups scm C) (scan-data T))
-(scm_class_opaque (groups scm C) (scan-data B))
-(scm_class_operator_class (groups scm C) (scan-data B))
-(scm_class_operator_with_setter_class (groups scm C) (scan-data B))
-(scm_class_output_port (groups scm C) (scan-data B))
-(scm_class_pair (groups scm C) (scan-data B))
-(scm_class_port (groups scm C) (scan-data B))
-(scm_class_precedence_list (groups scm C) (scan-data T))
-(scm_class_primitive_generic (groups scm C) (scan-data B))
-(scm_class_procedure (groups scm C) (scan-data B))
-(scm_class_procedure_class (groups scm C) (scan-data B))
-(scm_class_procedure_with_setter (groups scm C) (scan-data B))
-(scm_class_protected (groups scm C) (scan-data B))
-(scm_class_protected_opaque (groups scm C) (scan-data B))
-(scm_class_protected_read_only (groups scm C) (scan-data B))
-(scm_class_read_only (groups scm C) (scan-data B))
-(scm_class_real (groups scm C) (scan-data B))
-(scm_class_scm (groups scm C) (scan-data B))
-(scm_class_self (groups scm C) (scan-data B))
-(scm_class_simple_method (groups scm C) (scan-data B))
-(scm_class_slots (groups scm C) (scan-data T))
-(scm_class_string (groups scm C) (scan-data B))
-(scm_class_symbol (groups scm C) (scan-data B))
-(scm_class_top (groups scm C) (scan-data B))
-(scm_class_unknown (groups scm C) (scan-data B))
-(scm_class_vector (groups scm C) (scan-data B))
-(scm_close (groups scm C) (scan-data T))
-(scm_close_fdes (groups scm C) (scan-data T))
-(scm_close_input_port (groups scm C) (scan-data T))
-(scm_close_output_port (groups scm C) (scan-data T))
-(scm_close_port (groups scm C) (scan-data T))
-(scm_closedir (groups scm C) (scan-data T))
-(scm_closure (groups scm C) (scan-data T))
-(scm_closure_p (groups scm C) (scan-data T))
-(scm_compile_shell_switches (groups scm C) (scan-data T))
-(scm_complex_equalp (groups scm C) (scan-data T))
-(scm_components (groups scm C) (scan-data B))
-(scm_compute_applicable_methods (groups scm C) (scan-data T))
-(scm_connect (groups scm C) (scan-data T))
-(scm_cons (groups scm C) (scan-data T))
-(scm_cons2 (groups scm C) (scan-data T))
-(scm_cons_source (groups scm C) (scan-data T))
-(scm_cons_star (groups scm C) (scan-data T))
-(scm_copy_big_dec (groups scm C) (scan-data T))
-(scm_copy_file (groups scm C) (scan-data T))
-(scm_copy_fluids (groups scm C) (scan-data T))
-(scm_copy_random_state (groups scm C) (scan-data T))
-(scm_copy_smaller (groups scm C) (scan-data T))
-(scm_copy_tree (groups scm C) (scan-data T))
-(scm_count_argv (groups scm C) (scan-data T))
-(scm_critical_section_mutex (groups scm C) (scan-data B))
-(scm_crypt (groups scm C) (scan-data T))
-(scm_ctermid (groups scm C) (scan-data T))
-(scm_current_error_port (groups scm C) (scan-data T))
-(scm_current_input_port (groups scm C) (scan-data T))
-(scm_current_load_port (groups scm C) (scan-data T))
-(scm_current_module (groups scm C) (scan-data T))
-(scm_current_module_lookup_closure (groups scm C) (scan-data T))
-(scm_current_module_transformer (groups scm C) (scan-data T))
-(scm_current_output_port (groups scm C) (scan-data T))
-(scm_current_time (groups scm C) (scan-data T))
-(scm_cuserid (groups scm C) (scan-data T))
-(scm_cvref (groups scm C) (scan-data T))
-(scm_dapply (groups scm C) (scan-data T))
-(scm_dblprec (groups scm C) (scan-data B))
-(scm_debug_eframe_size (groups scm C) (scan-data B))
-(scm_debug_mode (groups scm C) (scan-data B))
-(scm_debug_object_p (groups scm C) (scan-data T))
-(scm_debug_options (groups scm C) (scan-data T))
-(scm_debug_opts (groups scm C) (scan-data D))
-(scm_default_init_heap_size_1 (groups scm C) (scan-data D))
-(scm_default_init_heap_size_2 (groups scm C) (scan-data D))
-(scm_default_max_segment_size (groups scm C) (scan-data D))
-(scm_default_min_yield_1 (groups scm C) (scan-data D))
-(scm_default_min_yield_2 (groups scm C) (scan-data D))
-(scm_define (groups scm C) (scan-data T))
-(scm_definedp (groups scm C) (scan-data T))
-(scm_delete (groups scm C) (scan-data T))
-(scm_delete1_x (groups scm C) (scan-data T))
-(scm_delete_file (groups scm C) (scan-data T))
-(scm_delete_x (groups scm C) (scan-data T))
-(scm_delq (groups scm C) (scan-data T))
-(scm_delq1_x (groups scm C) (scan-data T))
-(scm_delq_x (groups scm C) (scan-data T))
-(scm_delv (groups scm C) (scan-data T))
-(scm_delv1_x (groups scm C) (scan-data T))
-(scm_delv_x (groups scm C) (scan-data T))
-(scm_deprecated_newcell (groups scm C) (scan-data T))
-(scm_deprecated_newcell2 (groups scm C) (scan-data T))
-(scm_destroy_guardian_x (groups scm C) (scan-data T))
-(scm_deval (groups scm C) (scan-data T))
-(scm_difference (groups scm C) (scan-data T))
-(scm_dimensions_to_uniform_array (groups scm C) (scan-data T))
-(scm_directory_stream_p (groups scm C) (scan-data T))
-(scm_dirname (groups scm C) (scan-data T))
-(scm_display (groups scm C) (scan-data T))
-(scm_display_application (groups scm C) (scan-data T))
-(scm_display_backtrace (groups scm C) (scan-data T))
-(scm_display_error (groups scm C) (scan-data T))
-(scm_display_error_message (groups scm C) (scan-data T))
-(scm_divbigdig (groups scm C) (scan-data T))
-(scm_divide (groups scm C) (scan-data T))
-(scm_done_free (groups scm C) (scan-data T))
-(scm_done_malloc (groups scm C) (scan-data T))
-(scm_dot_string (groups scm C) (scan-data B))
-(scm_double2num (groups scm C) (scan-data T))
-(scm_doubly_weak_hash_table_p (groups scm C) (scan-data T))
-(scm_dowinds (groups scm C) (scan-data T))
-(scm_downcase (groups scm C) (scan-data T))
-(scm_drain_input (groups scm C) (scan-data T))
-(scm_dup2 (groups scm C) (scan-data T))
-(scm_dup_to_fdes (groups scm C) (scan-data T))
-(scm_dynamic_args_call (groups scm C) (scan-data T))
-(scm_dynamic_call (groups scm C) (scan-data T))
-(scm_dynamic_func (groups scm C) (scan-data T))
-(scm_dynamic_link (groups scm C) (scan-data T))
-(scm_dynamic_object_p (groups scm C) (scan-data T))
-(scm_dynamic_root (groups scm C) (scan-data T))
-(scm_dynamic_unlink (groups scm C) (scan-data T))
-(scm_dynamic_wind (groups scm C) (scan-data T))
-(scm_enable_primitive_generic_x (groups scm C) (scan-data T))
-(scm_enclose_array (groups scm C) (scan-data T))
-(scm_end_input (groups scm C) (scan-data T))
-(scm_ensure_accessor (groups scm C) (scan-data T))
-(scm_entity_p (groups scm C) (scan-data T))
-(scm_env_module (groups scm C) (scan-data T))
-(scm_env_top_level (groups scm C) (scan-data T))
-(scm_environ (groups scm C) (scan-data T))
-(scm_environment_bound_p (groups scm C) (scan-data T))
-(scm_environment_cell (groups scm C) (scan-data T))
-(scm_environment_define (groups scm C) (scan-data T))
-(scm_environment_fold (groups scm C) (scan-data T))
-(scm_environment_observe (groups scm C) (scan-data T))
-(scm_environment_observe_weak (groups scm C) (scan-data T))
-(scm_environment_p (groups scm C) (scan-data T))
-(scm_environment_ref (groups scm C) (scan-data T))
-(scm_environment_set_x (groups scm C) (scan-data T))
-(scm_environment_undefine (groups scm C) (scan-data T))
-(scm_environment_unobserve (groups scm C) (scan-data T))
-(scm_environments_prehistory (groups scm C) (scan-data T))
-(scm_eof_object_p (groups scm C) (scan-data T))
-(scm_eq_p (groups scm C) (scan-data T))
-(scm_equal_p (groups scm C) (scan-data T))
-(scm_eqv_p (groups scm C) (scan-data T))
-(scm_error (groups scm C) (scan-data T))
-(scm_error_environment_immutable_binding (groups scm C) (scan-data T))
-(scm_error_environment_immutable_location (groups scm C) (scan-data T))
-(scm_error_environment_unbound (groups scm C) (scan-data T))
-(scm_error_num_args_subr (groups scm C) (scan-data T))
-(scm_error_revive_threads (groups scm C) (scan-data T))
-(scm_error_scm (groups scm C) (scan-data T))
-(scm_eval (groups scm C) (scan-data T))
-(scm_eval_args (groups scm C) (scan-data T))
-(scm_eval_body (groups scm C) (scan-data T))
-(scm_eval_car (groups scm C) (scan-data T))
-(scm_eval_closure_lookup (groups scm C) (scan-data T))
-(scm_eval_environment_imported (groups scm C) (scan-data T))
-(scm_eval_environment_local (groups scm C) (scan-data T))
-(scm_eval_environment_p (groups scm C) (scan-data T))
-(scm_eval_environment_set_imported_x (groups scm C) (scan-data T))
-(scm_eval_environment_set_local_x (groups scm C) (scan-data T))
-(scm_eval_options_interface (groups scm C) (scan-data T))
-(scm_eval_opts (groups scm C) (scan-data D))
-(scm_eval_stack (groups scm C) (scan-data B))
-(scm_eval_string (groups scm C) (scan-data T))
-(scm_eval_x (groups scm C) (scan-data T))
-(scm_evaluator_trap_table (groups scm C) (scan-data D))
-(scm_evaluator_traps (groups scm C) (scan-data T))
-(scm_even_p (groups scm C) (scan-data T))
-(scm_evict_ports (groups scm C) (scan-data T))
-(scm_exact_p (groups scm C) (scan-data T))
-(scm_exact_to_inexact (groups scm C) (scan-data T))
-(scm_execl (groups scm C) (scan-data T))
-(scm_execle (groups scm C) (scan-data T))
-(scm_execlp (groups scm C) (scan-data T))
-(scm_exit_status (groups scm C) (scan-data T))
-(scm_expmem (groups scm C) (scan-data D))
-(scm_export_environment_p (groups scm C) (scan-data T))
-(scm_export_environment_private (groups scm C) (scan-data T))
-(scm_export_environment_set_private_x (groups scm C) (scan-data T))
-(scm_export_environment_set_signature_x (groups scm C) (scan-data T))
-(scm_export_environment_signature (groups scm C) (scan-data T))
-(scm_f_apply (groups scm C) (scan-data B))
-(scm_f_gsubr_apply (groups scm C) (scan-data B))
-(scm_fcntl (groups scm C) (scan-data T))
-(scm_fdes_to_port (groups scm C) (scan-data T))
-(scm_fdes_to_ports (groups scm C) (scan-data T))
-(scm_fdopen (groups scm C) (scan-data T))
-(scm_file_port_p (groups scm C) (scan-data T))
-(scm_fileno (groups scm C) (scan-data T))
-(scm_fill_input (groups scm C) (scan-data T))
-(scm_find_executable (groups scm C) (scan-data T))
-(scm_find_method (groups scm C) (scan-data T))
-(scm_finish_srcprop (groups scm C) (scan-data T))
-(scm_float2num (groups scm C) (scan-data T))
-(scm_flock (groups scm C) (scan-data T))
-(scm_fluid_p (groups scm C) (scan-data T))
-(scm_fluid_ref (groups scm C) (scan-data T))
-(scm_fluid_set_x (groups scm C) (scan-data T))
-(scm_flush (groups scm C) (scan-data T))
-(scm_flush_all_ports (groups scm C) (scan-data T))
-(scm_flush_ws (groups scm C) (scan-data T))
-(scm_for_each (groups scm C) (scan-data T))
-(scm_force (groups scm C) (scan-data T))
-(scm_force_output (groups scm C) (scan-data T))
-(scm_fork (groups scm C) (scan-data T))
-(scm_frame_arguments (groups scm C) (scan-data T))
-(scm_frame_evaluating_args_p (groups scm C) (scan-data T))
-(scm_frame_next (groups scm C) (scan-data T))
-(scm_frame_number (groups scm C) (scan-data T))
-(scm_frame_overflow_p (groups scm C) (scan-data T))
-(scm_frame_p (groups scm C) (scan-data T))
-(scm_frame_previous (groups scm C) (scan-data T))
-(scm_frame_procedure (groups scm C) (scan-data T))
-(scm_frame_procedure_p (groups scm C) (scan-data T))
-(scm_frame_real_p (groups scm C) (scan-data T))
-(scm_frame_source (groups scm C) (scan-data T))
-(scm_free0 (groups scm C) (scan-data T))
-(scm_free_print_state (groups scm C) (scan-data T))
-(scm_free_subr_entry (groups scm C) (scan-data T))
-(scm_freelist (groups scm C) (scan-data D))
-(scm_freelist2 (groups scm C) (scan-data D))
-(scm_fsync (groups scm C) (scan-data T))
-(scm_ftell (groups scm C) (scan-data T))
-(scm_gc (groups scm C) (scan-data T))
-(scm_gc_cells_collected (groups scm C) (scan-data B))
-(scm_gc_cells_marked_acc (groups scm C) (scan-data D))
-(scm_gc_cells_swept (groups scm C) (scan-data D))
-(scm_gc_cells_swept_acc (groups scm C) (scan-data D))
-(scm_gc_for_newcell (groups scm C) (scan-data T))
-(scm_gc_free (groups scm C) (scan-data T))
-(scm_gc_heap_lock (groups scm C) (scan-data D))
-(scm_gc_malloc (groups scm C) (scan-data T))
-(scm_gc_malloc_collected (groups scm C) (scan-data B))
-(scm_gc_mark (groups scm C) (scan-data T))
-(scm_gc_mark_dependencies (groups scm C) (scan-data T))
-(scm_gc_mark_time_taken (groups scm C) (scan-data D))
-(scm_gc_ports_collected (groups scm C) (scan-data B))
-(scm_gc_protect_object (groups scm C) (scan-data T))
-(scm_gc_realloc (groups scm C) (scan-data T))
-(scm_gc_register_collectable_memory (groups scm C) (scan-data T))
-(scm_gc_register_root (groups scm C) (scan-data T))
-(scm_gc_register_roots (groups scm C) (scan-data T))
-(scm_gc_running_p (groups scm C) (scan-data D))
-(scm_gc_stats (groups scm C) (scan-data T))
-(scm_gc_strdup (groups scm C) (scan-data T))
-(scm_gc_strndup (groups scm C) (scan-data T))
-(scm_gc_sweep (groups scm C) (scan-data T))
-(scm_gc_sweep_time_taken (groups scm C) (scan-data D))
-(scm_gc_time_taken (groups scm C) (scan-data D))
-(scm_gc_times (groups scm C) (scan-data D))
-(scm_gc_unprotect_object (groups scm C) (scan-data T))
-(scm_gc_unregister_collectable_memory (groups scm C) (scan-data T))
-(scm_gc_unregister_root (groups scm C) (scan-data T))
-(scm_gc_unregister_roots (groups scm C) (scan-data T))
-(scm_gc_yield (groups scm C) (scan-data B))
-(scm_gcd (groups scm C) (scan-data T))
-(scm_generic_capability_p (groups scm C) (scan-data T))
-(scm_generic_function_methods (groups scm C) (scan-data T))
-(scm_generic_function_name (groups scm C) (scan-data T))
-(scm_gensym (groups scm C) (scan-data T))
-(scm_geq_p (groups scm C) (scan-data T))
-(scm_get_internal_real_time (groups scm C) (scan-data T))
-(scm_get_internal_run_time (groups scm C) (scan-data T))
-(scm_get_keyword (groups scm C) (scan-data T))
-(scm_get_meta_args (groups scm C) (scan-data T))
-(scm_get_one_zombie (groups scm C) (scan-data T))
-(scm_get_output_string (groups scm C) (scan-data T))
-(scm_get_pre_modules_obarray (groups scm C) (scan-data T))
-(scm_get_print_state (groups scm C) (scan-data T))
-(scm_get_stack_base (groups scm C) (scan-data T))
-(scm_getc (groups scm C) (scan-data T))
-(scm_getcwd (groups scm C) (scan-data T))
-(scm_getegid (groups scm C) (scan-data T))
-(scm_getenv (groups scm C) (scan-data T))
-(scm_geteuid (groups scm C) (scan-data T))
-(scm_getgid (groups scm C) (scan-data T))
-(scm_getgrgid (groups scm C) (scan-data T))
-(scm_getgroups (groups scm C) (scan-data T))
-(scm_gethost (groups scm C) (scan-data T))
-(scm_gethostname (groups scm C) (scan-data T))
-(scm_getitimer (groups scm C) (scan-data T))
-(scm_getlogin (groups scm C) (scan-data T))
-(scm_getnet (groups scm C) (scan-data T))
-(scm_getpass (groups scm C) (scan-data T))
-(scm_getpeername (groups scm C) (scan-data T))
-(scm_getpgrp (groups scm C) (scan-data T))
-(scm_getpid (groups scm C) (scan-data T))
-(scm_getppid (groups scm C) (scan-data T))
-(scm_getpriority (groups scm C) (scan-data T))
-(scm_getproto (groups scm C) (scan-data T))
-(scm_getpwuid (groups scm C) (scan-data T))
-(scm_getserv (groups scm C) (scan-data T))
-(scm_getsockname (groups scm C) (scan-data T))
-(scm_getsockopt (groups scm C) (scan-data T))
-(scm_gettimeofday (groups scm C) (scan-data T))
-(scm_getuid (groups scm C) (scan-data T))
-(scm_gmtime (groups scm C) (scan-data T))
-(scm_gr_p (groups scm C) (scan-data T))
-(scm_grow_tok_buf (groups scm C) (scan-data T))
-(scm_gsubr_apply (groups scm C) (scan-data T))
-(scm_guard (groups scm C) (scan-data T))
-(scm_guardian_destroyed_p (groups scm C) (scan-data T))
-(scm_guardian_greedy_p (groups scm C) (scan-data T))
-(scm_handle_by_message (groups scm C) (scan-data T))
-(scm_handle_by_message_noexit (groups scm C) (scan-data T))
-(scm_handle_by_proc (groups scm C) (scan-data T))
-(scm_handle_by_proc_catching_all (groups scm C) (scan-data T))
-(scm_handle_by_throw (groups scm C) (scan-data T))
-(scm_hash (groups scm C) (scan-data T))
-(scm_hash_create_handle_x (groups scm C) (scan-data T))
-(scm_hash_fn_create_handle_x (groups scm C) (scan-data T))
-(scm_hash_fn_get_handle (groups scm C) (scan-data T))
-(scm_hash_fn_ref (groups scm C) (scan-data T))
-(scm_hash_fn_remove_x (groups scm C) (scan-data T))
-(scm_hash_fn_set_x (groups scm C) (scan-data T))
-(scm_hash_fold (groups scm C) (scan-data T))
-(scm_hash_get_handle (groups scm C) (scan-data T))
-(scm_hash_ref (groups scm C) (scan-data T))
-(scm_hash_remove_x (groups scm C) (scan-data T))
-(scm_hash_set_x (groups scm C) (scan-data T))
-(scm_hasher (groups scm C) (scan-data T))
-(scm_hashq (groups scm C) (scan-data T))
-(scm_hashq_create_handle_x (groups scm C) (scan-data T))
-(scm_hashq_get_handle (groups scm C) (scan-data T))
-(scm_hashq_ref (groups scm C) (scan-data T))
-(scm_hashq_remove_x (groups scm C) (scan-data T))
-(scm_hashq_set_x (groups scm C) (scan-data T))
-(scm_hashv (groups scm C) (scan-data T))
-(scm_hashv_create_handle_x (groups scm C) (scan-data T))
-(scm_hashv_get_handle (groups scm C) (scan-data T))
-(scm_hashv_ref (groups scm C) (scan-data T))
-(scm_hashv_remove_x (groups scm C) (scan-data T))
-(scm_hashv_set_x (groups scm C) (scan-data T))
-(scm_hashx_create_handle_x (groups scm C) (scan-data T))
-(scm_hashx_get_handle (groups scm C) (scan-data T))
-(scm_hashx_ref (groups scm C) (scan-data T))
-(scm_hashx_remove_x (groups scm C) (scan-data T))
-(scm_hashx_set_x (groups scm C) (scan-data T))
-(scm_heap_org (groups scm C) (scan-data B))
-(scm_heap_table (groups scm C) (scan-data D))
-(scm_hook_empty_p (groups scm C) (scan-data T))
-(scm_hook_p (groups scm C) (scan-data T))
-(scm_hook_to_list (groups scm C) (scan-data T))
-(scm_htonl (groups scm C) (scan-data T))
-(scm_htons (groups scm C) (scan-data T))
-(scm_i_adjbig (groups scm libguile-internal C) (scan-data T))
-(scm_i_big2dbl (groups scm libguile-internal C) (scan-data T))
-(scm_i_big2inum (groups scm libguile-internal C) (scan-data T))
-(scm_i_copy_rstate (groups scm libguile-internal C) (scan-data T))
-(scm_i_copybig (groups scm libguile-internal C) (scan-data T))
-(scm_i_dbl2big (groups scm libguile-internal C) (scan-data T))
-(scm_i_display_error (groups scm libguile-internal C) (scan-data T))
-(scm_i_dummy (groups scm libguile-internal C) (scan-data B))
-(scm_i_eval (groups scm libguile-internal C) (scan-data T))
-(scm_i_eval_x (groups scm libguile-internal C) (scan-data T))
-(scm_i_get_keyword (groups scm libguile-internal C) (scan-data T))
-(scm_i_init_rstate (groups scm libguile-internal C) (scan-data T))
-(scm_i_int2big (groups scm libguile-internal C) (scan-data T))
-(scm_i_long2big (groups scm libguile-internal C) (scan-data T))
-(scm_i_long_long2big (groups scm libguile-internal C) (scan-data T))
-(scm_i_make_class_object (groups scm libguile-internal C) (scan-data T))
-(scm_i_mem2number (groups scm libguile-internal C) (scan-data T))
-(scm_i_mkbig (groups scm libguile-internal C) (scan-data T))
-(scm_i_normbig (groups scm libguile-internal C) (scan-data T))
-(scm_i_procedure_arity (groups scm libguile-internal C) (scan-data T))
-(scm_i_ptrdiff2big (groups scm libguile-internal C) (scan-data T))
-(scm_i_short2big (groups scm libguile-internal C) (scan-data T))
-(scm_i_size2big (groups scm libguile-internal C) (scan-data T))
-(scm_i_terminating (groups scm libguile-internal C) (scan-data B))
-(scm_i_uint2big (groups scm libguile-internal C) (scan-data T))
-(scm_i_ulong2big (groups scm libguile-internal C) (scan-data T))
-(scm_i_ulong_long2big (groups scm libguile-internal C) (scan-data T))
-(scm_i_uniform32 (groups scm libguile-internal C) (scan-data T))
-(scm_i_ushort2big (groups scm libguile-internal C) (scan-data T))
-(scm_i_variable_print (groups scm libguile-internal C) (scan-data T))
-(scm_ice_9_already_loaded (groups scm C) (scan-data D))
-(scm_igc (groups scm C) (scan-data T))
-(scm_ihash (groups scm C) (scan-data T))
-(scm_ihashq (groups scm C) (scan-data T))
-(scm_ihashv (groups scm C) (scan-data T))
-(scm_iint2str (groups scm C) (scan-data T))
-(scm_ilength (groups scm C) (scan-data T))
-(scm_ilookup (groups scm C) (scan-data T))
-(scm_imag_part (groups scm C) (scan-data T))
-(scm_import_environment_imports (groups scm C) (scan-data T))
-(scm_import_environment_p (groups scm C) (scan-data T))
-(scm_import_environment_set_imports_x (groups scm C) (scan-data T))
-(scm_include_deprecated_features (groups scm C) (scan-data T))
-(scm_inet_aton (groups scm C) (scan-data T))
-(scm_inet_makeaddr (groups scm C) (scan-data T))
-(scm_inet_netof (groups scm C) (scan-data T))
-(scm_inet_ntoa (groups scm C) (scan-data T))
-(scm_inet_ntop (groups scm C) (scan-data T))
-(scm_inet_pton (groups scm C) (scan-data T))
-(scm_inexact_p (groups scm C) (scan-data T))
-(scm_inexact_to_exact (groups scm C) (scan-data T))
-(scm_inf (groups scm C) (scan-data T))
-(scm_inf_p (groups scm C) (scan-data T))
-(scm_init_alist (groups scm C) (scan-data T))
-(scm_init_arbiters (groups scm C) (scan-data T))
-(scm_init_async (groups scm C) (scan-data T))
-(scm_init_backtrace (groups scm C) (scan-data T))
-(scm_init_boolean (groups scm C) (scan-data T))
-(scm_init_chars (groups scm C) (scan-data T))
-(scm_init_continuations (groups scm C) (scan-data T))
-(scm_init_debug (groups scm C) (scan-data T))
-(scm_init_deprecation (groups scm C) (scan-data T))
-(scm_init_dynamic_linking (groups scm C) (scan-data T))
-(scm_init_dynwind (groups scm C) (scan-data T))
-(scm_init_environments (groups scm C) (scan-data T))
-(scm_init_eq (groups scm C) (scan-data T))
-(scm_init_error (groups scm C) (scan-data T))
-(scm_init_eval (groups scm C) (scan-data T))
-(scm_init_evalext (groups scm C) (scan-data T))
-(scm_init_extensions (groups scm C) (scan-data T))
-(scm_init_feature (groups scm C) (scan-data T))
-(scm_init_filesys (groups scm C) (scan-data T))
-(scm_init_fluids (groups scm C) (scan-data T))
-(scm_init_fports (groups scm C) (scan-data T))
-(scm_init_gc (groups scm C) (scan-data T))
-(scm_init_gdbint (groups scm C) (scan-data T))
-(scm_init_goops (groups scm C) (scan-data T))
-(scm_init_goops_builtins (groups scm C) (scan-data T))
-(scm_init_gsubr (groups scm C) (scan-data T))
-(scm_init_guardians (groups scm C) (scan-data T))
-(scm_init_guile (groups scm C) (scan-data T))
-(scm_init_hash (groups scm C) (scan-data T))
-(scm_init_hashtab (groups scm C) (scan-data T))
-(scm_init_hooks (groups scm C) (scan-data T))
-(scm_init_ioext (groups scm C) (scan-data T))
-(scm_init_iselect (groups scm C) (scan-data T))
-(scm_init_keywords (groups scm C) (scan-data T))
-(scm_init_lang (groups scm C) (scan-data T))
-(scm_init_list (groups scm C) (scan-data T))
-(scm_init_load (groups scm C) (scan-data T))
-(scm_init_load_path (groups scm C) (scan-data T))
-(scm_init_macros (groups scm C) (scan-data T))
-(scm_init_mallocs (groups scm C) (scan-data T))
-(scm_init_modules (groups scm C) (scan-data T))
-(scm_init_net_db (groups scm C) (scan-data T))
-(scm_init_numbers (groups scm C) (scan-data T))
-(scm_init_objects (groups scm C) (scan-data T))
-(scm_init_objprop (groups scm C) (scan-data T))
-(scm_init_options (groups scm C) (scan-data T))
-(scm_init_opts (groups scm C) (scan-data T))
-(scm_init_pairs (groups scm C) (scan-data T))
-(scm_init_ports (groups scm C) (scan-data T))
-(scm_init_posix (groups scm C) (scan-data T))
-(scm_init_print (groups scm C) (scan-data T))
-(scm_init_procprop (groups scm C) (scan-data T))
-(scm_init_procs (groups scm C) (scan-data T))
-(scm_init_properties (groups scm C) (scan-data T))
-(scm_init_ramap (groups scm C) (scan-data T))
-(scm_init_random (groups scm C) (scan-data T))
-(scm_init_rdelim (groups scm C) (scan-data T))
-(scm_init_rdelim_builtins (groups scm C) (scan-data T))
-(scm_init_read (groups scm C) (scan-data T))
-(scm_init_regex_posix (groups scm C) (scan-data T))
-(scm_init_root (groups scm C) (scan-data T))
-(scm_init_rw (groups scm C) (scan-data T))
-(scm_init_rw_builtins (groups scm C) (scan-data T))
-(scm_init_scmsigs (groups scm C) (scan-data T))
-(scm_init_script (groups scm C) (scan-data T))
-(scm_init_simpos (groups scm C) (scan-data T))
-(scm_init_socket (groups scm C) (scan-data T))
-(scm_init_sort (groups scm C) (scan-data T))
-(scm_init_srcprop (groups scm C) (scan-data T))
-(scm_init_stackchk (groups scm C) (scan-data T))
-(scm_init_stacks (groups scm C) (scan-data T))
-(scm_init_stime (groups scm C) (scan-data T))
-(scm_init_storage (groups scm C) (scan-data T))
-(scm_init_strings (groups scm C) (scan-data T))
-(scm_init_strop (groups scm C) (scan-data T))
-(scm_init_strorder (groups scm C) (scan-data T))
-(scm_init_strports (groups scm C) (scan-data T))
-(scm_init_struct (groups scm C) (scan-data T))
-(scm_init_subr_table (groups scm C) (scan-data T))
-(scm_init_symbols (groups scm C) (scan-data T))
-(scm_init_threads (groups scm C) (scan-data T))
-(scm_init_throw (groups scm C) (scan-data T))
-(scm_init_unif (groups scm C) (scan-data T))
-(scm_init_values (groups scm C) (scan-data T))
-(scm_init_variable (groups scm C) (scan-data T))
-(scm_init_vectors (groups scm C) (scan-data T))
-(scm_init_version (groups scm C) (scan-data T))
-(scm_init_vports (groups scm C) (scan-data T))
-(scm_init_weaks (groups scm C) (scan-data T))
-(scm_initialized_p (groups scm C) (scan-data D))
-(scm_input_port_p (groups scm C) (scan-data T))
-(scm_instance_p (groups scm C) (scan-data T))
-(scm_int2num (groups scm C) (scan-data T))
-(scm_integer_expt (groups scm C) (scan-data T))
-(scm_integer_length (groups scm C) (scan-data T))
-(scm_integer_p (groups scm C) (scan-data T))
-(scm_integer_to_char (groups scm C) (scan-data T))
-(scm_interaction_environment (groups scm C) (scan-data T))
-(scm_internal_catch (groups scm C) (scan-data T))
-(scm_internal_cwdr (groups scm C) (scan-data T))
-(scm_internal_dynamic_wind (groups scm C) (scan-data T))
-(scm_internal_hash_fold (groups scm C) (scan-data T))
-(scm_internal_lazy_catch (groups scm C) (scan-data T))
-(scm_internal_parse_path (groups scm C) (scan-data T))
-(scm_internal_select (groups scm C) (scan-data T))
-(scm_internal_stack_catch (groups scm C) (scan-data T))
-(scm_intprint (groups scm C) (scan-data T))
-(scm_ints_disabled (groups scm C) (scan-data D))
-(scm_iprin1 (groups scm C) (scan-data T))
-(scm_iprlist (groups scm C) (scan-data T))
-(scm_ipruk (groups scm C) (scan-data T))
-(scm_isatty_p (groups scm C) (scan-data T))
-(scm_issue_deprecation_warning (groups scm C) (scan-data T))
-(scm_istr2bve (groups scm C) (scan-data T))
-(scm_isymnames (groups scm C) (scan-data D))
-(scm_ithrow (groups scm C) (scan-data T))
-(scm_join_thread (groups scm C) (scan-data T))
-(scm_keyword_dash_symbol (groups scm C) (scan-data T))
-(scm_keyword_p (groups scm C) (scan-data T))
-(scm_kill (groups scm C) (scan-data T))
-(scm_last_pair (groups scm C) (scan-data T))
-(scm_last_stack_frame (groups scm C) (scan-data T))
-(scm_lazy_catch (groups scm C) (scan-data T))
-(scm_lcm (groups scm C) (scan-data T))
-(scm_leaf_environment_p (groups scm C) (scan-data T))
-(scm_length (groups scm C) (scan-data T))
-(scm_leq_p (groups scm C) (scan-data T))
-(scm_less_p (groups scm C) (scan-data T))
-(scm_lfwrite (groups scm C) (scan-data T))
-(scm_link (groups scm C) (scan-data T))
-(scm_list (groups scm C) (scan-data T))
-(scm_list_1 (groups scm C) (scan-data T))
-(scm_list_2 (groups scm C) (scan-data T))
-(scm_list_3 (groups scm C) (scan-data T))
-(scm_list_4 (groups scm C) (scan-data T))
-(scm_list_5 (groups scm C) (scan-data T))
-(scm_list_cdr_set_x (groups scm C) (scan-data T))
-(scm_list_copy (groups scm C) (scan-data T))
-(scm_list_head (groups scm C) (scan-data T))
-(scm_list_n (groups scm C) (scan-data T))
-(scm_list_p (groups scm C) (scan-data T))
-(scm_list_ref (groups scm C) (scan-data T))
-(scm_list_set_x (groups scm C) (scan-data T))
-(scm_list_tail (groups scm C) (scan-data T))
-(scm_list_to_uniform_array (groups scm C) (scan-data T))
-(scm_listen (groups scm C) (scan-data T))
-(scm_listofnullstr (groups scm C) (scan-data B))
-(scm_lnaof (groups scm C) (scan-data T))
-(scm_load_extension (groups scm C) (scan-data T))
-(scm_load_goops (groups scm C) (scan-data T))
-(scm_load_startup_files (groups scm C) (scan-data T))
-(scm_local_eval (groups scm C) (scan-data T))
-(scm_localtime (groups scm C) (scan-data T))
-(scm_lock_mutex (groups scm C) (scan-data T))
-(scm_logand (groups scm C) (scan-data T))
-(scm_logbit_p (groups scm C) (scan-data T))
-(scm_logcount (groups scm C) (scan-data T))
-(scm_logior (groups scm C) (scan-data T))
-(scm_lognot (groups scm C) (scan-data T))
-(scm_logtest (groups scm C) (scan-data T))
-(scm_logxor (groups scm C) (scan-data T))
-(scm_long2num (groups scm C) (scan-data T))
-(scm_long_long2num (groups scm C) (scan-data T))
-(scm_lookup (groups scm C) (scan-data T))
-(scm_lookup_closure_module (groups scm C) (scan-data T))
-(scm_lookupcar (groups scm C) (scan-data T))
-(scm_lreadparen (groups scm C) (scan-data T))
-(scm_lreadr (groups scm C) (scan-data T))
-(scm_lreadrecparen (groups scm C) (scan-data T))
-(scm_lstat (groups scm C) (scan-data T))
-(scm_m_and (groups scm C) (scan-data T))
-(scm_m_apply (groups scm C) (scan-data T))
-(scm_m_at_call_with_values (groups scm C) (scan-data T))
-(scm_m_atbind (groups scm C) (scan-data T))
-(scm_m_atdispatch (groups scm C) (scan-data T))
-(scm_m_atfop (groups scm C) (scan-data T))
-(scm_m_atslot_ref (groups scm C) (scan-data T))
-(scm_m_atslot_set_x (groups scm C) (scan-data T))
-(scm_m_begin (groups scm C) (scan-data T))
-(scm_m_case (groups scm C) (scan-data T))
-(scm_m_cond (groups scm C) (scan-data T))
-(scm_m_cont (groups scm C) (scan-data T))
-(scm_m_define (groups scm C) (scan-data T))
-(scm_m_delay (groups scm C) (scan-data T))
-(scm_m_do (groups scm C) (scan-data T))
-(scm_m_expand_body (groups scm C) (scan-data T))
-(scm_m_generalized_set_x (groups scm C) (scan-data T))
-(scm_m_if (groups scm C) (scan-data T))
-(scm_m_lambda (groups scm C) (scan-data T))
-(scm_m_let (groups scm C) (scan-data T))
-(scm_m_letrec (groups scm C) (scan-data T))
-(scm_m_letstar (groups scm C) (scan-data T))
-(scm_m_nil_cond (groups scm C) (scan-data T))
-(scm_m_or (groups scm C) (scan-data T))
-(scm_m_quasiquote (groups scm C) (scan-data T))
-(scm_m_quote (groups scm C) (scan-data T))
-(scm_m_set_x (groups scm C) (scan-data T))
-(scm_m_undefine (groups scm C) (scan-data T))
-(scm_macro_name (groups scm C) (scan-data T))
-(scm_macro_p (groups scm C) (scan-data T))
-(scm_macro_transformer (groups scm C) (scan-data T))
-(scm_macro_type (groups scm C) (scan-data T))
-(scm_macroexp (groups scm C) (scan-data T))
-(scm_magnitude (groups scm C) (scan-data T))
-(scm_major_version (groups scm C) (scan-data T))
-(scm_makacro (groups scm C) (scan-data T))
-(scm_makcclo (groups scm C) (scan-data T))
-(scm_make (groups scm C) (scan-data T))
-(scm_make_arbiter (groups scm C) (scan-data T))
-(scm_make_class (groups scm C) (scan-data T))
-(scm_make_class_object (groups scm C) (scan-data T))
-(scm_make_complex (groups scm C) (scan-data T))
-(scm_make_condition_variable (groups scm C) (scan-data T))
-(scm_make_continuation (groups scm C) (scan-data T))
-(scm_make_debugobj (groups scm C) (scan-data T))
-(scm_make_doubly_weak_hash_table (groups scm C) (scan-data T))
-(scm_make_environment (groups scm C) (scan-data T))
-(scm_make_eval_environment (groups scm C) (scan-data T))
-(scm_make_export_environment (groups scm C) (scan-data T))
-(scm_make_extended_class (groups scm C) (scan-data T))
-(scm_make_fluid (groups scm C) (scan-data T))
-(scm_make_foreign_object (groups scm C) (scan-data T))
-(scm_make_guardian (groups scm C) (scan-data T))
-(scm_make_hook (groups scm C) (scan-data T))
-(scm_make_import_environment (groups scm C) (scan-data T))
-(scm_make_initial_fluids (groups scm C) (scan-data T))
-(scm_make_keyword_from_dash_symbol (groups scm C) (scan-data T))
-(scm_make_leaf_environment (groups scm C) (scan-data T))
-(scm_make_memoized (groups scm C) (scan-data T))
-(scm_make_method_cache (groups scm C) (scan-data T))
-(scm_make_mutex (groups scm C) (scan-data T))
-(scm_make_polar (groups scm C) (scan-data T))
-(scm_make_port_classes (groups scm C) (scan-data T))
-(scm_make_port_type (groups scm C) (scan-data T))
-(scm_make_print_state (groups scm C) (scan-data T))
-(scm_make_procedure_with_setter (groups scm C) (scan-data T))
-(scm_make_ra (groups scm C) (scan-data T))
-(scm_make_real (groups scm C) (scan-data T))
-(scm_make_rectangular (groups scm C) (scan-data T))
-(scm_make_regexp (groups scm C) (scan-data T))
-(scm_make_root (groups scm C) (scan-data T))
-(scm_make_shared_array (groups scm C) (scan-data T))
-(scm_make_smob (groups scm C) (scan-data T))
-(scm_make_smob_type (groups scm C) (scan-data T))
-(scm_make_soft_port (groups scm C) (scan-data T))
-(scm_make_srcprops (groups scm C) (scan-data T))
-(scm_make_stack (groups scm C) (scan-data T))
-(scm_make_string (groups scm C) (scan-data T))
-(scm_make_struct (groups scm C) (scan-data T))
-(scm_make_struct_layout (groups scm C) (scan-data T))
-(scm_make_subclass_object (groups scm C) (scan-data T))
-(scm_make_symbol (groups scm C) (scan-data T))
-(scm_make_synt (groups scm C) (scan-data T))
-(scm_make_undefined_variable (groups scm C) (scan-data T))
-(scm_make_uve (groups scm C) (scan-data T))
-(scm_make_variable (groups scm C) (scan-data T))
-(scm_make_vector (groups scm C) (scan-data T))
-(scm_make_vtable_vtable (groups scm C) (scan-data T))
-(scm_make_weak_key_hash_table (groups scm C) (scan-data T))
-(scm_make_weak_value_hash_table (groups scm C) (scan-data T))
-(scm_make_weak_vector (groups scm C) (scan-data T))
-(scm_makfrom0str (groups scm C) (scan-data T))
-(scm_makfrom0str_opt (groups scm C) (scan-data T))
-(scm_makfromstrs (groups scm C) (scan-data T))
-(scm_makmacro (groups scm C) (scan-data T))
-(scm_makmmacro (groups scm C) (scan-data T))
-(scm_makprom (groups scm C) (scan-data T))
-(scm_malloc (groups scm C) (scan-data T))
-(scm_malloc_obj (groups scm C) (scan-data T))
-(scm_mallocated (groups scm C) (scan-data D))
-(scm_map (groups scm C) (scan-data T))
-(scm_mark0 (groups scm C) (scan-data T))
-(scm_mark_locations (groups scm C) (scan-data T))
-(scm_mark_subr_table (groups scm C) (scan-data T))
-(scm_markcdr (groups scm C) (scan-data T))
-(scm_markstream (groups scm C) (scan-data T))
-(scm_mask_ints (groups scm C) (scan-data D))
-(scm_mask_signals (groups scm C) (scan-data T))
-(scm_masktab (groups scm C) (scan-data B))
-(scm_master_freelist (groups scm C) (scan-data D))
-(scm_master_freelist2 (groups scm C) (scan-data D))
-(scm_max (groups scm C) (scan-data T))
-(scm_max_segment_size (groups scm C) (scan-data B))
-(scm_mcache_compute_cmethod (groups scm C) (scan-data T))
-(scm_mcache_lookup_cmethod (groups scm C) (scan-data T))
-(scm_mem2string (groups scm C) (scan-data T))
-(scm_mem2symbol (groups scm C) (scan-data T))
-(scm_mem2uninterned_symbol (groups scm C) (scan-data T))
-(scm_member (groups scm C) (scan-data T))
-(scm_memoize_method (groups scm C) (scan-data T))
-(scm_memoized_environment (groups scm C) (scan-data T))
-(scm_memoized_p (groups scm C) (scan-data T))
-(scm_memory_alloc_key (groups scm C) (scan-data B))
-(scm_memory_error (groups scm C) (scan-data T))
-(scm_memq (groups scm C) (scan-data T))
-(scm_memv (groups scm C) (scan-data T))
-(scm_merge (groups scm C) (scan-data T))
-(scm_merge_x (groups scm C) (scan-data T))
-(scm_metaclass_operator (groups scm C) (scan-data B))
-(scm_metaclass_standard (groups scm C) (scan-data B))
-(scm_method_generic_function (groups scm C) (scan-data T))
-(scm_method_procedure (groups scm C) (scan-data T))
-(scm_method_specializers (groups scm C) (scan-data T))
-(scm_micro_version (groups scm C) (scan-data T))
-(scm_min (groups scm C) (scan-data T))
-(scm_minor_version (groups scm C) (scan-data T))
-(scm_misc_error (groups scm C) (scan-data T))
-(scm_misc_error_key (groups scm C) (scan-data B))
-(scm_mkdir (groups scm C) (scan-data T))
-(scm_mknod (groups scm C) (scan-data T))
-(scm_mkstemp (groups scm C) (scan-data T))
-(scm_mkstrport (groups scm C) (scan-data T))
-(scm_mktime (groups scm C) (scan-data T))
-(scm_mode_bits (groups scm C) (scan-data T))
-(scm_module_define (groups scm C) (scan-data T))
-(scm_module_goops (groups scm C) (scan-data B))
-(scm_module_lookup (groups scm C) (scan-data T))
-(scm_module_lookup_closure (groups scm C) (scan-data T))
-(scm_module_reverse_lookup (groups scm C) (scan-data T))
-(scm_module_system_booted_p (groups scm C) (scan-data D))
-(scm_module_tag (groups scm C) (scan-data B))
-(scm_module_transformer (groups scm C) (scan-data T))
-(scm_modules_prehistory (groups scm C) (scan-data T))
-(scm_modulo (groups scm C) (scan-data T))
-(scm_mtrigger (groups scm C) (scan-data B))
-(scm_mulbig (groups scm C) (scan-data T))
-(scm_must_free (groups scm C) (scan-data T))
-(scm_must_malloc (groups scm C) (scan-data T))
-(scm_must_realloc (groups scm C) (scan-data T))
-(scm_must_strdup (groups scm C) (scan-data T))
-(scm_must_strndup (groups scm C) (scan-data T))
-(scm_n_charnames (groups scm C) (scan-data D))
-(scm_n_heap_segs (groups scm C) (scan-data D))
-(scm_nan (groups scm C) (scan-data T))
-(scm_nan_p (groups scm C) (scan-data T))
-(scm_nconc2last (groups scm C) (scan-data T))
-(scm_negative_p (groups scm C) (scan-data T))
-(scm_newline (groups scm C) (scan-data T))
-(scm_nice (groups scm C) (scan-data T))
-(scm_no_applicable_method (groups scm C) (scan-data B))
-(scm_noop (groups scm C) (scan-data T))
-(scm_not (groups scm C) (scan-data T))
-(scm_ntohl (groups scm C) (scan-data T))
-(scm_ntohs (groups scm C) (scan-data T))
-(scm_null_p (groups scm C) (scan-data T))
-(scm_num2dbl (groups scm C) (scan-data T))
-(scm_num2double (groups scm C) (scan-data T))
-(scm_num2float (groups scm C) (scan-data T))
-(scm_num2int (groups scm C) (scan-data T))
-(scm_num2long (groups scm C) (scan-data T))
-(scm_num2long_long (groups scm C) (scan-data T))
-(scm_num2ptrdiff (groups scm C) (scan-data T))
-(scm_num2short (groups scm C) (scan-data T))
-(scm_num2size (groups scm C) (scan-data T))
-(scm_num2uint (groups scm C) (scan-data T))
-(scm_num2ulong (groups scm C) (scan-data T))
-(scm_num2ulong_long (groups scm C) (scan-data T))
-(scm_num2ushort (groups scm C) (scan-data T))
-(scm_num_eq_p (groups scm C) (scan-data T))
-(scm_num_overflow (groups scm C) (scan-data T))
-(scm_num_overflow_key (groups scm C) (scan-data B))
-(scm_number_p (groups scm C) (scan-data T))
-(scm_number_to_string (groups scm C) (scan-data T))
-(scm_numptob (groups scm C) (scan-data B))
-(scm_numsmob (groups scm C) (scan-data B))
-(scm_object_address (groups scm C) (scan-data T))
-(scm_object_properties (groups scm C) (scan-data T))
-(scm_object_property (groups scm C) (scan-data T))
-(scm_object_to_string (groups scm C) (scan-data T))
-(scm_odd_p (groups scm C) (scan-data T))
-(scm_open (groups scm C) (scan-data T))
-(scm_open_fdes (groups scm C) (scan-data T))
-(scm_open_file (groups scm C) (scan-data T))
-(scm_open_input_string (groups scm C) (scan-data T))
-(scm_open_output_string (groups scm C) (scan-data T))
-(scm_opendir (groups scm C) (scan-data T))
-(scm_operator_p (groups scm C) (scan-data T))
-(scm_options (groups scm C) (scan-data T))
-(scm_out_of_range (groups scm C) (scan-data T))
-(scm_out_of_range_key (groups scm C) (scan-data B))
-(scm_out_of_range_pos (groups scm C) (scan-data T))
-(scm_output_port_p (groups scm C) (scan-data T))
-(scm_pair_p (groups scm C) (scan-data T))
-(scm_parse_path (groups scm C) (scan-data T))
-(scm_pause (groups scm C) (scan-data T))
-(scm_peek_char (groups scm C) (scan-data T))
-(scm_permanent_object (groups scm C) (scan-data T))
-(scm_pipe (groups scm C) (scan-data T))
-(scm_port_class (groups scm C) (scan-data D))
-(scm_port_closed_p (groups scm C) (scan-data T))
-(scm_port_column (groups scm C) (scan-data T))
-(scm_port_filename (groups scm C) (scan-data T))
-(scm_port_for_each (groups scm C) (scan-data T))
-(scm_port_line (groups scm C) (scan-data T))
-(scm_port_mode (groups scm C) (scan-data T))
-(scm_port_non_buffer (groups scm C) (scan-data T))
-(scm_port_p (groups scm C) (scan-data T))
-(scm_port_print (groups scm C) (scan-data T))
-(scm_port_revealed (groups scm C) (scan-data T))
-(scm_port_table (groups scm C) (scan-data B))
-(scm_port_table_room (groups scm C) (scan-data D))
-(scm_port_table_size (groups scm C) (scan-data D))
-(scm_port_with_print_state (groups scm C) (scan-data T))
-(scm_ports_prehistory (groups scm C) (scan-data T))
-(scm_positive_p (groups scm C) (scan-data T))
-(scm_pre_modules_obarray (groups scm C) (scan-data B))
-(scm_primitive_eval (groups scm C) (scan-data T))
-(scm_primitive_eval_x (groups scm C) (scan-data T))
-(scm_primitive_exit (groups scm C) (scan-data T))
-(scm_primitive_generic_generic (groups scm C) (scan-data T))
-(scm_primitive_load (groups scm C) (scan-data T))
-(scm_primitive_load_path (groups scm C) (scan-data T))
-(scm_primitive_make_property (groups scm C) (scan-data T))
-(scm_primitive_move_to_fdes (groups scm C) (scan-data T))
-(scm_primitive_property_del_x (groups scm C) (scan-data T))
-(scm_primitive_property_ref (groups scm C) (scan-data T))
-(scm_primitive_property_set_x (groups scm C) (scan-data T))
-(scm_prin1 (groups scm C) (scan-data T))
-(scm_print_carefully_p (groups scm C) (scan-data B))
-(scm_print_complex (groups scm C) (scan-data T))
-(scm_print_options (groups scm C) (scan-data T))
-(scm_print_opts (groups scm C) (scan-data D))
-(scm_print_port_mode (groups scm C) (scan-data T))
-(scm_print_real (groups scm C) (scan-data T))
-(scm_print_state_vtable (groups scm C) (scan-data D))
-(scm_print_struct (groups scm C) (scan-data T))
-(scm_print_symbol_name (groups scm C) (scan-data T))
-(scm_printer_apply (groups scm C) (scan-data T))
-(scm_procedure (groups scm C) (scan-data T))
-(scm_procedure_documentation (groups scm C) (scan-data T))
-(scm_procedure_environment (groups scm C) (scan-data T))
-(scm_procedure_name (groups scm C) (scan-data T))
-(scm_procedure_p (groups scm C) (scan-data T))
-(scm_procedure_properties (groups scm C) (scan-data T))
-(scm_procedure_property (groups scm C) (scan-data T))
-(scm_procedure_source (groups scm C) (scan-data T))
-(scm_procedure_with_setter_p (groups scm C) (scan-data T))
-(scm_product (groups scm C) (scan-data T))
-(scm_program_arguments (groups scm C) (scan-data T))
-(scm_promise_p (groups scm C) (scan-data T))
-(scm_pseudolong (groups scm C) (scan-data T))
-(scm_ptobs (groups scm C) (scan-data B))
-(scm_ptrdiff2num (groups scm C) (scan-data T))
-(scm_putc (groups scm C) (scan-data T))
-(scm_putenv (groups scm C) (scan-data T))
-(scm_puts (groups scm C) (scan-data T))
-(scm_quotient (groups scm C) (scan-data T))
-(scm_ra2contig (groups scm C) (scan-data T))
-(scm_ra_difference (groups scm C) (scan-data T))
-(scm_ra_divide (groups scm C) (scan-data T))
-(scm_ra_eqp (groups scm C) (scan-data T))
-(scm_ra_greqp (groups scm C) (scan-data T))
-(scm_ra_grp (groups scm C) (scan-data T))
-(scm_ra_leqp (groups scm C) (scan-data T))
-(scm_ra_lessp (groups scm C) (scan-data T))
-(scm_ra_matchp (groups scm C) (scan-data T))
-(scm_ra_product (groups scm C) (scan-data T))
-(scm_ra_set_contp (groups scm C) (scan-data T))
-(scm_ra_sum (groups scm C) (scan-data T))
-(scm_raequal (groups scm C) (scan-data T))
-(scm_raise (groups scm C) (scan-data T))
-(scm_ramapc (groups scm C) (scan-data T))
-(scm_random (groups scm C) (scan-data T))
-(scm_random_exp (groups scm C) (scan-data T))
-(scm_random_hollow_sphere_x (groups scm C) (scan-data T))
-(scm_random_normal (groups scm C) (scan-data T))
-(scm_random_normal_vector_x (groups scm C) (scan-data T))
-(scm_random_solid_sphere_x (groups scm C) (scan-data T))
-(scm_random_uniform (groups scm C) (scan-data T))
-(scm_raprin1 (groups scm C) (scan-data T))
-(scm_read (groups scm C) (scan-data T))
-(scm_read_char (groups scm C) (scan-data T))
-(scm_read_delimited_x (groups scm C) (scan-data T))
-(scm_read_hash_extend (groups scm C) (scan-data T))
-(scm_read_line (groups scm C) (scan-data T))
-(scm_read_options (groups scm C) (scan-data T))
-(scm_read_opts (groups scm C) (scan-data D))
-(scm_read_string_x_partial (groups scm C) (scan-data T))
-(scm_read_token (groups scm C) (scan-data T))
-(scm_readdir (groups scm C) (scan-data T))
-(scm_readlink (groups scm C) (scan-data T))
-(scm_real_equalp (groups scm C) (scan-data T))
-(scm_real_p (groups scm C) (scan-data T))
-(scm_real_part (groups scm C) (scan-data T))
-(scm_realloc (groups scm C) (scan-data T))
-(scm_recv (groups scm C) (scan-data T))
-(scm_recvfrom (groups scm C) (scan-data T))
-(scm_redirect_port (groups scm C) (scan-data T))
-(scm_regexp_exec (groups scm C) (scan-data T))
-(scm_regexp_p (groups scm C) (scan-data T))
-(scm_release_arbiter (groups scm C) (scan-data T))
-(scm_remainder (groups scm C) (scan-data T))
-(scm_remember_upto_here (groups scm C) (scan-data T))
-(scm_remember_upto_here_1 (groups scm C) (scan-data T))
-(scm_remember_upto_here_2 (groups scm C) (scan-data T))
-(scm_remove_from_port_table (groups scm C) (scan-data T))
-(scm_remove_hook_x (groups scm C) (scan-data T))
-(scm_rename (groups scm C) (scan-data T))
-(scm_report_stack_overflow (groups scm C) (scan-data T))
-(scm_reset_hook_x (groups scm C) (scan-data T))
-(scm_resolve_module (groups scm C) (scan-data T))
-(scm_restore_signals (groups scm C) (scan-data T))
-(scm_restricted_vector_sort_x (groups scm C) (scan-data T))
-(scm_return_first (groups scm C) (scan-data T))
-(scm_return_first_int (groups scm C) (scan-data T))
-(scm_revealed_count (groups scm C) (scan-data T))
-(scm_reverse (groups scm C) (scan-data T))
-(scm_reverse_lookup (groups scm C) (scan-data T))
-(scm_reverse_x (groups scm C) (scan-data T))
-(scm_rewinddir (groups scm C) (scan-data T))
-(scm_rmdir (groups scm C) (scan-data T))
-(scm_round (groups scm C) (scan-data T))
-(scm_run_asyncs (groups scm C) (scan-data T))
-(scm_run_hook (groups scm C) (scan-data T))
-(scm_s_bindings (groups scm C) (scan-data R))
-(scm_s_body (groups scm C) (scan-data R))
-(scm_s_clauses (groups scm C) (scan-data R))
-(scm_s_duplicate_bindings (groups scm C) (scan-data R))
-(scm_s_duplicate_formals (groups scm C) (scan-data R))
-(scm_s_expression (groups scm C) (scan-data R))
-(scm_s_formals (groups scm C) (scan-data R))
-(scm_s_set_x (groups scm C) (scan-data R))
-(scm_s_slot_set_x (groups scm C) (scan-data D))
-(scm_s_test (groups scm C) (scan-data R))
-(scm_s_variable (groups scm C) (scan-data R))
-(scm_search_path (groups scm C) (scan-data T))
-(scm_seed_to_random_state (groups scm C) (scan-data T))
-(scm_seek (groups scm C) (scan-data T))
-(scm_select (groups scm C) (scan-data T))
-(scm_send (groups scm C) (scan-data T))
-(scm_sendto (groups scm C) (scan-data T))
-(scm_set_car_x (groups scm C) (scan-data T))
-(scm_set_cdr_x (groups scm C) (scan-data T))
-(scm_set_current_error_port (groups scm C) (scan-data T))
-(scm_set_current_input_port (groups scm C) (scan-data T))
-(scm_set_current_module (groups scm C) (scan-data T))
-(scm_set_current_output_port (groups scm C) (scan-data T))
-(scm_set_object_procedure_x (groups scm C) (scan-data T))
-(scm_set_object_properties_x (groups scm C) (scan-data T))
-(scm_set_object_property_x (groups scm C) (scan-data T))
-(scm_set_port_close (groups scm C) (scan-data T))
-(scm_set_port_column_x (groups scm C) (scan-data T))
-(scm_set_port_end_input (groups scm C) (scan-data T))
-(scm_set_port_equalp (groups scm C) (scan-data T))
-(scm_set_port_filename_x (groups scm C) (scan-data T))
-(scm_set_port_flush (groups scm C) (scan-data T))
-(scm_set_port_free (groups scm C) (scan-data T))
-(scm_set_port_input_waiting (groups scm C) (scan-data T))
-(scm_set_port_line_x (groups scm C) (scan-data T))
-(scm_set_port_mark (groups scm C) (scan-data T))
-(scm_set_port_print (groups scm C) (scan-data T))
-(scm_set_port_revealed_x (groups scm C) (scan-data T))
-(scm_set_port_seek (groups scm C) (scan-data T))
-(scm_set_port_truncate (groups scm C) (scan-data T))
-(scm_set_procedure_properties_x (groups scm C) (scan-data T))
-(scm_set_procedure_property_x (groups scm C) (scan-data T))
-(scm_set_program_arguments (groups scm C) (scan-data T))
-(scm_set_smob_apply (groups scm C) (scan-data T))
-(scm_set_smob_equalp (groups scm C) (scan-data T))
-(scm_set_smob_free (groups scm C) (scan-data T))
-(scm_set_smob_mark (groups scm C) (scan-data T))
-(scm_set_smob_print (groups scm C) (scan-data T))
-(scm_set_source_properties_x (groups scm C) (scan-data T))
-(scm_set_source_property_x (groups scm C) (scan-data T))
-(scm_set_struct_vtable_name_x (groups scm C) (scan-data T))
-(scm_setegid (groups scm C) (scan-data T))
-(scm_seteuid (groups scm C) (scan-data T))
-(scm_setgid (groups scm C) (scan-data T))
-(scm_setgrent (groups scm C) (scan-data T))
-(scm_sethost (groups scm C) (scan-data T))
-(scm_sethostname (groups scm C) (scan-data T))
-(scm_setitimer (groups scm C) (scan-data T))
-(scm_setlocale (groups scm C) (scan-data T))
-(scm_setnet (groups scm C) (scan-data T))
-(scm_setpgid (groups scm C) (scan-data T))
-(scm_setpriority (groups scm C) (scan-data T))
-(scm_setproto (groups scm C) (scan-data T))
-(scm_setpwent (groups scm C) (scan-data T))
-(scm_setserv (groups scm C) (scan-data T))
-(scm_setsid (groups scm C) (scan-data T))
-(scm_setsockopt (groups scm C) (scan-data T))
-(scm_setter (groups scm C) (scan-data T))
-(scm_setuid (groups scm C) (scan-data T))
-(scm_setvbuf (groups scm C) (scan-data T))
-(scm_shap2ra (groups scm C) (scan-data T))
-(scm_shared_array_increments (groups scm C) (scan-data T))
-(scm_shared_array_offset (groups scm C) (scan-data T))
-(scm_shared_array_root (groups scm C) (scan-data T))
-(scm_shell (groups scm C) (scan-data T))
-(scm_shell_usage (groups scm C) (scan-data T))
-(scm_short2num (groups scm C) (scan-data T))
-(scm_shutdown (groups scm C) (scan-data T))
-(scm_sigaction (groups scm C) (scan-data T))
-(scm_signal_condition_variable (groups scm C) (scan-data T))
-(scm_simple_format (groups scm C) (scan-data T))
-(scm_single_thread_p (groups scm C) (scan-data T))
-(scm_size2num (groups scm C) (scan-data T))
-(scm_sleep (groups scm C) (scan-data T))
-(scm_sloppy_assoc (groups scm C) (scan-data T))
-(scm_sloppy_assq (groups scm C) (scan-data T))
-(scm_sloppy_assv (groups scm C) (scan-data T))
-(scm_slot_bound_p (groups scm C) (scan-data T))
-(scm_slot_bound_using_class_p (groups scm C) (scan-data T))
-(scm_slot_exists_p (groups scm C) (scan-data T))
-(scm_slot_exists_using_class_p (groups scm C) (scan-data T))
-(scm_slot_ref (groups scm C) (scan-data T))
-(scm_slot_ref_using_class (groups scm C) (scan-data T))
-(scm_slot_set_using_class_x (groups scm C) (scan-data T))
-(scm_slot_set_x (groups scm C) (scan-data T))
-(scm_smob_class (groups scm C) (scan-data D))
-(scm_smob_free (groups scm C) (scan-data T))
-(scm_smob_prehistory (groups scm C) (scan-data T))
-(scm_smob_print (groups scm C) (scan-data T))
-(scm_smobs (groups scm C) (scan-data B))
-(scm_socket (groups scm C) (scan-data T))
-(scm_socketpair (groups scm C) (scan-data T))
-(scm_sort (groups scm C) (scan-data T))
-(scm_sort_list (groups scm C) (scan-data T))
-(scm_sort_list_x (groups scm C) (scan-data T))
-(scm_sort_x (groups scm C) (scan-data T))
-(scm_sorted_p (groups scm C) (scan-data T))
-(scm_source_properties (groups scm C) (scan-data T))
-(scm_source_property (groups scm C) (scan-data T))
-(scm_spawn_thread (groups scm C) (scan-data T))
-(scm_srcprops_to_plist (groups scm C) (scan-data T))
-(scm_stable_sort (groups scm C) (scan-data T))
-(scm_stable_sort_x (groups scm C) (scan-data T))
-(scm_stack_checking_enabled_p (groups scm C) (scan-data B))
-(scm_stack_id (groups scm C) (scan-data T))
-(scm_stack_length (groups scm C) (scan-data T))
-(scm_stack_p (groups scm C) (scan-data T))
-(scm_stack_ref (groups scm C) (scan-data T))
-(scm_stack_report (groups scm C) (scan-data T))
-(scm_stack_size (groups scm C) (scan-data T))
-(scm_stack_type (groups scm C) (scan-data B))
-(scm_standard_eval_closure (groups scm C) (scan-data T))
-(scm_standard_interface_eval_closure (groups scm C) (scan-data T))
-(scm_start_stack (groups scm C) (scan-data T))
-(scm_stat (groups scm C) (scan-data T))
-(scm_status_exit_val (groups scm C) (scan-data T))
-(scm_status_stop_sig (groups scm C) (scan-data T))
-(scm_status_term_sig (groups scm C) (scan-data T))
-(scm_str2string (groups scm C) (scan-data T))
-(scm_str2symbol (groups scm C) (scan-data T))
-(scm_strdup (groups scm C) (scan-data T))
-(scm_strerror (groups scm C) (scan-data T))
-(scm_strftime (groups scm C) (scan-data T))
-(scm_string (groups scm C) (scan-data T))
-(scm_string_append (groups scm C) (scan-data T))
-(scm_string_capitalize (groups scm C) (scan-data T))
-(scm_string_capitalize_x (groups scm C) (scan-data T))
-(scm_string_ci_equal_p (groups scm C) (scan-data T))
-(scm_string_ci_geq_p (groups scm C) (scan-data T))
-(scm_string_ci_gr_p (groups scm C) (scan-data T))
-(scm_string_ci_leq_p (groups scm C) (scan-data T))
-(scm_string_ci_less_p (groups scm C) (scan-data T))
-(scm_string_ci_to_symbol (groups scm C) (scan-data T))
-(scm_string_copy (groups scm C) (scan-data T))
-(scm_string_downcase (groups scm C) (scan-data T))
-(scm_string_downcase_x (groups scm C) (scan-data T))
-(scm_string_equal_p (groups scm C) (scan-data T))
-(scm_string_fill_x (groups scm C) (scan-data T))
-(scm_string_geq_p (groups scm C) (scan-data T))
-(scm_string_gr_p (groups scm C) (scan-data T))
-(scm_string_hash (groups scm C) (scan-data T))
-(scm_string_index (groups scm C) (scan-data T))
-(scm_string_length (groups scm C) (scan-data T))
-(scm_string_leq_p (groups scm C) (scan-data T))
-(scm_string_less_p (groups scm C) (scan-data T))
-(scm_string_null_p (groups scm C) (scan-data T))
-(scm_string_p (groups scm C) (scan-data T))
-(scm_string_ref (groups scm C) (scan-data T))
-(scm_string_rindex (groups scm C) (scan-data T))
-(scm_string_set_x (groups scm C) (scan-data T))
-(scm_string_split (groups scm C) (scan-data T))
-(scm_string_to_list (groups scm C) (scan-data T))
-(scm_string_to_number (groups scm C) (scan-data T))
-(scm_string_to_symbol (groups scm C) (scan-data T))
-(scm_string_upcase (groups scm C) (scan-data T))
-(scm_string_upcase_x (groups scm C) (scan-data T))
-(scm_strndup (groups scm C) (scan-data T))
-(scm_strport_to_string (groups scm C) (scan-data T))
-(scm_strptime (groups scm C) (scan-data T))
-(scm_struct_create_handle (groups scm C) (scan-data T))
-(scm_struct_free_0 (groups scm C) (scan-data T))
-(scm_struct_free_entity (groups scm C) (scan-data T))
-(scm_struct_free_light (groups scm C) (scan-data T))
-(scm_struct_free_standard (groups scm C) (scan-data T))
-(scm_struct_ihashq (groups scm C) (scan-data T))
-(scm_struct_p (groups scm C) (scan-data T))
-(scm_struct_prehistory (groups scm C) (scan-data T))
-(scm_struct_ref (groups scm C) (scan-data T))
-(scm_struct_set_x (groups scm C) (scan-data T))
-(scm_struct_table (groups scm C) (scan-data B))
-(scm_struct_vtable (groups scm C) (scan-data T))
-(scm_struct_vtable_name (groups scm C) (scan-data T))
-(scm_struct_vtable_p (groups scm C) (scan-data T))
-(scm_struct_vtable_tag (groups scm C) (scan-data T))
-(scm_structs_to_free (groups scm C) (scan-data B))
-(scm_subr_p (groups scm C) (scan-data T))
-(scm_subr_table (groups scm C) (scan-data B))
-(scm_subr_table_room (groups scm C) (scan-data D))
-(scm_subr_table_size (groups scm C) (scan-data D))
-(scm_substring (groups scm C) (scan-data T))
-(scm_substring_fill_x (groups scm C) (scan-data T))
-(scm_substring_move_x (groups scm C) (scan-data T))
-(scm_sum (groups scm C) (scan-data T))
-(scm_swap_bindings (groups scm C) (scan-data T))
-(scm_swap_fluids (groups scm C) (scan-data T))
-(scm_swap_fluids_reverse (groups scm C) (scan-data T))
-(scm_switch_counter (groups scm C) (scan-data D))
-(scm_sym2var (groups scm C) (scan-data T))
-(scm_sym_and (groups scm C) (scan-data B))
-(scm_sym_apply (groups scm C) (scan-data B))
-(scm_sym_apply_frame (groups scm C) (scan-data B))
-(scm_sym_arity (groups scm C) (scan-data B))
-(scm_sym_arrow (groups scm C) (scan-data B))
-(scm_sym_at_call_with_values (groups scm C) (scan-data B))
-(scm_sym_atapply (groups scm C) (scan-data B))
-(scm_sym_atcall_cc (groups scm C) (scan-data B))
-(scm_sym_begin (groups scm C) (scan-data B))
-(scm_sym_breakpoint (groups scm C) (scan-data B))
-(scm_sym_case (groups scm C) (scan-data B))
-(scm_sym_column (groups scm C) (scan-data B))
-(scm_sym_cond (groups scm C) (scan-data B))
-(scm_sym_copy (groups scm C) (scan-data B))
-(scm_sym_define (groups scm C) (scan-data B))
-(scm_sym_delay (groups scm C) (scan-data B))
-(scm_sym_do (groups scm C) (scan-data B))
-(scm_sym_dot (groups scm C) (scan-data B))
-(scm_sym_else (groups scm C) (scan-data B))
-(scm_sym_enter_frame (groups scm C) (scan-data B))
-(scm_sym_exit_frame (groups scm C) (scan-data B))
-(scm_sym_filename (groups scm C) (scan-data B))
-(scm_sym_if (groups scm C) (scan-data B))
-(scm_sym_lambda (groups scm C) (scan-data B))
-(scm_sym_let (groups scm C) (scan-data B))
-(scm_sym_letrec (groups scm C) (scan-data B))
-(scm_sym_letstar (groups scm C) (scan-data B))
-(scm_sym_line (groups scm C) (scan-data B))
-(scm_sym_name (groups scm C) (scan-data B))
-(scm_sym_or (groups scm C) (scan-data B))
-(scm_sym_quasiquote (groups scm C) (scan-data B))
-(scm_sym_quote (groups scm C) (scan-data B))
-(scm_sym_set_x (groups scm C) (scan-data B))
-(scm_sym_system_procedure (groups scm C) (scan-data B))
-(scm_sym_trace (groups scm C) (scan-data B))
-(scm_sym_unquote (groups scm C) (scan-data B))
-(scm_sym_uq_splicing (groups scm C) (scan-data B))
-(scm_symbol_fref (groups scm C) (scan-data T))
-(scm_symbol_fset_x (groups scm C) (scan-data T))
-(scm_symbol_hash (groups scm C) (scan-data T))
-(scm_symbol_interned_p (groups scm C) (scan-data T))
-(scm_symbol_p (groups scm C) (scan-data T))
-(scm_symbol_pref (groups scm C) (scan-data T))
-(scm_symbol_pset_x (groups scm C) (scan-data T))
-(scm_symbol_to_string (groups scm C) (scan-data T))
-(scm_symbols_prehistory (groups scm C) (scan-data T))
-(scm_symlink (groups scm C) (scan-data T))
-(scm_sync (groups scm C) (scan-data T))
-(scm_sys_allocate_instance (groups scm C) (scan-data T))
-(scm_sys_atan2 (groups scm C) (scan-data T))
-(scm_sys_compute_applicable_methods (groups scm C) (scan-data T))
-(scm_sys_compute_slots (groups scm C) (scan-data T))
-(scm_sys_expt (groups scm C) (scan-data T))
-(scm_sys_fast_slot_ref (groups scm C) (scan-data T))
-(scm_sys_fast_slot_set_x (groups scm C) (scan-data T))
-(scm_sys_inherit_magic_x (groups scm C) (scan-data T))
-(scm_sys_initialize_object (groups scm C) (scan-data T))
-(scm_sys_invalidate_class (groups scm C) (scan-data T))
-(scm_sys_invalidate_method_cache_x (groups scm C) (scan-data T))
-(scm_sys_library_dir (groups scm C) (scan-data T))
-(scm_sys_make_void_port (groups scm C) (scan-data T))
-(scm_sys_method_more_specific_p (groups scm C) (scan-data T))
-(scm_sys_modify_class (groups scm C) (scan-data T))
-(scm_sys_modify_instance (groups scm C) (scan-data T))
-(scm_sys_package_data_dir (groups scm C) (scan-data T))
-(scm_sys_prep_layout_x (groups scm C) (scan-data T))
-(scm_sys_protects (groups scm C) (scan-data B))
-(scm_sys_search_load_path (groups scm C) (scan-data T))
-(scm_sys_set_object_setter_x (groups scm C) (scan-data T))
-(scm_sys_site_dir (groups scm C) (scan-data T))
-(scm_sys_tag_body (groups scm C) (scan-data T))
-(scm_syserror (groups scm C) (scan-data T))
-(scm_syserror_msg (groups scm C) (scan-data T))
-(scm_system (groups scm C) (scan-data T))
-(scm_system_async (groups scm C) (scan-data T))
-(scm_system_async_mark (groups scm C) (scan-data T))
-(scm_system_async_mark_from_signal_handler (groups scm C) (scan-data T))
-(scm_system_environment (groups scm C) (scan-data B))
-(scm_system_error_key (groups scm C) (scan-data B))
-(scm_system_module_env_p (groups scm C) (scan-data T))
-(scm_tables_prehistory (groups scm C) (scan-data T))
-(scm_take0str (groups scm C) (scan-data T))
-(scm_take_from_input_buffers (groups scm C) (scan-data T))
-(scm_take_str (groups scm C) (scan-data T))
-(scm_tc16_allocated (groups scm C) (scan-data B))
-(scm_tc16_array (groups scm C) (scan-data B))
-(scm_tc16_condvar (groups scm C) (scan-data B))
-(scm_tc16_continuation (groups scm C) (scan-data B))
-(scm_tc16_debugobj (groups scm C) (scan-data B))
-(scm_tc16_dir (groups scm C) (scan-data B))
-(scm_tc16_dynamic_obj (groups scm C) (scan-data B))
-(scm_tc16_environment (groups scm C) (scan-data B))
-(scm_tc16_eval_closure (groups scm C) (scan-data B))
-(scm_tc16_fluid (groups scm C) (scan-data B))
-(scm_tc16_fport (groups scm C) (scan-data B))
-(scm_tc16_hook (groups scm C) (scan-data B))
-(scm_tc16_keyword (groups scm C) (scan-data B))
-(scm_tc16_macro (groups scm C) (scan-data B))
-(scm_tc16_malloc (groups scm C) (scan-data B))
-(scm_tc16_memoized (groups scm C) (scan-data B))
-(scm_tc16_mutex (groups scm C) (scan-data B))
-(scm_tc16_observer (groups scm C) (scan-data B))
-(scm_tc16_port_with_ps (groups scm C) (scan-data B))
-(scm_tc16_promise (groups scm C) (scan-data B))
-(scm_tc16_regex (groups scm C) (scan-data B))
-(scm_tc16_root (groups scm C) (scan-data B))
-(scm_tc16_rstate (groups scm C) (scan-data B))
-(scm_tc16_srcprops (groups scm C) (scan-data B))
-(scm_tc16_strport (groups scm C) (scan-data B))
-(scm_tc16_thread (groups scm C) (scan-data B))
-(scm_tc16_void_port (groups scm C) (scan-data D))
-(scm_tcgetpgrp (groups scm C) (scan-data T))
-(scm_tcsetpgrp (groups scm C) (scan-data T))
-(scm_the_last_stack_fluid_var (groups scm C) (scan-data B))
-(scm_the_rng (groups scm C) (scan-data B))
-(scm_thread_count (groups scm C) (scan-data D))
-(scm_thread_sleep (groups scm C) (scan-data T))
-(scm_thread_usleep (groups scm C) (scan-data T))
-(scm_threads_init (groups scm C) (scan-data T))
-(scm_threads_mark_stacks (groups scm C) (scan-data T))
-(scm_throw (groups scm C) (scan-data T))
-(scm_thunk_p (groups scm C) (scan-data T))
-(scm_times (groups scm C) (scan-data T))
-(scm_tmpnam (groups scm C) (scan-data T))
-(scm_top_level_env (groups scm C) (scan-data T))
-(scm_transpose_array (groups scm C) (scan-data T))
-(scm_truncate (groups scm C) (scan-data T))
-(scm_truncate_file (groups scm C) (scan-data T))
-(scm_try_arbiter (groups scm C) (scan-data T))
-(scm_ttyname (groups scm C) (scan-data T))
-(scm_type_eval_environment (groups scm C) (scan-data D))
-(scm_type_export_environment (groups scm C) (scan-data D))
-(scm_type_import_environment (groups scm C) (scan-data D))
-(scm_type_leaf_environment (groups scm C) (scan-data D))
-(scm_tzset (groups scm C) (scan-data T))
-(scm_uint2num (groups scm C) (scan-data T))
-(scm_ulong2num (groups scm C) (scan-data T))
-(scm_ulong_long2num (groups scm C) (scan-data T))
-(scm_umask (groups scm C) (scan-data T))
-(scm_uname (groups scm C) (scan-data T))
-(scm_ungetc (groups scm C) (scan-data T))
-(scm_ungets (groups scm C) (scan-data T))
-(scm_uniform_array_read_x (groups scm C) (scan-data T))
-(scm_uniform_array_write (groups scm C) (scan-data T))
-(scm_uniform_element_size (groups scm C) (scan-data T))
-(scm_uniform_vector_length (groups scm C) (scan-data T))
-(scm_uniform_vector_ref (groups scm C) (scan-data T))
-(scm_unlock_mutex (groups scm C) (scan-data T))
-(scm_unmask_signals (groups scm C) (scan-data T))
-(scm_unmemocar (groups scm C) (scan-data T))
-(scm_unmemocopy (groups scm C) (scan-data T))
-(scm_unmemoize (groups scm C) (scan-data T))
-(scm_unread_char (groups scm C) (scan-data T))
-(scm_unread_string (groups scm C) (scan-data T))
-(scm_upcase (groups scm C) (scan-data T))
-(scm_usage_name (groups scm C) (scan-data D))
-(scm_ushort2num (groups scm C) (scan-data T))
-(scm_usleep (groups scm C) (scan-data T))
-(scm_utime (groups scm C) (scan-data T))
-(scm_valid_object_procedure_p (groups scm C) (scan-data T))
-(scm_valid_oport_value_p (groups scm C) (scan-data T))
-(scm_values (groups scm C) (scan-data T))
-(scm_values_vtable (groups scm C) (scan-data B))
-(scm_var_random_state (groups scm C) (scan-data B))
-(scm_variable_bound_p (groups scm C) (scan-data T))
-(scm_variable_p (groups scm C) (scan-data T))
-(scm_variable_ref (groups scm C) (scan-data T))
-(scm_variable_set_x (groups scm C) (scan-data T))
-(scm_vector (groups scm C) (scan-data T))
-(scm_vector_equal_p (groups scm C) (scan-data T))
-(scm_vector_fill_x (groups scm C) (scan-data T))
-(scm_vector_length (groups scm C) (scan-data T))
-(scm_vector_move_left_x (groups scm C) (scan-data T))
-(scm_vector_move_right_x (groups scm C) (scan-data T))
-(scm_vector_p (groups scm C) (scan-data T))
-(scm_vector_ref (groups scm C) (scan-data T))
-(scm_vector_set_x (groups scm C) (scan-data T))
-(scm_vector_to_list (groups scm C) (scan-data T))
-(scm_version (groups scm C) (scan-data T))
-(scm_void_port (groups scm C) (scan-data T))
-(scm_wait_condition_variable (groups scm C) (scan-data T))
-(scm_waitpid (groups scm C) (scan-data T))
-(scm_weak_key_hash_table_p (groups scm C) (scan-data T))
-(scm_weak_value_hash_table_p (groups scm C) (scan-data T))
-(scm_weak_vector (groups scm C) (scan-data T))
-(scm_weak_vector_p (groups scm C) (scan-data T))
-(scm_weak_vectors (groups scm C) (scan-data B))
-(scm_weaks_prehistory (groups scm C) (scan-data T))
-(scm_with_fluids (groups scm C) (scan-data T))
-(scm_with_traps (groups scm C) (scan-data T))
-(scm_wrap_component (groups scm C) (scan-data T))
-(scm_wrap_object (groups scm C) (scan-data T))
-(scm_write (groups scm C) (scan-data T))
-(scm_write_char (groups scm C) (scan-data T))
-(scm_write_line (groups scm C) (scan-data T))
-(scm_write_string_partial (groups scm C) (scan-data T))
-(scm_wrong_num_args (groups scm C) (scan-data T))
-(scm_wrong_type_arg (groups scm C) (scan-data T))
-(scm_wrong_type_arg_msg (groups scm C) (scan-data T))
-(scm_yield (groups scm C) (scan-data T))
-(scm_your_base (groups scm C) (scan-data D))
-(scm_zero_p (groups scm C) (scan-data T))
-(search-path (groups Scheme) (scan-data "#<primitive-procedure search-path>"))
-(seed->random-state (groups Scheme) (scan-data "#<primitive-procedure seed->random-state>"))
-(seek (groups Scheme) (scan-data "#<primitive-procedure seek>"))
-(select (groups POSIX Scheme) (scan-data "#<primitive-procedure select>"))
-(send (groups Scheme) (scan-data "#<primitive-procedure send>"))
-(sendto (groups Scheme) (scan-data "#<primitive-procedure sendto>"))
-(servent:aliases (groups Scheme) (scan-data "#<procedure servent:aliases (obj)>"))
-(servent:name (groups Scheme) (scan-data "#<procedure servent:name (obj)>"))
-(servent:port (groups Scheme) (scan-data "#<procedure servent:port (obj)>"))
-(servent:proto (groups Scheme) (scan-data "#<procedure servent:proto (obj)>"))
-(set! (groups Scheme) (scan-data ""))
-(set-autoloaded! (groups Scheme) (scan-data "#<procedure set-autoloaded! (p m done?)>"))
-(set-batch-mode?! (groups Scheme) (scan-data "#<procedure set-batch-mode?! (arg)>"))
-(set-car! (groups Scheme) (scan-data "#<primitive-procedure set-car!>"))
-(set-cdr! (groups Scheme) (scan-data "#<primitive-procedure set-cdr!>"))
-(set-current-error-port (groups Scheme) (scan-data "#<primitive-procedure set-current-error-port>"))
-(set-current-input-port (groups Scheme) (scan-data "#<primitive-procedure set-current-input-port>"))
-(set-current-module (groups Scheme) (scan-data "#<primitive-procedure set-current-module>"))
-(set-current-output-port (groups Scheme) (scan-data "#<primitive-procedure set-current-output-port>"))
-(set-defmacro-transformer! (groups Scheme) (scan-data "#<procedure set-defmacro-transformer! (m t)>"))
-(set-module-binder! (groups Scheme) (scan-data "#<procedure set-module-binder! (obj val)>"))
-(set-module-eval-closure! (groups Scheme) (scan-data "#<procedure set-module-eval-closure! (module closure)>"))
-(set-module-kind! (groups Scheme) (scan-data "#<procedure set-module-kind! (obj val)>"))
-(set-module-name! (groups Scheme) (scan-data "#<procedure set-module-name! (obj val)>"))
-(set-module-obarray! (groups Scheme) (scan-data "#<procedure set-module-obarray! (obj val)>"))
-(set-module-observer-id! (groups Scheme) (scan-data "#<procedure set-module-observer-id! (obj val)>"))
-(set-module-observers! (groups Scheme) (scan-data "#<procedure set-module-observers! (obj val)>"))
-(set-module-public-interface! (groups Scheme) (scan-data "#<procedure set-module-public-interface! (m i)>"))
-(set-module-transformer! (groups Scheme) (scan-data "#<procedure set-module-transformer! (obj val)>"))
-(set-module-uses! (groups Scheme) (scan-data "#<procedure set-module-uses! (obj val)>"))
-(set-object-procedure! (groups Scheme) (scan-data "#<primitive-procedure set-object-procedure!>"))
-(set-object-properties! (groups Scheme) (scan-data "#<primitive-procedure set-object-properties!>"))
-(set-object-property! (groups Scheme) (scan-data "#<primitive-procedure set-object-property!>"))
-(set-port-column! (groups Scheme) (scan-data "#<primitive-procedure set-port-column!>"))
-(set-port-filename! (groups Scheme) (scan-data "#<primitive-procedure set-port-filename!>"))
-(set-port-line! (groups Scheme) (scan-data "#<primitive-procedure set-port-line!>"))
-(set-port-revealed! (groups POSIX Scheme) (scan-data "#<primitive-procedure set-port-revealed!>"))
-(set-procedure-properties! (groups Scheme) (scan-data "#<primitive-procedure set-procedure-properties!>"))
-(set-procedure-property! (groups Scheme) (scan-data "#<primitive-procedure set-procedure-property!>"))
-(set-repl-prompt! (groups Scheme) (scan-data "#<procedure set-repl-prompt! (v)>"))
-(set-source-properties! (groups Scheme) (scan-data "#<primitive-procedure set-source-properties!>"))
-(set-source-property! (groups Scheme) (scan-data "#<primitive-procedure set-source-property!>"))
-(set-struct-vtable-name! (groups Scheme) (scan-data "#<primitive-procedure set-struct-vtable-name!>"))
-(set-symbol-property! (groups Scheme) (scan-data "#<procedure set-symbol-property! (sym prop val)>"))
-(set-system-module! (groups Scheme) (scan-data "#<procedure set-system-module! (m s)>"))
-(set-tm:gmtoff (groups POSIX Scheme) (scan-data "#<procedure set-tm:gmtoff (obj val)>"))
-(set-tm:hour (groups POSIX Scheme) (scan-data "#<procedure set-tm:hour (obj val)>"))
-(set-tm:isdst (groups POSIX Scheme) (scan-data "#<procedure set-tm:isdst (obj val)>"))
-(set-tm:mday (groups POSIX Scheme) (scan-data "#<procedure set-tm:mday (obj val)>"))
-(set-tm:min (groups POSIX Scheme) (scan-data "#<procedure set-tm:min (obj val)>"))
-(set-tm:mon (groups POSIX Scheme) (scan-data "#<procedure set-tm:mon (obj val)>"))
-(set-tm:sec (groups POSIX Scheme) (scan-data "#<procedure set-tm:sec (obj val)>"))
-(set-tm:wday (groups POSIX Scheme) (scan-data "#<procedure set-tm:wday (obj val)>"))
-(set-tm:yday (groups POSIX Scheme) (scan-data "#<procedure set-tm:yday (obj val)>"))
-(set-tm:year (groups POSIX Scheme) (scan-data "#<procedure set-tm:year (obj val)>"))
-(set-tm:zone (groups POSIX Scheme) (scan-data "#<procedure set-tm:zone (obj val)>"))
-(setegid (groups POSIX Scheme) (scan-data "#<primitive-procedure setegid>"))
-(setenv (groups POSIX Scheme) (scan-data "#<procedure setenv (name value)>"))
-(seteuid (groups POSIX Scheme) (scan-data "#<primitive-procedure seteuid>"))
-(setgid (groups POSIX Scheme) (scan-data "#<primitive-procedure setgid>"))
-(setgr (groups POSIX Scheme) (scan-data "#<primitive-procedure setgr>"))
-(setgrent (groups POSIX Scheme) (scan-data "#<procedure setgrent ()>"))
-(sethost (groups Scheme) (scan-data "#<primitive-procedure sethost>"))
-(sethostent (groups Scheme) (scan-data "#<procedure sethostent stayopen>"))
-(sethostname (groups POSIX Scheme) (scan-data "#<primitive-procedure sethostname>"))
-(setitimer (groups POSIX Scheme) (scan-data "#<primitive-procedure setitimer>"))
-(setlocale (groups POSIX Scheme) (scan-data "#<primitive-procedure setlocale>"))
-(setnet (groups Scheme) (scan-data "#<primitive-procedure setnet>"))
-(setnetent (groups Scheme) (scan-data "#<procedure setnetent stayopen>"))
-(setpgid (groups POSIX Scheme) (scan-data "#<primitive-procedure setpgid>"))
-(setpriority (groups POSIX Scheme) (scan-data "#<primitive-procedure setpriority>"))
-(setproto (groups Scheme) (scan-data "#<primitive-procedure setproto>"))
-(setprotoent (groups Scheme) (scan-data "#<procedure setprotoent stayopen>"))
-(setpw (groups POSIX Scheme) (scan-data "#<primitive-procedure setpw>"))
-(setpwent (groups POSIX Scheme) (scan-data "#<procedure setpwent ()>"))
-(setserv (groups Scheme) (scan-data "#<primitive-procedure setserv>"))
-(setservent (groups Scheme) (scan-data "#<procedure setservent stayopen>"))
-(setsid (groups POSIX Scheme) (scan-data "#<primitive-procedure setsid>"))
-(setsockopt (groups Scheme) (scan-data "#<primitive-procedure setsockopt>"))
-(setter (groups Scheme) (scan-data "#<primitive-procedure setter>"))
-(setuid (groups POSIX Scheme) (scan-data "#<primitive-procedure setuid>"))
-(setvbuf (groups POSIX Scheme) (scan-data "#<primitive-procedure setvbuf>"))
-(shared-array-increments (groups Scheme) (scan-data "#<primitive-procedure shared-array-increments>"))
-(shared-array-offset (groups Scheme) (scan-data "#<primitive-procedure shared-array-offset>"))
-(shared-array-root (groups Scheme) (scan-data "#<primitive-procedure shared-array-root>"))
-(shutdown (groups Scheme) (scan-data "#<primitive-procedure shutdown>"))
-(sigaction (groups POSIX Scheme) (scan-data "#<primitive-procedure sigaction>"))
-(signal-condition-variable (groups Scheme) (scan-data "#<primitive-procedure signal-condition-variable>"))
-(signal-handlers (groups Scheme) (scan-data ""))
-(simple-format (groups Scheme) (scan-data "#<primitive-procedure simple-format>"))
-(sin (groups Scheme) (scan-data "#<procedure sin (z)>"))
-(single-active-thread? (groups Scheme) (scan-data "#<primitive-procedure single-active-thread?>"))
-(sinh (groups Scheme) (scan-data "#<procedure sinh (z)>"))
-(sleep (groups POSIX Scheme) (scan-data "#<primitive-procedure sleep>"))
-(sloppy-assoc (groups Scheme) (scan-data "#<primitive-procedure sloppy-assoc>"))
-(sloppy-assq (groups Scheme) (scan-data "#<primitive-procedure sloppy-assq>"))
-(sloppy-assv (groups Scheme) (scan-data "#<primitive-procedure sloppy-assv>"))
-(sockaddr:addr (groups Scheme) (scan-data "#<procedure sockaddr:addr (obj)>"))
-(sockaddr:fam (groups Scheme) (scan-data "#<procedure sockaddr:fam (obj)>"))
-(sockaddr:path (groups Scheme) (scan-data "#<procedure sockaddr:path (obj)>"))
-(sockaddr:port (groups Scheme) (scan-data "#<procedure sockaddr:port (obj)>"))
-(socket (groups Scheme) (scan-data "#<primitive-procedure socket>"))
-(socketpair (groups Scheme) (scan-data "#<primitive-procedure socketpair>"))
-(sort (groups Scheme) (scan-data "#<primitive-procedure sort>"))
-(sort! (groups Scheme) (scan-data "#<primitive-procedure sort!>"))
-(sort-list (groups Scheme) (scan-data "#<primitive-procedure sort-list>"))
-(sort-list! (groups Scheme) (scan-data "#<primitive-procedure sort-list!>"))
-(sorted? (groups Scheme) (scan-data "#<primitive-procedure sorted?>"))
-(source-properties (groups Scheme) (scan-data "#<primitive-procedure source-properties>"))
-(source-property (groups Scheme) (scan-data "#<primitive-procedure source-property>"))
-(source-whash (groups Scheme) (scan-data ""))
-(sqrt (groups Scheme) (scan-data "#<procedure sqrt (z)>"))
-(stable-sort (groups Scheme) (scan-data "#<primitive-procedure stable-sort>"))
-(stable-sort! (groups Scheme) (scan-data "#<primitive-procedure stable-sort!>"))
-(stack-id (groups Scheme) (scan-data "#<primitive-procedure stack-id>"))
-(stack-length (groups Scheme) (scan-data "#<primitive-procedure stack-length>"))
-(stack-ref (groups Scheme) (scan-data "#<primitive-procedure stack-ref>"))
-(stack-saved? (groups Scheme) (scan-data ""))
-(stack? (groups Scheme) (scan-data "#<primitive-procedure stack?>"))
-(standard-eval-closure (groups Scheme) (scan-data "#<primitive-procedure standard-eval-closure>"))
-(standard-interface-eval-closure (groups Scheme) (scan-data "#<primitive-procedure standard-interface-eval-closure>"))
-(start-stack (groups Scheme) (scan-data ""))
-(stat (groups POSIX Scheme) (scan-data "#<primitive-procedure stat>"))
-(stat:atime (groups POSIX Scheme) (scan-data "#<procedure stat:atime (f)>"))
-(stat:blksize (groups POSIX Scheme) (scan-data "#<procedure stat:blksize (f)>"))
-(stat:blocks (groups POSIX Scheme) (scan-data "#<procedure stat:blocks (f)>"))
-(stat:ctime (groups POSIX Scheme) (scan-data "#<procedure stat:ctime (f)>"))
-(stat:dev (groups POSIX Scheme) (scan-data "#<procedure stat:dev (f)>"))
-(stat:gid (groups POSIX Scheme) (scan-data "#<procedure stat:gid (f)>"))
-(stat:ino (groups POSIX Scheme) (scan-data "#<procedure stat:ino (f)>"))
-(stat:mode (groups POSIX Scheme) (scan-data "#<procedure stat:mode (f)>"))
-(stat:mtime (groups POSIX Scheme) (scan-data "#<procedure stat:mtime (f)>"))
-(stat:nlink (groups POSIX Scheme) (scan-data "#<procedure stat:nlink (f)>"))
-(stat:perms (groups POSIX Scheme) (scan-data "#<procedure stat:perms (f)>"))
-(stat:rdev (groups POSIX Scheme) (scan-data "#<procedure stat:rdev (f)>"))
-(stat:size (groups POSIX Scheme) (scan-data "#<procedure stat:size (f)>"))
-(stat:type (groups POSIX Scheme) (scan-data "#<procedure stat:type (f)>"))
-(stat:uid (groups POSIX Scheme) (scan-data "#<procedure stat:uid (f)>"))
-(status:exit-val (groups POSIX Scheme) (scan-data "#<primitive-procedure status:exit-val>"))
-(status:stop-sig (groups POSIX Scheme) (scan-data "#<primitive-procedure status:stop-sig>"))
-(status:term-sig (groups POSIX Scheme) (scan-data "#<primitive-procedure status:term-sig>"))
-(strerror (groups Scheme) (scan-data "#<primitive-procedure strerror>"))
-(strftime (groups POSIX Scheme) (scan-data "#<primitive-procedure strftime>"))
-(string (groups Scheme) (scan-data "#<primitive-procedure string>"))
-(string->list (groups Scheme) (scan-data "#<primitive-procedure string->list>"))
-(string->number (groups Scheme) (scan-data "#<primitive-procedure string->number>"))
-(string->symbol (groups Scheme) (scan-data "#<primitive-procedure string->symbol>"))
-(string-append (groups Scheme) (scan-data "#<primitive-procedure string-append>"))
-(string-capitalize (groups Scheme) (scan-data "#<primitive-procedure string-capitalize>"))
-(string-capitalize! (groups Scheme) (scan-data "#<primitive-procedure string-capitalize!>"))
-(string-ci->symbol (groups Scheme) (scan-data "#<primitive-procedure string-ci->symbol>"))
-(string-ci<=? (groups Scheme) (scan-data "#<primitive-procedure string-ci<=?>"))
-(string-ci<? (groups Scheme) (scan-data "#<primitive-procedure string-ci<?>"))
-(string-ci=? (groups Scheme) (scan-data "#<primitive-procedure string-ci=?>"))
-(string-ci>=? (groups Scheme) (scan-data "#<primitive-procedure string-ci>=?>"))
-(string-ci>? (groups Scheme) (scan-data "#<primitive-procedure string-ci>?>"))
-(string-copy (groups Scheme) (scan-data "#<primitive-procedure string-copy>"))
-(string-downcase (groups Scheme) (scan-data "#<primitive-procedure string-downcase>"))
-(string-downcase! (groups Scheme) (scan-data "#<primitive-procedure string-downcase!>"))
-(string-fill! (groups Scheme) (scan-data "#<primitive-procedure string-fill!>"))
-(string-index (groups Scheme) (scan-data "#<primitive-procedure string-index>"))
-(string-length (groups Scheme) (scan-data "#<primitive-procedure string-length>"))
-(string-null? (groups Scheme) (scan-data "#<primitive-procedure string-null?>"))
-(string-ref (groups Scheme) (scan-data "#<primitive-procedure string-ref>"))
-(string-rindex (groups Scheme) (scan-data "#<primitive-procedure string-rindex>"))
-(string-set! (groups Scheme) (scan-data "#<primitive-procedure string-set!>"))
-(string-split (groups Scheme) (scan-data "#<primitive-procedure string-split>"))
-(string-upcase (groups Scheme) (scan-data "#<primitive-procedure string-upcase>"))
-(string-upcase! (groups Scheme) (scan-data "#<primitive-procedure string-upcase!>"))
-(string<=? (groups Scheme) (scan-data "#<primitive-procedure string<=?>"))
-(string<? (groups Scheme) (scan-data "#<primitive-procedure string<?>"))
-(string=? (groups Scheme) (scan-data "#<primitive-procedure string=?>"))
-(string>=? (groups Scheme) (scan-data "#<primitive-procedure string>=?>"))
-(string>? (groups Scheme) (scan-data "#<primitive-procedure string>?>"))
-(string? (groups Scheme) (scan-data "#<primitive-procedure string?>"))
-(strptime (groups POSIX Scheme) (scan-data "#<primitive-procedure strptime>"))
-(struct-layout (groups Scheme) (scan-data "#<procedure struct-layout (s)>"))
-(struct-ref (groups Scheme) (scan-data "#<primitive-procedure struct-ref>"))
-(struct-set! (groups Scheme) (scan-data "#<primitive-procedure struct-set!>"))
-(struct-vtable (groups Scheme) (scan-data "#<primitive-procedure struct-vtable>"))
-(struct-vtable-name (groups Scheme) (scan-data "#<primitive-procedure struct-vtable-name>"))
-(struct-vtable-tag (groups Scheme) (scan-data "#<primitive-procedure struct-vtable-tag>"))
-(struct-vtable? (groups Scheme) (scan-data "#<primitive-procedure struct-vtable?>"))
-(struct? (groups Scheme) (scan-data "#<primitive-procedure struct?>"))
-(substring (groups Scheme) (scan-data "#<primitive-procedure substring>"))
-(substring-fill! (groups Scheme) (scan-data "#<primitive-procedure substring-fill!>"))
-(substring-move! (groups Scheme) (scan-data "#<primitive-procedure substring-move!>"))
-(symbol (groups Scheme) (scan-data "#<procedure symbol args>"))
-(symbol->keyword (groups Scheme) (scan-data "#<procedure symbol->keyword (symbol)>"))
-(symbol->string (groups Scheme) (scan-data "#<primitive-procedure symbol->string>"))
-(symbol-append (groups Scheme) (scan-data "#<procedure symbol-append args>"))
-(symbol-fref (groups Scheme) (scan-data "#<primitive-procedure symbol-fref>"))
-(symbol-fset! (groups Scheme) (scan-data "#<primitive-procedure symbol-fset!>"))
-(symbol-hash (groups Scheme) (scan-data "#<primitive-procedure symbol-hash>"))
-(symbol-interned? (groups Scheme) (scan-data "#<primitive-procedure symbol-interned?>"))
-(symbol-pref (groups Scheme) (scan-data "#<primitive-procedure symbol-pref>"))
-(symbol-prefix-proc (groups Scheme) (scan-data "#<procedure symbol-prefix-proc (prefix)>"))
-(symbol-property (groups Scheme) (scan-data "#<procedure symbol-property (sym prop)>"))
-(symbol-property-remove! (groups Scheme) (scan-data "#<procedure symbol-property-remove! (sym prop)>"))
-(symbol-pset! (groups Scheme) (scan-data "#<primitive-procedure symbol-pset!>"))
-(symbol? (groups Scheme) (scan-data "#<primitive-procedure symbol?>"))
-(symlink (groups POSIX Scheme) (scan-data "#<primitive-procedure symlink>"))
-(sync (groups POSIX Scheme) (scan-data "#<primitive-procedure sync>"))
-(system (groups POSIX Scheme) (scan-data "#<primitive-procedure system>"))
-(system-async (groups Scheme) (scan-data "#<primitive-procedure system-async>"))
-(system-async-mark (groups Scheme) (scan-data "#<primitive-procedure system-async-mark>"))
-(system-error-errno (groups Scheme) (scan-data "#<procedure system-error-errno (args)>"))
-(tan (groups Scheme) (scan-data "#<procedure tan (z)>"))
-(tanh (groups Scheme) (scan-data "#<procedure tanh (z)>"))
-(tcgetpgrp (groups POSIX Scheme) (scan-data "#<primitive-procedure tcgetpgrp>"))
-(tcsetpgrp (groups POSIX Scheme) (scan-data "#<primitive-procedure tcsetpgrp>"))
-(the-environment (groups Scheme) (scan-data ""))
-(the-eof-object (groups Scheme) (scan-data ""))
-(the-last-stack (groups Scheme) (scan-data ""))
-(the-root-environment (groups Scheme) (scan-data ""))
-(the-root-module (groups Scheme) (scan-data ""))
-(the-scm-module (groups Scheme) (scan-data ""))
-(throw (groups Scheme) (scan-data "#<primitive-procedure throw>"))
-(thunk? (groups Scheme) (scan-data "#<primitive-procedure thunk?>"))
-(times (groups POSIX Scheme) (scan-data "#<primitive-procedure times>"))
-(tm:gmtoff (groups POSIX Scheme) (scan-data "#<procedure tm:gmtoff (obj)>"))
-(tm:hour (groups POSIX Scheme) (scan-data "#<procedure tm:hour (obj)>"))
-(tm:isdst (groups POSIX Scheme) (scan-data "#<procedure tm:isdst (obj)>"))
-(tm:mday (groups POSIX Scheme) (scan-data "#<procedure tm:mday (obj)>"))
-(tm:min (groups POSIX Scheme) (scan-data "#<procedure tm:min (obj)>"))
-(tm:mon (groups POSIX Scheme) (scan-data "#<procedure tm:mon (obj)>"))
-(tm:sec (groups POSIX Scheme) (scan-data "#<procedure tm:sec (obj)>"))
-(tm:wday (groups POSIX Scheme) (scan-data "#<procedure tm:wday (obj)>"))
-(tm:yday (groups POSIX Scheme) (scan-data "#<procedure tm:yday (obj)>"))
-(tm:year (groups POSIX Scheme) (scan-data "#<procedure tm:year (obj)>"))
-(tm:zone (groups POSIX Scheme) (scan-data "#<procedure tm:zone (obj)>"))
-(tmpnam (groups POSIX Scheme) (scan-data "#<primitive-procedure tmpnam>"))
-(tms:clock (groups POSIX Scheme) (scan-data "#<procedure tms:clock (obj)>"))
-(tms:cstime (groups POSIX Scheme) (scan-data "#<procedure tms:cstime (obj)>"))
-(tms:cutime (groups POSIX Scheme) (scan-data "#<procedure tms:cutime (obj)>"))
-(tms:stime (groups POSIX Scheme) (scan-data "#<procedure tms:stime (obj)>"))
-(tms:utime (groups POSIX Scheme) (scan-data "#<procedure tms:utime (obj)>"))
-(top-repl (groups Scheme) (scan-data "#<procedure top-repl ()>"))
-(transform-usage-lambda (groups Scheme) (scan-data "#<procedure transform-usage-lambda (cases)>"))
-(transpose-array (groups Scheme) (scan-data "#<primitive-procedure transpose-array>"))
-(trap-disable (groups Scheme) (scan-data "#<procedure trap-disable flags>"))
-(trap-enable (groups Scheme) (scan-data "#<procedure trap-enable flags>"))
-(trap-set! (groups Scheme) (scan-data ""))
-(traps (groups Scheme) (scan-data "#<procedure traps args>"))
-(truncate (groups Scheme) (scan-data "#<primitive-procedure truncate>"))
-(truncate-file (groups Scheme) (scan-data "#<primitive-procedure truncate-file>"))
-(try-arbiter (groups Scheme) (scan-data "#<primitive-procedure try-arbiter>"))
-(try-load-module (groups Scheme) (scan-data "#<procedure try-load-module (name)>"))
-(try-module-autoload (groups Scheme) (scan-data "#<procedure try-module-autoload (module-name)>"))
-(ttyname (groups POSIX Scheme) (scan-data "#<primitive-procedure ttyname>"))
-(turn-on-debugging (groups Scheme) (scan-data "#<procedure turn-on-debugging ()>"))
-(tzset (groups POSIX Scheme) (scan-data "#<primitive-procedure tzset>"))
-(umask (groups POSIX Scheme) (scan-data "#<primitive-procedure umask>"))
-(uname (groups POSIX Scheme) (scan-data "#<primitive-procedure uname>"))
-(undefine (groups Scheme) (scan-data ""))
-(uniform-array-read! (groups Scheme) (scan-data "#<primitive-procedure uniform-array-read!>"))
-(uniform-array-set1! (groups Scheme) (scan-data "#<primitive-procedure uniform-array-set1!>"))
-(uniform-array-write (groups Scheme) (scan-data "#<primitive-procedure uniform-array-write>"))
-(uniform-vector-fill! (groups Scheme) (scan-data "#<primitive-procedure array-fill!>"))
-(uniform-vector-length (groups Scheme) (scan-data "#<primitive-procedure uniform-vector-length>"))
-(uniform-vector-read! (groups Scheme) (scan-data "#<primitive-procedure uniform-array-read!>"))
-(uniform-vector-ref (groups Scheme) (scan-data "#<primitive-procedure uniform-vector-ref>"))
-(uniform-vector-set! (groups Scheme) (scan-data "#<procedure uniform-vector-set! (u i o)>"))
-(uniform-vector-write (groups Scheme) (scan-data "#<primitive-procedure uniform-array-write>"))
-(uniform-vector? (groups Scheme) (scan-data "#<primitive-procedure array?>"))
-(unlock-mutex (groups Scheme) (scan-data "#<primitive-procedure unlock-mutex>"))
-(unmask-signals (groups Scheme) (scan-data "#<primitive-procedure unmask-signals>"))
-(unmemoize (groups Scheme) (scan-data "#<primitive-procedure unmemoize>"))
-(unread-char (groups POSIX Scheme) (scan-data "#<primitive-procedure unread-char>"))
-(unread-string (groups POSIX Scheme) (scan-data "#<primitive-procedure unread-string>"))
-(unsetenv (groups Scheme) (scan-data "#<procedure unsetenv (name)>"))
-(unspecified? (groups Scheme) (scan-data "#<procedure unspecified? (v)>"))
-(use-emacs-interface (groups Scheme) (scan-data ""))
-(use-modules (groups Scheme) (scan-data ""))
-(use-srfis (groups Scheme) (scan-data "#<procedure use-srfis (srfis)>"))
-(use-syntax (groups Scheme) (scan-data ""))
-(using-readline? (groups Scheme) (scan-data "#<procedure-with-setter>"))
-(usleep (groups POSIX Scheme) (scan-data "#<primitive-procedure usleep>"))
-(utime (groups POSIX Scheme) (scan-data "#<primitive-procedure utime>"))
-(utsname:machine (groups POSIX Scheme) (scan-data "#<procedure utsname:machine (obj)>"))
-(utsname:nodename (groups POSIX Scheme) (scan-data "#<procedure utsname:nodename (obj)>"))
-(utsname:release (groups POSIX Scheme) (scan-data "#<procedure utsname:release (obj)>"))
-(utsname:sysname (groups POSIX Scheme) (scan-data "#<procedure utsname:sysname (obj)>"))
-(utsname:version (groups POSIX Scheme) (scan-data "#<procedure utsname:version (obj)>"))
-(valid-object-procedure? (groups Scheme) (scan-data "#<primitive-procedure valid-object-procedure?>"))
-(values (groups Scheme) (scan-data "#<primitive-procedure values>"))
-(variable-bound? (groups Scheme) (scan-data "#<primitive-procedure variable-bound?>"))
-(variable-ref (groups Scheme) (scan-data "#<primitive-procedure variable-ref>"))
-(variable-set! (groups Scheme) (scan-data "#<primitive-procedure variable-set!>"))
-(variable? (groups Scheme) (scan-data "#<primitive-procedure variable?>"))
-(vector (groups Scheme) (scan-data "#<primitive-procedure vector>"))
-(vector->list (groups Scheme) (scan-data "#<primitive-procedure vector->list>"))
-(vector-fill! (groups Scheme) (scan-data "#<primitive-procedure vector-fill!>"))
-(vector-length (groups Scheme) (scan-data "#<primitive-procedure vector-length>"))
-(vector-move-left! (groups Scheme) (scan-data "#<primitive-procedure vector-move-left!>"))
-(vector-move-right! (groups Scheme) (scan-data "#<primitive-procedure vector-move-right!>"))
-(vector-ref (groups Scheme) (scan-data "#<primitive-procedure vector-ref>"))
-(vector-set! (groups Scheme) (scan-data "#<primitive-procedure vector-set!>"))
-(vector? (groups Scheme) (scan-data "#<primitive-procedure vector?>"))
-(version (groups Scheme) (scan-data "#<primitive-procedure version>"))
-(vtable-index-layout (groups Scheme) (scan-data ""))
-(vtable-index-printer (groups Scheme) (scan-data ""))
-(vtable-index-vtable (groups Scheme) (scan-data ""))
-(vtable-offset-user (groups Scheme) (scan-data ""))
-(wait-condition-variable (groups Scheme) (scan-data "#<primitive-procedure wait-condition-variable>"))
-(waitpid (groups POSIX Scheme) (scan-data "#<primitive-procedure waitpid>"))
-(warn (groups Scheme) (scan-data "#<procedure warn stuff>"))
-(weak-key-hash-table? (groups Scheme) (scan-data "#<primitive-procedure weak-key-hash-table?>"))
-(weak-value-hash-table? (groups Scheme) (scan-data "#<primitive-procedure weak-value-hash-table?>"))
-(weak-vector (groups Scheme) (scan-data "#<primitive-procedure weak-vector>"))
-(weak-vector? (groups Scheme) (scan-data "#<primitive-procedure weak-vector?>"))
-(while (groups Scheme) (scan-data ""))
-(with-error-to-file (groups Scheme) (scan-data "#<procedure with-error-to-file (file thunk)>"))
-(with-error-to-port (groups Scheme) (scan-data "#<procedure with-error-to-port (port thunk)>"))
-(with-error-to-string (groups Scheme) (scan-data "#<procedure with-error-to-string (thunk)>"))
-(with-fluids (groups Scheme) (scan-data ""))
-(with-fluids* (groups Scheme) (scan-data "#<primitive-procedure with-fluids*>"))
-(with-input-from-file (groups Scheme) (scan-data "#<procedure with-input-from-file (file thunk)>"))
-(with-input-from-port (groups Scheme) (scan-data "#<procedure with-input-from-port (port thunk)>"))
-(with-input-from-string (groups Scheme) (scan-data "#<procedure with-input-from-string (string thunk)>"))
-(with-output-to-file (groups Scheme) (scan-data "#<procedure with-output-to-file (file thunk)>"))
-(with-output-to-port (groups Scheme) (scan-data "#<procedure with-output-to-port (port thunk)>"))
-(with-output-to-string (groups Scheme) (scan-data "#<procedure with-output-to-string (thunk)>"))
-(with-traps (groups Scheme) (scan-data "#<primitive-procedure with-traps>"))
-(write (groups Scheme) (scan-data "#<primitive-procedure write>"))
-(write-char (groups Scheme) (scan-data "#<primitive-procedure write-char>"))
-(xformer-table (groups Scheme) (scan-data ""))
-(yield (groups Scheme) (scan-data "#<primitive-procedure yield>"))
-(zero? (groups Scheme) (scan-data "#<primitive-procedure zero?>"))
-) ;; end of interface
-) ;; eof
diff --git a/doc/guile.1 b/doc/guile.1
deleted file mode 100644
index ddf3cde1c..000000000
--- a/doc/guile.1
+++ /dev/null
@@ -1,93 +0,0 @@
-.\" Written by Robert Merkel (rgmerk@mira.net)
-.\" augmented by Rob Browning <rlb@cs.utexas.edu>
-.\" Process this file with
-.\" groff -man -Tascii foo.1
-.\"
-.TH GUILE 1 "January 2001" Version "1.4"
-.SH NAME
-guile \- a Scheme interpreter
-.SH SYNOPSIS
-.B guile [-q] [-ds] [--help] [--version] [--emacs] [--debug]
-.B [-l FILE] [-e FUNCTION] [\]
-.B [-c EXPR] [-s SCRIPT] [--]
-.SH DESCRIPTION
-Guile is an interpreter for the Scheme programming language. It
-implements a superset of R4RS, providing the additional features
-necessary for real-world use. It is extremely simple to embed guile
-into a C program, calling C from Scheme and Scheme from C. Guile's
-design makes it very suitable for use as an "extension" or "glue"
-language, but it also works well as a stand-alone scheme development
-environment.
-
-The
-.B guile
-executable itself provides a stand-alone interpreter for scheme
-programs, for either interactive use or executing scripts.
-
-This manpage provides only brief instruction in invoking
-.B guile
-from the command line. Please consult the guile info documentation
-(type
-.B info guile
-at a command prompt) for more information. There is also a tutorial
-.B (info guile-tut)
-available.
-
-.SH OPTIONS
-.IP -l FILE
-Load scheme source code from file.
-.IP -e FUNCTION
-After reading script, apply FUNCTION to command-line arguments
-.IP -ds
-do -s SCRIPT at this point (note that this argument must be used in
-conjuction with -s)
-.IP --help
-Describe command line options and exit
-.IP --debug
-Start guile with debugging evaluator and backtraces enabled
-(useful for debugging guile scripts)
-.IP --version
-Display guile version and exit.
-.IP --emacs
-Enable emacs protocol for use from within emacs (experimental)
-.IP --
-Stop argument processing, start guile in interactive mode.
-.IP -c EXPR
-Stop argument processing, evaluate EXPR as a scheme expression.
-.IP -s SCRIPT-FILE
-Load Scheme source from SCRIPT-FILE and execute as a script.
-
-.SH ENVIRONMENT
-.\".TP \w'MANROFFSEQ\ \ 'u
-.TP
-.B GUILE_LOAD_PATH
-If
-.RB $ GUILE_LOAD_PATH
-is set, its value is used to agument the path to search for scheme
-files when loading. It should be a colon separated list of
-directories which will be prepended to the default %load-path.
-
-.SH FILES
-.I ~/.guile
-is a guile script that is executed before any other processing occurs.
-For example, the following .guile activates guile's readline
-interface:
-
-.RS 4
-(use-modules (ice-9 readline))
-.RS 0
-(activate-readline)
-
-.SH "SEE ALSO"
-.B info guile, info guile-tut
-
-http://www.schemers.org provides a general introduction to the
-Scheme language.
-
-.SH AUTHORS
-Robert Merkel <rgmerk@mira.net> wrote this manpage.
-Rob Browning <rlb@cs.utexas.edu> has added to it.
-
-.B guile
-is GNU software. Guile is originally based on Aubrey Jaffer's
-SCM interpreter, and is the work of many individuals.
diff --git a/doc/hacks.el b/doc/hacks.el
deleted file mode 100644
index c5a3f576b..000000000
--- a/doc/hacks.el
+++ /dev/null
@@ -1,16 +0,0 @@
-;;;; hacks.el --- a few functions to help me work on the manual
-;;;; Jim Blandy <jimb@red-bean.com> --- October 1998
-
-(defun jh-exemplify-region (start end)
- (interactive "r")
- (save-excursion
- (save-restriction
- (narrow-to-region start end)
-
- ;; Texinfo doesn't handle tabs well.
- (untabify (point-min) (point-max))
-
- ;; Quote any characters special to texinfo.
- (goto-char (point-min))
- (while (re-search-forward "[{}@]" nil t)
- (replace-match "@\\&")))))
diff --git a/doc/maint/ChangeLog b/doc/maint/ChangeLog
deleted file mode 100644
index dc3bccbfe..000000000
--- a/doc/maint/ChangeLog
+++ /dev/null
@@ -1,59 +0,0 @@
-2002-07-10 Gary Houston <ghouston@arglist.com>
-
- * docstring.el: optional 2nd environment variable to locate
- built files.
-
-2002-07-09 Gary Houston <ghouston@arglist.com>
-
- * docstring.el: defined caddr, used in several places but missing
- for some reason.
-
-2002-04-02 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * doctring.el: List commands in commentary; nfc.
-
-2002-03-15 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile.texi: Replaced by regenerated libguile version.
-
-2002-03-12 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile.texi: Replaced by regenerated libguile version.
-
-2002-03-08 Neil Jerram <neil@ossau.uklinux.net>
-
- * docstring.el (docstring-libguile-directory,
- docstring-display-location, docstring-show-source): New.
-
-2001-11-16 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile.texi: Replaced by regenerated libguile version.
-
- * docstring.el (make-module-description-list): Exclude @deffn's
- with category {C Function}.
- (docstring-process-alist): Bind key "d" to
- docstring-ediff-this-line in the docstring output buffer.
-
-2001-11-13 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile.texi: Replaced by libguile version (after automatically
- updating docstrings in the reference manual).
-
-2001-11-07 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile.texi: Replaced by libguile version (after automatically
- updating docstrings in the reference manual).
-
- * docstring.el (docstring-manual-directory): Added "/ref" to end.
- (docstring-manual-files): Now calculated automatically, since by
- definition all the .texi files in doc/ref are reference manual
- files.
-
-2001-04-03 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * guile.texi: Automated docstring merging.
-
-2001-03-23 Neil Jerram <neil@ossau.uklinux.net>
-
- * ChangeLog, README, docstring.el, guile.texi: New files.
-
diff --git a/doc/maint/README b/doc/maint/README
deleted file mode 100644
index adfa13f82..000000000
--- a/doc/maint/README
+++ /dev/null
@@ -1,35 +0,0 @@
-README for guile-core/doc/maint -*- text -*-
-
-The files in this directory are used by the maintainers to automate
-the process of updating the Guile reference manual when the docstrings
-in the libguile C source change.
-
-- ChangeLog is the change log for files in this directory.
-
-- README is this file.
-
-- docstring.el is a helpful Emacs Lisp library (see source for
- customization). The two key entry points are:
- `docstring-process-module' and
- `docstring-ediff-this-line'.
-
-- guile.texi is a snapshot of the built file libguile/guile.texi,
- copied last time the reference manual was determined to be in sync
- with the libguile source.
-
-docstring.el requires the setting of an environment variable, e.g.,
-
-export GUILE_MAINTAINER_GUILE_CORE_DIR=$HOME/guile/guile-core
-
-If the build directory differs from the source directory, an additional
-variable is required:
-
-export GUILE_MAINTAINER_BUILD_CORE_DIR=$HOME/guile/guile-core-build
-
-If you've just fixed a docstring in, say, ../libguile/strop.c, do in emacs:
-
- M-x load-file RET .../doc/maint/docstring.el RET
- M-x docstring-process-module RET (guile) RET
-
-Save all modified .texi files and copy the current ../libguile/guile.texi
-to ./guile.texi, then commit. See elisp var `docstring-snarfed-roots'.
diff --git a/doc/maint/docstring.el b/doc/maint/docstring.el
deleted file mode 100644
index a01558fbb..000000000
--- a/doc/maint/docstring.el
+++ /dev/null
@@ -1,622 +0,0 @@
-;;; docstring.el --- utilities for Guile docstring maintenance
-;;;
-;;; Copyright (C) 2001 Neil Jerram
-;;;
-;;; This file is not part of GNU Emacs, but the same permissions apply.
-;;;
-;;; GNU Emacs 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 2, or (at your option)
-;;; any later version.
-;;;
-;;; GNU Emacs 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 Emacs; see the file COPYING. If not, write to the
-;;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-;;; Boston, MA 02111-1307, USA.
-
-;;; Commentary:
-
-;; The basic premise of these utilities is that - at least in the
-;; short term - we can get a lot of reference manual mileage by
-;; co-opting the docstrings that are snarfed automatically from
-;; Guile's C and Scheme source code. But this leads to problems of
-;; synchronization... How do you track when a docstring has been
-;; updated in the source and so needs updating in the reference
-;; manual. What if a procedure is removed from the Guile source? And
-;; so on. To complicate matters, the exact snarfed docstring text
-;; will probably need to be modified so that it fits into the flow of
-;; the manual section in which it appears. Can we design solutions to
-;; synchronization problems that continue to work even when the manual
-;; text has been enhanced in this way?
-;;
-;; This file implements an approach to this problem that I have found
-;; useful. It involves keeping track of three copies of each
-;; docstring:
-;;
-;; "MANUAL" = the docstring as it appears in the reference manual.
-;;
-;; "SNARFED" = the docstring as snarfed from the current C or Scheme
-;; source.
-;;
-;; "TRACKING" = the docstring as it appears in a tracking file whose
-;; purpose is to record the most recent snarfed docstrings
-;; that are known to be in sync with the reference manual.
-;;
-;; The approaches are as follows.
-;;
-;; 1. Comparison of MANUAL-DOC, SOURCE-DOC and TRACK-DOC, to produce a
-;; summary output buffer in which keystrokes are defined to bring up
-;; detailed comparisons.
-;;
-;; 2. Comparison of MANUAL-DOC, SOURCE-DOC and TRACK-DOC using Ediff.
-;;
-;; Here is a brief list of commands available (via "M-x COMMAND"):
-;;
-;; docstring-process-current-buffer
-;; docstring-process-current-region BEG END
-;; docstring-process-module MODULE
-;; docstring-ediff-this-line
-;; docstring-show-source
-
-
-(defvar guile-core-dir (or (getenv "GUILE_MAINTAINER_GUILE_CORE_DIR")
- (error "GUILE_MAINTAINER_GUILE_CORE_DIR not set"))
- "*Full path of guile-core source directory.")
-
-(defvar guile-build-dir (or (getenv "GUILE_MAINTAINER_BUILD_CORE_DIR")
- guile-core-dir)
- "*Full path of guile-core build directory. Defaults to guile-core-dir.")
-
-(defvar docstring-manual-directory (expand-file-name "doc/ref" guile-core-dir)
- "*The directory containing the Texinfo source for the Guile reference manual.")
-
-(defvar docstring-tracking-root (expand-file-name "doc/maint" guile-core-dir)
- "*Root directory for docstring tracking files. The tracking file
-for module (a b c) is expected to be in the file
-<docstring-tracking-root>/a/b/c.texi.")
-
-(defvar docstring-snarfed-roots (mapcar
- #'(lambda (frag)
- (expand-file-name frag guile-build-dir))
- '("libguile" "ice-9" "oop"))
- "*List of possible root directories for snarfed docstring files.
-For each entry in this list, the snarfed docstring file for module (a
-b c) is looked for in the file <entry>/a/b/c.texi.")
-
-(defvar docstring-manual-files
- (directory-files docstring-manual-directory nil "\\.texi$" t)
- "List of Texinfo source files that comprise the Guile reference manual.")
-
-(defvar docstring-new-docstrings-file "new-docstrings.texi"
- "The name of a file in the Guile reference manual source directory
-to which new docstrings should be added.")
-
-;; Apply FN in turn to each element in the list CANDIDATES until the
-;; first application that returns non-nil.
-(defun or-map (fn candidates args)
- (let ((result nil))
- (while candidates
- (setq result (apply fn (car candidates) args))
- (if result
- (setq result (cons (car candidates) result)
- candidates nil)
- (setq candidates (cdr candidates))))
- result))
-
-;; Return t if the current buffer position is in the scope of the
-;; specified MODULE, as determined by "@c module ..." comments in the
-;; buffer. DEFAULT-OK specifies the return value in the case that
-;; there are no preceding module comments at all.
-(defun docstring-in-module (module default-ok)
- (save-excursion
- (if (re-search-backward "^@c module " nil t)
- (progn
- (search-forward "@c module ")
- (equal module (read (current-buffer))))
- default-ok)))
-
-;; Find a docstring in the specified FILE-NAME for the item in module
-;; MODULE and with description DESCRIPTION. MODULE should be a list
-;; of symbols, Guile-style, for example: '(ice-9 session).
-;; DESCRIPTION should be the string that is expected after the @deffn,
-;; for example "primitive acons" or "syntax let*".
-(defun find-docstring (file-name module description)
- (and (file-exists-p file-name)
- (let ((buf (find-file-noselect file-name))
- (deffn-regexp (concat "^@deffnx? "
- (regexp-quote description)
- "[ \n\t]"))
- found
- result)
- (save-excursion
- (set-buffer buf)
- (goto-char (point-min))
- (while (and (not found)
- (re-search-forward deffn-regexp nil t))
- (save-excursion
- (goto-char (match-beginning 0))
- (beginning-of-line)
- (if (docstring-in-module module t)
- (setq found t))))
- (if found
- (setq result
- (list (current-buffer)
- (progn
- (re-search-backward "^@deffn ")
- (beginning-of-line)
- (point))
- (progn
- (re-search-forward "^@end deffn")
- (forward-line 1)
- (point))))))
- result)))
-
-;; Find the reference manual version of the specified docstring.
-;; MODULE and DESCRIPTION specify the docstring as per
-;; `find-docstring'. The set of files that `find-manual-docstring'
-;; searches is determined by the value of the `docstring-manual-files'
-;; variable.
-(defun find-manual-docstring (module description)
- (let* ((result
- (or-map 'find-docstring
- (mapcar (function (lambda (file-name)
- (concat docstring-manual-directory
- "/"
- file-name)))
- (cons docstring-new-docstrings-file
- docstring-manual-files))
- (list module
- description)))
- (matched-file-name (and (cdr result)
- (file-name-nondirectory (car result)))))
- (if matched-file-name
- (setq docstring-manual-files
- (cons matched-file-name
- (delete matched-file-name docstring-manual-files))))
- (cdr result)))
-
-;; Convert MODULE to a directory subpath.
-(defun module-to-path (module)
- (mapconcat (function (lambda (component)
- (symbol-name component)))
- module
- "/"))
-
-;; Find the current snarfed version of the specified docstring.
-;; MODULE and DESCRIPTION specify the docstring as per
-;; `find-docstring'. The file that `find-snarfed-docstring' looks in
-;; is automatically generated from MODULE.
-(defun find-snarfed-docstring (module description)
- (let ((modpath (module-to-path module)))
- (cdr (or-map (function (lambda (root)
- (find-docstring (concat root
- "/"
- modpath
- ".texi")
- module
- description)))
- docstring-snarfed-roots
- nil))))
-
-;; Find the tracking version of the specified docstring. MODULE and
-;; DESCRIPTION specify the docstring as per `find-docstring'. The
-;; file that `find-tracking-docstring' looks in is automatically
-;; generated from MODULE.
-(defun find-tracking-docstring (module description)
- (find-docstring (concat docstring-tracking-root
- "/"
- (module-to-path module)
- ".texi")
- module
- description))
-
-;; Extract an alist of modules and descriptions from the current
-;; buffer.
-(defun make-module-description-list ()
- (let ((alist nil)
- (module '(guile)))
- (save-excursion
- (goto-char (point-min))
- (while (re-search-forward "^\\(@c module \\|@deffnx? \\({[^}]+}\\|[^ ]+\\) \\([^ \n]+\\)\\)"
- nil
- t)
- (let ((matched (buffer-substring (match-beginning 1)
- (match-end 1))))
- (if (string-equal matched "@c module ")
- (setq module (read (current-buffer)))
- (let ((type (buffer-substring (match-beginning 2)
- (match-end 2))))
- (if (string-equal type "{C Function}")
- nil
- (setq matched
- (concat type
- " "
- (buffer-substring (match-beginning 3)
- (match-end 3))))
- (message "Found docstring: %S: %s" module matched)
- (let ((descriptions (assoc module alist)))
- (setq alist
- (cons (cons module (cons matched (cdr-safe descriptions)))
- (if descriptions
- (delete descriptions alist)
- alist))))))))))
- alist))
-
-;; missing in some environments?
-(defun caddr (list)
- (nth 2 list))
-
-;; Return the docstring from the specified LOCATION. LOCATION is a
-;; list of three elements: buffer, start position and end position.
-(defun location-to-docstring (location)
- (and location
- (save-excursion
- (set-buffer (car location))
- (buffer-substring (cadr location) (caddr location)))))
-
-;; Perform a comparison of the specified docstring. MODULE and
-;; DESCRIPTION are as per usual.
-(defun docstring-compare (module description)
- (let* ((manual-location (find-manual-docstring module description))
- (snarf-location (find-snarfed-docstring module description))
- (track-location (find-tracking-docstring module description))
-
- (manual-docstring (location-to-docstring manual-location))
- (snarf-docstring (location-to-docstring snarf-location))
- (track-docstring (location-to-docstring track-location))
-
- action
- issue)
-
- ;; Decide what to do.
- (cond ((null snarf-location)
- (setq action nil
- issue (if manual-location
- 'consider-removal
- nil)))
-
- ((null manual-location)
- (setq action 'add-to-manual issue nil))
-
- ((null track-location)
- (setq action nil
- issue (if (string-equal manual-docstring snarf-docstring)
- nil
- 'check-needed)))
-
- ((string-equal track-docstring snarf-docstring)
- (setq action nil issue nil))
-
- ((string-equal track-docstring manual-docstring)
- (setq action 'auto-update-manual issue nil))
-
- (t
- (setq action nil issue 'update-needed)))
-
- ;; Return a pair indicating any automatic action that can be
- ;; taken, and any issue for resolution.
- (cons action issue)))
-
-;; Add the specified docstring to the manual.
-(defun docstring-add-to-manual (module description)
- (let ((buf (find-file-noselect (concat docstring-manual-directory
- "/"
- docstring-new-docstrings-file))))
- (save-excursion
- (set-buffer buf)
- (goto-char (point-max))
- (or (docstring-in-module module nil)
- (insert "\n@c module " (prin1-to-string module) "\n"))
- (insert "\n" (location-to-docstring (find-snarfed-docstring module
- description))))))
-
-;; Auto-update the specified docstring in the manual.
-(defun docstring-auto-update-manual (module description)
- (let ((manual-location (find-manual-docstring module description))
- (track-location (find-tracking-docstring module description)))
- (save-excursion
- (set-buffer (car manual-location))
- (goto-char (cadr manual-location))
- (delete-region (cadr manual-location) (caddr manual-location))
- (insert (location-to-docstring (find-snarfed-docstring module
- description))))))
-
-;; Process an alist of modules and descriptions, and produce a summary
-;; buffer describing actions taken and issues to be resolved.
-(defun docstring-process-alist (alist)
- (let (check-needed-list
- update-needed-list
- consider-removal-list
- added-to-manual-list
- auto-updated-manual-list)
-
- (mapcar
- (function (lambda (module-list)
- (let ((module (car module-list)))
- (message "Module: %S" module)
- (mapcar
- (function (lambda (description)
- (message "Comparing docstring: %S: %s" module description)
- (let* ((ai (docstring-compare module description))
- (action (car ai))
- (issue (cdr ai)))
-
- (cond ((eq action 'add-to-manual)
- (docstring-add-to-manual module description)
- (setq added-to-manual-list
- (cons (cons module description)
- added-to-manual-list)))
-
- ((eq action 'auto-update-manual)
- (docstring-auto-update-manual module description)
- (setq auto-updated-manual-list
- (cons (cons module description)
- auto-updated-manual-list))))
-
- (cond ((eq issue 'check-needed)
- (setq check-needed-list
- (cons (cons module description)
- check-needed-list)))
-
- ((eq issue 'update-needed)
- (setq update-needed-list
- (cons (cons module description)
- update-needed-list)))
-
- ((eq issue 'consider-removal)
- (setq consider-removal-list
- (cons (cons module description)
- consider-removal-list)))))))
- (cdr module-list)))))
- alist)
-
- ;; Prepare a buffer describing the results.
- (set-buffer (get-buffer-create "*Docstring Results*"))
- (erase-buffer)
-
- (insert "
-The following items have been automatically added to the manual in
-file `" docstring-manual-directory "/" docstring-new-docstrings-file "'.\n\n")
- (if added-to-manual-list
- (mapcar (function (lambda (moddesc)
- (insert (prin1-to-string (car moddesc))
- ": "
- (cdr moddesc)
- "\n")))
- added-to-manual-list)
- (insert "(none)\n"))
-
- (insert "
-The following items have been automatically updated in the manual.\n\n")
- (if auto-updated-manual-list
- (mapcar (function (lambda (moddesc)
- (insert (prin1-to-string (car moddesc))
- ": "
- (cdr moddesc)
- "\n")))
- auto-updated-manual-list)
- (insert "(none)\n"))
-
- (insert "
-The following items are already documented in the manual but are not
-mentioned in the reference copy of the snarfed docstrings file.
-You should check that the manual documentation matches the docstring
-in the current snarfed docstrings file.\n\n")
- (if check-needed-list
- (mapcar (function (lambda (moddesc)
- (insert (prin1-to-string (car moddesc))
- ": "
- (cdr moddesc)
- "\n")))
- check-needed-list)
- (insert "(none)\n"))
-
- (insert "
-The following items have manual documentation that is different from
-the docstring in the reference copy of the snarfed docstrings file,
-and the snarfed docstring has changed. You need to update the manual
-documentation by hand with reference to the snarfed docstring changes.\n\n")
- (if update-needed-list
- (mapcar (function (lambda (moddesc)
- (insert (prin1-to-string (car moddesc))
- ": "
- (cdr moddesc)
- "\n")))
- update-needed-list)
- (insert "(none)\n"))
-
- (insert "
-The following items are documented in the manual but are no longer
-present in the snarfed docstrings file. You should consider whether
-the existing manual documentation is still pertinent. If it is, its
-docstring module comment may need updating, to connect it with a
-new snarfed docstring file.\n\n")
- (if consider-removal-list
- (mapcar (function (lambda (moddesc)
- (insert (prin1-to-string (car moddesc))
- ": "
- (cdr moddesc)
- "\n")))
- consider-removal-list)
- (insert "(none)\n"))
- (insert "\n")
-
- (goto-char (point-min))
- (local-set-key "d" 'docstring-ediff-this-line)
-
- ;; Popup the issues buffer.
- (let ((pop-up-frames t))
- (set-window-point (display-buffer (current-buffer))
- (point-min)))))
-
-(defun docstring-process-current-buffer ()
- (interactive)
- (docstring-process-alist (make-module-description-list)))
-
-(defun docstring-process-current-region (beg end)
- (interactive "r")
- (narrow-to-region beg end)
- (unwind-protect
- (save-excursion
- (docstring-process-alist (make-module-description-list)))
- (widen)))
-
-(defun docstring-process-module (module)
- (interactive "xModule: ")
- (let ((modpath (module-to-path module))
- (mdlist nil))
- (mapcar (function (lambda (root)
- (let ((fn (concat root
- "/"
- modpath
- ".texi")))
- (if (file-exists-p fn)
- (save-excursion
- (find-file fn)
- (message "Getting docstring list from %s" fn)
- (setq mdlist
- (append mdlist
- (make-module-description-list))))))))
- docstring-snarfed-roots)
- (docstring-process-alist mdlist)))
-
-(defun docstring-ediff-this-line ()
- (interactive)
- (let (module
- description)
- (save-excursion
- (beginning-of-line)
- (setq module (read (current-buffer)))
- (forward-char 2)
- (setq description (buffer-substring (point)
- (progn
- (end-of-line)
- (point)))))
-
- (message "Ediff docstring: %S: %s" module description)
-
- (let ((track-location (or (find-tracking-docstring module description)
- (docstring-temp-location "No docstring in tracking file")))
- (snarf-location (or (find-snarfed-docstring module description)
- (docstring-temp-location "No docstring in snarfed file")))
- (manual-location (or (find-manual-docstring module description)
- (docstring-temp-location "No docstring in manual"))))
-
- (setq docstring-ediff-buffers
- (list (car track-location)
- (car snarf-location)
- (car manual-location)))
-
- (docstring-narrow-to-location track-location)
- (docstring-narrow-to-location snarf-location)
- (docstring-narrow-to-location manual-location)
-
- (add-hook 'ediff-quit-hook 'docstring-widen-ediff-buffers)
-
- (ediff-buffers3 (nth 0 docstring-ediff-buffers)
- (nth 1 docstring-ediff-buffers)
- (nth 2 docstring-ediff-buffers)))))
-
-(defun docstring-narrow-to-location (location)
- (save-excursion
- (set-buffer (car location))
- (narrow-to-region (cadr location) (caddr location))))
-
-(defun docstring-temp-location (str)
- (let ((buf (generate-new-buffer "*Docstring Temp*")))
- (save-excursion
- (set-buffer buf)
- (erase-buffer)
- (insert str "\n")
- (list buf (point-min) (point-max)))))
-
-(require 'ediff)
-
-(defvar docstring-ediff-buffers '())
-
-(defun docstring-widen-ediff-buffers ()
- (remove-hook 'ediff-quit-hook 'docstring-widen-ediff-buffers)
- (save-excursion
- (mapcar (function (lambda (buffer)
- (set-buffer buffer)
- (widen)))
- docstring-ediff-buffers)))
-
-
-;;; Tests:
-
-;(find-docstring "/home/neil/Guile/cvs/guile-core/doc/maint/guile.texi" nil "primitive sloppy-assq")
-;(find-manual-docstring '(guile) "primitive sloppy-assq")
-;(find-tracking-docstring '(guile) "primitive sloppy-assq")
-;(find-snarfed-docstring '(guile) "primitive sloppy-assq")
-
-(defvar docstring-libguile-directory (expand-file-name "libguile"
- guile-core-dir)
- "*The directory containing the C source for libguile.")
-
-(defvar docstring-libguile-build-directory (expand-file-name "libguile"
- guile-build-dir)
- "*The directory containing the libguile build directory.")
-
-(defun docstring-display-location (file line)
- (let ((buffer (find-file-noselect
- (expand-file-name file docstring-libguile-directory))))
- (if buffer
- (let* ((window (or (get-buffer-window buffer)
- (display-buffer buffer)))
- (pos (save-excursion
- (set-buffer buffer)
- (goto-line line)
- (point))))
- (set-window-point window pos)))))
-
-(defun docstring-show-source ()
- "Given that point is sitting in a docstring in one of the Texinfo
-source files for the Guile manual, and that that docstring may be
-snarfed automatically from a libguile C file, determine whether the
-docstring is from libguile and, if it is, display the relevant C file
-at the line from which the docstring was snarfed.
-
-Why? When updating snarfed docstrings, you should usually edit the C
-source rather than the Texinfo source, so that your updates benefit
-Guile's online help as well. This function locates the C source for a
-docstring so that it is easy for you to do this."
- (interactive)
- (let* ((deffn-line
- (save-excursion
- (end-of-line)
- (or (re-search-backward "^@deffn " nil t)
- (error "No docstring here!"))
- (buffer-substring (point)
- (progn
- (end-of-line)
- (point)))))
- (guile-texi-file
- (expand-file-name "guile.texi" docstring-libguile-build-directory))
- (source-location
- (save-excursion
- (set-buffer (find-file-noselect guile-texi-file))
- (save-excursion
- (goto-char (point-min))
- (or (re-search-forward (concat "^"
- (regexp-quote deffn-line)
- "$")
- nil t)
- (error "Docstring not from libguile"))
- (forward-line -1)
- (if (looking-at "^@c snarfed from \\([^:]+\\):\\([0-9]+\\)$")
- (cons (match-string 1)
- (string-to-int (match-string 2)))
- (error "Corrupt docstring entry in guile.texi"))))))
- (docstring-display-location (car source-location)
- (cdr source-location))))
-
-
-(provide 'docstring)
-
-;;; docstring.el ends here
diff --git a/doc/maint/guile.texi b/doc/maint/guile.texi
deleted file mode 100644
index fa8125594..000000000
--- a/doc/maint/guile.texi
+++ /dev/null
@@ -1,7846 +0,0 @@
-
- acons
-@c snarfed from /home/ghouston/guile/guile-core/libguile/alist.c:59
-@deffn {Scheme Procedure} acons key value alist
-@deffnx {C Function} scm_acons (key, value, alist)
-Add a new key-value pair to @var{alist}. A new pair is
-created whose car is @var{key} and whose cdr is @var{value}, and the
-pair is consed onto @var{alist}, and the new list is returned. This
-function is @emph{not} destructive; @var{alist} is not modified.
-@end deffn
-
- sloppy-assq
-@c snarfed from /home/ghouston/guile/guile-core/libguile/alist.c:73
-@deffn {Scheme Procedure} sloppy-assq key alist
-@deffnx {C Function} scm_sloppy_assq (key, alist)
-Behaves like @code{assq} but does not do any error checking.
-Recommended only for use in Guile internals.
-@end deffn
-
- sloppy-assv
-@c snarfed from /home/ghouston/guile/guile-core/libguile/alist.c:91
-@deffn {Scheme Procedure} sloppy-assv key alist
-@deffnx {C Function} scm_sloppy_assv (key, alist)
-Behaves like @code{assv} but does not do any error checking.
-Recommended only for use in Guile internals.
-@end deffn
-
- sloppy-assoc
-@c snarfed from /home/ghouston/guile/guile-core/libguile/alist.c:109
-@deffn {Scheme Procedure} sloppy-assoc key alist
-@deffnx {C Function} scm_sloppy_assoc (key, alist)
-Behaves like @code{assoc} but does not do any error checking.
-Recommended only for use in Guile internals.
-@end deffn
-
- assq
-@c snarfed from /home/ghouston/guile/guile-core/libguile/alist.c:136
-@deffn {Scheme Procedure} assq key alist
-@deffnx {Scheme Procedure} assv key alist
-@deffnx {Scheme Procedure} assoc key alist
-@deffnx {C Function} scm_assq (key, alist)
-Fetch the entry in @var{alist} that is associated with @var{key}. To
-decide whether the argument @var{key} matches a particular entry in
-@var{alist}, @code{assq} compares keys with @code{eq?}, @code{assv}
-uses @code{eqv?} and @code{assoc} uses @code{equal?}. If @var{key}
-cannot be found in @var{alist} (according to whichever equality
-predicate is in use), then return @code{#f}. These functions
-return the entire alist entry found (i.e. both the key and the value).
-@end deffn
-
- assv
-@c snarfed from /home/ghouston/guile/guile-core/libguile/alist.c:157
-@deffn {Scheme Procedure} assv key alist
-@deffnx {C Function} scm_assv (key, alist)
-Behaves like @code{assq} but uses @code{eqv?} for key comparison.
-@end deffn
-
- assoc
-@c snarfed from /home/ghouston/guile/guile-core/libguile/alist.c:178
-@deffn {Scheme Procedure} assoc key alist
-@deffnx {C Function} scm_assoc (key, alist)
-Behaves like @code{assq} but uses @code{equal?} for key comparison.
-@end deffn
-
- assq-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/alist.c:222
-@deffn {Scheme Procedure} assq-ref alist key
-@deffnx {Scheme Procedure} assv-ref alist key
-@deffnx {Scheme Procedure} assoc-ref alist key
-@deffnx {C Function} scm_assq_ref (alist, key)
-Like @code{assq}, @code{assv} and @code{assoc}, except that only the
-value associated with @var{key} in @var{alist} is returned. These
-functions are equivalent to
-
-@lisp
-(let ((ent (@var{associator} @var{key} @var{alist})))
- (and ent (cdr ent)))
-@end lisp
-
-where @var{associator} is one of @code{assq}, @code{assv} or @code{assoc}.
-@end deffn
-
- assv-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/alist.c:239
-@deffn {Scheme Procedure} assv-ref alist key
-@deffnx {C Function} scm_assv_ref (alist, key)
-Behaves like @code{assq-ref} but uses @code{eqv?} for key comparison.
-@end deffn
-
- assoc-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/alist.c:256
-@deffn {Scheme Procedure} assoc-ref alist key
-@deffnx {C Function} scm_assoc_ref (alist, key)
-Behaves like @code{assq-ref} but uses @code{equal?} for key comparison.
-@end deffn
-
- assq-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/alist.c:285
-@deffn {Scheme Procedure} assq-set! alist key val
-@deffnx {Scheme Procedure} assv-set! alist key value
-@deffnx {Scheme Procedure} assoc-set! alist key value
-@deffnx {C Function} scm_assq_set_x (alist, key, val)
-Reassociate @var{key} in @var{alist} with @var{value}: find any existing
-@var{alist} entry for @var{key} and associate it with the new
-@var{value}. If @var{alist} does not contain an entry for @var{key},
-add a new one. Return the (possibly new) alist.
-
-These functions do not attempt to verify the structure of @var{alist},
-and so may cause unusual results if passed an object that is not an
-association list.
-@end deffn
-
- assv-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/alist.c:303
-@deffn {Scheme Procedure} assv-set! alist key val
-@deffnx {C Function} scm_assv_set_x (alist, key, val)
-Behaves like @code{assq-set!} but uses @code{eqv?} for key comparison.
-@end deffn
-
- assoc-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/alist.c:321
-@deffn {Scheme Procedure} assoc-set! alist key val
-@deffnx {C Function} scm_assoc_set_x (alist, key, val)
-Behaves like @code{assq-set!} but uses @code{equal?} for key comparison.
-@end deffn
-
- assq-remove!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/alist.c:345
-@deffn {Scheme Procedure} assq-remove! alist key
-@deffnx {Scheme Procedure} assv-remove! alist key
-@deffnx {Scheme Procedure} assoc-remove! alist key
-@deffnx {C Function} scm_assq_remove_x (alist, key)
-Delete the first entry in @var{alist} associated with @var{key}, and return
-the resulting alist.
-@end deffn
-
- assv-remove!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/alist.c:361
-@deffn {Scheme Procedure} assv-remove! alist key
-@deffnx {C Function} scm_assv_remove_x (alist, key)
-Behaves like @code{assq-remove!} but uses @code{eqv?} for key comparison.
-@end deffn
-
- assoc-remove!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/alist.c:377
-@deffn {Scheme Procedure} assoc-remove! alist key
-@deffnx {C Function} scm_assoc_remove_x (alist, key)
-Behaves like @code{assq-remove!} but uses @code{equal?} for key comparison.
-@end deffn
-
- make-arbiter
-@c snarfed from /home/ghouston/guile/guile-core/libguile/arbiters.c:82
-@deffn {Scheme Procedure} make-arbiter name
-@deffnx {C Function} scm_make_arbiter (name)
-Return an object of type arbiter and name @var{name}. Its
-state is initially unlocked. Arbiters are a way to achieve
-process synchronization.
-@end deffn
-
- try-arbiter
-@c snarfed from /home/ghouston/guile/guile-core/libguile/arbiters.c:92
-@deffn {Scheme Procedure} try-arbiter arb
-@deffnx {C Function} scm_try_arbiter (arb)
-Return @code{#t} and lock the arbiter @var{arb} if the arbiter
-was unlocked. Otherwise, return @code{#f}.
-@end deffn
-
- release-arbiter
-@c snarfed from /home/ghouston/guile/guile-core/libguile/arbiters.c:113
-@deffn {Scheme Procedure} release-arbiter arb
-@deffnx {C Function} scm_release_arbiter (arb)
-Return @code{#t} and unlock the arbiter @var{arb} if the
-arbiter was locked. Otherwise, return @code{#f}.
-@end deffn
-
- async
-@c snarfed from /home/ghouston/guile/guile-core/libguile/async.c:289
-@deffn {Scheme Procedure} async thunk
-@deffnx {C Function} scm_async (thunk)
-Create a new async for the procedure @var{thunk}.
-@end deffn
-
- system-async
-@c snarfed from /home/ghouston/guile/guile-core/libguile/async.c:299
-@deffn {Scheme Procedure} system-async thunk
-@deffnx {C Function} scm_system_async (thunk)
-Create a new async for the procedure @var{thunk}. Also
-add it to the system's list of active async objects.
-@end deffn
-
- async-mark
-@c snarfed from /home/ghouston/guile/guile-core/libguile/async.c:310
-@deffn {Scheme Procedure} async-mark a
-@deffnx {C Function} scm_async_mark (a)
-Mark the async @var{a} for future execution.
-@end deffn
-
- system-async-mark
-@c snarfed from /home/ghouston/guile/guile-core/libguile/async.c:326
-@deffn {Scheme Procedure} system-async-mark a
-@deffnx {C Function} scm_system_async_mark (a)
-Mark the async @var{a} for future execution.
-@end deffn
-
- run-asyncs
-@c snarfed from /home/ghouston/guile/guile-core/libguile/async.c:351
-@deffn {Scheme Procedure} run-asyncs list_of_a
-@deffnx {C Function} scm_run_asyncs (list_of_a)
-Execute all thunks from the asyncs of the list @var{list_of_a}.
-@end deffn
-
- noop
-@c snarfed from /home/ghouston/guile/guile-core/libguile/async.c:385
-@deffn {Scheme Procedure} noop . args
-@deffnx {C Function} scm_noop (args)
-Do nothing. When called without arguments, return @code{#f},
-otherwise return the first argument.
-@end deffn
-
- unmask-signals
-@c snarfed from /home/ghouston/guile/guile-core/libguile/async.c:437
-@deffn {Scheme Procedure} unmask-signals
-@deffnx {C Function} scm_unmask_signals ()
-Unmask signals. The returned value is not specified.
-@end deffn
-
- mask-signals
-@c snarfed from /home/ghouston/guile/guile-core/libguile/async.c:448
-@deffn {Scheme Procedure} mask-signals
-@deffnx {C Function} scm_mask_signals ()
-Mask signals. The returned value is not specified.
-@end deffn
-
- display-error
-@c snarfed from /home/ghouston/guile/guile-core/libguile/backtrace.c:264
-@deffn {Scheme Procedure} display-error stack port subr message args rest
-@deffnx {C Function} scm_display_error (stack, port, subr, message, args, rest)
-Display an error message to the output port @var{port}.
-@var{stack} is the saved stack for the error, @var{subr} is
-the name of the procedure in which the error occurred and
-@var{message} is the actual error message, which may contain
-formatting instructions. These will format the arguments in
-the list @var{args} accordingly. @var{rest} is currently
-ignored.
-@end deffn
-
- display-application
-@c snarfed from /home/ghouston/guile/guile-core/libguile/backtrace.c:400
-@deffn {Scheme Procedure} display-application frame [port [indent]]
-@deffnx {C Function} scm_display_application (frame, port, indent)
-Display a procedure application @var{frame} to the output port
-@var{port}. @var{indent} specifies the indentation of the
-output.
-@end deffn
-
- display-backtrace
-@c snarfed from /home/ghouston/guile/guile-core/libguile/backtrace.c:711
-@deffn {Scheme Procedure} display-backtrace stack port [first [depth]]
-@deffnx {C Function} scm_display_backtrace (stack, port, first, depth)
-Display a backtrace to the output port @var{port}. @var{stack}
-is the stack to take the backtrace from, @var{first} specifies
-where in the stack to start and @var{depth} how much frames
-to display. Both @var{first} and @var{depth} can be @code{#f},
-which means that default values will be used.
-@end deffn
-
- backtrace
-@c snarfed from /home/ghouston/guile/guile-core/libguile/backtrace.c:734
-@deffn {Scheme Procedure} backtrace
-@deffnx {C Function} scm_backtrace ()
-Display a backtrace of the stack saved by the last error
-to the current output port.
-@end deffn
-
- not
-@c snarfed from /home/ghouston/guile/guile-core/libguile/boolean.c:55
-@deffn {Scheme Procedure} not x
-@deffnx {C Function} scm_not (x)
-Return @code{#t} iff @var{x} is @code{#f}, else return @code{#f}.
-@end deffn
-
- boolean?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/boolean.c:65
-@deffn {Scheme Procedure} boolean? obj
-@deffnx {C Function} scm_boolean_p (obj)
-Return @code{#t} iff @var{obj} is either @code{#t} or @code{#f}.
-@end deffn
-
- char?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:54
-@deffn {Scheme Procedure} char? x
-@deffnx {C Function} scm_char_p (x)
-Return @code{#t} iff @var{x} is a character, else @code{#f}.
-@end deffn
-
- char=?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:63
-@deffn {Scheme Procedure} char=? x y
-Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}.
-@end deffn
-
- char<?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:76
-@deffn {Scheme Procedure} char<? x y
-Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence,
-else @code{#f}.
-@end deffn
-
- char<=?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:88
-@deffn {Scheme Procedure} char<=? x y
-Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
-ASCII sequence, else @code{#f}.
-@end deffn
-
- char>?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:100
-@deffn {Scheme Procedure} char>? x y
-Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
-sequence, else @code{#f}.
-@end deffn
-
- char>=?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:112
-@deffn {Scheme Procedure} char>=? x y
-Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
-ASCII sequence, else @code{#f}.
-@end deffn
-
- char-ci=?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:124
-@deffn {Scheme Procedure} char-ci=? x y
-Return @code{#t} iff @var{x} is the same character as @var{y} ignoring
-case, else @code{#f}.
-@end deffn
-
- char-ci<?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:136
-@deffn {Scheme Procedure} char-ci<? x y
-Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence
-ignoring case, else @code{#f}.
-@end deffn
-
- char-ci<=?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:148
-@deffn {Scheme Procedure} char-ci<=? x y
-Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
-ASCII sequence ignoring case, else @code{#f}.
-@end deffn
-
- char-ci>?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:160
-@deffn {Scheme Procedure} char-ci>? x y
-Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
-sequence ignoring case, else @code{#f}.
-@end deffn
-
- char-ci>=?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:172
-@deffn {Scheme Procedure} char-ci>=? x y
-Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
-ASCII sequence ignoring case, else @code{#f}.
-@end deffn
-
- char-alphabetic?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:185
-@deffn {Scheme Procedure} char-alphabetic? chr
-@deffnx {C Function} scm_char_alphabetic_p (chr)
-Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
-Alphabetic means the same thing as the isalpha C library function.
-@end deffn
-
- char-numeric?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:196
-@deffn {Scheme Procedure} char-numeric? chr
-@deffnx {C Function} scm_char_numeric_p (chr)
-Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
-Numeric means the same thing as the isdigit C library function.
-@end deffn
-
- char-whitespace?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:207
-@deffn {Scheme Procedure} char-whitespace? chr
-@deffnx {C Function} scm_char_whitespace_p (chr)
-Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
-Whitespace means the same thing as the isspace C library function.
-@end deffn
-
- char-upper-case?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:220
-@deffn {Scheme Procedure} char-upper-case? chr
-@deffnx {C Function} scm_char_upper_case_p (chr)
-Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
-Uppercase means the same thing as the isupper C library function.
-@end deffn
-
- char-lower-case?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:232
-@deffn {Scheme Procedure} char-lower-case? chr
-@deffnx {C Function} scm_char_lower_case_p (chr)
-Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
-Lowercase means the same thing as the islower C library function.
-@end deffn
-
- char-is-both?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:246
-@deffn {Scheme Procedure} char-is-both? chr
-@deffnx {C Function} scm_char_is_both_p (chr)
-Return @code{#t} iff @var{chr} is either uppercase or lowercase, else @code{#f}.
-Uppercase and lowercase are as defined by the isupper and islower
-C library functions.
-@end deffn
-
- char->integer
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:260
-@deffn {Scheme Procedure} char->integer chr
-@deffnx {C Function} scm_char_to_integer (chr)
-Return the number corresponding to ordinal position of @var{chr} in the
-ASCII sequence.
-@end deffn
-
- integer->char
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:272
-@deffn {Scheme Procedure} integer->char n
-@deffnx {C Function} scm_integer_to_char (n)
-Return the character at position @var{n} in the ASCII sequence.
-@end deffn
-
- char-upcase
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:283
-@deffn {Scheme Procedure} char-upcase chr
-@deffnx {C Function} scm_char_upcase (chr)
-Return the uppercase character version of @var{chr}.
-@end deffn
-
- char-downcase
-@c snarfed from /home/ghouston/guile/guile-core/libguile/chars.c:294
-@deffn {Scheme Procedure} char-downcase chr
-@deffnx {C Function} scm_char_downcase (chr)
-Return the lowercase character version of @var{chr}.
-@end deffn
-
- debug-options-interface
-@c snarfed from /home/ghouston/guile/guile-core/libguile/debug.c:79
-@deffn {Scheme Procedure} debug-options-interface [setting]
-@deffnx {C Function} scm_debug_options (setting)
-Option interface for the debug options. Instead of using
-this procedure directly, use the procedures @code{debug-enable},
-@code{debug-disable}, @code{debug-set!} and @code{debug-options}.
-@end deffn
-
- with-traps
-@c snarfed from /home/ghouston/guile/guile-core/libguile/debug.c:122
-@deffn {Scheme Procedure} with-traps thunk
-@deffnx {C Function} scm_with_traps (thunk)
-Call @var{thunk} with traps enabled.
-@end deffn
-
- memoized?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/debug.c:164
-@deffn {Scheme Procedure} memoized? obj
-@deffnx {C Function} scm_memoized_p (obj)
-Return @code{#t} if @var{obj} is memoized.
-@end deffn
-
- unmemoize
-@c snarfed from /home/ghouston/guile/guile-core/libguile/debug.c:328
-@deffn {Scheme Procedure} unmemoize m
-@deffnx {C Function} scm_unmemoize (m)
-Unmemoize the memoized expression @var{m},
-@end deffn
-
- memoized-environment
-@c snarfed from /home/ghouston/guile/guile-core/libguile/debug.c:338
-@deffn {Scheme Procedure} memoized-environment m
-@deffnx {C Function} scm_memoized_environment (m)
-Return the environment of the memoized expression @var{m}.
-@end deffn
-
- procedure-name
-@c snarfed from /home/ghouston/guile/guile-core/libguile/debug.c:348
-@deffn {Scheme Procedure} procedure-name proc
-@deffnx {C Function} scm_procedure_name (proc)
-Return the name of the procedure @var{proc}
-@end deffn
-
- procedure-source
-@c snarfed from /home/ghouston/guile/guile-core/libguile/debug.c:374
-@deffn {Scheme Procedure} procedure-source proc
-@deffnx {C Function} scm_procedure_source (proc)
-Return the source of the procedure @var{proc}.
-@end deffn
-
- procedure-environment
-@c snarfed from /home/ghouston/guile/guile-core/libguile/debug.c:407
-@deffn {Scheme Procedure} procedure-environment proc
-@deffnx {C Function} scm_procedure_environment (proc)
-Return the environment of the procedure @var{proc}.
-@end deffn
-
- local-eval
-@c snarfed from /home/ghouston/guile/guile-core/libguile/debug.c:439
-@deffn {Scheme Procedure} local-eval exp [env]
-@deffnx {C Function} scm_local_eval (exp, env)
-Evaluate @var{exp} in its environment. If @var{env} is supplied,
-it is the environment in which to evaluate @var{exp}. Otherwise,
-@var{exp} must be a memoized code object (in which case, its environment
-is implicit).
-@end deffn
-
- debug-object?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/debug.c:526
-@deffn {Scheme Procedure} debug-object? obj
-@deffnx {C Function} scm_debug_object_p (obj)
-Return @code{#t} if @var{obj} is a debug object.
-@end deffn
-
- dynamic-link
-@c snarfed from /home/ghouston/guile/guile-core/libguile/dynl.c:212
-@deffn {Scheme Procedure} dynamic-link filename
-@deffnx {C Function} scm_dynamic_link (filename)
-Find the shared object (shared library) denoted by
-@var{filename} and link it into the running Guile
-application. The returned
-scheme object is a ``handle'' for the library which can
-be passed to @code{dynamic-func}, @code{dynamic-call} etc.
-
-Searching for object files is system dependent. Normally,
-if @var{filename} does have an explicit directory it will
-be searched for in locations
-such as @file{/usr/lib} and @file{/usr/local/lib}.
-@end deffn
-
- dynamic-object?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/dynl.c:227
-@deffn {Scheme Procedure} dynamic-object? obj
-@deffnx {C Function} scm_dynamic_object_p (obj)
-Return @code{#t} if @var{obj} is a dynamic object handle,
-or @code{#f} otherwise.
-@end deffn
-
- dynamic-unlink
-@c snarfed from /home/ghouston/guile/guile-core/libguile/dynl.c:241
-@deffn {Scheme Procedure} dynamic-unlink dobj
-@deffnx {C Function} scm_dynamic_unlink (dobj)
-Unlink a dynamic object from the application, if possible. The
-object must have been linked by @code{dynamic-link}, with
-@var{dobj} the corresponding handle. After this procedure
-is called, the handle can no longer be used to access the
-object.
-@end deffn
-
- dynamic-func
-@c snarfed from /home/ghouston/guile/guile-core/libguile/dynl.c:266
-@deffn {Scheme Procedure} dynamic-func name dobj
-@deffnx {C Function} scm_dynamic_func (name, dobj)
-Return a ``handle'' for the function @var{name} in the
-shared object referred to by @var{dobj}. The handle
-can be passed to @code{dynamic-call} to actually
-call the function.
-
-Regardless whether your C compiler prepends an underscore
-@samp{_} to the global names in a program, you should
-@strong{not} include this underscore in @var{name}
-since it will be added automatically when necessary.
-@end deffn
-
- dynamic-call
-@c snarfed from /home/ghouston/guile/guile-core/libguile/dynl.c:308
-@deffn {Scheme Procedure} dynamic-call func dobj
-@deffnx {C Function} scm_dynamic_call (func, dobj)
-Call a C function in a dynamic object. Two styles of
-invocation are supported:
-
-@itemize @bullet
-@item @var{func} can be a function handle returned by
-@code{dynamic-func}. In this case @var{dobj} is
-ignored
-@item @var{func} can be a string with the name of the
-function to call, with @var{dobj} the handle of the
-dynamic object in which to find the function.
-This is equivalent to
-@smallexample
-
-(dynamic-call (dynamic-func @var{func} @var{dobj}) #f)
-@end smallexample
-@end itemize
-
-In either case, the function is passed no arguments
-and its return value is ignored.
-@end deffn
-
- dynamic-args-call
-@c snarfed from /home/ghouston/guile/guile-core/libguile/dynl.c:363
-@deffn {Scheme Procedure} dynamic-args-call func dobj args
-@deffnx {C Function} scm_dynamic_args_call (func, dobj, args)
-Call the C function indicated by @var{func} and @var{dobj},
-just like @code{dynamic-call}, but pass it some arguments and
-return its return value. The C function is expected to take
-two arguments and return an @code{int}, just like @code{main}:
-@smallexample
-int c_func (int argc, char **argv);
-@end smallexample
-
-The parameter @var{args} must be a list of strings and is
-converted into an array of @code{char *}. The array is passed
-in @var{argv} and its size in @var{argc}. The return value is
-converted to a Scheme number and returned from the call to
-@code{dynamic-args-call}.
-@end deffn
-
- dynamic-wind
-@c snarfed from /home/ghouston/guile/guile-core/libguile/dynwind.c:119
-@deffn {Scheme Procedure} dynamic-wind in_guard thunk out_guard
-@deffnx {C Function} scm_dynamic_wind (in_guard, thunk, out_guard)
-All three arguments must be 0-argument procedures.
-@var{in_guard} is called, then @var{thunk}, then
-@var{out_guard}.
-
-If, any time during the execution of @var{thunk}, the
-continuation of the @code{dynamic_wind} expression is escaped
-non-locally, @var{out_guard} is called. If the continuation of
-the dynamic-wind is re-entered, @var{in_guard} is called. Thus
-@var{in_guard} and @var{out_guard} may be called any number of
-times.
-@lisp
-(define x 'normal-binding)
-@result{} x
-(define a-cont (call-with-current-continuation
- (lambda (escape)
- (let ((old-x x))
- (dynamic-wind
- ;; in-guard:
- ;;
- (lambda () (set! x 'special-binding))
-
- ;; thunk
- ;;
- (lambda () (display x) (newline)
- (call-with-current-continuation escape)
- (display x) (newline)
- x)
-
- ;; out-guard:
- ;;
- (lambda () (set! x old-x)))))))
-
-;; Prints:
-special-binding
-;; Evaluates to:
-@result{} a-cont
-x
-@result{} normal-binding
-(a-cont #f)
-;; Prints:
-special-binding
-;; Evaluates to:
-@result{} a-cont ;; the value of the (define a-cont...)
-x
-@result{} normal-binding
-a-cont
-@result{} special-binding
-@end lisp
-@end deffn
-
- environment?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:129
-@deffn {Scheme Procedure} environment? obj
-@deffnx {C Function} scm_environment_p (obj)
-Return @code{#t} if @var{obj} is an environment, or @code{#f}
-otherwise.
-@end deffn
-
- environment-bound?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:140
-@deffn {Scheme Procedure} environment-bound? env sym
-@deffnx {C Function} scm_environment_bound_p (env, sym)
-Return @code{#t} if @var{sym} is bound in @var{env}, or
-@code{#f} otherwise.
-@end deffn
-
- environment-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:155
-@deffn {Scheme Procedure} environment-ref env sym
-@deffnx {C Function} scm_environment_ref (env, sym)
-Return the value of the location bound to @var{sym} in
-@var{env}. If @var{sym} is unbound in @var{env}, signal an
-@code{environment:unbound} error.
-@end deffn
-
- environment-fold
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:225
-@deffn {Scheme Procedure} environment-fold env proc init
-@deffnx {C Function} scm_environment_fold (env, proc, init)
-Iterate over all the bindings in @var{env}, accumulating some
-value.
-For each binding in @var{env}, apply @var{proc} to the symbol
-bound, its value, and the result from the previous application
-of @var{proc}.
-Use @var{init} as @var{proc}'s third argument the first time
-@var{proc} is applied.
-If @var{env} contains no bindings, this function simply returns
-@var{init}.
-If @var{env} binds the symbol sym1 to the value val1, sym2 to
-val2, and so on, then this procedure computes:
-@lisp
- (proc sym1 val1
- (proc sym2 val2
- ...
- (proc symn valn
- init)))
-@end lisp
-Each binding in @var{env} will be processed exactly once.
-@code{environment-fold} makes no guarantees about the order in
-which the bindings are processed.
-Here is a function which, given an environment, constructs an
-association list representing that environment's bindings,
-using environment-fold:
-@lisp
- (define (environment->alist env)
- (environment-fold env
- (lambda (sym val tail)
- (cons (cons sym val) tail))
- '()))
-@end lisp
-@end deffn
-
- environment-define
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:260
-@deffn {Scheme Procedure} environment-define env sym val
-@deffnx {C Function} scm_environment_define (env, sym, val)
-Bind @var{sym} to a new location containing @var{val} in
-@var{env}. If @var{sym} is already bound to another location
-in @var{env} and the binding is mutable, that binding is
-replaced. The new binding and location are both mutable. The
-return value is unspecified.
-If @var{sym} is already bound in @var{env}, and the binding is
-immutable, signal an @code{environment:immutable-binding} error.
-@end deffn
-
- environment-undefine
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:286
-@deffn {Scheme Procedure} environment-undefine env sym
-@deffnx {C Function} scm_environment_undefine (env, sym)
-Remove any binding for @var{sym} from @var{env}. If @var{sym}
-is unbound in @var{env}, do nothing. The return value is
-unspecified.
-If @var{sym} is already bound in @var{env}, and the binding is
-immutable, signal an @code{environment:immutable-binding} error.
-@end deffn
-
- environment-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:314
-@deffn {Scheme Procedure} environment-set! env sym val
-@deffnx {C Function} scm_environment_set_x (env, sym, val)
-If @var{env} binds @var{sym} to some location, change that
-location's value to @var{val}. The return value is
-unspecified.
-If @var{sym} is not bound in @var{env}, signal an
-@code{environment:unbound} error. If @var{env} binds @var{sym}
-to an immutable location, signal an
-@code{environment:immutable-location} error.
-@end deffn
-
- environment-cell
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:349
-@deffn {Scheme Procedure} environment-cell env sym for_write
-@deffnx {C Function} scm_environment_cell (env, sym, for_write)
-Return the value cell which @var{env} binds to @var{sym}, or
-@code{#f} if the binding does not live in a value cell.
-The argument @var{for-write} indicates whether the caller
-intends to modify the variable's value by mutating the value
-cell. If the variable is immutable, then
-@code{environment-cell} signals an
-@code{environment:immutable-location} error.
-If @var{sym} is unbound in @var{env}, signal an
-@code{environment:unbound} error.
-If you use this function, you should consider using
-@code{environment-observe}, to be notified when @var{sym} gets
-re-bound to a new value cell, or becomes undefined.
-@end deffn
-
- environment-observe
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:401
-@deffn {Scheme Procedure} environment-observe env proc
-@deffnx {C Function} scm_environment_observe (env, proc)
-Whenever @var{env}'s bindings change, apply @var{proc} to
-@var{env}.
-This function returns an object, token, which you can pass to
-@code{environment-unobserve} to remove @var{proc} from the set
-of procedures observing @var{env}. The type and value of
-token is unspecified.
-@end deffn
-
- environment-observe-weak
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:418
-@deffn {Scheme Procedure} environment-observe-weak env proc
-@deffnx {C Function} scm_environment_observe_weak (env, proc)
-This function is the same as environment-observe, except that
-the reference @var{env} retains to @var{proc} is a weak
-reference. This means that, if there are no other live,
-non-weak references to @var{proc}, it will be
-garbage-collected, and dropped from @var{env}'s
-list of observing procedures.
-@end deffn
-
- environment-unobserve
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:454
-@deffn {Scheme Procedure} environment-unobserve token
-@deffnx {C Function} scm_environment_unobserve (token)
-Cancel the observation request which returned the value
-@var{token}. The return value is unspecified.
-If a call @code{(environment-observe env proc)} returns
-@var{token}, then the call @code{(environment-unobserve token)}
-will cause @var{proc} to no longer be called when @var{env}'s
-bindings change.
-@end deffn
-
- make-leaf-environment
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:1031
-@deffn {Scheme Procedure} make-leaf-environment
-@deffnx {C Function} scm_make_leaf_environment ()
-Create a new leaf environment, containing no bindings.
-All bindings and locations created in the new environment
-will be mutable.
-@end deffn
-
- leaf-environment?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:1054
-@deffn {Scheme Procedure} leaf-environment? object
-@deffnx {C Function} scm_leaf_environment_p (object)
-Return @code{#t} if object is a leaf environment, or @code{#f}
-otherwise.
-@end deffn
-
- make-eval-environment
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:1419
-@deffn {Scheme Procedure} make-eval-environment local imported
-@deffnx {C Function} scm_make_eval_environment (local, imported)
-Return a new environment object eval whose bindings are the
-union of the bindings in the environments @var{local} and
-@var{imported}, with bindings from @var{local} taking
-precedence. Definitions made in eval are placed in @var{local}.
-Applying @code{environment-define} or
-@code{environment-undefine} to eval has the same effect as
-applying the procedure to @var{local}.
-Note that eval incorporates @var{local} and @var{imported} by
-reference:
-If, after creating eval, the program changes the bindings of
-@var{local} or @var{imported}, those changes will be visible
-in eval.
-Since most Scheme evaluation takes place in eval environments,
-they transparently cache the bindings received from @var{local}
-and @var{imported}. Thus, the first time the program looks up
-a symbol in eval, eval may make calls to @var{local} or
-@var{imported} to find their bindings, but subsequent
-references to that symbol will be as fast as references to
-bindings in finite environments.
-In typical use, @var{local} will be a finite environment, and
-@var{imported} will be an import environment
-@end deffn
-
- eval-environment?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:1456
-@deffn {Scheme Procedure} eval-environment? object
-@deffnx {C Function} scm_eval_environment_p (object)
-Return @code{#t} if object is an eval environment, or @code{#f}
-otherwise.
-@end deffn
-
- eval-environment-local
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:1466
-@deffn {Scheme Procedure} eval-environment-local env
-@deffnx {C Function} scm_eval_environment_local (env)
-Return the local environment of eval environment @var{env}.
-@end deffn
-
- eval-environment-set-local!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:1478
-@deffn {Scheme Procedure} eval-environment-set-local! env local
-@deffnx {C Function} scm_eval_environment_set_local_x (env, local)
-Change @var{env}'s local environment to @var{local}.
-@end deffn
-
- eval-environment-imported
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:1504
-@deffn {Scheme Procedure} eval-environment-imported env
-@deffnx {C Function} scm_eval_environment_imported (env)
-Return the imported environment of eval environment @var{env}.
-@end deffn
-
- eval-environment-set-imported!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:1516
-@deffn {Scheme Procedure} eval-environment-set-imported! env imported
-@deffnx {C Function} scm_eval_environment_set_imported_x (env, imported)
-Change @var{env}'s imported environment to @var{imported}.
-@end deffn
-
- make-import-environment
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:1839
-@deffn {Scheme Procedure} make-import-environment imports conflict_proc
-@deffnx {C Function} scm_make_import_environment (imports, conflict_proc)
-Return a new environment @var{imp} whose bindings are the union
-of the bindings from the environments in @var{imports};
-@var{imports} must be a list of environments. That is,
-@var{imp} binds a symbol to a location when some element of
-@var{imports} does.
-If two different elements of @var{imports} have a binding for
-the same symbol, the @var{conflict-proc} is called with the
-following parameters: the import environment, the symbol and
-the list of the imported environments that bind the symbol.
-If the @var{conflict-proc} returns an environment @var{env},
-the conflict is considered as resolved and the binding from
-@var{env} is used. If the @var{conflict-proc} returns some
-non-environment object, the conflict is considered unresolved
-and the symbol is treated as unspecified in the import
-environment.
-The checking for conflicts may be performed lazily, i. e. at
-the moment when a value or binding for a certain symbol is
-requested instead of the moment when the environment is
-created or the bindings of the imports change.
-All bindings in @var{imp} are immutable. If you apply
-@code{environment-define} or @code{environment-undefine} to
-@var{imp}, Guile will signal an
- @code{environment:immutable-binding} error. However,
-notice that the set of bindings in @var{imp} may still change,
-if one of its imported environments changes.
-@end deffn
-
- import-environment?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:1868
-@deffn {Scheme Procedure} import-environment? object
-@deffnx {C Function} scm_import_environment_p (object)
-Return @code{#t} if object is an import environment, or
-@code{#f} otherwise.
-@end deffn
-
- import-environment-imports
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:1879
-@deffn {Scheme Procedure} import-environment-imports env
-@deffnx {C Function} scm_import_environment_imports (env)
-Return the list of environments imported by the import
-environment @var{env}.
-@end deffn
-
- import-environment-set-imports!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:1892
-@deffn {Scheme Procedure} import-environment-set-imports! env imports
-@deffnx {C Function} scm_import_environment_set_imports_x (env, imports)
-Change @var{env}'s list of imported environments to
-@var{imports}, and check for conflicts.
-@end deffn
-
- make-export-environment
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:2159
-@deffn {Scheme Procedure} make-export-environment private signature
-@deffnx {C Function} scm_make_export_environment (private, signature)
-Return a new environment @var{exp} containing only those
-bindings in private whose symbols are present in
-@var{signature}. The @var{private} argument must be an
-environment.
-
-The environment @var{exp} binds symbol to location when
-@var{env} does, and symbol is exported by @var{signature}.
-
-@var{signature} is a list specifying which of the bindings in
-@var{private} should be visible in @var{exp}. Each element of
-@var{signature} should be a list of the form:
- (symbol attribute ...)
-where each attribute is one of the following:
-@table @asis
-@item the symbol @code{mutable-location}
- @var{exp} should treat the
- location bound to symbol as mutable. That is, @var{exp}
- will pass calls to @code{environment-set!} or
- @code{environment-cell} directly through to private.
-@item the symbol @code{immutable-location}
- @var{exp} should treat
- the location bound to symbol as immutable. If the program
- applies @code{environment-set!} to @var{exp} and symbol, or
- calls @code{environment-cell} to obtain a writable value
- cell, @code{environment-set!} will signal an
- @code{environment:immutable-location} error. Note that, even
- if an export environment treats a location as immutable, the
- underlying environment may treat it as mutable, so its
- value may change.
-@end table
-It is an error for an element of signature to specify both
-@code{mutable-location} and @code{immutable-location}. If
-neither is specified, @code{immutable-location} is assumed.
-
-As a special case, if an element of signature is a lone
-symbol @var{sym}, it is equivalent to an element of the form
-@code{(sym)}.
-
-All bindings in @var{exp} are immutable. If you apply
-@code{environment-define} or @code{environment-undefine} to
-@var{exp}, Guile will signal an
-@code{environment:immutable-binding} error. However,
-notice that the set of bindings in @var{exp} may still change,
-if the bindings in private change.
-@end deffn
-
- export-environment?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:2194
-@deffn {Scheme Procedure} export-environment? object
-@deffnx {C Function} scm_export_environment_p (object)
-Return @code{#t} if object is an export environment, or
-@code{#f} otherwise.
-@end deffn
-
- export-environment-private
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:2204
-@deffn {Scheme Procedure} export-environment-private env
-@deffnx {C Function} scm_export_environment_private (env)
-Return the private environment of export environment @var{env}.
-@end deffn
-
- export-environment-set-private!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:2216
-@deffn {Scheme Procedure} export-environment-set-private! env private
-@deffnx {C Function} scm_export_environment_set_private_x (env, private)
-Change the private environment of export environment @var{env}.
-@end deffn
-
- export-environment-signature
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:2238
-@deffn {Scheme Procedure} export-environment-signature env
-@deffnx {C Function} scm_export_environment_signature (env)
-Return the signature of export environment @var{env}.
-@end deffn
-
- export-environment-set-signature!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/environments.c:2312
-@deffn {Scheme Procedure} export-environment-set-signature! env signature
-@deffnx {C Function} scm_export_environment_set_signature_x (env, signature)
-Change the signature of export environment @var{env}.
-@end deffn
-
- eq?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/eq.c:62
-@deffn {Scheme Procedure} eq? x y
-Return @code{#t} iff @var{x} references the same object as @var{y}.
-@code{eq?} is similar to @code{eqv?} except that in some cases it is
-capable of discerning distinctions finer than those detectable by
-@code{eqv?}.
-@end deffn
-
- eqv?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/eq.c:85
-@deffn {Scheme Procedure} eqv? x y
-The @code{eqv?} procedure defines a useful equivalence relation on objects.
-Briefly, it returns @code{#t} if @var{x} and @var{y} should normally be
-regarded as the same object. This relation is left slightly open to
-interpretation, but works for comparing immediate integers, characters,
-and inexact numbers.
-@end deffn
-
- equal?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/eq.c:138
-@deffn {Scheme Procedure} equal? x y
-Return @code{#t} iff @var{x} and @var{y} are recursively @code{eqv?} equivalent.
-@code{equal?} recursively compares the contents of pairs,
-vectors, and strings, applying @code{eqv?} on other objects such as
-numbers and symbols. A rule of thumb is that objects are generally
-@code{equal?} if they print the same. @code{equal?} may fail to
-terminate if its arguments are circular data structures.
-@end deffn
-
- scm-error
-@c snarfed from /home/ghouston/guile/guile-core/libguile/error.c:117
-@deffn {Scheme Procedure} scm-error key subr message args data
-@deffnx {C Function} scm_error_scm (key, subr, message, args, data)
-Raise an error with key @var{key}. @var{subr} can be a string
-naming the procedure associated with the error, or @code{#f}.
-@var{message} is the error message string, possibly containing
-@code{~S} and @code{~A} escapes. When an error is reported,
-these are replaced by formatting the corresponding members of
-@var{args}: @code{~A} (was @code{%s} in older versions of
-Guile) formats using @code{display} and @code{~S} (was
-@code{%S}) formats using @code{write}. @var{data} is a list or
-@code{#f} depending on @var{key}: if @var{key} is
-@code{system-error} then it should be a list containing the
-Unix @code{errno} value; If @var{key} is @code{signal} then it
-should be a list containing the Unix signal number; otherwise
-it will usually be @code{#f}.
-@end deffn
-
- strerror
-@c snarfed from /home/ghouston/guile/guile-core/libguile/error.c:168
-@deffn {Scheme Procedure} strerror err
-@deffnx {C Function} scm_strerror (err)
-Return the Unix error message corresponding to @var{err}, which
-must be an integer value.
-@end deffn
-
- apply:nconc2last
-@c snarfed from /home/ghouston/guile/guile-core/libguile/eval.c:3409
-@deffn {Scheme Procedure} apply:nconc2last lst
-@deffnx {C Function} scm_nconc2last (lst)
-Given a list (@var{arg1} @dots{} @var{args}), this function
-conses the @var{arg1} @dots{} arguments onto the front of
-@var{args}, and returns the resulting list. Note that
-@var{args} is a list; thus, the argument to this function is
-a list whose last element is a list.
-Note: Rather than do new consing, @code{apply:nconc2last}
-destroys its argument, so use with care.
-@end deffn
-
- force
-@c snarfed from /home/ghouston/guile/guile-core/libguile/eval.c:3945
-@deffn {Scheme Procedure} force x
-@deffnx {C Function} scm_force (x)
-If the promise @var{x} has not been computed yet, compute and
-return @var{x}, otherwise just return the previously computed
-value.
-@end deffn
-
- promise?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/eval.c:3968
-@deffn {Scheme Procedure} promise? obj
-@deffnx {C Function} scm_promise_p (obj)
-Return true if @var{obj} is a promise, i.e. a delayed computation
-(@pxref{Delayed evaluation,,,r5rs.info,The Revised^5 Report on Scheme}).
-@end deffn
-
- cons-source
-@c snarfed from /home/ghouston/guile/guile-core/libguile/eval.c:3980
-@deffn {Scheme Procedure} cons-source xorig x y
-@deffnx {C Function} scm_cons_source (xorig, x, y)
-Create and return a new pair whose car and cdr are @var{x} and @var{y}.
-Any source properties associated with @var{xorig} are also associated
-with the new pair.
-@end deffn
-
- copy-tree
-@c snarfed from /home/ghouston/guile/guile-core/libguile/eval.c:4000
-@deffn {Scheme Procedure} copy-tree obj
-@deffnx {C Function} scm_copy_tree (obj)
-Recursively copy the data tree that is bound to @var{obj}, and return a
-pointer to the new data structure. @code{copy-tree} recurses down the
-contents of both pairs and vectors (since both cons cells and vector
-cells may point to arbitrary objects), and stops recursing when it hits
-any other object.
-@end deffn
-
- primitive-eval
-@c snarfed from /home/ghouston/guile/guile-core/libguile/eval.c:4093
-@deffn {Scheme Procedure} primitive-eval exp
-@deffnx {C Function} scm_primitive_eval (exp)
-Evaluate @var{exp} in the top-level environment specified by
-the current module.
-@end deffn
-
- eval
-@c snarfed from /home/ghouston/guile/guile-core/libguile/eval.c:4162
-@deffn {Scheme Procedure} eval exp module
-@deffnx {C Function} scm_eval (exp, module)
-Evaluate @var{exp}, a list representing a Scheme expression,
-in the top-level environment specified by @var{module}.
-While @var{exp} is evaluated (using @code{primitive-eval}),
-@var{module} is made the current module. The current module
-is reset to its previous value when @var{eval} returns.
-@end deffn
-
- eval-options-interface
-@c snarfed from /home/ghouston/guile/guile-core/libguile/eval.c:1747
-@deffn {Scheme Procedure} eval-options-interface [setting]
-@deffnx {C Function} scm_eval_options_interface (setting)
-Option interface for the evaluation options. Instead of using
-this procedure directly, use the procedures @code{eval-enable},
-@code{eval-disable}, @code{eval-set!} and @code{eval-options}.
-@end deffn
-
- evaluator-traps-interface
-@c snarfed from /home/ghouston/guile/guile-core/libguile/eval.c:1764
-@deffn {Scheme Procedure} evaluator-traps-interface [setting]
-@deffnx {C Function} scm_evaluator_traps (setting)
-Option interface for the evaluator trap options.
-@end deffn
-
- defined?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/evalext.c:75
-@deffn {Scheme Procedure} defined? sym [env]
-@deffnx {C Function} scm_definedp (sym, env)
-Return @code{#t} if @var{sym} is defined in the lexical environment @var{env}. When @var{env} is not specified, look in the top-level environment as defined by the current module.
-@end deffn
-
- map-in-order
-@c snarfed from /home/ghouston/guile/guile-core/libguile/evalext.c:144
-@deffn {Scheme Procedure} map-in-order
-implemented by the C function "scm_map"
-@end deffn
-
- load-extension
-@c snarfed from /home/ghouston/guile/guile-core/libguile/extensions.c:152
-@deffn {Scheme Procedure} load-extension lib init
-@deffnx {C Function} scm_load_extension (lib, init)
-Load and initialize the extension designated by LIB and INIT.
-When there is no pre-registered function for LIB/INIT, this is
-equivalent to
-
-@lisp
-(dynamic-call INIT (dynamic-link LIB))
-@end lisp
-
-When there is a pre-registered function, that function is called
-instead.
-
-Normally, there is no pre-registered function. This option exists
-only for situations where dynamic linking is unavailable or unwanted.
-In that case, you would statically link your program with the desired
-library, and register its init function right after Guile has been
-initialized.
-
-LIB should be a string denoting a shared library without any file type
-suffix such as ".so". The suffix is provided automatically. It
-should also not contain any directory components. Libraries that
-implement Guile Extensions should be put into the normal locations for
-shared libraries. We recommend to use the naming convention
-libguile-bla-blum for a extension related to a module `(bla blum)'.
-
-The normal way for a extension to be used is to write a small Scheme
-file that defines a module, and to load the extension into this
-module. When the module is auto-loaded, the extension is loaded as
-well. For example,
-
-@lisp
-(define-module (bla blum))
-
-(load-extension "libguile-bla-blum" "bla_init_blum")
-@end lisp
-@end deffn
-
- program-arguments
-@c snarfed from /home/ghouston/guile/guile-core/libguile/feature.c:77
-@deffn {Scheme Procedure} program-arguments
-@deffnx {Scheme Procedure} command-line
-@deffnx {C Function} scm_program_arguments ()
-Return the list of command line arguments passed to Guile, as a list of
-strings. The list includes the invoked program name, which is usually
-@code{"guile"}, but excludes switches and parameters for command line
-options like @code{-e} and @code{-l}.
-@end deffn
-
- make-fluid
-@c snarfed from /home/ghouston/guile/guile-core/libguile/fluids.c:124
-@deffn {Scheme Procedure} make-fluid
-@deffnx {C Function} scm_make_fluid ()
-Return a newly created fluid.
-Fluids are objects of a certain type (a smob) that can hold one SCM
-value per dynamic root. That is, modifications to this value are
-only visible to code that executes within the same dynamic root as
-the modifying code. When a new dynamic root is constructed, it
-inherits the values from its parent. Because each thread executes
-in its own dynamic root, you can use fluids for thread local storage.
-@end deffn
-
- fluid?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/fluids.c:137
-@deffn {Scheme Procedure} fluid? obj
-@deffnx {C Function} scm_fluid_p (obj)
-Return @code{#t} iff @var{obj} is a fluid; otherwise, return
-@code{#f}.
-@end deffn
-
- fluid-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/fluids.c:148
-@deffn {Scheme Procedure} fluid-ref fluid
-@deffnx {C Function} scm_fluid_ref (fluid)
-Return the value associated with @var{fluid} in the current
-dynamic root. If @var{fluid} has not been set, then return
-@code{#f}.
-@end deffn
-
- fluid-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/fluids.c:164
-@deffn {Scheme Procedure} fluid-set! fluid value
-@deffnx {C Function} scm_fluid_set_x (fluid, value)
-Set the value associated with @var{fluid} in the current dynamic root.
-@end deffn
-
- with-fluids*
-@c snarfed from /home/ghouston/guile/guile-core/libguile/fluids.c:223
-@deffn {Scheme Procedure} with-fluids* fluids values thunk
-@deffnx {C Function} scm_with_fluids (fluids, values, thunk)
-Set @var{fluids} to @var{values} temporary, and call @var{thunk}.
-@var{fluids} must be a list of fluids and @var{values} must be the same
-number of their values to be applied. Each substitution is done
-one after another. @var{thunk} must be a procedure with no argument.
-@end deffn
-
- setvbuf
-@c snarfed from /home/ghouston/guile/guile-core/libguile/fports.c:156
-@deffn {Scheme Procedure} setvbuf port mode [size]
-@deffnx {C Function} scm_setvbuf (port, mode, size)
-Set the buffering mode for @var{port}. @var{mode} can be:
-@table @code
-@item _IONBF
-non-buffered
-@item _IOLBF
-line buffered
-@item _IOFBF
-block buffered, using a newly allocated buffer of @var{size} bytes.
-If @var{size} is omitted, a default size will be used.
-@end table
-@end deffn
-
- file-port?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/fports.c:245
-@deffn {Scheme Procedure} file-port? obj
-@deffnx {C Function} scm_file_port_p (obj)
-Determine whether @var{obj} is a port that is related to a file.
-@end deffn
-
- open-file
-@c snarfed from /home/ghouston/guile/guile-core/libguile/fports.c:299
-@deffn {Scheme Procedure} open-file filename mode
-@deffnx {C Function} scm_open_file (filename, mode)
-Open the file whose name is @var{filename}, and return a port
-representing that file. The attributes of the port are
-determined by the @var{mode} string. The way in which this is
-interpreted is similar to C stdio. The first character must be
-one of the following:
-@table @samp
-@item r
-Open an existing file for input.
-@item w
-Open a file for output, creating it if it doesn't already exist
-or removing its contents if it does.
-@item a
-Open a file for output, creating it if it doesn't already
-exist. All writes to the port will go to the end of the file.
-The "append mode" can be turned off while the port is in use
-@pxref{Ports and File Descriptors, fcntl}
-@end table
-The following additional characters can be appended:
-@table @samp
-@item +
-Open the port for both input and output. E.g., @code{r+}: open
-an existing file for both input and output.
-@item 0
-Create an "unbuffered" port. In this case input and output
-operations are passed directly to the underlying port
-implementation without additional buffering. This is likely to
-slow down I/O operations. The buffering mode can be changed
-while a port is in use @pxref{Ports and File Descriptors,
-setvbuf}
-@item l
-Add line-buffering to the port. The port output buffer will be
-automatically flushed whenever a newline character is written.
-@end table
-In theory we could create read/write ports which were buffered
-in one direction only. However this isn't included in the
-current interfaces. If a file cannot be opened with the access
-requested, @code{open-file} throws an exception.
-@end deffn
-
- gc-stats
-@c snarfed from /home/ghouston/guile/guile-core/libguile/gc.c:735
-@deffn {Scheme Procedure} gc-stats
-@deffnx {C Function} scm_gc_stats ()
-Return an association list of statistics about Guile's current
-use of storage.
-@end deffn
-
- object-address
-@c snarfed from /home/ghouston/guile/guile-core/libguile/gc.c:832
-@deffn {Scheme Procedure} object-address obj
-@deffnx {C Function} scm_object_address (obj)
-Return an integer that for the lifetime of @var{obj} is uniquely
-returned by this function for @var{obj}
-@end deffn
-
- gc
-@c snarfed from /home/ghouston/guile/guile-core/libguile/gc.c:843
-@deffn {Scheme Procedure} gc
-@deffnx {C Function} scm_gc ()
-Scans all of SCM objects and reclaims for further use those that are
-no longer accessible.
-@end deffn
-
- %compute-slots
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:291
-@deffn {Scheme Procedure} %compute-slots class
-@deffnx {C Function} scm_sys_compute_slots (class)
-Return a list consisting of the names of all slots belonging to
-class @var{class}, i. e. the slots of @var{class} and of all of
-its superclasses.
-@end deffn
-
- get-keyword
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:376
-@deffn {Scheme Procedure} get-keyword key l default_value
-@deffnx {C Function} scm_get_keyword (key, l, default_value)
-Determine an associated value for the keyword @var{key} from
-the list @var{l}. The list @var{l} has to consist of an even
-number of elements, where, starting with the first, every
-second element is a keyword, followed by its associated value.
-If @var{l} does not hold a value for @var{key}, the value
-@var{default_value} is returned.
-@end deffn
-
- %initialize-object
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:399
-@deffn {Scheme Procedure} %initialize-object obj initargs
-@deffnx {C Function} scm_sys_initialize_object (obj, initargs)
-Initialize the object @var{obj} with the given arguments
-@var{initargs}.
-@end deffn
-
- %prep-layout!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:479
-@deffn {Scheme Procedure} %prep-layout! class
-@deffnx {C Function} scm_sys_prep_layout_x (class)
-
-@end deffn
-
- %inherit-magic!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:556
-@deffn {Scheme Procedure} %inherit-magic! class dsupers
-@deffnx {C Function} scm_sys_inherit_magic_x (class, dsupers)
-
-@end deffn
-
- instance?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:799
-@deffn {Scheme Procedure} instance? obj
-@deffnx {C Function} scm_instance_p (obj)
-Return @code{#t} if @var{obj} is an instance.
-@end deffn
-
- class-name
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:814
-@deffn {Scheme Procedure} class-name obj
-@deffnx {C Function} scm_class_name (obj)
-Return the class name of @var{obj}.
-@end deffn
-
- class-direct-supers
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:824
-@deffn {Scheme Procedure} class-direct-supers obj
-@deffnx {C Function} scm_class_direct_supers (obj)
-Return the direct superclasses of the class @var{obj}.
-@end deffn
-
- class-direct-slots
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:834
-@deffn {Scheme Procedure} class-direct-slots obj
-@deffnx {C Function} scm_class_direct_slots (obj)
-Return the direct slots of the class @var{obj}.
-@end deffn
-
- class-direct-subclasses
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:844
-@deffn {Scheme Procedure} class-direct-subclasses obj
-@deffnx {C Function} scm_class_direct_subclasses (obj)
-Return the direct subclasses of the class @var{obj}.
-@end deffn
-
- class-direct-methods
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:854
-@deffn {Scheme Procedure} class-direct-methods obj
-@deffnx {C Function} scm_class_direct_methods (obj)
-Return the direct methods of the class @var{obj}
-@end deffn
-
- class-precedence-list
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:864
-@deffn {Scheme Procedure} class-precedence-list obj
-@deffnx {C Function} scm_class_precedence_list (obj)
-Return the class precedence list of the class @var{obj}.
-@end deffn
-
- class-slots
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:874
-@deffn {Scheme Procedure} class-slots obj
-@deffnx {C Function} scm_class_slots (obj)
-Return the slot list of the class @var{obj}.
-@end deffn
-
- class-environment
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:884
-@deffn {Scheme Procedure} class-environment obj
-@deffnx {C Function} scm_class_environment (obj)
-Return the environment of the class @var{obj}.
-@end deffn
-
- generic-function-name
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:895
-@deffn {Scheme Procedure} generic-function-name obj
-@deffnx {C Function} scm_generic_function_name (obj)
-Return the name of the generic function @var{obj}.
-@end deffn
-
- generic-function-methods
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:905
-@deffn {Scheme Procedure} generic-function-methods obj
-@deffnx {C Function} scm_generic_function_methods (obj)
-Return the methods of the generic function @var{obj}.
-@end deffn
-
- method-generic-function
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:916
-@deffn {Scheme Procedure} method-generic-function obj
-@deffnx {C Function} scm_method_generic_function (obj)
-Return the generic function for the method @var{obj}.
-@end deffn
-
- method-specializers
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:926
-@deffn {Scheme Procedure} method-specializers obj
-@deffnx {C Function} scm_method_specializers (obj)
-Return specializers of the method @var{obj}.
-@end deffn
-
- method-procedure
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:936
-@deffn {Scheme Procedure} method-procedure obj
-@deffnx {C Function} scm_method_procedure (obj)
-Return the procedure of the method @var{obj}.
-@end deffn
-
- accessor-method-slot-definition
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:946
-@deffn {Scheme Procedure} accessor-method-slot-definition obj
-@deffnx {C Function} scm_accessor_method_slot_definition (obj)
-Return the slot definition of the accessor @var{obj}.
-@end deffn
-
- %tag-body
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:956
-@deffn {Scheme Procedure} %tag-body body
-@deffnx {C Function} scm_sys_tag_body (body)
-Internal GOOPS magic---don't use this function!
-@end deffn
-
- make-unbound
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:971
-@deffn {Scheme Procedure} make-unbound
-@deffnx {C Function} scm_make_unbound ()
-Return the unbound value.
-@end deffn
-
- unbound?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:980
-@deffn {Scheme Procedure} unbound? obj
-@deffnx {C Function} scm_unbound_p (obj)
-Return @code{#t} if @var{obj} is unbound.
-@end deffn
-
- assert-bound
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:990
-@deffn {Scheme Procedure} assert-bound value obj
-@deffnx {C Function} scm_assert_bound (value, obj)
-Return @var{value} if it is bound, and invoke the
-@var{slot-unbound} method of @var{obj} if it is not.
-@end deffn
-
- @@assert-bound-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1002
-@deffn {Scheme Procedure} @@assert-bound-ref obj index
-@deffnx {C Function} scm_at_assert_bound_ref (obj, index)
-Like @code{assert-bound}, but use @var{index} for accessing
-the value from @var{obj}.
-@end deffn
-
- %fast-slot-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1014
-@deffn {Scheme Procedure} %fast-slot-ref obj index
-@deffnx {C Function} scm_sys_fast_slot_ref (obj, index)
-Return the slot value with index @var{index} from @var{obj}.
-@end deffn
-
- %fast-slot-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1032
-@deffn {Scheme Procedure} %fast-slot-set! obj index value
-@deffnx {C Function} scm_sys_fast_slot_set_x (obj, index, value)
-Set the slot with index @var{index} in @var{obj} to
-@var{value}.
-@end deffn
-
- slot-ref-using-class
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1162
-@deffn {Scheme Procedure} slot-ref-using-class class obj slot_name
-@deffnx {C Function} scm_slot_ref_using_class (class, obj, slot_name)
-
-@end deffn
-
- slot-set-using-class!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1181
-@deffn {Scheme Procedure} slot-set-using-class! class obj slot_name value
-@deffnx {C Function} scm_slot_set_using_class_x (class, obj, slot_name, value)
-
-@end deffn
-
- slot-bound-using-class?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1195
-@deffn {Scheme Procedure} slot-bound-using-class? class obj slot_name
-@deffnx {C Function} scm_slot_bound_using_class_p (class, obj, slot_name)
-
-@end deffn
-
- slot-exists-using-class?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1210
-@deffn {Scheme Procedure} slot-exists-using-class? class obj slot_name
-@deffnx {C Function} scm_slot_exists_using_class_p (class, obj, slot_name)
-
-@end deffn
-
- slot-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1226
-@deffn {Scheme Procedure} slot-ref obj slot_name
-@deffnx {C Function} scm_slot_ref (obj, slot_name)
-Return the value from @var{obj}'s slot with the name
-@var{slot_name}.
-@end deffn
-
- slot-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1243
-@deffn {Scheme Procedure} slot-set! obj slot_name value
-@deffnx {C Function} scm_slot_set_x (obj, slot_name, value)
-Set the slot named @var{slot_name} of @var{obj} to @var{value}.
-@end deffn
-
- slot-bound?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1260
-@deffn {Scheme Procedure} slot-bound? obj slot_name
-@deffnx {C Function} scm_slot_bound_p (obj, slot_name)
-Return @code{#t} if the slot named @var{slot_name} of @var{obj}
-is bound.
-@end deffn
-
- slot-exists?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1278
-@deffn {Scheme Procedure} slot-exists? obj slot_name
-@deffnx {C Function} scm_slot_exists_p (obj, slot_name)
-Return @code{#t} if @var{obj} has a slot named @var{slot_name}.
-@end deffn
-
- %allocate-instance
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1317
-@deffn {Scheme Procedure} %allocate-instance class initargs
-@deffnx {C Function} scm_sys_allocate_instance (class, initargs)
-Create a new instance of class @var{class} and initialize it
-from the arguments @var{initargs}.
-@end deffn
-
- %set-object-setter!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1387
-@deffn {Scheme Procedure} %set-object-setter! obj setter
-@deffnx {C Function} scm_sys_set_object_setter_x (obj, setter)
-
-@end deffn
-
- %modify-instance
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1412
-@deffn {Scheme Procedure} %modify-instance old new
-@deffnx {C Function} scm_sys_modify_instance (old, new)
-
-@end deffn
-
- %modify-class
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1438
-@deffn {Scheme Procedure} %modify-class old new
-@deffnx {C Function} scm_sys_modify_class (old, new)
-
-@end deffn
-
- %invalidate-class
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1462
-@deffn {Scheme Procedure} %invalidate-class class
-@deffnx {C Function} scm_sys_invalidate_class (class)
-
-@end deffn
-
- %invalidate-method-cache!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1589
-@deffn {Scheme Procedure} %invalidate-method-cache! gf
-@deffnx {C Function} scm_sys_invalidate_method_cache_x (gf)
-
-@end deffn
-
- generic-capability?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1615
-@deffn {Scheme Procedure} generic-capability? proc
-@deffnx {C Function} scm_generic_capability_p (proc)
-
-@end deffn
-
- enable-primitive-generic!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1628
-@deffn {Scheme Procedure} enable-primitive-generic! . subrs
-@deffnx {C Function} scm_enable_primitive_generic_x (subrs)
-
-@end deffn
-
- primitive-generic-generic
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:1649
-@deffn {Scheme Procedure} primitive-generic-generic subr
-@deffnx {C Function} scm_primitive_generic_generic (subr)
-
-@end deffn
-
- make
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:2010
-@deffn {Scheme Procedure} make . args
-@deffnx {C Function} scm_make (args)
-Make a new object. @var{args} must contain the class and
-all necessary initialization information.
-@end deffn
-
- find-method
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:2103
-@deffn {Scheme Procedure} find-method . l
-@deffnx {C Function} scm_find_method (l)
-
-@end deffn
-
- %method-more-specific?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:2123
-@deffn {Scheme Procedure} %method-more-specific? m1 m2 targs
-@deffnx {C Function} scm_sys_method_more_specific_p (m1, m2, targs)
-
-@end deffn
-
- %goops-loaded
-@c snarfed from /home/ghouston/guile/guile-core/libguile/goops.c:2648
-@deffn {Scheme Procedure} %goops-loaded
-@deffnx {C Function} scm_sys_goops_loaded ()
-Announce that GOOPS is loaded and perform initialization
-on the C level which depends on the loaded GOOPS modules.
-@end deffn
-
- make-guardian
-@c snarfed from /home/ghouston/guile/guile-core/libguile/guardians.c:330
-@deffn {Scheme Procedure} make-guardian [greedy_p]
-@deffnx {C Function} scm_make_guardian (greedy_p)
-Create a new guardian.
-A guardian protects a set of objects from garbage collection,
-allowing a program to apply cleanup or other actions.
-
-@code{make-guardian} returns a procedure representing the guardian.
-Calling the guardian procedure with an argument adds the
-argument to the guardian's set of protected objects.
-Calling the guardian procedure without an argument returns
-one of the protected objects which are ready for garbage
-collection, or @code{#f} if no such object is available.
-Objects which are returned in this way are removed from
-the guardian.
-
-@code{make-guardian} takes one optional argument that says whether the
-new guardian should be greedy or sharing. If there is any chance
-that any object protected by the guardian may be resurrected,
-then you should make the guardian greedy (this is the default).
-
-See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993)
-"Guardians in a Generation-Based Garbage Collector".
-ACM SIGPLAN Conference on Programming Language Design
-and Implementation, June 1993.
-
-(the semantics are slightly different at this point, but the
-paper still (mostly) accurately describes the interface).
-@end deffn
-
- guardian-destroyed?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/guardians.c:358
-@deffn {Scheme Procedure} guardian-destroyed? guardian
-@deffnx {C Function} scm_guardian_destroyed_p (guardian)
-Return @code{#t} if @var{guardian} has been destroyed, otherwise @code{#f}.
-@end deffn
-
- guardian-greedy?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/guardians.c:376
-@deffn {Scheme Procedure} guardian-greedy? guardian
-@deffnx {C Function} scm_guardian_greedy_p (guardian)
-Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}.
-@end deffn
-
- destroy-guardian!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/guardians.c:387
-@deffn {Scheme Procedure} destroy-guardian! guardian
-@deffnx {C Function} scm_destroy_guardian_x (guardian)
-Destroys @var{guardian}, by making it impossible to put any more
-objects in it or get any objects from it. It also unguards any
-objects guarded by @var{guardian}.
-@end deffn
-
- hashq
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hash.c:200
-@deffn {Scheme Procedure} hashq key size
-@deffnx {C Function} scm_hashq (key, size)
-Determine a hash value for @var{key} that is suitable for
-lookups in a hashtable of size @var{size}, where @code{eq?} is
-used as the equality predicate. The function returns an
-integer in the range 0 to @var{size} - 1. Note that
-@code{hashq} may use internal addresses. Thus two calls to
-hashq where the keys are @code{eq?} are not guaranteed to
-deliver the same value if the key object gets garbage collected
-in between. This can happen, for example with symbols:
-@code{(hashq 'foo n) (gc) (hashq 'foo n)} may produce two
-different values, since @code{foo} will be garbage collected.
-@end deffn
-
- hashv
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hash.c:236
-@deffn {Scheme Procedure} hashv key size
-@deffnx {C Function} scm_hashv (key, size)
-Determine a hash value for @var{key} that is suitable for
-lookups in a hashtable of size @var{size}, where @code{eqv?} is
-used as the equality predicate. The function returns an
-integer in the range 0 to @var{size} - 1. Note that
-@code{(hashv key)} may use internal addresses. Thus two calls
-to hashv where the keys are @code{eqv?} are not guaranteed to
-deliver the same value if the key object gets garbage collected
-in between. This can happen, for example with symbols:
-@code{(hashv 'foo n) (gc) (hashv 'foo n)} may produce two
-different values, since @code{foo} will be garbage collected.
-@end deffn
-
- hash
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hash.c:259
-@deffn {Scheme Procedure} hash key size
-@deffnx {C Function} scm_hash (key, size)
-Determine a hash value for @var{key} that is suitable for
-lookups in a hashtable of size @var{size}, where @code{equal?}
-is used as the equality predicate. The function returns an
-integer in the range 0 to @var{size} - 1.
-@end deffn
-
- hashq-get-handle
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:173
-@deffn {Scheme Procedure} hashq-get-handle table key
-@deffnx {C Function} scm_hashq_get_handle (table, key)
-This procedure returns the @code{(key . value)} pair from the
-hash table @var{table}. If @var{table} does not hold an
-associated value for @var{key}, @code{#f} is returned.
-Uses @code{eq?} for equality testing.
-@end deffn
-
- hashq-create-handle!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:185
-@deffn {Scheme Procedure} hashq-create-handle! table key init
-@deffnx {C Function} scm_hashq_create_handle_x (table, key, init)
-This function looks up @var{key} in @var{table} and returns its handle.
-If @var{key} is not already present, a new handle is created which
-associates @var{key} with @var{init}.
-@end deffn
-
- hashq-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:198
-@deffn {Scheme Procedure} hashq-ref table key [dflt]
-@deffnx {C Function} scm_hashq_ref (table, key, dflt)
-Look up @var{key} in the hash table @var{table}, and return the
-value (if any) associated with it. If @var{key} is not found,
-return @var{default} (or @code{#f} if no @var{default} argument
-is supplied). Uses @code{eq?} for equality testing.
-@end deffn
-
- hashq-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:212
-@deffn {Scheme Procedure} hashq-set! table key val
-@deffnx {C Function} scm_hashq_set_x (table, key, val)
-Find the entry in @var{table} associated with @var{key}, and
-store @var{value} there. Uses @code{eq?} for equality testing.
-@end deffn
-
- hashq-remove!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:224
-@deffn {Scheme Procedure} hashq-remove! table key
-@deffnx {C Function} scm_hashq_remove_x (table, key)
-Remove @var{key} (and any value associated with it) from
-@var{table}. Uses @code{eq?} for equality tests.
-@end deffn
-
- hashv-get-handle
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:240
-@deffn {Scheme Procedure} hashv-get-handle table key
-@deffnx {C Function} scm_hashv_get_handle (table, key)
-This procedure returns the @code{(key . value)} pair from the
-hash table @var{table}. If @var{table} does not hold an
-associated value for @var{key}, @code{#f} is returned.
-Uses @code{eqv?} for equality testing.
-@end deffn
-
- hashv-create-handle!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:252
-@deffn {Scheme Procedure} hashv-create-handle! table key init
-@deffnx {C Function} scm_hashv_create_handle_x (table, key, init)
-This function looks up @var{key} in @var{table} and returns its handle.
-If @var{key} is not already present, a new handle is created which
-associates @var{key} with @var{init}.
-@end deffn
-
- hashv-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:266
-@deffn {Scheme Procedure} hashv-ref table key [dflt]
-@deffnx {C Function} scm_hashv_ref (table, key, dflt)
-Look up @var{key} in the hash table @var{table}, and return the
-value (if any) associated with it. If @var{key} is not found,
-return @var{default} (or @code{#f} if no @var{default} argument
-is supplied). Uses @code{eqv?} for equality testing.
-@end deffn
-
- hashv-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:280
-@deffn {Scheme Procedure} hashv-set! table key val
-@deffnx {C Function} scm_hashv_set_x (table, key, val)
-Find the entry in @var{table} associated with @var{key}, and
-store @var{value} there. Uses @code{eqv?} for equality testing.
-@end deffn
-
- hashv-remove!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:291
-@deffn {Scheme Procedure} hashv-remove! table key
-@deffnx {C Function} scm_hashv_remove_x (table, key)
-Remove @var{key} (and any value associated with it) from
-@var{table}. Uses @code{eqv?} for equality tests.
-@end deffn
-
- hash-get-handle
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:306
-@deffn {Scheme Procedure} hash-get-handle table key
-@deffnx {C Function} scm_hash_get_handle (table, key)
-This procedure returns the @code{(key . value)} pair from the
-hash table @var{table}. If @var{table} does not hold an
-associated value for @var{key}, @code{#f} is returned.
-Uses @code{equal?} for equality testing.
-@end deffn
-
- hash-create-handle!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:318
-@deffn {Scheme Procedure} hash-create-handle! table key init
-@deffnx {C Function} scm_hash_create_handle_x (table, key, init)
-This function looks up @var{key} in @var{table} and returns its handle.
-If @var{key} is not already present, a new handle is created which
-associates @var{key} with @var{init}.
-@end deffn
-
- hash-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:331
-@deffn {Scheme Procedure} hash-ref table key [dflt]
-@deffnx {C Function} scm_hash_ref (table, key, dflt)
-Look up @var{key} in the hash table @var{table}, and return the
-value (if any) associated with it. If @var{key} is not found,
-return @var{default} (or @code{#f} if no @var{default} argument
-is supplied). Uses @code{equal?} for equality testing.
-@end deffn
-
- hash-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:346
-@deffn {Scheme Procedure} hash-set! table key val
-@deffnx {C Function} scm_hash_set_x (table, key, val)
-Find the entry in @var{table} associated with @var{key}, and
-store @var{value} there. Uses @code{equal?} for equality
-testing.
-@end deffn
-
- hash-remove!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:358
-@deffn {Scheme Procedure} hash-remove! table key
-@deffnx {C Function} scm_hash_remove_x (table, key)
-Remove @var{key} (and any value associated with it) from
-@var{table}. Uses @code{equal?} for equality tests.
-@end deffn
-
- hashx-get-handle
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:422
-@deffn {Scheme Procedure} hashx-get-handle hash assoc table key
-@deffnx {C Function} scm_hashx_get_handle (hash, assoc, table, key)
-This behaves the same way as the corresponding
-@code{-get-handle} function, but uses @var{hash} as a hash
-function and @var{assoc} to compare keys. @code{hash} must be
-a function that takes two arguments, a key to be hashed and a
-table size. @code{assoc} must be an associator function, like
-@code{assoc}, @code{assq} or @code{assv}.
-@end deffn
-
- hashx-create-handle!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:441
-@deffn {Scheme Procedure} hashx-create-handle! hash assoc table key init
-@deffnx {C Function} scm_hashx_create_handle_x (hash, assoc, table, key, init)
-This behaves the same way as the corresponding
-@code{-create-handle} function, but uses @var{hash} as a hash
-function and @var{assoc} to compare keys. @code{hash} must be
-a function that takes two arguments, a key to be hashed and a
-table size. @code{assoc} must be an associator function, like
-@code{assoc}, @code{assq} or @code{assv}.
-@end deffn
-
- hashx-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:464
-@deffn {Scheme Procedure} hashx-ref hash assoc table key [dflt]
-@deffnx {C Function} scm_hashx_ref (hash, assoc, table, key, dflt)
-This behaves the same way as the corresponding @code{ref}
-function, but uses @var{hash} as a hash function and
-@var{assoc} to compare keys. @code{hash} must be a function
-that takes two arguments, a key to be hashed and a table size.
-@code{assoc} must be an associator function, like @code{assoc},
-@code{assq} or @code{assv}.
-
-By way of illustration, @code{hashq-ref table key} is
-equivalent to @code{hashx-ref hashq assq table key}.
-@end deffn
-
- hashx-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:490
-@deffn {Scheme Procedure} hashx-set! hash assoc table key val
-@deffnx {C Function} scm_hashx_set_x (hash, assoc, table, key, val)
-This behaves the same way as the corresponding @code{set!}
-function, but uses @var{hash} as a hash function and
-@var{assoc} to compare keys. @code{hash} must be a function
-that takes two arguments, a key to be hashed and a table size.
-@code{assoc} must be an associator function, like @code{assoc},
-@code{assq} or @code{assv}.
-
- By way of illustration, @code{hashq-set! table key} is
-equivalent to @code{hashx-set! hashq assq table key}.
-@end deffn
-
- hash-fold
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hashtab.c:528
-@deffn {Scheme Procedure} hash-fold proc init table
-@deffnx {C Function} scm_hash_fold (proc, init, table)
-An iterator over hash-table elements.
-Accumulates and returns a result by applying PROC successively.
-The arguments to PROC are "(key value prior-result)" where key
-and value are successive pairs from the hash table TABLE, and
-prior-result is either INIT (for the first application of PROC)
-or the return value of the previous application of PROC.
-For example, @code{(hash-fold acons '() tab)} will convert a hash
-table into an a-list of key-value pairs.
-@end deffn
-
- make-hook
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hooks.c:178
-@deffn {Scheme Procedure} make-hook [n_args]
-@deffnx {C Function} scm_make_hook (n_args)
-Create a hook for storing procedure of arity @var{n_args}.
-@var{n_args} defaults to zero. The returned value is a hook
-object to be used with the other hook procedures.
-@end deffn
-
- hook?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hooks.c:201
-@deffn {Scheme Procedure} hook? x
-@deffnx {C Function} scm_hook_p (x)
-Return @code{#t} if @var{x} is a hook, @code{#f} otherwise.
-@end deffn
-
- hook-empty?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hooks.c:212
-@deffn {Scheme Procedure} hook-empty? hook
-@deffnx {C Function} scm_hook_empty_p (hook)
-Return @code{#t} if @var{hook} is an empty hook, @code{#f}
-otherwise.
-@end deffn
-
- add-hook!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hooks.c:226
-@deffn {Scheme Procedure} add-hook! hook proc [append_p]
-@deffnx {C Function} scm_add_hook_x (hook, proc, append_p)
-Add the procedure @var{proc} to the hook @var{hook}. The
-procedure is added to the end if @var{append_p} is true,
-otherwise it is added to the front. The return value of this
-procedure is not specified.
-@end deffn
-
- remove-hook!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hooks.c:253
-@deffn {Scheme Procedure} remove-hook! hook proc
-@deffnx {C Function} scm_remove_hook_x (hook, proc)
-Remove the procedure @var{proc} from the hook @var{hook}. The
-return value of this procedure is not specified.
-@end deffn
-
- reset-hook!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hooks.c:267
-@deffn {Scheme Procedure} reset-hook! hook
-@deffnx {C Function} scm_reset_hook_x (hook)
-Remove all procedures from the hook @var{hook}. The return
-value of this procedure is not specified.
-@end deffn
-
- run-hook
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hooks.c:281
-@deffn {Scheme Procedure} run-hook hook . args
-@deffnx {C Function} scm_run_hook (hook, args)
-Apply all procedures from the hook @var{hook} to the arguments
-@var{args}. The order of the procedure application is first to
-last. The return value of this procedure is not specified.
-@end deffn
-
- hook->list
-@c snarfed from /home/ghouston/guile/guile-core/libguile/hooks.c:308
-@deffn {Scheme Procedure} hook->list hook
-@deffnx {C Function} scm_hook_to_list (hook)
-Convert the procedure list of @var{hook} to a list.
-@end deffn
-
- ftell
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ioext.c:73
-@deffn {Scheme Procedure} ftell fd_port
-@deffnx {C Function} scm_ftell (fd_port)
-Return an integer representing the current position of
-@var{fd/port}, measured from the beginning. Equivalent to:
-
-@lisp
-(seek port 0 SEEK_CUR)
-@end lisp
-@end deffn
-
- redirect-port
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ioext.c:91
-@deffn {Scheme Procedure} redirect-port old new
-@deffnx {C Function} scm_redirect_port (old, new)
-This procedure takes two ports and duplicates the underlying file
-descriptor from @var{old-port} into @var{new-port}. The
-current file descriptor in @var{new-port} will be closed.
-After the redirection the two ports will share a file position
-and file status flags.
-
-The return value is unspecified.
-
-Unexpected behaviour can result if both ports are subsequently used
-and the original and/or duplicate ports are buffered.
-
-This procedure does not have any side effects on other ports or
-revealed counts.
-@end deffn
-
- dup->fdes
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ioext.c:130
-@deffn {Scheme Procedure} dup->fdes fd_or_port [fd]
-@deffnx {C Function} scm_dup_to_fdes (fd_or_port, fd)
-Return a new integer file descriptor referring to the open file
-designated by @var{fd_or_port}, which must be either an open
-file port or a file descriptor.
-@end deffn
-
- dup2
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ioext.c:177
-@deffn {Scheme Procedure} dup2 oldfd newfd
-@deffnx {C Function} scm_dup2 (oldfd, newfd)
-A simple wrapper for the @code{dup2} system call.
-Copies the file descriptor @var{oldfd} to descriptor
-number @var{newfd}, replacing the previous meaning
-of @var{newfd}. Both @var{oldfd} and @var{newfd} must
-be integers.
-Unlike for dup->fdes or primitive-move->fdes, no attempt
-is made to move away ports which are using @var{newfd}.
-The return value is unspecified.
-@end deffn
-
- fileno
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ioext.c:196
-@deffn {Scheme Procedure} fileno port
-@deffnx {C Function} scm_fileno (port)
-Return the integer file descriptor underlying @var{port}. Does
-not change its revealed count.
-@end deffn
-
- isatty?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ioext.c:216
-@deffn {Scheme Procedure} isatty? port
-@deffnx {C Function} scm_isatty_p (port)
-Return @code{#t} if @var{port} is using a serial non--file
-device, otherwise @code{#f}.
-@end deffn
-
- fdopen
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ioext.c:238
-@deffn {Scheme Procedure} fdopen fdes modes
-@deffnx {C Function} scm_fdopen (fdes, modes)
-Return a new port based on the file descriptor @var{fdes}.
-Modes are given by the string @var{modes}. The revealed count
-of the port is initialized to zero. The modes string is the
-same as that accepted by @ref{File Ports, open-file}.
-@end deffn
-
- primitive-move->fdes
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ioext.c:262
-@deffn {Scheme Procedure} primitive-move->fdes port fd
-@deffnx {C Function} scm_primitive_move_to_fdes (port, fd)
-Moves the underlying file descriptor for @var{port} to the integer
-value @var{fdes} without changing the revealed count of @var{port}.
-Any other ports already using this descriptor will be automatically
-shifted to new descriptors and their revealed counts reset to zero.
-The return value is @code{#f} if the file descriptor already had the
-required value or @code{#t} if it was moved.
-@end deffn
-
- fdes->ports
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ioext.c:296
-@deffn {Scheme Procedure} fdes->ports fd
-@deffnx {C Function} scm_fdes_to_ports (fd)
-Return a list of existing ports which have @var{fdes} as an
-underlying file descriptor, without changing their revealed
-counts.
-@end deffn
-
- make-keyword-from-dash-symbol
-@c snarfed from /home/ghouston/guile/guile-core/libguile/keywords.c:74
-@deffn {Scheme Procedure} make-keyword-from-dash-symbol symbol
-@deffnx {C Function} scm_make_keyword_from_dash_symbol (symbol)
-Make a keyword object from a @var{symbol} that starts with a dash.
-@end deffn
-
- keyword?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/keywords.c:112
-@deffn {Scheme Procedure} keyword? obj
-@deffnx {C Function} scm_keyword_p (obj)
-Return @code{#t} if the argument @var{obj} is a keyword, else
-@code{#f}.
-@end deffn
-
- keyword-dash-symbol
-@c snarfed from /home/ghouston/guile/guile-core/libguile/keywords.c:123
-@deffn {Scheme Procedure} keyword-dash-symbol keyword
-@deffnx {C Function} scm_keyword_dash_symbol (keyword)
-Return the dash symbol for @var{keyword}.
-This is the inverse of @code{make-keyword-from-dash-symbol}.
-@end deffn
-
- list
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:127
-@deffn {Scheme Procedure} list . objs
-@deffnx {C Function} scm_list (objs)
-Return a list containing @var{objs}, the arguments to
-@code{list}.
-@end deffn
-
- cons*
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:142
-@deffn {Scheme Procedure} cons* arg . rest
-@deffnx {C Function} scm_cons_star (arg, rest)
-Like @code{list}, but the last arg provides the tail of the
-constructed list, returning @code{(cons @var{arg1} (cons
-@var{arg2} (cons @dots{} @var{argn})))}. Requires at least one
-argument. If given one argument, that argument is returned as
-result. This function is called @code{list*} in some other
-Schemes and in Common LISP.
-@end deffn
-
- null?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:166
-@deffn {Scheme Procedure} null? x
-@deffnx {C Function} scm_null_p (x)
-Return @code{#t} iff @var{x} is the empty list, else @code{#f}.
-@end deffn
-
- list?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:176
-@deffn {Scheme Procedure} list? x
-@deffnx {C Function} scm_list_p (x)
-Return @code{#t} iff @var{x} is a proper list, else @code{#f}.
-@end deffn
-
- length
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:217
-@deffn {Scheme Procedure} length lst
-@deffnx {C Function} scm_length (lst)
-Return the number of elements in list @var{lst}.
-@end deffn
-
- append
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:246
-@deffn {Scheme Procedure} append . args
-@deffnx {C Function} scm_append (args)
-Return a list consisting of the elements the lists passed as
-arguments.
-@lisp
-(append '(x) '(y)) @result{} (x y)
-(append '(a) '(b c d)) @result{} (a b c d)
-(append '(a (b)) '((c))) @result{} (a (b) (c))
-@end lisp
-The resulting list is always newly allocated, except that it
-shares structure with the last list argument. The last
-argument may actually be any object; an improper list results
-if the last argument is not a proper list.
-@lisp
-(append '(a b) '(c . d)) @result{} (a b c . d)
-(append '() 'a) @result{} a
-@end lisp
-@end deffn
-
- append!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:280
-@deffn {Scheme Procedure} append! . lists
-@deffnx {C Function} scm_append_x (lists)
-A destructive version of @code{append} (@pxref{Pairs and
-Lists,,,r5rs, The Revised^5 Report on Scheme}). The cdr field
-of each list's final pair is changed to point to the head of
-the next list, so no consing is performed. Return a pointer to
-the mutated list.
-@end deffn
-
- last-pair
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:306
-@deffn {Scheme Procedure} last-pair lst
-@deffnx {C Function} scm_last_pair (lst)
-Return a pointer to the last pair in @var{lst}, signalling an error if
-@var{lst} is circular.
-@end deffn
-
- reverse
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:336
-@deffn {Scheme Procedure} reverse lst
-@deffnx {C Function} scm_reverse (lst)
-Return a new list that contains the elements of @var{lst} but
-in reverse order.
-@end deffn
-
- reverse!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:370
-@deffn {Scheme Procedure} reverse! lst [new_tail]
-@deffnx {C Function} scm_reverse_x (lst, new_tail)
-A destructive version of @code{reverse} (@pxref{Pairs and Lists,,,r5rs,
-The Revised^5 Report on Scheme}). The cdr of each cell in @var{lst} is
-modified to point to the previous list element. Return a pointer to the
-head of the reversed list.
-
-Caveat: because the list is modified in place, the tail of the original
-list now becomes its head, and the head of the original list now becomes
-the tail. Therefore, the @var{lst} symbol to which the head of the
-original list was bound now points to the tail. To ensure that the head
-of the modified list is not lost, it is wise to save the return value of
-@code{reverse!}
-@end deffn
-
- list-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:396
-@deffn {Scheme Procedure} list-ref list k
-@deffnx {C Function} scm_list_ref (list, k)
-Return the @var{k}th element from @var{list}.
-@end deffn
-
- list-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:420
-@deffn {Scheme Procedure} list-set! list k val
-@deffnx {C Function} scm_list_set_x (list, k, val)
-Set the @var{k}th element of @var{list} to @var{val}.
-@end deffn
-
- list-cdr-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:443
-@deffn {Scheme Procedure} list-cdr-ref
-implemented by the C function "scm_list_tail"
-@end deffn
-
- list-tail
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:452
-@deffn {Scheme Procedure} list-tail lst k
-@deffnx {Scheme Procedure} list-cdr-ref lst k
-@deffnx {C Function} scm_list_tail (lst, k)
-Return the "tail" of @var{lst} beginning with its @var{k}th element.
-The first element of the list is considered to be element 0.
-
-@code{list-tail} and @code{list-cdr-ref} are identical. It may help to
-think of @code{list-cdr-ref} as accessing the @var{k}th cdr of the list,
-or returning the results of cdring @var{k} times down @var{lst}.
-@end deffn
-
- list-cdr-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:468
-@deffn {Scheme Procedure} list-cdr-set! list k val
-@deffnx {C Function} scm_list_cdr_set_x (list, k, val)
-Set the @var{k}th cdr of @var{list} to @var{val}.
-@end deffn
-
- list-head
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:497
-@deffn {Scheme Procedure} list-head lst k
-@deffnx {C Function} scm_list_head (lst, k)
-Copy the first @var{k} elements from @var{lst} into a new list, and
-return it.
-@end deffn
-
- list-copy
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:521
-@deffn {Scheme Procedure} list-copy lst
-@deffnx {C Function} scm_list_copy (lst)
-Return a (newly-created) copy of @var{lst}.
-@end deffn
-
- memq
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:575
-@deffn {Scheme Procedure} memq x lst
-@deffnx {C Function} scm_memq (x, lst)
-Return the first sublist of @var{lst} whose car is @code{eq?}
-to @var{x} where the sublists of @var{lst} are the non-empty
-lists returned by @code{(list-tail @var{lst} @var{k})} for
-@var{k} less than the length of @var{lst}. If @var{x} does not
-occur in @var{lst}, then @code{#f} (not the empty list) is
-returned.
-@end deffn
-
- memv
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:591
-@deffn {Scheme Procedure} memv x lst
-@deffnx {C Function} scm_memv (x, lst)
-Return the first sublist of @var{lst} whose car is @code{eqv?}
-to @var{x} where the sublists of @var{lst} are the non-empty
-lists returned by @code{(list-tail @var{lst} @var{k})} for
-@var{k} less than the length of @var{lst}. If @var{x} does not
-occur in @var{lst}, then @code{#f} (not the empty list) is
-returned.
-@end deffn
-
- member
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:612
-@deffn {Scheme Procedure} member x lst
-@deffnx {C Function} scm_member (x, lst)
-Return the first sublist of @var{lst} whose car is
-@code{equal?} to @var{x} where the sublists of @var{lst} are
-the non-empty lists returned by @code{(list-tail @var{lst}
-@var{k})} for @var{k} less than the length of @var{lst}. If
-@var{x} does not occur in @var{lst}, then @code{#f} (not the
-empty list) is returned.
-@end deffn
-
- delq!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:637
-@deffn {Scheme Procedure} delq! item lst
-@deffnx {Scheme Procedure} delv! item lst
-@deffnx {Scheme Procedure} delete! item lst
-@deffnx {C Function} scm_delq_x (item, lst)
-These procedures are destructive versions of @code{delq}, @code{delv}
-and @code{delete}: they modify the pointers in the existing @var{lst}
-rather than creating a new list. Caveat evaluator: Like other
-destructive list functions, these functions cannot modify the binding of
-@var{lst}, and so cannot be used to delete the first element of
-@var{lst} destructively.
-@end deffn
-
- delv!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:661
-@deffn {Scheme Procedure} delv! item lst
-@deffnx {C Function} scm_delv_x (item, lst)
-Destructively remove all elements from @var{lst} that are
-@code{eqv?} to @var{item}.
-@end deffn
-
- delete!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:686
-@deffn {Scheme Procedure} delete! item lst
-@deffnx {C Function} scm_delete_x (item, lst)
-Destructively remove all elements from @var{lst} that are
-@code{equal?} to @var{item}.
-@end deffn
-
- delq
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:715
-@deffn {Scheme Procedure} delq item lst
-@deffnx {C Function} scm_delq (item, lst)
-Return a newly-created copy of @var{lst} with elements
-@code{eq?} to @var{item} removed. This procedure mirrors
-@code{memq}: @code{delq} compares elements of @var{lst} against
-@var{item} with @code{eq?}.
-@end deffn
-
- delv
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:728
-@deffn {Scheme Procedure} delv item lst
-@deffnx {C Function} scm_delv (item, lst)
-Return a newly-created copy of @var{lst} with elements
-@code{eqv?} to @var{item} removed. This procedure mirrors
-@code{memv}: @code{delv} compares elements of @var{lst} against
-@var{item} with @code{eqv?}.
-@end deffn
-
- delete
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:741
-@deffn {Scheme Procedure} delete item lst
-@deffnx {C Function} scm_delete (item, lst)
-Return a newly-created copy of @var{lst} with elements
-@code{equal?} to @var{item} removed. This procedure mirrors
-@code{member}: @code{delete} compares elements of @var{lst}
-against @var{item} with @code{equal?}.
-@end deffn
-
- delq1!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:754
-@deffn {Scheme Procedure} delq1! item lst
-@deffnx {C Function} scm_delq1_x (item, lst)
-Like @code{delq!}, but only deletes the first occurrence of
-@var{item} from @var{lst}. Tests for equality using
-@code{eq?}. See also @code{delv1!} and @code{delete1!}.
-@end deffn
-
- delv1!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:782
-@deffn {Scheme Procedure} delv1! item lst
-@deffnx {C Function} scm_delv1_x (item, lst)
-Like @code{delv!}, but only deletes the first occurrence of
-@var{item} from @var{lst}. Tests for equality using
-@code{eqv?}. See also @code{delq1!} and @code{delete1!}.
-@end deffn
-
- delete1!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/list.c:810
-@deffn {Scheme Procedure} delete1! item lst
-@deffnx {C Function} scm_delete1_x (item, lst)
-Like @code{delete!}, but only deletes the first occurrence of
-@var{item} from @var{lst}. Tests for equality using
-@code{equal?}. See also @code{delq1!} and @code{delv1!}.
-@end deffn
-
- primitive-load
-@c snarfed from /home/ghouston/guile/guile-core/libguile/load.c:111
-@deffn {Scheme Procedure} primitive-load filename
-@deffnx {C Function} scm_primitive_load (filename)
-Load the file named @var{filename} and evaluate its contents in
-the top-level environment. The load paths are not searched;
-@var{filename} must either be a full pathname or be a pathname
-relative to the current directory. If the variable
-@code{%load-hook} is defined, it should be bound to a procedure
-that will be called before any code is loaded. See the
-documentation for @code{%load-hook} later in this section.
-@end deffn
-
- %package-data-dir
-@c snarfed from /home/ghouston/guile/guile-core/libguile/load.c:151
-@deffn {Scheme Procedure} %package-data-dir
-@deffnx {C Function} scm_sys_package_data_dir ()
-Return the name of the directory where Scheme packages, modules and
-libraries are kept. On most Unix systems, this will be
-@samp{/usr/local/share/guile}.
-@end deffn
-
- %library-dir
-@c snarfed from /home/ghouston/guile/guile-core/libguile/load.c:163
-@deffn {Scheme Procedure} %library-dir
-@deffnx {C Function} scm_sys_library_dir ()
-Return the directory where the Guile Scheme library files are installed.
-E.g., may return "/usr/share/guile/1.3.5".
-@end deffn
-
- %site-dir
-@c snarfed from /home/ghouston/guile/guile-core/libguile/load.c:175
-@deffn {Scheme Procedure} %site-dir
-@deffnx {C Function} scm_sys_site_dir ()
-Return the directory where the Guile site files are installed.
-E.g., may return "/usr/share/guile/site".
-@end deffn
-
- parse-path
-@c snarfed from /home/ghouston/guile/guile-core/libguile/load.c:227
-@deffn {Scheme Procedure} parse-path path [tail]
-@deffnx {C Function} scm_parse_path (path, tail)
-Parse @var{path}, which is expected to be a colon-separated
-string, into a list and return the resulting list with
-@var{tail} appended. If @var{path} is @code{#f}, @var{tail}
-is returned.
-@end deffn
-
- search-path
-@c snarfed from /home/ghouston/guile/guile-core/libguile/load.c:277
-@deffn {Scheme Procedure} search-path path filename [extensions]
-@deffnx {C Function} scm_search_path (path, filename, extensions)
-Search @var{path} for a directory containing a file named
-@var{filename}. The file must be readable, and not a directory.
-If we find one, return its full filename; otherwise, return
-@code{#f}. If @var{filename} is absolute, return it unchanged.
-If given, @var{extensions} is a list of strings; for each
-directory in @var{path}, we search for @var{filename}
-concatenated with each @var{extension}.
-@end deffn
-
- %search-load-path
-@c snarfed from /home/ghouston/guile/guile-core/libguile/load.c:423
-@deffn {Scheme Procedure} %search-load-path filename
-@deffnx {C Function} scm_sys_search_load_path (filename)
-Search @var{%load-path} for the file named @var{filename},
-which must be readable by the current user. If @var{filename}
-is found in the list of paths to search or is an absolute
-pathname, return its full pathname. Otherwise, return
-@code{#f}. Filenames may have any of the optional extensions
-in the @code{%load-extensions} list; @code{%search-load-path}
-will try each extension automatically.
-@end deffn
-
- primitive-load-path
-@c snarfed from /home/ghouston/guile/guile-core/libguile/load.c:444
-@deffn {Scheme Procedure} primitive-load-path filename
-@deffnx {C Function} scm_primitive_load_path (filename)
-Search @var{%load-path} for the file named @var{filename} and
-load it into the top-level environment. If @var{filename} is a
-relative pathname and is not found in the list of search paths,
-an error is signalled.
-@end deffn
-
- procedure->syntax
-@c snarfed from /home/ghouston/guile/guile-core/libguile/macros.c:104
-@deffn {Scheme Procedure} procedure->syntax code
-@deffnx {C Function} scm_makacro (code)
-Return a @dfn{macro} which, when a symbol defined to this value
-appears as the first symbol in an expression, returns the
-result of applying @var{code} to the expression and the
-environment.
-@end deffn
-
- procedure->macro
-@c snarfed from /home/ghouston/guile/guile-core/libguile/macros.c:125
-@deffn {Scheme Procedure} procedure->macro code
-@deffnx {C Function} scm_makmacro (code)
-Return a @dfn{macro} which, when a symbol defined to this value
-appears as the first symbol in an expression, evaluates the
-result of applying @var{code} to the expression and the
-environment. For example:
-
-@lisp
-(define trace
- (procedure->macro
- (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
-
-(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).
-@end lisp
-@end deffn
-
- procedure->memoizing-macro
-@c snarfed from /home/ghouston/guile/guile-core/libguile/macros.c:143
-@deffn {Scheme Procedure} procedure->memoizing-macro code
-@deffnx {C Function} scm_makmmacro (code)
-Return a @dfn{macro} which, when a symbol defined to this value
-appears as the first symbol in an expression, evaluates the
-result of applying @var{code} to the expression and the
-environment.
-
-@code{procedure->memoizing-macro} is the same as
-@code{procedure->macro}, except that the expression returned by
-@var{code} replaces the original macro expression in the memoized
-form of the containing code.
-@end deffn
-
- macro?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/macros.c:155
-@deffn {Scheme Procedure} macro? obj
-@deffnx {C Function} scm_macro_p (obj)
-Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a
-syntax transformer.
-@end deffn
-
- macro-type
-@c snarfed from /home/ghouston/guile/guile-core/libguile/macros.c:173
-@deffn {Scheme Procedure} macro-type m
-@deffnx {C Function} scm_macro_type (m)
-Return one of the symbols @code{syntax}, @code{macro} or
-@code{macro!}, depending on whether @var{m} is a syntax
-transformer, a regular macro, or a memoizing macro,
-respectively. If @var{m} is not a macro, @code{#f} is
-returned.
-@end deffn
-
- macro-name
-@c snarfed from /home/ghouston/guile/guile-core/libguile/macros.c:191
-@deffn {Scheme Procedure} macro-name m
-@deffnx {C Function} scm_macro_name (m)
-Return the name of the macro @var{m}.
-@end deffn
-
- macro-transformer
-@c snarfed from /home/ghouston/guile/guile-core/libguile/macros.c:202
-@deffn {Scheme Procedure} macro-transformer m
-@deffnx {C Function} scm_macro_transformer (m)
-Return the transformer of the macro @var{m}.
-@end deffn
-
- current-module
-@c snarfed from /home/ghouston/guile/guile-core/libguile/modules.c:69
-@deffn {Scheme Procedure} current-module
-@deffnx {C Function} scm_current_module ()
-Return the current module.
-@end deffn
-
- set-current-module
-@c snarfed from /home/ghouston/guile/guile-core/libguile/modules.c:81
-@deffn {Scheme Procedure} set-current-module module
-@deffnx {C Function} scm_set_current_module (module)
-Set the current module to @var{module} and return
-the previous current module.
-@end deffn
-
- interaction-environment
-@c snarfed from /home/ghouston/guile/guile-core/libguile/modules.c:104
-@deffn {Scheme Procedure} interaction-environment
-@deffnx {C Function} scm_interaction_environment ()
-Return a specifier for the environment that contains
-implementation--defined bindings, typically a superset of those
-listed in the report. The intent is that this procedure will
-return the environment in which the implementation would
-evaluate expressions dynamically typed by the user.
-@end deffn
-
- env-module
-@c snarfed from /home/ghouston/guile/guile-core/libguile/modules.c:271
-@deffn {Scheme Procedure} env-module env
-@deffnx {C Function} scm_env_module (env)
-Return the module of @var{ENV}, a lexical environment.
-@end deffn
-
- standard-eval-closure
-@c snarfed from /home/ghouston/guile/guile-core/libguile/modules.c:348
-@deffn {Scheme Procedure} standard-eval-closure module
-@deffnx {C Function} scm_standard_eval_closure (module)
-Return an eval closure for the module @var{module}.
-@end deffn
-
- standard-interface-eval-closure
-@c snarfed from /home/ghouston/guile/guile-core/libguile/modules.c:359
-@deffn {Scheme Procedure} standard-interface-eval-closure module
-@deffnx {C Function} scm_standard_interface_eval_closure (module)
-Return a interface eval closure for the module @var{module}. Such a closure does not allow new bindings to be added.
-@end deffn
-
- %get-pre-modules-obarray
-@c snarfed from /home/ghouston/guile/guile-core/libguile/modules.c:582
-@deffn {Scheme Procedure} %get-pre-modules-obarray
-@deffnx {C Function} scm_get_pre_modules_obarray ()
-Return the obarray that is used for all new bindings before the module system is booted. The first call to @code{set-current-module} will boot the module system.
-@end deffn
-
- exact?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:106
-@deffn {Scheme Procedure} exact? x
-@deffnx {C Function} scm_exact_p (x)
-Return @code{#t} if @var{x} is an exact number, @code{#f}
-otherwise.
-@end deffn
-
- odd?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:123
-@deffn {Scheme Procedure} odd? n
-@deffnx {C Function} scm_odd_p (n)
-Return @code{#t} if @var{n} is an odd number, @code{#f}
-otherwise.
-@end deffn
-
- even?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:142
-@deffn {Scheme Procedure} even? n
-@deffnx {C Function} scm_even_p (n)
-Return @code{#t} if @var{n} is an even number, @code{#f}
-otherwise.
-@end deffn
-
- inf?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:184
-@deffn {Scheme Procedure} inf? n
-@deffnx {C Function} scm_inf_p (n)
-Return @code{#t} if @var{n} is infinite, @code{#f}
-otherwise.
-@end deffn
-
- nan?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:201
-@deffn {Scheme Procedure} nan? n
-@deffnx {C Function} scm_nan_p (n)
-Return @code{#t} if @var{n} is a NaN, @code{#f}
-otherwise.
-@end deffn
-
- inf
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:263
-@deffn {Scheme Procedure} inf
-@deffnx {C Function} scm_inf ()
-Return Inf.
-@end deffn
-
- nan
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:278
-@deffn {Scheme Procedure} nan
-@deffnx {C Function} scm_nan ()
-Return NaN.
-@end deffn
-
- logand
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:891
-@deffn {Scheme Procedure} logand n1 n2
-Return the bitwise AND of the integer arguments.
-
-@lisp
-(logand) @result{} -1
-(logand 7) @result{} 7
-(logand #b111 #b011 #b001) @result{} 1
-@end lisp
-@end deffn
-
- logior
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:972
-@deffn {Scheme Procedure} logior n1 n2
-Return the bitwise OR of the integer arguments.
-
-@lisp
-(logior) @result{} 0
-(logior 7) @result{} 7
-(logior #b000 #b001 #b011) @result{} 3
-@end lisp
-@end deffn
-
- logxor
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:1054
-@deffn {Scheme Procedure} logxor n1 n2
-Return the bitwise XOR of the integer arguments. A bit is
-set in the result if it is set in an odd number of arguments.
-@lisp
-(logxor) @result{} 0
-(logxor 7) @result{} 7
-(logxor #b000 #b001 #b011) @result{} 2
-(logxor #b000 #b001 #b011 #b011) @result{} 1
-@end lisp
-@end deffn
-
- logtest
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:1118
-@deffn {Scheme Procedure} logtest j k
-@deffnx {C Function} scm_logtest (j, k)
-@lisp
-(logtest j k) @equiv{} (not (zero? (logand j k)))
-
-(logtest #b0100 #b1011) @result{} #f
-(logtest #b0100 #b0111) @result{} #t
-@end lisp
-@end deffn
-
- logbit?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:1175
-@deffn {Scheme Procedure} logbit? index j
-@deffnx {C Function} scm_logbit_p (index, j)
-@lisp
-(logbit? index j) @equiv{} (logtest (integer-expt 2 index) j)
-
-(logbit? 0 #b1101) @result{} #t
-(logbit? 1 #b1101) @result{} #f
-(logbit? 2 #b1101) @result{} #t
-(logbit? 3 #b1101) @result{} #t
-(logbit? 4 #b1101) @result{} #f
-@end lisp
-@end deffn
-
- lognot
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:1224
-@deffn {Scheme Procedure} lognot n
-@deffnx {C Function} scm_lognot (n)
-Return the integer which is the 2s-complement of the integer
-argument.
-
-@lisp
-(number->string (lognot #b10000000) 2)
- @result{} "-10000001"
-(number->string (lognot #b0) 2)
- @result{} "-1"
-@end lisp
-@end deffn
-
- integer-expt
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:1241
-@deffn {Scheme Procedure} integer-expt n k
-@deffnx {C Function} scm_integer_expt (n, k)
-Return @var{n} raised to the non-negative integer exponent
-@var{k}.
-
-@lisp
-(integer-expt 2 5)
- @result{} 32
-(integer-expt -3 3)
- @result{} -27
-@end lisp
-@end deffn
-
- ash
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:1296
-@deffn {Scheme Procedure} ash n cnt
-@deffnx {C Function} scm_ash (n, cnt)
-The function ash performs an arithmetic shift left by @var{cnt}
-bits (or shift right, if @var{cnt} is negative). 'Arithmetic'
-means, that the function does not guarantee to keep the bit
-structure of @var{n}, but rather guarantees that the result
-will always be rounded towards minus infinity. Therefore, the
-results of ash and a corresponding bitwise shift will differ if
-@var{n} is negative.
-
-Formally, the function returns an integer equivalent to
-@code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}.
-
-@lisp
-(number->string (ash #b1 3) 2) @result{} "1000"
-(number->string (ash #b1010 -1) 2) @result{} "101"
-@end lisp
-@end deffn
-
- bit-extract
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:1349
-@deffn {Scheme Procedure} bit-extract n start end
-@deffnx {C Function} scm_bit_extract (n, start, end)
-Return the integer composed of the @var{start} (inclusive)
-through @var{end} (exclusive) bits of @var{n}. The
-@var{start}th bit becomes the 0-th bit in the result.
-
-@lisp
-(number->string (bit-extract #b1101101010 0 4) 2)
- @result{} "1010"
-(number->string (bit-extract #b1101101010 4 9) 2)
- @result{} "10110"
-@end lisp
-@end deffn
-
- logcount
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:1421
-@deffn {Scheme Procedure} logcount n
-@deffnx {C Function} scm_logcount (n)
-Return the number of bits in integer @var{n}. If integer is
-positive, the 1-bits in its binary representation are counted.
-If negative, the 0-bits in its two's-complement binary
-representation are counted. If 0, 0 is returned.
-
-@lisp
-(logcount #b10101010)
- @result{} 4
-(logcount 0)
- @result{} 0
-(logcount -2)
- @result{} 1
-@end lisp
-@end deffn
-
- integer-length
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:1472
-@deffn {Scheme Procedure} integer-length n
-@deffnx {C Function} scm_integer_length (n)
-Return the number of bits necessary to represent @var{n}.
-
-@lisp
-(integer-length #b10101010)
- @result{} 8
-(integer-length 0)
- @result{} 0
-(integer-length #b1111)
- @result{} 4
-@end lisp
-@end deffn
-
- number->string
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:2330
-@deffn {Scheme Procedure} number->string n [radix]
-@deffnx {C Function} scm_number_to_string (n, radix)
-Return a string holding the external representation of the
-number @var{n} in the given @var{radix}. If @var{n} is
-inexact, a radix of 10 will be used.
-@end deffn
-
- string->number
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:2989
-@deffn {Scheme Procedure} string->number string [radix]
-@deffnx {C Function} scm_string_to_number (string, radix)
-Return a number of the maximally precise representation
-expressed by the given @var{string}. @var{radix} must be an
-exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
-is a default radix that may be overridden by an explicit radix
-prefix in @var{string} (e.g. "#o177"). If @var{radix} is not
-supplied, then the default radix is 10. If string is not a
-syntactically valid notation for a number, then
-@code{string->number} returns @code{#f}.
-@end deffn
-
- number?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:3058
-@deffn {Scheme Procedure} number?
-implemented by the C function "scm_number_p"
-@end deffn
-
- complex?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:3070
-@deffn {Scheme Procedure} complex? x
-@deffnx {C Function} scm_number_p (x)
-Return @code{#t} if @var{x} is a complex number, @code{#f}
-otherwise. Note that the sets of real, rational and integer
-values form subsets of the set of complex numbers, i. e. the
-predicate will also be fulfilled if @var{x} is a real,
-rational or integer number.
-@end deffn
-
- real?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:3078
-@deffn {Scheme Procedure} real?
-implemented by the C function "scm_real_p"
-@end deffn
-
- rational?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:3091
-@deffn {Scheme Procedure} rational? x
-@deffnx {C Function} scm_real_p (x)
-Return @code{#t} if @var{x} is a rational number, @code{#f}
-otherwise. Note that the set of integer values forms a subset of
-the set of rational numbers, i. e. the predicate will also be
-fulfilled if @var{x} is an integer number. Real numbers
-will also satisfy this predicate, because of their limited
-precision.
-@end deffn
-
- integer?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:3112
-@deffn {Scheme Procedure} integer? x
-@deffnx {C Function} scm_integer_p (x)
-Return @code{#t} if @var{x} is an integer number, @code{#f}
-else.
-@end deffn
-
- inexact?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:3137
-@deffn {Scheme Procedure} inexact? x
-@deffnx {C Function} scm_inexact_p (x)
-Return @code{#t} if @var{x} is an inexact number, @code{#f}
-else.
-@end deffn
-
- $expt
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:4297
-@deffn {Scheme Procedure} $expt x y
-@deffnx {C Function} scm_sys_expt (x, y)
-Return @var{x} raised to the power of @var{y}. This
-procedure does not accept complex arguments.
-@end deffn
-
- $atan2
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:4313
-@deffn {Scheme Procedure} $atan2 x y
-@deffnx {C Function} scm_sys_atan2 (x, y)
-Return the arc tangent of the two arguments @var{x} and
-@var{y}. This is similar to calculating the arc tangent of
-@var{x} / @var{y}, except that the signs of both arguments
-are used to determine the quadrant of the result. This
-procedure does not accept complex arguments.
-@end deffn
-
- make-rectangular
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:4326
-@deffn {Scheme Procedure} make-rectangular real imaginary
-@deffnx {C Function} scm_make_rectangular (real, imaginary)
-Return a complex number constructed of the given @var{real} and
-@var{imaginary} parts.
-@end deffn
-
- make-polar
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:4339
-@deffn {Scheme Procedure} make-polar x y
-@deffnx {C Function} scm_make_polar (x, y)
-Return the complex number @var{x} * e^(i * @var{y}).
-@end deffn
-
- inexact->exact
-@c snarfed from /home/ghouston/guile/guile-core/libguile/numbers.c:4474
-@deffn {Scheme Procedure} inexact->exact z
-@deffnx {C Function} scm_inexact_to_exact (z)
-Return an exact number that is numerically closest to @var{z}.
-@end deffn
-
- class-of
-@c snarfed from /home/ghouston/guile/guile-core/libguile/objects.c:86
-@deffn {Scheme Procedure} class-of x
-@deffnx {C Function} scm_class_of (x)
-Return the class of @var{x}.
-@end deffn
-
- entity?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/objects.c:360
-@deffn {Scheme Procedure} entity? obj
-@deffnx {C Function} scm_entity_p (obj)
-Return @code{#t} if @var{obj} is an entity.
-@end deffn
-
- operator?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/objects.c:369
-@deffn {Scheme Procedure} operator? obj
-@deffnx {C Function} scm_operator_p (obj)
-Return @code{#t} if @var{obj} is an operator.
-@end deffn
-
- valid-object-procedure?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/objects.c:385
-@deffn {Scheme Procedure} valid-object-procedure? proc
-@deffnx {C Function} scm_valid_object_procedure_p (proc)
-Return @code{#t} iff @var{proc} is a procedure that can be used with @code{set-object-procedure}. It is always valid to use a closure constructed by @code{lambda}.
-@end deffn
-
- set-object-procedure!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/objects.c:407
-@deffn {Scheme Procedure} set-object-procedure! obj proc
-@deffnx {C Function} scm_set_object_procedure_x (obj, proc)
-Set the object procedure of @var{obj} to @var{proc}.
-@var{obj} must be either an entity or an operator.
-@end deffn
-
- make-class-object
-@c snarfed from /home/ghouston/guile/guile-core/libguile/objects.c:467
-@deffn {Scheme Procedure} make-class-object metaclass layout
-@deffnx {C Function} scm_make_class_object (metaclass, layout)
-Create a new class object of class @var{metaclass}, with the
-slot layout specified by @var{layout}.
-@end deffn
-
- make-subclass-object
-@c snarfed from /home/ghouston/guile/guile-core/libguile/objects.c:482
-@deffn {Scheme Procedure} make-subclass-object class layout
-@deffnx {C Function} scm_make_subclass_object (class, layout)
-Create a subclass object of @var{class}, with the slot layout
-specified by @var{layout}.
-@end deffn
-
- object-properties
-@c snarfed from /home/ghouston/guile/guile-core/libguile/objprop.c:59
-@deffn {Scheme Procedure} object-properties obj
-@deffnx {C Function} scm_object_properties (obj)
-Return @var{obj}'s property list.
-@end deffn
-
- set-object-properties!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/objprop.c:69
-@deffn {Scheme Procedure} set-object-properties! obj alist
-@deffnx {C Function} scm_set_object_properties_x (obj, alist)
-Set @var{obj}'s property list to @var{alist}.
-@end deffn
-
- object-property
-@c snarfed from /home/ghouston/guile/guile-core/libguile/objprop.c:80
-@deffn {Scheme Procedure} object-property obj key
-@deffnx {C Function} scm_object_property (obj, key)
-Return the property of @var{obj} with name @var{key}.
-@end deffn
-
- set-object-property!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/objprop.c:92
-@deffn {Scheme Procedure} set-object-property! obj key value
-@deffnx {C Function} scm_set_object_property_x (obj, key, value)
-In @var{obj}'s property list, set the property named @var{key}
-to @var{value}.
-@end deffn
-
- cons
-@c snarfed from /home/ghouston/guile/guile-core/libguile/pairs.c:80
-@deffn {Scheme Procedure} cons x y
-@deffnx {C Function} scm_cons (x, y)
-Return a newly allocated pair whose car is @var{x} and whose
-cdr is @var{y}. The pair is guaranteed to be different (in the
-sense of @code{eq?}) from every previously existing object.
-@end deffn
-
- pair?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/pairs.c:98
-@deffn {Scheme Procedure} pair? x
-@deffnx {C Function} scm_pair_p (x)
-Return @code{#t} if @var{x} is a pair; otherwise return
-@code{#f}.
-@end deffn
-
- set-car!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/pairs.c:109
-@deffn {Scheme Procedure} set-car! pair value
-@deffnx {C Function} scm_set_car_x (pair, value)
-Stores @var{value} in the car field of @var{pair}. The value returned
-by @code{set-car!} is unspecified.
-@end deffn
-
- set-cdr!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/pairs.c:122
-@deffn {Scheme Procedure} set-cdr! pair value
-@deffnx {C Function} scm_set_cdr_x (pair, value)
-Stores @var{value} in the cdr field of @var{pair}. The value returned
-by @code{set-cdr!} is unspecified.
-@end deffn
-
- char-ready?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:259
-@deffn {Scheme Procedure} char-ready? [port]
-@deffnx {C Function} scm_char_ready_p (port)
-Return @code{#t} if a character is ready on input @var{port}
-and return @code{#f} otherwise. If @code{char-ready?} returns
-@code{#t} then the next @code{read-char} operation on
-@var{port} is guaranteed not to hang. If @var{port} is a file
-port at end of file then @code{char-ready?} returns @code{#t}.
-@footnote{@code{char-ready?} exists to make it possible for a
-program to accept characters from interactive ports without
-getting stuck waiting for input. Any input editors associated
-with such ports must make sure that characters whose existence
-has been asserted by @code{char-ready?} cannot be rubbed out.
-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.}
-@end deffn
-
- drain-input
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:336
-@deffn {Scheme Procedure} drain-input port
-@deffnx {C Function} scm_drain_input (port)
-This procedure clears a port's input buffers, similar
-to the way that force-output clears the output buffer. The
-contents of the buffers are returned as a single string, e.g.,
-
-@lisp
-(define p (open-input-file ...))
-(drain-input p) => empty string, nothing buffered yet.
-(unread-char (read-char p) p)
-(drain-input p) => initial chars from p, up to the buffer size.
-@end lisp
-
-Draining the buffers may be useful for cleanly finishing
-buffered I/O so that the file descriptor can be used directly
-for further input.
-@end deffn
-
- current-input-port
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:363
-@deffn {Scheme Procedure} current-input-port
-@deffnx {C Function} scm_current_input_port ()
-Return the current input port. This is the default port used
-by many input procedures. Initially, @code{current-input-port}
-returns the @dfn{standard input} in Unix and C terminology.
-@end deffn
-
- current-output-port
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:375
-@deffn {Scheme Procedure} current-output-port
-@deffnx {C Function} scm_current_output_port ()
-Return the current output port. This is the default port used
-by many output procedures. Initially,
-@code{current-output-port} returns the @dfn{standard output} in
-Unix and C terminology.
-@end deffn
-
- current-error-port
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:385
-@deffn {Scheme Procedure} current-error-port
-@deffnx {C Function} scm_current_error_port ()
-Return the port to which errors and warnings should be sent (the
-@dfn{standard error} in Unix and C terminology).
-@end deffn
-
- current-load-port
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:395
-@deffn {Scheme Procedure} current-load-port
-@deffnx {C Function} scm_current_load_port ()
-Return the current-load-port.
-The load port is used internally by @code{primitive-load}.
-@end deffn
-
- set-current-input-port
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:408
-@deffn {Scheme Procedure} set-current-input-port port
-@deffnx {Scheme Procedure} set-current-output-port port
-@deffnx {Scheme Procedure} set-current-error-port port
-@deffnx {C Function} scm_set_current_input_port (port)
-Change the ports returned by @code{current-input-port},
-@code{current-output-port} and @code{current-error-port}, respectively,
-so that they use the supplied @var{port} for input or output.
-@end deffn
-
- set-current-output-port
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:421
-@deffn {Scheme Procedure} set-current-output-port port
-@deffnx {C Function} scm_set_current_output_port (port)
-Set the current default output port to @var{port}.
-@end deffn
-
- set-current-error-port
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:435
-@deffn {Scheme Procedure} set-current-error-port port
-@deffnx {C Function} scm_set_current_error_port (port)
-Set the current default error port to @var{port}.
-@end deffn
-
- port-revealed
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:578
-@deffn {Scheme Procedure} port-revealed port
-@deffnx {C Function} scm_port_revealed (port)
-Return the revealed count for @var{port}.
-@end deffn
-
- set-port-revealed!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:591
-@deffn {Scheme Procedure} set-port-revealed! port rcount
-@deffnx {C Function} scm_set_port_revealed_x (port, rcount)
-Sets the revealed count for a port to a given value.
-The return value is unspecified.
-@end deffn
-
- port-mode
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:634
-@deffn {Scheme Procedure} port-mode port
-@deffnx {C Function} scm_port_mode (port)
-Return the port modes associated with the open port @var{port}.
-These will not necessarily be identical to the modes used when
-the port was opened, since modes such as "append" which are
-used only during port creation are not retained.
-@end deffn
-
- close-port
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:671
-@deffn {Scheme Procedure} close-port port
-@deffnx {C Function} scm_close_port (port)
-Close the specified port object. Return @code{#t} if it
-successfully closes a port or @code{#f} if it was already
-closed. An exception may be raised if an error occurs, for
-example when flushing buffered output. See also @ref{Ports and
-File Descriptors, close}, for a procedure which can close file
-descriptors.
-@end deffn
-
- close-input-port
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:699
-@deffn {Scheme Procedure} close-input-port port
-@deffnx {C Function} scm_close_input_port (port)
-Close the specified input port object. The routine has no effect if
-the file has already been closed. An exception may be raised if an
-error occurs. The value returned is unspecified.
-
-See also @ref{Ports and File Descriptors, close}, for a procedure
-which can close file descriptors.
-@end deffn
-
- close-output-port
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:714
-@deffn {Scheme Procedure} close-output-port port
-@deffnx {C Function} scm_close_output_port (port)
-Close the specified output port object. The routine has no effect if
-the file has already been closed. An exception may be raised if an
-error occurs. The value returned is unspecified.
-
-See also @ref{Ports and File Descriptors, close}, for a procedure
-which can close file descriptors.
-@end deffn
-
- port-for-each
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:731
-@deffn {Scheme Procedure} port-for-each proc
-@deffnx {C Function} scm_port_for_each (proc)
-Apply @var{proc} to each port in the Guile port table
-in turn. The return value is unspecified. More specifically,
-@var{proc} is applied exactly once to every port that exists
-in the system at the time @var{port-for-each} is invoked.
-Changes to the port table while @var{port-for-each} is running
-have no effect as far as @var{port-for-each} is concerned.
-@end deffn
-
- input-port?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:772
-@deffn {Scheme Procedure} input-port? x
-@deffnx {C Function} scm_input_port_p (x)
-Return @code{#t} if @var{x} is an input port, otherwise return
-@code{#f}. Any object satisfying this predicate also satisfies
-@code{port?}.
-@end deffn
-
- output-port?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:783
-@deffn {Scheme Procedure} output-port? x
-@deffnx {C Function} scm_output_port_p (x)
-Return @code{#t} if @var{x} is an output port, otherwise return
-@code{#f}. Any object satisfying this predicate also satisfies
-@code{port?}.
-@end deffn
-
- port?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:795
-@deffn {Scheme Procedure} port? x
-@deffnx {C Function} scm_port_p (x)
-Return a boolean indicating whether @var{x} is a port.
-Equivalent to @code{(or (input-port? @var{x}) (output-port?
-@var{x}))}.
-@end deffn
-
- port-closed?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:805
-@deffn {Scheme Procedure} port-closed? port
-@deffnx {C Function} scm_port_closed_p (port)
-Return @code{#t} if @var{port} is closed or @code{#f} if it is
-open.
-@end deffn
-
- eof-object?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:816
-@deffn {Scheme Procedure} eof-object? x
-@deffnx {C Function} scm_eof_object_p (x)
-Return @code{#t} if @var{x} is an end-of-file object; otherwise
-return @code{#f}.
-@end deffn
-
- force-output
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:830
-@deffn {Scheme Procedure} force-output [port]
-@deffnx {C Function} scm_force_output (port)
-Flush the specified output port, or the current output port if @var{port}
-is omitted. The current output buffer contents are passed to the
-underlying port implementation (e.g., in the case of fports, the
-data will be written to the file and the output buffer will be cleared.)
-It has no effect on an unbuffered port.
-
-The return value is unspecified.
-@end deffn
-
- flush-all-ports
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:848
-@deffn {Scheme Procedure} flush-all-ports
-@deffnx {C Function} scm_flush_all_ports ()
-Equivalent to calling @code{force-output} on
-all open output ports. The return value is unspecified.
-@end deffn
-
- read-char
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:866
-@deffn {Scheme Procedure} read-char [port]
-@deffnx {C Function} scm_read_char (port)
-Return the next character available from @var{port}, updating
-@var{port} to point to the following character. If no more
-characters are available, the end-of-file object is returned.
-@end deffn
-
- peek-char
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:1192
-@deffn {Scheme Procedure} peek-char [port]
-@deffnx {C Function} scm_peek_char (port)
-Return the next character available from @var{port},
-@emph{without} updating @var{port} to point to the following
-character. If no more characters are available, the
-end-of-file object is returned.@footnote{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} on the same
-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.}
-@end deffn
-
- unread-char
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:1213
-@deffn {Scheme Procedure} unread-char cobj [port]
-@deffnx {C Function} scm_unread_char (cobj, port)
-Place @var{char} in @var{port} so that it will be read by the
-next read operation. If called multiple times, the unread characters
-will be read again in last-in first-out order. If @var{port} is
-not supplied, the current input port is used.
-@end deffn
-
- unread-string
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:1236
-@deffn {Scheme Procedure} unread-string str port
-@deffnx {C Function} scm_unread_string (str, port)
-Place the string @var{str} in @var{port} so that its characters will be
-read in subsequent read operations. If called multiple times, the
-unread characters will be read again in last-in first-out order. If
-@var{port} is not supplied, the current-input-port is used.
-@end deffn
-
- seek
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:1275
-@deffn {Scheme Procedure} seek fd_port offset whence
-@deffnx {C Function} scm_seek (fd_port, offset, whence)
-Sets the current position of @var{fd/port} to the integer
-@var{offset}, which is interpreted according to the value of
-@var{whence}.
-
-One of the following variables should be supplied for
-@var{whence}:
-@defvar SEEK_SET
-Seek from the beginning of the file.
-@end defvar
-@defvar SEEK_CUR
-Seek from the current position.
-@end defvar
-@defvar SEEK_END
-Seek from the end of the file.
-@end defvar
-If @var{fd/port} is a file descriptor, the underlying system
-call is @code{lseek}. @var{port} may be a string port.
-
-The value returned is the new position in the file. This means
-that the current position of a port can be obtained using:
-@lisp
-(seek port 0 SEEK_CUR)
-@end lisp
-@end deffn
-
- truncate-file
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:1330
-@deffn {Scheme Procedure} truncate-file object [length]
-@deffnx {C Function} scm_truncate_file (object, length)
-Truncates the object referred to by @var{object} to at most
-@var{length} bytes. @var{object} can be a string containing a
-file name or an integer file descriptor or a port.
-@var{length} may be omitted if @var{object} is not a file name,
-in which case the truncation occurs at the current port.
-position. The return value is unspecified.
-@end deffn
-
- port-line
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:1383
-@deffn {Scheme Procedure} port-line port
-@deffnx {C Function} scm_port_line (port)
-Return the current line number for @var{port}.
-@end deffn
-
- set-port-line!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:1394
-@deffn {Scheme Procedure} set-port-line! port line
-@deffnx {C Function} scm_set_port_line_x (port, line)
-Set the current line number for @var{port} to @var{line}.
-@end deffn
-
- port-column
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:1415
-@deffn {Scheme Procedure} port-column port
-@deffnx {Scheme Procedure} port-line port
-@deffnx {C Function} scm_port_column (port)
-Return the current column number or line number of @var{port},
-using the current input port if none is specified. If the number is
-unknown, the result is #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.)
-@end deffn
-
- set-port-column!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:1428
-@deffn {Scheme Procedure} set-port-column! port column
-@deffnx {Scheme Procedure} set-port-line! port line
-@deffnx {C Function} scm_set_port_column_x (port, column)
-Set the current column or line number of @var{port}, using the
-current input port if none is specified.
-@end deffn
-
- port-filename
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:1443
-@deffn {Scheme Procedure} port-filename port
-@deffnx {C Function} scm_port_filename (port)
-Return the filename associated with @var{port}. This function returns
-the strings "standard input", "standard output" and "standard error"
-when called on the current input, output and error ports respectively.
-@end deffn
-
- set-port-filename!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:1457
-@deffn {Scheme Procedure} set-port-filename! port filename
-@deffnx {C Function} scm_set_port_filename_x (port, filename)
-Change the filename associated with @var{port}, using the current input
-port if none is specified. Note that this does not change the port's
-source of data, but only the value that is returned by
-@code{port-filename} and reported in diagnostic output.
-@end deffn
-
- %make-void-port
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ports.c:1551
-@deffn {Scheme Procedure} %make-void-port mode
-@deffnx {C Function} scm_sys_make_void_port (mode)
-Create and return a new void port. A void port acts like
-@file{/dev/null}. The @var{mode} argument
-specifies the input/output modes for this port: see the
-documentation for @code{open-file} in @ref{File Ports}.
-@end deffn
-
- print-options-interface
-@c snarfed from /home/ghouston/guile/guile-core/libguile/print.c:142
-@deffn {Scheme Procedure} print-options-interface [setting]
-@deffnx {C Function} scm_print_options (setting)
-Option interface for the print options. Instead of using
-this procedure directly, use the procedures
-@code{print-enable}, @code{print-disable}, @code{print-set!}
-and @code{print-options}.
-@end deffn
-
- simple-format
-@c snarfed from /home/ghouston/guile/guile-core/libguile/print.c:921
-@deffn {Scheme Procedure} simple-format destination message . args
-@deffnx {C Function} scm_simple_format (destination, message, args)
-Write @var{message} to @var{destination}, defaulting to
-the current output port.
-@var{message} can contain @code{~A} (was @code{%s}) and
-@code{~S} (was @code{%S}) escapes. When printed,
-the escapes are replaced with corresponding members of
-@var{ARGS}:
-@code{~A} formats using @code{display} and @code{~S} formats
-using @code{write}.
-If @var{destination} is @code{#t}, then use the current output
-port, if @var{destination} is @code{#f}, then return a string
-containing the formatted text. Does not add a trailing newline.
-@end deffn
-
- newline
-@c snarfed from /home/ghouston/guile/guile-core/libguile/print.c:1009
-@deffn {Scheme Procedure} newline [port]
-@deffnx {C Function} scm_newline (port)
-Send a newline to @var{port}.
-If @var{port} is omitted, send to the current output port.
-@end deffn
-
- write-char
-@c snarfed from /home/ghouston/guile/guile-core/libguile/print.c:1024
-@deffn {Scheme Procedure} write-char chr [port]
-@deffnx {C Function} scm_write_char (chr, port)
-Send character @var{chr} to @var{port}.
-@end deffn
-
- port-with-print-state
-@c snarfed from /home/ghouston/guile/guile-core/libguile/print.c:1078
-@deffn {Scheme Procedure} port-with-print-state port pstate
-@deffnx {C Function} scm_port_with_print_state (port, pstate)
-Create a new port which behaves like @var{port}, but with an
-included print state @var{pstate}.
-@end deffn
-
- get-print-state
-@c snarfed from /home/ghouston/guile/guile-core/libguile/print.c:1093
-@deffn {Scheme Procedure} get-print-state port
-@deffnx {C Function} scm_get_print_state (port)
-Return the print state of the port @var{port}. If @var{port}
-has no associated print state, @code{#f} is returned.
-@end deffn
-
- procedure-properties
-@c snarfed from /home/ghouston/guile/guile-core/libguile/procprop.c:176
-@deffn {Scheme Procedure} procedure-properties proc
-@deffnx {C Function} scm_procedure_properties (proc)
-Return @var{obj}'s property list.
-@end deffn
-
- set-procedure-properties!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/procprop.c:189
-@deffn {Scheme Procedure} set-procedure-properties! proc new_val
-@deffnx {C Function} scm_set_procedure_properties_x (proc, new_val)
-Set @var{obj}'s property list to @var{alist}.
-@end deffn
-
- procedure-property
-@c snarfed from /home/ghouston/guile/guile-core/libguile/procprop.c:202
-@deffn {Scheme Procedure} procedure-property p k
-@deffnx {C Function} scm_procedure_property (p, k)
-Return the property of @var{obj} with name @var{key}.
-@end deffn
-
- set-procedure-property!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/procprop.c:225
-@deffn {Scheme Procedure} set-procedure-property! p k v
-@deffnx {C Function} scm_set_procedure_property_x (p, k, v)
-In @var{obj}'s property list, set the property named @var{key} to
-@var{value}.
-@end deffn
-
- procedure?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/procs.c:186
-@deffn {Scheme Procedure} procedure? obj
-@deffnx {C Function} scm_procedure_p (obj)
-Return @code{#t} if @var{obj} is a procedure.
-@end deffn
-
- closure?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/procs.c:213
-@deffn {Scheme Procedure} closure? obj
-@deffnx {C Function} scm_closure_p (obj)
-Return @code{#t} if @var{obj} is a closure.
-@end deffn
-
- thunk?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/procs.c:222
-@deffn {Scheme Procedure} thunk? obj
-@deffnx {C Function} scm_thunk_p (obj)
-Return @code{#t} if @var{obj} is a thunk.
-@end deffn
-
- procedure-documentation
-@c snarfed from /home/ghouston/guile/guile-core/libguile/procs.c:272
-@deffn {Scheme Procedure} procedure-documentation proc
-@deffnx {C Function} scm_procedure_documentation (proc)
-Return the documentation string associated with @code{proc}. By
-convention, if a procedure contains more than one expression and the
-first expression is a string constant, that string is assumed to contain
-documentation for that procedure.
-@end deffn
-
- procedure-with-setter?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/procs.c:308
-@deffn {Scheme Procedure} procedure-with-setter? obj
-@deffnx {C Function} scm_procedure_with_setter_p (obj)
-Return @code{#t} if @var{obj} is a procedure with an
-associated setter procedure.
-@end deffn
-
- make-procedure-with-setter
-@c snarfed from /home/ghouston/guile/guile-core/libguile/procs.c:318
-@deffn {Scheme Procedure} make-procedure-with-setter procedure setter
-@deffnx {C Function} scm_make_procedure_with_setter (procedure, setter)
-Create a new procedure which behaves like @var{procedure}, but
-with the associated setter @var{setter}.
-@end deffn
-
- procedure
-@c snarfed from /home/ghouston/guile/guile-core/libguile/procs.c:332
-@deffn {Scheme Procedure} procedure proc
-@deffnx {C Function} scm_procedure (proc)
-Return the procedure of @var{proc}, which must be either a
-procedure with setter, or an operator struct.
-@end deffn
-
- primitive-make-property
-@c snarfed from /home/ghouston/guile/guile-core/libguile/properties.c:64
-@deffn {Scheme Procedure} primitive-make-property not_found_proc
-@deffnx {C Function} scm_primitive_make_property (not_found_proc)
-Create a @dfn{property token} that can be used with
-@code{primitive-property-ref} and @code{primitive-property-set!}.
-See @code{primitive-property-ref} for the significance of
-@var{not_found_proc}.
-@end deffn
-
- primitive-property-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/properties.c:82
-@deffn {Scheme Procedure} primitive-property-ref prop obj
-@deffnx {C Function} scm_primitive_property_ref (prop, obj)
-Return the property @var{prop} of @var{obj}. When no value
-has yet been associated with @var{prop} and @var{obj}, call
-@var{not-found-proc} instead (see @code{primitive-make-property})
-and use its return value. That value is also associated with
-@var{obj} via @code{primitive-property-set!}. When
-@var{not-found-proc} is @code{#f}, use @code{#f} as the
-default value of @var{prop}.
-@end deffn
-
- primitive-property-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/properties.c:113
-@deffn {Scheme Procedure} primitive-property-set! prop obj val
-@deffnx {C Function} scm_primitive_property_set_x (prop, obj, val)
-Associate @var{code} with @var{prop} and @var{obj}.
-@end deffn
-
- primitive-property-del!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/properties.c:134
-@deffn {Scheme Procedure} primitive-property-del! prop obj
-@deffnx {C Function} scm_primitive_property_del_x (prop, obj)
-Remove any value associated with @var{prop} and @var{obj}.
-@end deffn
-
- random
-@c snarfed from /home/ghouston/guile/guile-core/libguile/random.c:376
-@deffn {Scheme Procedure} random n [state]
-@deffnx {C Function} scm_random (n, state)
-Return a number in [0,N).
-
-Accepts a positive integer or real n and returns a
-number of the same type between zero (inclusive) and
-N (exclusive). The values returned have a uniform
-distribution.
-
-The optional argument @var{state} must be of the type produced
-by @code{seed->random-state}. It defaults to the value of the
-variable @var{*random-state*}. This object is used to maintain
-the state of the pseudo-random-number generator and is altered
-as a side effect of the random operation.
-@end deffn
-
- copy-random-state
-@c snarfed from /home/ghouston/guile/guile-core/libguile/random.c:399
-@deffn {Scheme Procedure} copy-random-state [state]
-@deffnx {C Function} scm_copy_random_state (state)
-Return a copy of the random state @var{state}.
-@end deffn
-
- seed->random-state
-@c snarfed from /home/ghouston/guile/guile-core/libguile/random.c:411
-@deffn {Scheme Procedure} seed->random-state seed
-@deffnx {C Function} scm_seed_to_random_state (seed)
-Return a new random state using @var{seed}.
-@end deffn
-
- random:uniform
-@c snarfed from /home/ghouston/guile/guile-core/libguile/random.c:425
-@deffn {Scheme Procedure} random:uniform [state]
-@deffnx {C Function} scm_random_uniform (state)
-Return a uniformly distributed inexact real random number in
-[0,1).
-@end deffn
-
- random:normal
-@c snarfed from /home/ghouston/guile/guile-core/libguile/random.c:440
-@deffn {Scheme Procedure} random:normal [state]
-@deffnx {C Function} scm_random_normal (state)
-Return an inexact real in a normal distribution. The
-distribution used has mean 0 and standard deviation 1. For a
-normal distribution with mean m and standard deviation d use
-@code{(+ m (* d (random:normal)))}.
-@end deffn
-
- random:solid-sphere!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/random.c:496
-@deffn {Scheme Procedure} random:solid-sphere! v [state]
-@deffnx {C Function} scm_random_solid_sphere_x (v, state)
-Fills vect with inexact real random numbers
-the sum of whose squares is less than 1.0.
-Thinking of vect as coordinates in space of
-dimension n = (vector-length vect), the coordinates
-are uniformly distributed within the unit n-sphere.
-The sum of the squares of the numbers is returned.
-@end deffn
-
- random:hollow-sphere!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/random.c:519
-@deffn {Scheme Procedure} random:hollow-sphere! v [state]
-@deffnx {C Function} scm_random_hollow_sphere_x (v, state)
-Fills vect with inexact real random numbers
-the sum of whose squares is equal to 1.0.
-Thinking of vect as coordinates in space of
-dimension n = (vector-length vect), the coordinates
-are uniformly distributed over the surface of the
-unit n-sphere.
-@end deffn
-
- random:normal-vector!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/random.c:537
-@deffn {Scheme Procedure} random:normal-vector! v [state]
-@deffnx {C Function} scm_random_normal_vector_x (v, state)
-Fills vect with inexact real random numbers that are
-independent and standard normally distributed
-(i.e., with mean 0 and variance 1).
-@end deffn
-
- random:exp
-@c snarfed from /home/ghouston/guile/guile-core/libguile/random.c:562
-@deffn {Scheme Procedure} random:exp [state]
-@deffnx {C Function} scm_random_exp (state)
-Return an inexact real in an exponential distribution with mean
-1. For an exponential distribution with mean u use (* u
-(random:exp)).
-@end deffn
-
- %read-delimited!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/rdelim.c:78
-@deffn {Scheme Procedure} %read-delimited! delims str gobble [port [start [end]]]
-@deffnx {C Function} scm_read_delimited_x (delims, str, gobble, port, start, end)
-Read characters from @var{port} into @var{str} until one of the
-characters in the @var{delims} string is encountered. If
-@var{gobble} is true, discard the delimiter character;
-otherwise, leave it in the input stream for the next read. If
-@var{port} is not specified, use the value of
-@code{(current-input-port)}. If @var{start} or @var{end} are
-specified, store data only into the substring of @var{str}
-bounded by @var{start} and @var{end} (which default to the
-beginning and end of the string, respectively).
-
- Return a pair consisting of the delimiter that terminated the
-string and the number of characters read. If reading stopped
-at the end of file, the delimiter returned is the
-@var{eof-object}; if the string was filled without encountering
-a delimiter, this value is @code{#f}.
-@end deffn
-
- %read-line
-@c snarfed from /home/ghouston/guile/guile-core/libguile/rdelim.c:222
-@deffn {Scheme Procedure} %read-line [port]
-@deffnx {C Function} scm_read_line (port)
-Read a newline-terminated line from @var{port}, allocating storage as
-necessary. The newline terminator (if any) is removed from the string,
-and a pair consisting of the line and its delimiter is returned. The
-delimiter may be either a newline or the @var{eof-object}; if
-@code{%read-line} is called at the end of file, it returns the pair
-@code{(#<eof> . #<eof>)}.
-@end deffn
-
- write-line
-@c snarfed from /home/ghouston/guile/guile-core/libguile/rdelim.c:275
-@deffn {Scheme Procedure} write-line obj [port]
-@deffnx {C Function} scm_write_line (obj, port)
-Display @var{obj} and a newline character to @var{port}. If
-@var{port} is not specified, @code{(current-output-port)} is
-used. This function is equivalent to:
-@lisp
-(display obj [port])
-(newline [port])
-@end lisp
-@end deffn
-
- read-options-interface
-@c snarfed from /home/ghouston/guile/guile-core/libguile/read.c:82
-@deffn {Scheme Procedure} read-options-interface [setting]
-@deffnx {C Function} scm_read_options (setting)
-Option interface for the read options. Instead of using
-this procedure directly, use the procedures @code{read-enable},
-@code{read-disable}, @code{read-set!} and @code{read-options}.
-@end deffn
-
- read
-@c snarfed from /home/ghouston/guile/guile-core/libguile/read.c:102
-@deffn {Scheme Procedure} read [port]
-@deffnx {C Function} scm_read (port)
-Read an s-expression from the input port @var{port}, or from
-the current input port if @var{port} is not specified.
-Any whitespace before the next token is discarded.
-@end deffn
-
- read-hash-extend
-@c snarfed from /home/ghouston/guile/guile-core/libguile/read.c:769
-@deffn {Scheme Procedure} read-hash-extend chr proc
-@deffnx {C Function} scm_read_hash_extend (chr, proc)
-Install the procedure @var{proc} for reading expressions
-starting with the character sequence @code{#} and @var{chr}.
-@var{proc} will be called with two arguments: the character
-@var{chr} and the port to read further data from. The object
-returned will be the return value of @code{read}.
-@end deffn
-
- call-with-dynamic-root
-@c snarfed from /home/ghouston/guile/guile-core/libguile/root.c:346
-@deffn {Scheme Procedure} call-with-dynamic-root thunk handler
-@deffnx {C Function} scm_call_with_dynamic_root (thunk, handler)
-Evaluate @code{(thunk)} in a new dynamic context, returning its value.
-
-If an error occurs during evaluation, apply @var{handler} to the
-arguments to the throw, just as @code{throw} would. If this happens,
-@var{handler} is called outside the scope of the new root -- it is
-called in the same dynamic context in which
-@code{call-with-dynamic-root} was evaluated.
-
-If @var{thunk} captures a continuation, the continuation is rooted at
-the call to @var{thunk}. In particular, the call to
-@code{call-with-dynamic-root} is not captured. Therefore,
-@code{call-with-dynamic-root} always returns at most one time.
-
-Before calling @var{thunk}, the dynamic-wind chain is un-wound back to
-the root and a new chain started for @var{thunk}. Therefore, this call
-may not do what you expect:
-
-@lisp
-;; Almost certainly a bug:
-(with-output-to-port
- some-port
-
- (lambda ()
- (call-with-dynamic-root
- (lambda ()
- (display 'fnord)
- (newline))
- (lambda (errcode) errcode))))
-@end lisp
-
-The problem is, on what port will @samp{fnord} be displayed? You
-might expect that because of the @code{with-output-to-port} that
-it will be displayed on the port bound to @code{some-port}. But it
-probably won't -- before evaluating the thunk, dynamic winds are
-unwound, including those created by @code{with-output-to-port}.
-So, the standard output port will have been re-set to its default value
-before @code{display} is evaluated.
-
-(This function was added to Guile mostly to help calls to functions in C
-libraries that can not tolerate non-local exits or calls that return
-multiple times. If such functions call back to the interpreter, it should
-be under a new dynamic root.)
-@end deffn
-
- dynamic-root
-@c snarfed from /home/ghouston/guile/guile-core/libguile/root.c:359
-@deffn {Scheme Procedure} dynamic-root
-@deffnx {C Function} scm_dynamic_root ()
-Return an object representing the current dynamic root.
-
-These objects are only useful for comparison using @code{eq?}.
-They are currently represented as numbers, but your code should
-in no way depend on this.
-@end deffn
-
- read-string!/partial
-@c snarfed from /home/ghouston/guile/guile-core/libguile/rw.c:121
-@deffn {Scheme Procedure} read-string!/partial str [port_or_fdes [start [end]]]
-@deffnx {C Function} scm_read_string_x_partial (str, port_or_fdes, start, end)
-Read characters from a port or file descriptor into a
-string @var{str}. A port must have an underlying file
-descriptor --- a so-called fport. This procedure is
-scsh-compatible and can efficiently read large strings.
-It will:
-
-@itemize
-@item
-attempt to fill the entire string, unless the @var{start}
-and/or @var{end} arguments are supplied. i.e., @var{start}
-defaults to 0 and @var{end} defaults to
-@code{(string-length str)}
-@item
-use the current input port if @var{port_or_fdes} is not
-supplied.
-@item
-return fewer than the requested number of characters in some
-cases, e.g., on end of file, if interrupted by a signal, or if
-not all the characters are immediately available.
-@item
-wait indefinitely for some input if no characters are
-currently available,
-unless the port is in non-blocking mode.
-@item
-read characters from the port's input buffers if available,
-instead from the underlying file descriptor.
-@item
-return @code{#f} if end-of-file is encountered before reading
-any characters, otherwise return the number of characters
-read.
-@item
-return 0 if the port is in non-blocking mode and no characters
-are immediately available.
-@item
-return 0 if the request is for 0 bytes, with no
-end-of-file check.
-@end itemize
-@end deffn
-
- write-string/partial
-@c snarfed from /home/ghouston/guile/guile-core/libguile/rw.c:215
-@deffn {Scheme Procedure} write-string/partial str [port_or_fdes [start [end]]]
-@deffnx {C Function} scm_write_string_partial (str, port_or_fdes, start, end)
-Write characters from a string @var{str} to a port or file
-descriptor. A port must have an underlying file descriptor
---- a so-called fport. This procedure is
-scsh-compatible and can efficiently write large strings.
-It will:
-
-@itemize
-@item
-attempt to write the entire string, unless the @var{start}
-and/or @var{end} arguments are supplied. i.e., @var{start}
-defaults to 0 and @var{end} defaults to
-@code{(string-length str)}
-@item
-use the current output port if @var{port_of_fdes} is not
-supplied.
-@item
-in the case of a buffered port, store the characters in the
-port's output buffer, if all will fit. If they will not fit
-then any existing buffered characters will be flushed
-before attempting
-to write the new characters directly to the underlying file
-descriptor. If the port is in non-blocking mode and
-buffered characters can not be flushed immediately, then an
-@code{EAGAIN} system-error exception will be raised (Note:
-scsh does not support the use of non-blocking buffered ports.)
-@item
-write fewer than the requested number of
-characters in some cases, e.g., if interrupted by a signal or
-if not all of the output can be accepted immediately.
-@item
-wait indefinitely for at least one character
-from @var{str} to be accepted by the port, unless the port is
-in non-blocking mode.
-@item
-return the number of characters accepted by the port.
-@item
-return 0 if the port is in non-blocking mode and can not accept
-at least one character from @var{str} immediately
-@item
-return 0 immediately if the request size is 0 bytes.
-@end itemize
-@end deffn
-
- sigaction
-@c snarfed from /home/ghouston/guile/guile-core/libguile/scmsigs.c:182
-@deffn {Scheme Procedure} sigaction signum [handler [flags]]
-@deffnx {C Function} scm_sigaction (signum, handler, flags)
-Install or report the signal handler for a specified signal.
-
-@var{signum} is the signal number, which can be specified using the value
-of variables such as @code{SIGINT}.
-
-If @var{action} is omitted, @code{sigaction} returns a pair: the
-CAR is the current
-signal hander, which will be either an integer with the value @code{SIG_DFL}
-(default action) or @code{SIG_IGN} (ignore), or the Scheme procedure which
-handles the signal, or @code{#f} if a non-Scheme procedure handles the
-signal. The CDR contains the current @code{sigaction} flags for the handler.
-
-If @var{action} is provided, it is installed as the new handler for
-@var{signum}. @var{action} can be a Scheme procedure taking one
-argument, or the value of @code{SIG_DFL} (default action) or
-@code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
-was installed before @code{sigaction} was first used. Flags can
-optionally be specified for the new handler (@code{SA_RESTART} will
-always be added if it's available and the system is using restartable
-system calls.) The return value is a pair with information about the
-old handler as described above.
-
-This interface does not provide access to the "signal blocking"
-facility. Maybe this is not needed, since the thread support may
-provide solutions to the problem of consistent access to data
-structures.
-@end deffn
-
- restore-signals
-@c snarfed from /home/ghouston/guile/guile-core/libguile/scmsigs.c:345
-@deffn {Scheme Procedure} restore-signals
-@deffnx {C Function} scm_restore_signals ()
-Return all signal handlers to the values they had before any call to
-@code{sigaction} was made. The return value is unspecified.
-@end deffn
-
- alarm
-@c snarfed from /home/ghouston/guile/guile-core/libguile/scmsigs.c:384
-@deffn {Scheme Procedure} alarm i
-@deffnx {C Function} scm_alarm (i)
-Set a timer to raise a @code{SIGALRM} signal after the specified
-number of seconds (an integer). It's advisable to install a signal
-handler for
-@code{SIGALRM} beforehand, since the default action is to terminate
-the process.
-
-The return value indicates the time remaining for the previous alarm,
-if any. The new value replaces the previous alarm. If there was
-no previous alarm, the return value is zero.
-@end deffn
-
- setitimer
-@c snarfed from /home/ghouston/guile/guile-core/libguile/scmsigs.c:414
-@deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
-@deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds)
-Set the timer specified by @var{which_timer} according to the given
-@var{interval_seconds}, @var{interval_microseconds},
-@var{value_seconds}, and @var{value_microseconds} values.
-
-Return information about the timer's previous setting.
-Errors are handled as described in the guile info pages under ``POSIX
-Interface Conventions''.
-
-The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
-and @code{ITIMER_PROF}.
-
-The return value will be a list of two cons pairs representing the
-current state of the given timer. The first pair is the seconds and
-microseconds of the timer @code{it_interval}, and the second pair is
-the seconds and microseconds of the timer @code{it_value}.
-@end deffn
-
- getitimer
-@c snarfed from /home/ghouston/guile/guile-core/libguile/scmsigs.c:455
-@deffn {Scheme Procedure} getitimer which_timer
-@deffnx {C Function} scm_getitimer (which_timer)
-Return information about the timer specified by @var{which_timer}
-Errors are handled as described in the guile info pages under ``POSIX
-Interface Conventions''.
-
-The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
-and @code{ITIMER_PROF}.
-
-The return value will be a list of two cons pairs representing the
-current state of the given timer. The first pair is the seconds and
-microseconds of the timer @code{it_interval}, and the second pair is
-the seconds and microseconds of the timer @code{it_value}.
-@end deffn
-
- pause
-@c snarfed from /home/ghouston/guile/guile-core/libguile/scmsigs.c:482
-@deffn {Scheme Procedure} pause
-@deffnx {C Function} scm_pause ()
-Pause the current process (thread?) until a signal arrives whose
-action is to either terminate the current process or invoke a
-handler procedure. The return value is unspecified.
-@end deffn
-
- sleep
-@c snarfed from /home/ghouston/guile/guile-core/libguile/scmsigs.c:495
-@deffn {Scheme Procedure} sleep i
-@deffnx {C Function} scm_sleep (i)
-Wait for the given number of seconds (an integer) or until a signal
-arrives. The return value is zero if the time elapses or the number
-of seconds remaining otherwise.
-@end deffn
-
- usleep
-@c snarfed from /home/ghouston/guile/guile-core/libguile/scmsigs.c:513
-@deffn {Scheme Procedure} usleep i
-@deffnx {C Function} scm_usleep (i)
-Sleep for I microseconds. @code{usleep} is not available on
-all platforms.
-@end deffn
-
- raise
-@c snarfed from /home/ghouston/guile/guile-core/libguile/scmsigs.c:542
-@deffn {Scheme Procedure} raise sig
-@deffnx {C Function} scm_raise (sig)
-Sends a specified signal @var{sig} to the current process, where
-@var{sig} is as described for the kill procedure.
-@end deffn
-
- system
-@c snarfed from /home/ghouston/guile/guile-core/libguile/simpos.c:76
-@deffn {Scheme Procedure} system [cmd]
-@deffnx {C Function} scm_system (cmd)
-Execute @var{cmd} using the operating system's "command
-processor". Under Unix this is usually the default shell
-@code{sh}. The value returned is @var{cmd}'s exit status as
-returned by @code{waitpid}, which can be interpreted using the
-functions above.
-
-If @code{system} is called without arguments, return a boolean
-indicating whether the command processor is available.
-@end deffn
-
- getenv
-@c snarfed from /home/ghouston/guile/guile-core/libguile/simpos.c:103
-@deffn {Scheme Procedure} getenv nam
-@deffnx {C Function} scm_getenv (nam)
-Looks up the string @var{name} in the current environment. The return
-value is @code{#f} unless a string of the form @code{NAME=VALUE} is
-found, in which case the string @code{VALUE} is returned.
-@end deffn
-
- primitive-exit
-@c snarfed from /home/ghouston/guile/guile-core/libguile/simpos.c:118
-@deffn {Scheme Procedure} primitive-exit [status]
-@deffnx {C Function} scm_primitive_exit (status)
-Terminate the current process without unwinding the Scheme stack.
-This is would typically be useful after a fork. The exit status
-is @var{status} if supplied, otherwise zero.
-@end deffn
-
- restricted-vector-sort!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/sort.c:422
-@deffn {Scheme Procedure} restricted-vector-sort! vec less startpos endpos
-@deffnx {C Function} scm_restricted_vector_sort_x (vec, less, startpos, endpos)
-Sort the vector @var{vec}, using @var{less} for comparing
-the vector elements. @var{startpos} and @var{endpos} delimit
-the range of the vector which gets sorted. The return value
-is not specified.
-@end deffn
-
- sorted?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/sort.c:453
-@deffn {Scheme Procedure} sorted? items less
-@deffnx {C Function} scm_sorted_p (items, less)
-Return @code{#t} iff @var{items} is a list or a vector such that
-for all 1 <= i <= m, the predicate @var{less} returns true when
-applied to all elements i - 1 and i
-@end deffn
-
- merge
-@c snarfed from /home/ghouston/guile/guile-core/libguile/sort.c:526
-@deffn {Scheme Procedure} merge alist blist less
-@deffnx {C Function} scm_merge (alist, blist, less)
-Merge two already sorted lists into one.
-Given two lists @var{alist} and @var{blist}, such that
-@code{(sorted? alist less?)} and @code{(sorted? blist less?)},
-return a new list in which the elements of @var{alist} and
-@var{blist} have been stably interleaved so that
-@code{(sorted? (merge alist blist less?) less?)}.
-Note: this does _not_ accept vectors.
-@end deffn
-
- merge!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/sort.c:639
-@deffn {Scheme Procedure} merge! alist blist less
-@deffnx {C Function} scm_merge_x (alist, blist, less)
-Takes two lists @var{alist} and @var{blist} such that
-@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
-returns a new list in which the elements of @var{alist} and
-@var{blist} have been stably interleaved so that
- @code{(sorted? (merge alist blist less?) less?)}.
-This is the destructive variant of @code{merge}
-Note: this does _not_ accept vectors.
-@end deffn
-
- sort!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/sort.c:715
-@deffn {Scheme Procedure} sort! items less
-@deffnx {C Function} scm_sort_x (items, less)
-Sort the sequence @var{items}, which may be a list or a
-vector. @var{less} is used for comparing the sequence
-elements. The sorting is destructive, that means that the
-input sequence is modified to produce the sorted result.
-This is not a stable sort.
-@end deffn
-
- sort
-@c snarfed from /home/ghouston/guile/guile-core/libguile/sort.c:749
-@deffn {Scheme Procedure} sort items less
-@deffnx {C Function} scm_sort (items, less)
-Sort the sequence @var{items}, which may be a list or a
-vector. @var{less} is used for comparing the sequence
-elements. This is not a stable sort.
-@end deffn
-
- stable-sort!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/sort.c:845
-@deffn {Scheme Procedure} stable-sort! items less
-@deffnx {C Function} scm_stable_sort_x (items, less)
-Sort the sequence @var{items}, which may be a list or a
-vector. @var{less} is used for comparing the sequence elements.
-The sorting is destructive, that means that the input sequence
-is modified to produce the sorted result.
-This is a stable sort.
-@end deffn
-
- stable-sort
-@c snarfed from /home/ghouston/guile/guile-core/libguile/sort.c:885
-@deffn {Scheme Procedure} stable-sort items less
-@deffnx {C Function} scm_stable_sort (items, less)
-Sort the sequence @var{items}, which may be a list or a
-vector. @var{less} is used for comparing the sequence elements.
-This is a stable sort.
-@end deffn
-
- sort-list!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/sort.c:931
-@deffn {Scheme Procedure} sort-list! items less
-@deffnx {C Function} scm_sort_list_x (items, less)
-Sort the list @var{items}, using @var{less} for comparing the
-list elements. The sorting is destructive, that means that the
-input list is modified to produce the sorted result.
-This is a stable sort.
-@end deffn
-
- sort-list
-@c snarfed from /home/ghouston/guile/guile-core/libguile/sort.c:945
-@deffn {Scheme Procedure} sort-list items less
-@deffnx {C Function} scm_sort_list (items, less)
-Sort the list @var{items}, using @var{less} for comparing the
-list elements. This is a stable sort.
-@end deffn
-
- source-properties
-@c snarfed from /home/ghouston/guile/guile-core/libguile/srcprop.c:178
-@deffn {Scheme Procedure} source-properties obj
-@deffnx {C Function} scm_source_properties (obj)
-Return the source property association list of @var{obj}.
-@end deffn
-
- set-source-properties!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/srcprop.c:199
-@deffn {Scheme Procedure} set-source-properties! obj plist
-@deffnx {C Function} scm_set_source_properties_x (obj, plist)
-Install the association list @var{plist} as the source property
-list for @var{obj}.
-@end deffn
-
- source-property
-@c snarfed from /home/ghouston/guile/guile-core/libguile/srcprop.c:217
-@deffn {Scheme Procedure} source-property obj key
-@deffnx {C Function} scm_source_property (obj, key)
-Return the source property specified by @var{key} from
-@var{obj}'s source property list.
-@end deffn
-
- set-source-property!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/srcprop.c:248
-@deffn {Scheme Procedure} set-source-property! obj key datum
-@deffnx {C Function} scm_set_source_property_x (obj, key, datum)
-Set the source property of object @var{obj}, which is specified by
-@var{key} to @var{datum}. Normally, the key will be a symbol.
-@end deffn
-
- stack?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:411
-@deffn {Scheme Procedure} stack? obj
-@deffnx {C Function} scm_stack_p (obj)
-Return @code{#t} if @var{obj} is a calling stack.
-@end deffn
-
- make-stack
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:442
-@deffn {Scheme Procedure} make-stack obj . args
-@deffnx {C Function} scm_make_stack (obj, args)
-Create a new stack. If @var{obj} is @code{#t}, the current
-evaluation stack is used for creating the stack frames,
-otherwise the frames are taken from @var{obj} (which must be
-either a debug object or a continuation).
-
-@var{args} should be a list containing any combination of
-integer, procedure and @code{#t} values.
-
-These values specify various ways of cutting away uninteresting
-stack frames from the top and bottom of the stack that
-@code{make-stack} returns. They come in pairs like this:
-@code{(@var{inner_cut_1} @var{outer_cut_1} @var{inner_cut_2}
-@var{outer_cut_2} @dots{})}.
-
-Each @var{inner_cut_N} can be @code{#t}, an integer, or a
-procedure. @code{#t} means to cut away all frames up to but
-excluding the first user module frame. An integer means to cut
-away exactly that number of frames. A procedure means to cut
-away all frames up to but excluding the application frame whose
-procedure matches the specified one.
-
-Each @var{outer_cut_N} can be an integer or a procedure. An
-integer means to cut away that number of frames. A procedure
-means to cut away frames down to but excluding the application
-frame whose procedure matches the specified one.
-
-If the @var{outer_cut_N} of the last pair is missing, it is
-taken as 0.
-@end deffn
-
- stack-id
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:534
-@deffn {Scheme Procedure} stack-id stack
-@deffnx {C Function} scm_stack_id (stack)
-Return the identifier given to @var{stack} by @code{start-stack}.
-@end deffn
-
- stack-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:575
-@deffn {Scheme Procedure} stack-ref stack index
-@deffnx {C Function} scm_stack_ref (stack, index)
-Return the @var{index}'th frame from @var{stack}.
-@end deffn
-
- stack-length
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:591
-@deffn {Scheme Procedure} stack-length stack
-@deffnx {C Function} scm_stack_length (stack)
-Return the length of @var{stack}.
-@end deffn
-
- frame?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:604
-@deffn {Scheme Procedure} frame? obj
-@deffnx {C Function} scm_frame_p (obj)
-Return @code{#t} if @var{obj} is a stack frame.
-@end deffn
-
- last-stack-frame
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:615
-@deffn {Scheme Procedure} last-stack-frame obj
-@deffnx {C Function} scm_last_stack_frame (obj)
-Return a stack which consists of a single frame, which is the
-last stack frame for @var{obj}. @var{obj} must be either a
-debug object or a continuation.
-@end deffn
-
- frame-number
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:657
-@deffn {Scheme Procedure} frame-number frame
-@deffnx {C Function} scm_frame_number (frame)
-Return the frame number of @var{frame}.
-@end deffn
-
- frame-source
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:667
-@deffn {Scheme Procedure} frame-source frame
-@deffnx {C Function} scm_frame_source (frame)
-Return the source of @var{frame}.
-@end deffn
-
- frame-procedure
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:678
-@deffn {Scheme Procedure} frame-procedure frame
-@deffnx {C Function} scm_frame_procedure (frame)
-Return the procedure for @var{frame}, or @code{#f} if no
-procedure is associated with @var{frame}.
-@end deffn
-
- frame-arguments
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:690
-@deffn {Scheme Procedure} frame-arguments frame
-@deffnx {C Function} scm_frame_arguments (frame)
-Return the arguments of @var{frame}.
-@end deffn
-
- frame-previous
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:701
-@deffn {Scheme Procedure} frame-previous frame
-@deffnx {C Function} scm_frame_previous (frame)
-Return the previous frame of @var{frame}, or @code{#f} if
-@var{frame} is the first frame in its stack.
-@end deffn
-
- frame-next
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:717
-@deffn {Scheme Procedure} frame-next frame
-@deffnx {C Function} scm_frame_next (frame)
-Return the next frame of @var{frame}, or @code{#f} if
-@var{frame} is the last frame in its stack.
-@end deffn
-
- frame-real?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:732
-@deffn {Scheme Procedure} frame-real? frame
-@deffnx {C Function} scm_frame_real_p (frame)
-Return @code{#t} if @var{frame} is a real frame.
-@end deffn
-
- frame-procedure?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:742
-@deffn {Scheme Procedure} frame-procedure? frame
-@deffnx {C Function} scm_frame_procedure_p (frame)
-Return @code{#t} if a procedure is associated with @var{frame}.
-@end deffn
-
- frame-evaluating-args?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:752
-@deffn {Scheme Procedure} frame-evaluating-args? frame
-@deffnx {C Function} scm_frame_evaluating_args_p (frame)
-Return @code{#t} if @var{frame} contains evaluated arguments.
-@end deffn
-
- frame-overflow?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stacks.c:762
-@deffn {Scheme Procedure} frame-overflow? frame
-@deffnx {C Function} scm_frame_overflow_p (frame)
-Return @code{#t} if @var{frame} is an overflow frame.
-@end deffn
-
- get-internal-real-time
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stime.c:143
-@deffn {Scheme Procedure} get-internal-real-time
-@deffnx {C Function} scm_get_internal_real_time ()
-Return the number of time units since the interpreter was
-started.
-@end deffn
-
- times
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stime.c:188
-@deffn {Scheme Procedure} times
-@deffnx {C Function} scm_times ()
-Return an object with information about real and processor
-time. The following procedures accept such an object as an
-argument and return a selected component:
-
-@table @code
-@item tms:clock
-The current real time, expressed as time units relative to an
-arbitrary base.
-@item tms:utime
-The CPU time units used by the calling process.
-@item tms:stime
-The CPU time units used by the system on behalf of the calling
-process.
-@item tms:cutime
-The CPU time units used by terminated child processes of the
-calling process, whose status has been collected (e.g., using
-@code{waitpid}).
-@item tms:cstime
-Similarly, the CPU times units used by the system on behalf of
-terminated child processes.
-@end table
-@end deffn
-
- get-internal-run-time
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stime.c:220
-@deffn {Scheme Procedure} get-internal-run-time
-@deffnx {C Function} scm_get_internal_run_time ()
-Return the number of time units of processor time used by the
-interpreter. Both @emph{system} and @emph{user} time are
-included but subprocesses are not.
-@end deffn
-
- current-time
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stime.c:230
-@deffn {Scheme Procedure} current-time
-@deffnx {C Function} scm_current_time ()
-Return the number of seconds since 1970-01-01 00:00:00 UTC,
-excluding leap seconds.
-@end deffn
-
- gettimeofday
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stime.c:248
-@deffn {Scheme Procedure} gettimeofday
-@deffnx {C Function} scm_gettimeofday ()
-Return a pair containing the number of seconds and microseconds
-since 1970-01-01 00:00:00 UTC, excluding leap seconds. Note:
-whether true microsecond resolution is available depends on the
-operating system.
-@end deffn
-
- localtime
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stime.c:347
-@deffn {Scheme Procedure} localtime time [zone]
-@deffnx {C Function} scm_localtime (time, zone)
-Return an object representing the broken down components of
-@var{time}, an integer like the one returned by
-@code{current-time}. The time zone for the calculation is
-optionally specified by @var{zone} (a string), otherwise the
-@code{TZ} environment variable or the system default is used.
-@end deffn
-
- gmtime
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stime.c:420
-@deffn {Scheme Procedure} gmtime time
-@deffnx {C Function} scm_gmtime (time)
-Return an object representing the broken down components of
-@var{time}, an integer like the one returned by
-@code{current-time}. The values are calculated for UTC.
-@end deffn
-
- mktime
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stime.c:482
-@deffn {Scheme Procedure} mktime sbd_time [zone]
-@deffnx {C Function} scm_mktime (sbd_time, zone)
-@var{bd-time} is an object representing broken down time and @code{zone}
-is an optional time zone specifier (otherwise the TZ environment variable
-or the system default is used).
-
-Returns a pair: the car is a corresponding
-integer time value like that returned
-by @code{current-time}; the cdr is a broken down time object, similar to
-as @var{bd-time} but with normalized values.
-@end deffn
-
- tzset
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stime.c:556
-@deffn {Scheme Procedure} tzset
-@deffnx {C Function} scm_tzset ()
-Initialize the timezone from the TZ environment variable
-or the system default. It's not usually necessary to call this procedure
-since it's done automatically by other procedures that depend on the
-timezone.
-@end deffn
-
- strftime
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stime.c:573
-@deffn {Scheme Procedure} strftime format stime
-@deffnx {C Function} scm_strftime (format, stime)
-Formats a time specification @var{time} using @var{template}. @var{time}
-is an object with time components in the form returned by @code{localtime}
-or @code{gmtime}. @var{template} is a string which can include formatting
-specifications introduced by a @code{%} character. The formatting of
-month and day names is dependent on the current locale. The value returned
-is the formatted string.
-@xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.)
-@end deffn
-
- strptime
-@c snarfed from /home/ghouston/guile/guile-core/libguile/stime.c:670
-@deffn {Scheme Procedure} strptime format string
-@deffnx {C Function} scm_strptime (format, string)
-Performs the reverse action to @code{strftime}, parsing
-@var{string} according to the specification supplied in
-@var{template}. The interpretation of month and day names is
-dependent on the current locale. The value returned is a pair.
-The car has an object with time components
-in the form returned by @code{localtime} or @code{gmtime},
-but the time zone components
-are not usefully set.
-The cdr reports the number of characters from @var{string}
-which were used for the conversion.
-@end deffn
-
- string?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strings.c:61
-@deffn {Scheme Procedure} string? obj
-@deffnx {C Function} scm_string_p (obj)
-Return @code{#t} if @var{obj} is a string, else @code{#f}.
-@end deffn
-
- list->string
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strings.c:69
-@deffn {Scheme Procedure} list->string
-implemented by the C function "scm_string"
-@end deffn
-
- string
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strings.c:75
-@deffn {Scheme Procedure} string . chrs
-@deffnx {Scheme Procedure} list->string chrs
-@deffnx {C Function} scm_string (chrs)
-Return a newly allocated string composed of the arguments,
-@var{chrs}.
-@end deffn
-
- make-string
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strings.c:209
-@deffn {Scheme Procedure} make-string k [chr]
-@deffnx {C Function} scm_make_string (k, chr)
-Return a newly allocated string of
-length @var{k}. If @var{chr} is given, then all elements of
-the string are initialized to @var{chr}, otherwise the contents
-of the @var{string} are unspecified.
-@end deffn
-
- string-length
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strings.c:242
-@deffn {Scheme Procedure} string-length string
-@deffnx {C Function} scm_string_length (string)
-Return the number of characters in @var{string}.
-@end deffn
-
- string-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strings.c:253
-@deffn {Scheme Procedure} string-ref str k
-@deffnx {C Function} scm_string_ref (str, k)
-Return character @var{k} of @var{str} using zero-origin
-indexing. @var{k} must be a valid index of @var{str}.
-@end deffn
-
- string-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strings.c:270
-@deffn {Scheme Procedure} string-set! str k chr
-@deffnx {C Function} scm_string_set_x (str, k, chr)
-Store @var{chr} in element @var{k} of @var{str} and return
-an unspecified value. @var{k} must be a valid index of
-@var{str}.
-@end deffn
-
- substring
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strings.c:289
-@deffn {Scheme Procedure} substring str start [end]
-@deffnx {C Function} scm_substring (str, start, end)
-Return a newly allocated string formed from the characters
-of @var{str} beginning with index @var{start} (inclusive) and
-ending with index @var{end} (exclusive).
-@var{str} must be a string, @var{start} and @var{end} must be
-exact integers satisfying:
-
-0 <= @var{start} <= @var{end} <= (string-length @var{str}).
-@end deffn
-
- string-append
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strings.c:315
-@deffn {Scheme Procedure} string-append . args
-@deffnx {C Function} scm_string_append (args)
-Return a newly allocated string whose characters form the
-concatenation of the given strings, @var{args}.
-@end deffn
-
- string-index
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strop.c:138
-@deffn {Scheme Procedure} string-index str chr [frm [to]]
-@deffnx {C Function} scm_string_index (str, chr, frm, to)
-Return the index of the first occurrence of @var{chr} in
-@var{str}. The optional integer arguments @var{frm} and
-@var{to} limit the search to a portion of the string. This
-procedure essentially implements the @code{index} or
-@code{strchr} functions from the C library.
-
-@lisp
-(string-index "weiner" #\e)
-@result{} 1
-
-(string-index "weiner" #\e 2)
-@result{} 4
-
-(string-index "weiner" #\e 2 4)
-@result{} #f
-@end lisp
-@end deffn
-
- string-rindex
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strop.c:168
-@deffn {Scheme Procedure} string-rindex str chr [frm [to]]
-@deffnx {C Function} scm_string_rindex (str, chr, frm, to)
-Like @code{string-index}, but search from the right of the
-string rather than from the left. This procedure essentially
-implements the @code{rindex} or @code{strrchr} functions from
-the C library.
-
-@lisp
-(string-rindex "weiner" #\e)
-@result{} 4
-
-(string-rindex "weiner" #\e 2 4)
-@result{} #f
-
-(string-rindex "weiner" #\e 2 5)
-@result{} 4
-@end lisp
-@end deffn
-
- substring-move!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strop.c:188
-@deffn {Scheme Procedure} substring-move! str1 start1 end1 str2 start2
-@deffnx {C Function} scm_substring_move_x (str1, start1, end1, str2, start2)
-Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}
-into @var{str2} beginning at position @var{start2}.
-@var{str1} and @var{str2} can be the same string.
-@end deffn
-
- substring-fill!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strop.c:224
-@deffn {Scheme Procedure} substring-fill! str start end fill
-@deffnx {C Function} scm_substring_fill_x (str, start, end, fill)
-Change every character in @var{str} between @var{start} and
-@var{end} to @var{fill}.
-
-@lisp
-(define y "abcdefg")
-(substring-fill! y 1 3 #\r)
-y
-@result{} "arrdefg"
-@end lisp
-@end deffn
-
- string-null?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strop.c:249
-@deffn {Scheme Procedure} string-null? str
-@deffnx {C Function} scm_string_null_p (str)
-Return @code{#t} if @var{str}'s length is zero, and
-@code{#f} otherwise.
-@lisp
-(string-null? "") @result{} #t
-y @result{} "foo"
-(string-null? y) @result{} #f
-@end lisp
-@end deffn
-
- string->list
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strop.c:263
-@deffn {Scheme Procedure} string->list str
-@deffnx {C Function} scm_string_to_list (str)
-Return a newly allocated list of the characters that make up
-the given string @var{str}. @code{string->list} and
-@code{list->string} are inverses as far as @samp{equal?} is
-concerned.
-@end deffn
-
- string-copy
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strop.c:292
-@deffn {Scheme Procedure} string-copy str
-@deffnx {C Function} scm_string_copy (str)
-Return a newly allocated copy of the given @var{string}.
-@end deffn
-
- string-fill!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strop.c:305
-@deffn {Scheme Procedure} string-fill! str chr
-@deffnx {C Function} scm_string_fill_x (str, chr)
-Store @var{char} in every element of the given @var{string} and
-return an unspecified value.
-@end deffn
-
- string-upcase!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strop.c:340
-@deffn {Scheme Procedure} string-upcase! str
-@deffnx {C Function} scm_string_upcase_x (str)
-Destructively upcase every character in @var{str} and return
-@var{str}.
-@lisp
-y @result{} "arrdefg"
-(string-upcase! y) @result{} "ARRDEFG"
-y @result{} "ARRDEFG"
-@end lisp
-@end deffn
-
- string-upcase
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strop.c:353
-@deffn {Scheme Procedure} string-upcase str
-@deffnx {C Function} scm_string_upcase (str)
-Return a freshly allocated string containing the characters of
-@var{str} in upper case.
-@end deffn
-
- string-downcase!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strop.c:385
-@deffn {Scheme Procedure} string-downcase! str
-@deffnx {C Function} scm_string_downcase_x (str)
-Destructively downcase every character in @var{str} and return
-@var{str}.
-@lisp
-y @result{} "ARRDEFG"
-(string-downcase! y) @result{} "arrdefg"
-y @result{} "arrdefg"
-@end lisp
-@end deffn
-
- string-downcase
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strop.c:398
-@deffn {Scheme Procedure} string-downcase str
-@deffnx {C Function} scm_string_downcase (str)
-Return a freshly allocation string containing the characters in
-@var{str} in lower case.
-@end deffn
-
- string-capitalize!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strop.c:443
-@deffn {Scheme Procedure} string-capitalize! str
-@deffnx {C Function} scm_string_capitalize_x (str)
-Upcase the first character of every word in @var{str}
-destructively and return @var{str}.
-
-@lisp
-y @result{} "hello world"
-(string-capitalize! y) @result{} "Hello World"
-y @result{} "Hello World"
-@end lisp
-@end deffn
-
- string-capitalize
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strop.c:457
-@deffn {Scheme Procedure} string-capitalize str
-@deffnx {C Function} scm_string_capitalize (str)
-Return a freshly allocated string with the characters in
-@var{str}, where the first character of every word is
-capitalized.
-@end deffn
-
- string-split
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strop.c:486
-@deffn {Scheme Procedure} string-split str chr
-@deffnx {C Function} scm_string_split (str, chr)
-Split the string @var{str} into the a list of the substrings delimited
-by appearances of the character @var{chr}. Note that an empty substring
-between separator characters will result in an empty string in the
-result list.
-
-@lisp
-(string-split "root:x:0:0:root:/root:/bin/bash" #\:)
-@result{}
-("root" "x" "0" "0" "root" "/root" "/bin/bash")
-
-(string-split "::" #\:)
-@result{}
-("" "" "")
-
-(string-split "" #\:)
-@result{}
-("")
-@end lisp
-@end deffn
-
- string-ci->symbol
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strop.c:521
-@deffn {Scheme Procedure} string-ci->symbol str
-@deffnx {C Function} scm_string_ci_to_symbol (str)
-Return the symbol whose name is @var{str}. @var{str} is
-converted to lowercase before the conversion is done, if Guile
-is currently reading symbols case-insensitively.
-@end deffn
-
- string=?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strorder.c:62
-@deffn {Scheme Procedure} string=? s1 s2
-Lexicographic equality predicate; return @code{#t} if the two
-strings are the same length and contain the same characters in
-the same positions, otherwise return @code{#f}.
-
-The procedure @code{string-ci=?} treats upper and lower case
-letters as though they were the same character, but
-@code{string=?} treats upper and lower case as distinct
-characters.
-@end deffn
-
- string-ci=?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strorder.c:97
-@deffn {Scheme Procedure} string-ci=? s1 s2
-Case-insensitive string equality predicate; return @code{#t} if
-the two strings are the same length and their component
-characters match (ignoring case) at each position; otherwise
-return @code{#f}.
-@end deffn
-
- string<?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strorder.c:154
-@deffn {Scheme Procedure} string<? s1 s2
-Lexicographic ordering predicate; return @code{#t} if @var{s1}
-is lexicographically less than @var{s2}.
-@end deffn
-
- string<=?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strorder.c:168
-@deffn {Scheme Procedure} string<=? s1 s2
-Lexicographic ordering predicate; return @code{#t} if @var{s1}
-is lexicographically less than or equal to @var{s2}.
-@end deffn
-
- string>?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strorder.c:182
-@deffn {Scheme Procedure} string>? s1 s2
-Lexicographic ordering predicate; return @code{#t} if @var{s1}
-is lexicographically greater than @var{s2}.
-@end deffn
-
- string>=?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strorder.c:196
-@deffn {Scheme Procedure} string>=? s1 s2
-Lexicographic ordering predicate; return @code{#t} if @var{s1}
-is lexicographically greater than or equal to @var{s2}.
-@end deffn
-
- string-ci<?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strorder.c:235
-@deffn {Scheme Procedure} string-ci<? s1 s2
-Case insensitive lexicographic ordering predicate; return
-@code{#t} if @var{s1} is lexicographically less than @var{s2}
-regardless of case.
-@end deffn
-
- string-ci<=?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strorder.c:250
-@deffn {Scheme Procedure} string-ci<=? s1 s2
-Case insensitive lexicographic ordering predicate; return
-@code{#t} if @var{s1} is lexicographically less than or equal
-to @var{s2} regardless of case.
-@end deffn
-
- string-ci>?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strorder.c:265
-@deffn {Scheme Procedure} string-ci>? s1 s2
-Case insensitive lexicographic ordering predicate; return
-@code{#t} if @var{s1} is lexicographically greater than
-@var{s2} regardless of case.
-@end deffn
-
- string-ci>=?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strorder.c:280
-@deffn {Scheme Procedure} string-ci>=? s1 s2
-Case insensitive lexicographic ordering predicate; return
-@code{#t} if @var{s1} is lexicographically greater than or
-equal to @var{s2} regardless of case.
-@end deffn
-
- object->string
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strports.c:321
-@deffn {Scheme Procedure} object->string obj [printer]
-@deffnx {C Function} scm_object_to_string (obj, printer)
-Return a Scheme string obtained by printing @var{obj}.
-Printing function can be specified by the optional second
-argument @var{printer} (default: @code{write}).
-@end deffn
-
- call-with-output-string
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strports.c:345
-@deffn {Scheme Procedure} call-with-output-string proc
-@deffnx {C Function} scm_call_with_output_string (proc)
-Calls the one-argument procedure @var{proc} with a newly created output
-port. When the function returns, the string composed of the characters
-written into the port is returned.
-@end deffn
-
- call-with-input-string
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strports.c:364
-@deffn {Scheme Procedure} call-with-input-string string proc
-@deffnx {C Function} scm_call_with_input_string (string, proc)
-Calls the one-argument procedure @var{proc} with a newly
-created input port from which @var{string}'s contents may be
-read. The value yielded by the @var{proc} is returned.
-@end deffn
-
- open-input-string
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strports.c:377
-@deffn {Scheme Procedure} open-input-string str
-@deffnx {C Function} scm_open_input_string (str)
-Take a string and return an 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.
-@end deffn
-
- open-output-string
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strports.c:391
-@deffn {Scheme Procedure} open-output-string
-@deffnx {C Function} scm_open_output_string ()
-Return an 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.
-@end deffn
-
- get-output-string
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strports.c:408
-@deffn {Scheme Procedure} get-output-string port
-@deffnx {C Function} scm_get_output_string (port)
-Given an output port created by @code{open-output-string},
-return a string consisting of the characters that have been
-output to the port so far.
-@end deffn
-
- eval-string
-@c snarfed from /home/ghouston/guile/guile-core/libguile/strports.c:467
-@deffn {Scheme Procedure} eval-string string
-@deffnx {C Function} scm_eval_string (string)
-Evaluate @var{string} as the text representation of a Scheme
-form or forms, and return whatever value they produce.
-Evaluation takes place in the environment returned by the
-procedure @code{interaction-environment}.
-@end deffn
-
- make-struct-layout
-@c snarfed from /home/ghouston/guile/guile-core/libguile/struct.c:77
-@deffn {Scheme Procedure} make-struct-layout fields
-@deffnx {C Function} scm_make_struct_layout (fields)
-Return a new structure layout object.
-
-@var{fields} must be a string made up of pairs of characters
-strung together. The first character of each pair describes a field
-type, the second a field protection. Allowed types are 'p' for
-GC-protected Scheme data, 'u' for unprotected binary data, and 's' for
-a field that points to the structure itself. Allowed protections
-are 'w' for mutable fields, 'r' for read-only fields, and 'o' for opaque
-fields. The last field protection specification may be capitalized to
-indicate that the field is a tail-array.
-@end deffn
-
- struct?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/struct.c:244
-@deffn {Scheme Procedure} struct? x
-@deffnx {C Function} scm_struct_p (x)
-Return @code{#t} iff @var{x} is a structure object, else
-@code{#f}.
-@end deffn
-
- struct-vtable?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/struct.c:253
-@deffn {Scheme Procedure} struct-vtable? x
-@deffnx {C Function} scm_struct_vtable_p (x)
-Return @code{#t} iff @var{x} is a vtable structure.
-@end deffn
-
- make-struct
-@c snarfed from /home/ghouston/guile/guile-core/libguile/struct.c:434
-@deffn {Scheme Procedure} make-struct vtable tail_array_size . init
-@deffnx {C Function} scm_make_struct (vtable, tail_array_size, init)
-Create a new structure.
-
-@var{type} must be a vtable structure (@pxref{Vtables}).
-
-@var{tail-elts} must be a non-negative integer. If the layout
-specification indicated by @var{type} includes a tail-array,
-this is the number of elements allocated to that array.
-
-The @var{init1}, @dots{} are optional arguments describing how
-successive fields of the structure should be initialized. Only fields
-with protection 'r' or 'w' can be initialized, except for fields of
-type 's', which are automatically initialized to point to the new
-structure itself; fields with protection 'o' can not be initialized by
-Scheme programs.
-
-If fewer optional arguments than initializable fields are supplied,
-fields of type 'p' get default value #f while fields of type 'u' are
-initialized to 0.
-
-Structs are currently the basic representation for record-like data
-structures in Guile. The plan is to eventually replace them with a
-new representation which will at the same time be easier to use and
-more powerful.
-
-For more information, see the documentation for @code{make-vtable-vtable}.
-@end deffn
-
- make-vtable-vtable
-@c snarfed from /home/ghouston/guile/guile-core/libguile/struct.c:519
-@deffn {Scheme Procedure} make-vtable-vtable user_fields tail_array_size . init
-@deffnx {C Function} scm_make_vtable_vtable (user_fields, tail_array_size, init)
-Return a new, self-describing vtable structure.
-
-@var{user-fields} is a string describing user defined fields of the
-vtable beginning at index @code{vtable-offset-user}
-(see @code{make-struct-layout}).
-
-@var{tail-size} specifies the size of the tail-array (if any) of
-this vtable.
-
-@var{init1}, @dots{} are the optional initializers for the fields of
-the vtable.
-
-Vtables have one initializable system field---the struct printer.
-This field comes before the user fields in the initializers passed
-to @code{make-vtable-vtable} and @code{make-struct}, and thus works as
-a third optional argument to @code{make-vtable-vtable} and a fourth to
-@code{make-struct} when creating vtables:
-
-If the value is a procedure, it will be called instead of the standard
-printer whenever a struct described by this vtable is printed.
-The procedure will be called with arguments STRUCT and PORT.
-
-The structure of a struct is described by a vtable, so the vtable is
-in essence the type of the struct. The vtable is itself a struct with
-a vtable. This could go on forever if it weren't for the
-vtable-vtables which are self-describing vtables, and thus terminate
-the chain.
-
-There are several potential ways of using structs, but the standard
-one is to use three kinds of structs, together building up a type
-sub-system: one vtable-vtable working as the root and one or several
-"types", each with a set of "instances". (The vtable-vtable should be
-compared to the class <class> which is the class of itself.)
-
-@lisp
-(define ball-root (make-vtable-vtable "pr" 0))
-
-(define (make-ball-type ball-color)
- (make-struct ball-root 0
- (make-struct-layout "pw")
- (lambda (ball port)
- (format port "#<a ~A ball owned by ~A>"
- (color ball)
- (owner ball)))
- ball-color))
-(define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user))
-(define (owner ball) (struct-ref ball 0))
-
-(define red (make-ball-type 'red))
-(define green (make-ball-type 'green))
-
-(define (make-ball type owner) (make-struct type 0 owner))
-
-(define ball (make-ball green 'Nisse))
-ball @result{} #<a green ball owned by Nisse>
-@end lisp
-@end deffn
-
- struct-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/struct.c:560
-@deffn {Scheme Procedure} struct-ref handle pos
-@deffnx {Scheme Procedure} struct-set! struct n value
-@deffnx {C Function} scm_struct_ref (handle, pos)
-Access (or modify) the @var{n}th field of @var{struct}.
-
-If the field is of type 'p', then it can be set to an arbitrary value.
-
-If the field is of type 'u', then it can only be set to a non-negative
-integer value small enough to fit in one machine word.
-@end deffn
-
- struct-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/struct.c:638
-@deffn {Scheme Procedure} struct-set! handle pos val
-@deffnx {C Function} scm_struct_set_x (handle, pos, val)
-Set the slot of the structure @var{handle} with index @var{pos}
-to @var{val}. Signal an error if the slot can not be written
-to.
-@end deffn
-
- struct-vtable
-@c snarfed from /home/ghouston/guile/guile-core/libguile/struct.c:708
-@deffn {Scheme Procedure} struct-vtable handle
-@deffnx {C Function} scm_struct_vtable (handle)
-Return the vtable structure that describes the type of @var{struct}.
-@end deffn
-
- struct-vtable-tag
-@c snarfed from /home/ghouston/guile/guile-core/libguile/struct.c:719
-@deffn {Scheme Procedure} struct-vtable-tag handle
-@deffnx {C Function} scm_struct_vtable_tag (handle)
-Return the vtable tag of the structure @var{handle}.
-@end deffn
-
- struct-vtable-name
-@c snarfed from /home/ghouston/guile/guile-core/libguile/struct.c:758
-@deffn {Scheme Procedure} struct-vtable-name vtable
-@deffnx {C Function} scm_struct_vtable_name (vtable)
-Return the name of the vtable @var{vtable}.
-@end deffn
-
- set-struct-vtable-name!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/struct.c:768
-@deffn {Scheme Procedure} set-struct-vtable-name! vtable name
-@deffnx {C Function} scm_set_struct_vtable_name_x (vtable, name)
-Set the name of the vtable @var{vtable} to @var{name}.
-@end deffn
-
- symbol?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/symbols.c:164
-@deffn {Scheme Procedure} symbol? obj
-@deffnx {C Function} scm_symbol_p (obj)
-Return @code{#t} if @var{obj} is a symbol, otherwise return
-@code{#f}.
-@end deffn
-
- symbol-interned?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/symbols.c:174
-@deffn {Scheme Procedure} symbol-interned? symbol
-@deffnx {C Function} scm_symbol_interned_p (symbol)
-Return @code{#t} if @var{symbol} is interned, otherwise return
-@code{#f}.
-@end deffn
-
- make-symbol
-@c snarfed from /home/ghouston/guile/guile-core/libguile/symbols.c:186
-@deffn {Scheme Procedure} make-symbol name
-@deffnx {C Function} scm_make_symbol (name)
-Return a new uninterned symbol with the name @var{name}. The returned symbol is guaranteed to be unique and future calls to @code{string->symbol} will not return it.
-@end deffn
-
- symbol->string
-@c snarfed from /home/ghouston/guile/guile-core/libguile/symbols.c:222
-@deffn {Scheme Procedure} symbol->string s
-@deffnx {C Function} scm_symbol_to_string (s)
-Return the name of @var{symbol} as a string. If the symbol was
-part of an object returned as the value of a literal expression
-(section @pxref{Literal expressions,,,r5rs, The Revised^5
-Report on Scheme}) or by a call to the @code{read} procedure,
-and its name contains alphabetic characters, then the string
-returned will contain characters in the implementation's
-preferred standard case---some implementations will prefer
-upper case, others lower case. If the symbol was returned by
-@code{string->symbol}, the case of characters in the string
-returned will be the same as the case in the string that was
-passed to @code{string->symbol}. It is an error to apply
-mutation procedures like @code{string-set!} to strings returned
-by this procedure.
-
-The following examples assume that the implementation's
-standard case is lower case:
-
-@lisp
-(symbol->string 'flying-fish) @result{} "flying-fish"
-(symbol->string 'Martin) @result{} "martin"
-(symbol->string
- (string->symbol "Malvina")) @result{} "Malvina"
-@end lisp
-@end deffn
-
- string->symbol
-@c snarfed from /home/ghouston/guile/guile-core/libguile/symbols.c:255
-@deffn {Scheme Procedure} string->symbol string
-@deffnx {C Function} scm_string_to_symbol (string)
-Return the symbol whose name is @var{string}. This procedure
-can create symbols with names containing special characters or
-letters in the non-standard case, but it is usually a bad idea
-to create such symbols because in some implementations of
-Scheme they cannot be read as themselves. See
-@code{symbol->string}.
-
-The following examples assume that the implementation's
-standard case is lower case:
-
-@lisp
-(eq? 'mISSISSIppi 'mississippi) @result{} #t
-(string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"}
-(eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
-(eq? 'JollyWog
- (string->symbol (symbol->string 'JollyWog))) @result{} #t
-(string=? "K. Harper, M.D."
- (symbol->string
- (string->symbol "K. Harper, M.D."))) @result{}#t
-@end lisp
-@end deffn
-
- gensym
-@c snarfed from /home/ghouston/guile/guile-core/libguile/symbols.c:277
-@deffn {Scheme Procedure} gensym [prefix]
-@deffnx {C Function} scm_gensym (prefix)
-Create a new symbol with a name constructed from a prefix and
-a counter value. The string @var{prefix} can be specified as
-an optional argument. Default prefix is @code{ g}. The counter
-is increased by 1 at each call. There is no provision for
-resetting the counter.
-@end deffn
-
- symbol-hash
-@c snarfed from /home/ghouston/guile/guile-core/libguile/symbols.c:309
-@deffn {Scheme Procedure} symbol-hash symbol
-@deffnx {C Function} scm_symbol_hash (symbol)
-Return a hash value for @var{symbol}.
-@end deffn
-
- symbol-fref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/symbols.c:319
-@deffn {Scheme Procedure} symbol-fref s
-@deffnx {C Function} scm_symbol_fref (s)
-Return the contents of @var{symbol}'s @dfn{function slot}.
-@end deffn
-
- symbol-pref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/symbols.c:330
-@deffn {Scheme Procedure} symbol-pref s
-@deffnx {C Function} scm_symbol_pref (s)
-Return the @dfn{property list} currently associated with @var{symbol}.
-@end deffn
-
- symbol-fset!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/symbols.c:341
-@deffn {Scheme Procedure} symbol-fset! s val
-@deffnx {C Function} scm_symbol_fset_x (s, val)
-Change the binding of @var{symbol}'s function slot.
-@end deffn
-
- symbol-pset!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/symbols.c:353
-@deffn {Scheme Procedure} symbol-pset! s val
-@deffnx {C Function} scm_symbol_pset_x (s, val)
-Change the binding of @var{symbol}'s property slot.
-@end deffn
-
- catch
-@c snarfed from /home/ghouston/guile/guile-core/libguile/throw.c:534
-@deffn {Scheme Procedure} catch key thunk handler
-@deffnx {C Function} scm_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:
-@lisp
-(handler key args ...)
-@end lisp
-
-@var{key} is a symbol or @code{#t}.
-
-@var{thunk} takes no arguments. If @var{thunk} returns
-normally, that is the return value of @code{catch}.
-
-Handler is invoked outside the scope of its own @code{catch}.
-If @var{handler} 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}.
-@end deffn
-
- lazy-catch
-@c snarfed from /home/ghouston/guile/guile-core/libguile/throw.c:562
-@deffn {Scheme Procedure} lazy-catch key thunk handler
-@deffnx {C Function} scm_lazy_catch (key, thunk, handler)
-This behaves exactly like @code{catch}, except that it does
-not unwind the stack before invoking @var{handler}.
-The @var{handler} procedure is not allowed to return:
-it must throw to another catch, or otherwise exit non-locally.
-@end deffn
-
- throw
-@c snarfed from /home/ghouston/guile/guile-core/libguile/throw.c:595
-@deffn {Scheme Procedure} throw key . args
-@deffnx {C Function} scm_throw (key, args)
-Invoke the catch form matching @var{key}, passing @var{args} to the
-@var{handler}.
-
-@var{key} is a symbol. It will match catches of the same symbol or of
-@code{#t}.
-
-If there is no handler at all, Guile prints an error and then exits.
-@end deffn
-
- values
-@c snarfed from /home/ghouston/guile/guile-core/libguile/values.c:77
-@deffn {Scheme Procedure} values . args
-@deffnx {C Function} scm_values (args)
-Delivers all of its arguments to its continuation. Except for
-continuations created by the @code{call-with-values} procedure,
-all continuations take exactly one value. The effect of
-passing no value or more than one value to continuations that
-were not created by @code{call-with-values} is unspecified.
-@end deffn
-
- make-variable
-@c snarfed from /home/ghouston/guile/guile-core/libguile/variable.c:76
-@deffn {Scheme Procedure} make-variable init
-@deffnx {C Function} scm_make_variable (init)
-Return a variable initialized to value @var{init}.
-@end deffn
-
- make-undefined-variable
-@c snarfed from /home/ghouston/guile/guile-core/libguile/variable.c:86
-@deffn {Scheme Procedure} make-undefined-variable
-@deffnx {C Function} scm_make_undefined_variable ()
-Return a variable that is initially unbound.
-@end deffn
-
- variable?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/variable.c:97
-@deffn {Scheme Procedure} variable? obj
-@deffnx {C Function} scm_variable_p (obj)
-Return @code{#t} iff @var{obj} is a variable object, else
-return @code{#f}.
-@end deffn
-
- variable-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/variable.c:109
-@deffn {Scheme Procedure} variable-ref var
-@deffnx {C Function} scm_variable_ref (var)
-Dereference @var{var} and return its value.
-@var{var} must be a variable object; see @code{make-variable}
-and @code{make-undefined-variable}.
-@end deffn
-
- variable-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/variable.c:125
-@deffn {Scheme Procedure} variable-set! var val
-@deffnx {C Function} scm_variable_set_x (var, val)
-Set the value of the variable @var{var} to @var{val}.
-@var{var} must be a variable object, @var{val} can be any
-value. Return an unspecified value.
-@end deffn
-
- variable-bound?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/variable.c:137
-@deffn {Scheme Procedure} variable-bound? var
-@deffnx {C Function} scm_variable_bound_p (var)
-Return @code{#t} iff @var{var} is bound to a value.
-Throws an error if @var{var} is not a variable object.
-@end deffn
-
- vector?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/vectors.c:59
-@deffn {Scheme Procedure} vector? obj
-@deffnx {C Function} scm_vector_p (obj)
-Return @code{#t} if @var{obj} is a vector, otherwise return
-@code{#f}.
-@end deffn
-
- list->vector
-@c snarfed from /home/ghouston/guile/guile-core/libguile/vectors.c:76
-@deffn {Scheme Procedure} list->vector
-implemented by the C function "scm_vector"
-@end deffn
-
- vector
-@c snarfed from /home/ghouston/guile/guile-core/libguile/vectors.c:93
-@deffn {Scheme Procedure} vector . l
-@deffnx {Scheme Procedure} list->vector l
-@deffnx {C Function} scm_vector (l)
-Return a newly allocated vector composed of the
-given arguments. Analogous to @code{list}.
-
-@lisp
-(vector 'a 'b 'c) @result{} #(a b c)
-@end lisp
-@end deffn
-
- make-vector
-@c snarfed from /home/ghouston/guile/guile-core/libguile/vectors.c:179
-@deffn {Scheme Procedure} make-vector k [fill]
-@deffnx {C Function} scm_make_vector (k, fill)
-Return a newly allocated vector of @var{k} elements. If a
-second argument is given, then each position is initialized to
-@var{fill}. Otherwise the initial contents of each position is
-unspecified.
-@end deffn
-
- vector->list
-@c snarfed from /home/ghouston/guile/guile-core/libguile/vectors.c:233
-@deffn {Scheme Procedure} vector->list v
-@deffnx {C Function} scm_vector_to_list (v)
-Return a newly allocated list composed of the elements of @var{v}.
-
-@lisp
-(vector->list '#(dah dah didah)) @result{} (dah dah didah)
-(list->vector '(dididit dah)) @result{} #(dididit dah)
-@end lisp
-@end deffn
-
- vector-fill!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/vectors.c:250
-@deffn {Scheme Procedure} vector-fill! v fill
-@deffnx {C Function} scm_vector_fill_x (v, fill)
-Store @var{fill} in every position of @var{vector}. The value
-returned by @code{vector-fill!} is unspecified.
-@end deffn
-
- vector-move-left!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/vectors.c:283
-@deffn {Scheme Procedure} vector-move-left! vec1 start1 end1 vec2 start2
-@deffnx {C Function} scm_vector_move_left_x (vec1, start1, end1, vec2, start2)
-Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
-to @var{vec2} starting at position @var{start2}. @var{start1} and
-@var{start2} are inclusive indices; @var{end1} is exclusive.
-
-@code{vector-move-left!} copies elements in leftmost order.
-Therefore, in the case where @var{vec1} and @var{vec2} refer to the
-same vector, @code{vector-move-left!} is usually appropriate when
-@var{start1} is greater than @var{start2}.
-@end deffn
-
- vector-move-right!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/vectors.c:312
-@deffn {Scheme Procedure} vector-move-right! vec1 start1 end1 vec2 start2
-@deffnx {C Function} scm_vector_move_right_x (vec1, start1, end1, vec2, start2)
-Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
-to @var{vec2} starting at position @var{start2}. @var{start1} and
-@var{start2} are inclusive indices; @var{end1} is exclusive.
-
-@code{vector-move-right!} copies elements in rightmost order.
-Therefore, in the case where @var{vec1} and @var{vec2} refer to the
-same vector, @code{vector-move-right!} is usually appropriate when
-@var{start1} is less than @var{start2}.
-@end deffn
-
- major-version
-@c snarfed from /home/ghouston/guile/guile-core/libguile/version.c:59
-@deffn {Scheme Procedure} major-version
-@deffnx {C Function} scm_major_version ()
-Return a string containing Guile's major version number.
-E.g., the 1 in "1.6.5".
-@end deffn
-
- minor-version
-@c snarfed from /home/ghouston/guile/guile-core/libguile/version.c:72
-@deffn {Scheme Procedure} minor-version
-@deffnx {C Function} scm_minor_version ()
-Return a string containing Guile's minor version number.
-E.g., the 6 in "1.6.5".
-@end deffn
-
- micro-version
-@c snarfed from /home/ghouston/guile/guile-core/libguile/version.c:85
-@deffn {Scheme Procedure} micro-version
-@deffnx {C Function} scm_micro_version ()
-Return a string containing Guile's micro version number.
-E.g., the 5 in "1.6.5".
-@end deffn
-
- version
-@c snarfed from /home/ghouston/guile/guile-core/libguile/version.c:107
-@deffn {Scheme Procedure} version
-@deffnx {Scheme Procedure} major-version
-@deffnx {Scheme Procedure} minor-version
-@deffnx {Scheme Procedure} micro-version
-@deffnx {C Function} scm_version ()
-Return a string describing Guile's version number, or its major, minor
-or micro version number, respectively.
-
-@lisp
-(version) @result{} "1.6.0"
-(major-version) @result{} "1"
-(minor-version) @result{} "6"
-(micro-version) @result{} "0"
-@end lisp
-@end deffn
-
- make-soft-port
-@c snarfed from /home/ghouston/guile/guile-core/libguile/vports.c:185
-@deffn {Scheme Procedure} make-soft-port pv modes
-@deffnx {C Function} scm_make_soft_port (pv, modes)
-Return a port capable of receiving or delivering characters as
-specified by the @var{modes} string (@pxref{File Ports,
-open-file}). @var{pv} must be a vector of length 5. Its
-components are as follows:
-
-@enumerate 0
-@item
-procedure accepting one character for output
-@item
-procedure accepting a string for output
-@item
-thunk for flushing output
-@item
-thunk for getting one character
-@item
-thunk for closing port (not by garbage collection)
-@end enumerate
-
-For an output-only port only elements 0, 1, 2, and 4 need be
-procedures. For an input-only port only elements 3 and 4 need
-be procedures. Thunks 2 and 4 can instead be @code{#f} if
-there is no useful operation for them to perform.
-
-If thunk 3 returns @code{#f} or an @code{eof-object}
-(@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on
-Scheme}) it indicates that the port has reached end-of-file.
-For example:
-
-@lisp
-(define stdout (current-output-port))
-(define p (make-soft-port
- (vector
- (lambda (c) (write c stdout))
- (lambda (s) (display s stdout))
- (lambda () (display "." stdout))
- (lambda () (char-upcase (read-char)))
- (lambda () (display "@@" stdout)))
- "rw"))
-
-(write p p) @result{} #<input-output: soft 8081e20>
-@end lisp
-@end deffn
-
- make-weak-vector
-@c snarfed from /home/ghouston/guile/guile-core/libguile/weaks.c:116
-@deffn {Scheme Procedure} make-weak-vector size [fill]
-@deffnx {C Function} scm_make_weak_vector (size, fill)
-Return a weak vector with @var{size} elements. If the optional
-argument @var{fill} is given, all entries in the vector will be
-set to @var{fill}. The default value for @var{fill} is the
-empty list.
-@end deffn
-
- list->weak-vector
-@c snarfed from /home/ghouston/guile/guile-core/libguile/weaks.c:124
-@deffn {Scheme Procedure} list->weak-vector
-implemented by the C function "scm_weak_vector"
-@end deffn
-
- weak-vector
-@c snarfed from /home/ghouston/guile/guile-core/libguile/weaks.c:132
-@deffn {Scheme Procedure} weak-vector . l
-@deffnx {Scheme Procedure} list->weak-vector l
-@deffnx {C Function} scm_weak_vector (l)
-Construct a weak vector from a list: @code{weak-vector} uses
-the list of its arguments while @code{list->weak-vector} uses
-its only argument @var{l} (a list) to construct a weak vector
-the same way @code{list->vector} would.
-@end deffn
-
- weak-vector?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/weaks.c:160
-@deffn {Scheme Procedure} weak-vector? obj
-@deffnx {C Function} scm_weak_vector_p (obj)
-Return @code{#t} if @var{obj} is a weak vector. Note that all
-weak hashes are also weak vectors.
-@end deffn
-
- make-weak-key-hash-table
-@c snarfed from /home/ghouston/guile/guile-core/libguile/weaks.c:178
-@deffn {Scheme Procedure} make-weak-key-hash-table size
-@deffnx {Scheme Procedure} make-weak-value-hash-table size
-@deffnx {Scheme Procedure} make-doubly-weak-hash-table size
-@deffnx {C Function} scm_make_weak_key_hash_table (size)
-Return a weak hash table with @var{size} buckets. As with any
-hash table, choosing a good size for the table requires some
-caution.
-
-You can modify weak hash tables in exactly the same way you
-would modify regular hash tables. (@pxref{Hash Tables})
-@end deffn
-
- make-weak-value-hash-table
-@c snarfed from /home/ghouston/guile/guile-core/libguile/weaks.c:189
-@deffn {Scheme Procedure} make-weak-value-hash-table size
-@deffnx {C Function} scm_make_weak_value_hash_table (size)
-Return a hash table with weak values with @var{size} buckets.
-(@pxref{Hash Tables})
-@end deffn
-
- make-doubly-weak-hash-table
-@c snarfed from /home/ghouston/guile/guile-core/libguile/weaks.c:200
-@deffn {Scheme Procedure} make-doubly-weak-hash-table size
-@deffnx {C Function} scm_make_doubly_weak_hash_table (size)
-Return a hash table with weak keys and values with @var{size}
-buckets. (@pxref{Hash Tables})
-@end deffn
-
- weak-key-hash-table?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/weaks.c:214
-@deffn {Scheme Procedure} weak-key-hash-table? obj
-@deffnx {Scheme Procedure} weak-value-hash-table? obj
-@deffnx {Scheme Procedure} doubly-weak-hash-table? obj
-@deffnx {C Function} scm_weak_key_hash_table_p (obj)
-Return @code{#t} if @var{obj} is the specified weak hash
-table. Note that a doubly weak hash table is neither a weak key
-nor a weak value hash table.
-@end deffn
-
- weak-value-hash-table?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/weaks.c:224
-@deffn {Scheme Procedure} weak-value-hash-table? obj
-@deffnx {C Function} scm_weak_value_hash_table_p (obj)
-Return @code{#t} if @var{obj} is a weak value hash table.
-@end deffn
-
- doubly-weak-hash-table?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/weaks.c:234
-@deffn {Scheme Procedure} doubly-weak-hash-table? obj
-@deffnx {C Function} scm_doubly_weak_hash_table_p (obj)
-Return @code{#t} if @var{obj} is a doubly weak hash table.
-@end deffn
-
- array-fill!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ramap.c:462
-@deffn {Scheme Procedure} array-fill! ra fill
-@deffnx {C Function} scm_array_fill_x (ra, fill)
-Store @var{fill} in every element of @var{array}. The value returned
-is unspecified.
-@end deffn
-
- array-copy-in-order!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ramap.c:827
-@deffn {Scheme Procedure} array-copy-in-order!
-implemented by the C function "scm_array_copy_x"
-@end deffn
-
- array-copy!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ramap.c:836
-@deffn {Scheme Procedure} array-copy! src dst
-@deffnx {Scheme Procedure} array-copy-in-order! src dst
-@deffnx {C Function} scm_array_copy_x (src, dst)
-Copy every element from vector or array @var{source} to the
-corresponding element of @var{destination}. @var{destination} must have
-the same rank as @var{source}, and be at least as large in each
-dimension. The order is unspecified.
-@end deffn
-
- array-map-in-order!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ramap.c:1510
-@deffn {Scheme Procedure} array-map-in-order!
-implemented by the C function "scm_array_map_x"
-@end deffn
-
- array-map!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ramap.c:1521
-@deffn {Scheme Procedure} array-map! ra0 proc . lra
-@deffnx {Scheme Procedure} array-map-in-order! ra0 proc . lra
-@deffnx {C Function} scm_array_map_x (ra0, proc, lra)
-@var{array1}, @dots{} must have the same number of dimensions as
-@var{array0} and have a range for each index which includes the range
-for the corresponding index in @var{array0}. @var{proc} is applied to
-each tuple of elements of @var{array1} @dots{} and the result is stored
-as the corresponding element in @var{array0}. The value returned is
-unspecified. The order of application is unspecified.
-@end deffn
-
- array-for-each
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ramap.c:1668
-@deffn {Scheme Procedure} array-for-each proc ra0 . lra
-@deffnx {C Function} scm_array_for_each (proc, ra0, lra)
-Apply @var{proc} to each tuple of elements of @var{array0} @dots{}
-in row-major order. The value returned is unspecified.
-@end deffn
-
- array-index-map!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/ramap.c:1696
-@deffn {Scheme Procedure} array-index-map! ra proc
-@deffnx {C Function} scm_array_index_map_x (ra, proc)
-Apply @var{proc} to the indices of each element of @var{array} in
-turn, storing the result in the corresponding element. The value
-returned and the order of application are unspecified.
-
-One can implement @var{array-indexes} as
-@lisp
-(define (array-indexes array)
- (let ((ra (apply make-array #f (array-shape array))))
- (array-index-map! ra (lambda x x))
- ra))
-@end lisp
-Another example:
-@lisp
-(define (apl:index-generator n)
- (let ((v (make-uniform-vector n 1)))
- (array-index-map! v (lambda (i) i))
- v))
-@end lisp
-@end deffn
-
- uniform-vector-length
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:250
-@deffn {Scheme Procedure} uniform-vector-length v
-@deffnx {C Function} scm_uniform_vector_length (v)
-Return the number of elements in @var{uve}.
-@end deffn
-
- array?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:284
-@deffn {Scheme Procedure} array? v [prot]
-@deffnx {C Function} scm_array_p (v, prot)
-Return @code{#t} if the @var{obj} is an array, and @code{#f} if
-not. The @var{prototype} argument is used with uniform arrays
-and is described elsewhere.
-@end deffn
-
- array-rank
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:355
-@deffn {Scheme Procedure} array-rank ra
-@deffnx {C Function} scm_array_rank (ra)
-Return the number of dimensions of @var{obj}. If @var{obj} is
-not an array, @code{0} is returned.
-@end deffn
-
- array-dimensions
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:393
-@deffn {Scheme Procedure} array-dimensions ra
-@deffnx {C Function} scm_array_dimensions (ra)
-@code{Array-dimensions} is similar to @code{array-shape} but replaces
-elements with a @code{0} minimum with one greater than the maximum. So:
-@lisp
-(array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)
-@end lisp
-@end deffn
-
- shared-array-root
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:440
-@deffn {Scheme Procedure} shared-array-root ra
-@deffnx {C Function} scm_shared_array_root (ra)
-Return the root vector of a shared array.
-@end deffn
-
- shared-array-offset
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:451
-@deffn {Scheme Procedure} shared-array-offset ra
-@deffnx {C Function} scm_shared_array_offset (ra)
-Return the root vector index of the first element in the array.
-@end deffn
-
- shared-array-increments
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:462
-@deffn {Scheme Procedure} shared-array-increments ra
-@deffnx {C Function} scm_shared_array_increments (ra)
-For each dimension, return the distance between elements in the root vector.
-@end deffn
-
- dimensions->uniform-array
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:581
-@deffn {Scheme Procedure} dimensions->uniform-array dims prot [fill]
-@deffnx {Scheme Procedure} make-uniform-vector length prototype [fill]
-@deffnx {C Function} scm_dimensions_to_uniform_array (dims, prot, fill)
-Create and return a uniform array or vector of type
-corresponding to @var{prototype} with dimensions @var{dims} or
-length @var{length}. If @var{fill} is supplied, it's used to
-fill the array, otherwise @var{prototype} is used.
-@end deffn
-
- make-shared-array
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:670
-@deffn {Scheme Procedure} make-shared-array oldra mapfunc . dims
-@deffnx {C Function} scm_make_shared_array (oldra, mapfunc, dims)
-@code{make-shared-array} can be used to create shared subarrays of other
-arrays. The @var{mapper} is a function that translates coordinates in
-the new array into coordinates in the old array. A @var{mapper} must be
-linear, and its range must stay within the bounds of the old array, but
-it can be otherwise arbitrary. A simple example:
-@lisp
-(define fred (make-array #f 8 8))
-(define freds-diagonal
- (make-shared-array fred (lambda (i) (list i i)) 8))
-(array-set! freds-diagonal 'foo 3)
-(array-ref fred 3 3) @result{} foo
-(define freds-center
- (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
-(array-ref freds-center 0 0) @result{} foo
-@end lisp
-@end deffn
-
- transpose-array
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:802
-@deffn {Scheme Procedure} transpose-array ra . args
-@deffnx {C Function} scm_transpose_array (ra, args)
-Return an array sharing contents with @var{array}, but with
-dimensions arranged in a different order. There must be one
-@var{dim} argument for each dimension of @var{array}.
-@var{dim0}, @var{dim1}, @dots{} should be integers between 0
-and the rank of the array to be returned. Each integer in that
-range must appear at least once in the argument list.
-
-The values of @var{dim0}, @var{dim1}, @dots{} correspond to
-dimensions in the array to be returned, their positions in the
-argument list to dimensions of @var{array}. Several @var{dim}s
-may have the same value, in which case the returned array will
-have smaller rank than @var{array}.
-
-@lisp
-(transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))
-(transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)
-(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}
- #2((a 4) (b 5) (c 6))
-@end lisp
-@end deffn
-
- enclose-array
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:911
-@deffn {Scheme Procedure} enclose-array ra . axes
-@deffnx {C Function} scm_enclose_array (ra, axes)
-@var{dim0}, @var{dim1} @dots{} should be nonnegative integers less than
-the rank of @var{array}. @var{enclose-array} returns an array
-resembling an array of shared arrays. The dimensions of each shared
-array are the same as the @var{dim}th dimensions of the original array,
-the dimensions of the outer array are the same as those of the original
-array that did not match a @var{dim}.
-
-An enclosed array is not a general Scheme array. Its elements may not
-be set using @code{array-set!}. Two references to the same element of
-an enclosed array will be @code{equal?} but will not in general be
-@code{eq?}. The value returned by @var{array-prototype} when given an
-enclosed array is unspecified.
-
-examples:
-@lisp
-(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}
- #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
-
-(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}
- #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
-@end lisp
-@end deffn
-
- array-in-bounds?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:995
-@deffn {Scheme Procedure} array-in-bounds? v . args
-@deffnx {C Function} scm_array_in_bounds_p (v, args)
-Return @code{#t} if its arguments would be acceptable to
-@code{array-ref}.
-@end deffn
-
- array-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:1074
-@deffn {Scheme Procedure} array-ref
-implemented by the C function "scm_uniform_vector_ref"
-@end deffn
-
- uniform-vector-ref
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:1081
-@deffn {Scheme Procedure} uniform-vector-ref v args
-@deffnx {Scheme Procedure} array-ref v . args
-@deffnx {C Function} scm_uniform_vector_ref (v, args)
-Return the element at the @code{(index1, index2)} element in
-@var{array}.
-@end deffn
-
- uniform-array-set1!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:1250
-@deffn {Scheme Procedure} uniform-array-set1!
-implemented by the C function "scm_array_set_x"
-@end deffn
-
- array-set!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:1259
-@deffn {Scheme Procedure} array-set! v obj . args
-@deffnx {Scheme Procedure} uniform-array-set1! v obj args
-@deffnx {C Function} scm_array_set_x (v, obj, args)
-Set the element at the @code{(index1, index2)} element in @var{array} to
-@var{new-value}. The value returned by array-set! is unspecified.
-@end deffn
-
- array-contents
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:1374
-@deffn {Scheme Procedure} array-contents ra [strict]
-@deffnx {C Function} scm_array_contents (ra, strict)
-If @var{array} may be @dfn{unrolled} into a one dimensional shared array
-without changing their order (last subscript changing fastest), then
-@code{array-contents} returns that shared array, otherwise it returns
-@code{#f}. All arrays made by @var{make-array} and
-@var{make-uniform-array} may be unrolled, some arrays made by
-@var{make-shared-array} may not be.
-
-If the optional argument @var{strict} is provided, a shared array will
-be returned only if its elements are stored internally contiguous in
-memory.
-@end deffn
-
- uniform-array-read!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:1488
-@deffn {Scheme Procedure} uniform-array-read! ra [port_or_fd [start [end]]]
-@deffnx {Scheme Procedure} uniform-vector-read! uve [port-or-fdes] [start] [end]
-@deffnx {C Function} scm_uniform_array_read_x (ra, port_or_fd, start, end)
-Attempt to read all elements of @var{ura}, in lexicographic order, as
-binary objects from @var{port-or-fdes}.
-If an end of file is encountered,
-the objects up to that point are put into @var{ura}
-(starting at the beginning) and the remainder of the array is
-unchanged.
-
-The optional arguments @var{start} and @var{end} allow
-a specified region of a vector (or linearized array) to be read,
-leaving the remainder of the vector unchanged.
-
-@code{uniform-array-read!} returns the number of objects read.
-@var{port-or-fdes} may be omitted, in which case it defaults to the value
-returned by @code{(current-input-port)}.
-@end deffn
-
- uniform-array-write
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:1653
-@deffn {Scheme Procedure} uniform-array-write v [port_or_fd [start [end]]]
-@deffnx {Scheme Procedure} uniform-vector-write uve [port-or-fdes] [start] [end]
-@deffnx {C Function} scm_uniform_array_write (v, port_or_fd, start, end)
-Writes all elements of @var{ura} as binary objects to
-@var{port-or-fdes}.
-
-The optional arguments @var{start}
-and @var{end} allow
-a specified region of a vector (or linearized array) to be written.
-
-The number of objects actually written is returned.
-@var{port-or-fdes} may be
-omitted, in which case it defaults to the value returned by
-@code{(current-output-port)}.
-@end deffn
-
- bit-count
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:1780
-@deffn {Scheme Procedure} bit-count b bitvector
-@deffnx {C Function} scm_bit_count (b, bitvector)
-Return the number of occurrences of the boolean @var{b} in
-@var{bitvector}.
-@end deffn
-
- bit-position
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:1819
-@deffn {Scheme Procedure} bit-position item v k
-@deffnx {C Function} scm_bit_position (item, v, k)
-Return the minimum index of an occurrence of @var{bool} in
-@var{bv} which is at least @var{k}. If no @var{bool} occurs
-within the specified range @code{#f} is returned.
-@end deffn
-
- bit-set*!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:1887
-@deffn {Scheme Procedure} bit-set*! v kv obj
-@deffnx {C Function} scm_bit_set_star_x (v, kv, obj)
-If uve is a bit-vector @var{bv} and uve must be of the same
-length. If @var{bool} is @code{#t}, uve is OR'ed into
-@var{bv}; If @var{bool} is @code{#f}, the inversion of uve is
-AND'ed into @var{bv}.
-
-If uve is a unsigned long integer vector all the elements of uve
-must be between 0 and the @code{length} of @var{bv}. The bits
-of @var{bv} corresponding to the indexes in uve are set to
-@var{bool}. The return value is unspecified.
-@end deffn
-
- bit-count*
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:1941
-@deffn {Scheme Procedure} bit-count* v kv obj
-@deffnx {C Function} scm_bit_count_star (v, kv, obj)
-Return
-@lisp
-(bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).
-@end lisp
-@var{bv} is not modified.
-@end deffn
-
- bit-invert!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:2005
-@deffn {Scheme Procedure} bit-invert! v
-@deffnx {C Function} scm_bit_invert_x (v)
-Modify @var{bv} by replacing each element with its negation.
-@end deffn
-
- array->list
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:2084
-@deffn {Scheme Procedure} array->list v
-@deffnx {C Function} scm_array_to_list (v)
-Return a list consisting of all the elements, in order, of
-@var{array}.
-@end deffn
-
- list->uniform-array
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:2185
-@deffn {Scheme Procedure} list->uniform-array ndim prot lst
-@deffnx {Scheme Procedure} list->uniform-vector prot lst
-@deffnx {C Function} scm_list_to_uniform_array (ndim, prot, lst)
-Return a uniform array of the type indicated by prototype
-@var{prot} with elements the same as those of @var{lst}.
-Elements must be of the appropriate type, no coercions are
-done.
-@end deffn
-
- array-prototype
-@c snarfed from /home/ghouston/guile/guile-core/libguile/unif.c:2536
-@deffn {Scheme Procedure} array-prototype ra
-@deffnx {C Function} scm_array_prototype (ra)
-Return an object that would produce an array of the same type
-as @var{array}, if used as the @var{prototype} for
-@code{make-uniform-array}.
-@end deffn
-
- chown
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:214
-@deffn {Scheme Procedure} chown object owner group
-@deffnx {C Function} scm_chown (object, owner, group)
-Change the ownership and group of the file referred to by @var{object} to
-the integer values @var{owner} and @var{group}. @var{object} can be
-a string containing a file name or, if the platform
-supports fchown, a port or integer file descriptor
-which is open on the file. The return value
-is unspecified.
-
-If @var{object} is a symbolic link, either the
-ownership of the link or the ownership of the referenced file will be
-changed depending on the operating system (lchown is
-unsupported at present). If @var{owner} or @var{group} is specified
-as @code{-1}, then that ID is not changed.
-@end deffn
-
- chmod
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:254
-@deffn {Scheme Procedure} chmod object mode
-@deffnx {C Function} scm_chmod (object, mode)
-Changes the permissions of the file referred to by @var{obj}.
-@var{obj} can be a string containing a file name or a port or integer file
-descriptor which is open on a file (in which case @code{fchmod} is used
-as the underlying system call).
-@var{mode} specifies
-the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}.
-The return value is unspecified.
-@end deffn
-
- umask
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:287
-@deffn {Scheme Procedure} umask [mode]
-@deffnx {C Function} scm_umask (mode)
-If @var{mode} is omitted, returns a decimal number representing the current
-file creation mask. Otherwise the file creation mask is set to
-@var{mode} and the previous value is returned.
-
-E.g., @code{(umask #o022)} sets the mask to octal 22, decimal 18.
-@end deffn
-
- open-fdes
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:310
-@deffn {Scheme Procedure} open-fdes path flags [mode]
-@deffnx {C Function} scm_open_fdes (path, flags, mode)
-Similar to @code{open} but return a file descriptor instead of
-a port.
-@end deffn
-
- open
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:352
-@deffn {Scheme Procedure} open path flags [mode]
-@deffnx {C Function} scm_open (path, flags, mode)
-Open the file named by @var{path} for reading and/or writing.
-@var{flags} is an integer specifying how the file should be opened.
-@var{mode} is an integer specifying the permission bits of the file, if
-it needs to be created, before the umask is applied. The default is 666
-(Unix itself has no default).
-
-@var{flags} can be constructed by combining variables using @code{logior}.
-Basic flags are:
-
-@defvar O_RDONLY
-Open the file read-only.
-@end defvar
-@defvar O_WRONLY
-Open the file write-only.
-@end defvar
-@defvar O_RDWR
-Open the file read/write.
-@end defvar
-@defvar O_APPEND
-Append to the file instead of truncating.
-@end defvar
-@defvar O_CREAT
-Create the file if it does not already exist.
-@end defvar
-
-See the Unix documentation of the @code{open} system call
-for additional flags.
-@end deffn
-
- close
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:390
-@deffn {Scheme Procedure} close fd_or_port
-@deffnx {C Function} scm_close (fd_or_port)
-Similar to close-port (@pxref{Closing, close-port}),
-but also works on file descriptors. A side
-effect of closing a file descriptor is that any ports using that file
-descriptor are moved to a different file descriptor and have
-their revealed counts set to zero.
-@end deffn
-
- close-fdes
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:418
-@deffn {Scheme Procedure} close-fdes fd
-@deffnx {C Function} scm_close_fdes (fd)
-A simple wrapper for the @code{close} system call.
-Close file descriptor @var{fd}, which must be an integer.
-Unlike close (@pxref{Ports and File Descriptors, close}),
-the file descriptor will be closed even if a port is using it.
-The return value is unspecified.
-@end deffn
-
- stat
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:621
-@deffn {Scheme Procedure} stat object
-@deffnx {C Function} scm_stat (object)
-Return an object containing various information about the file
-determined by @var{obj}. @var{obj} can be a string containing
-a file name or a port or integer file descriptor which is open
-on a file (in which case @code{fstat} is used as the underlying
-system call).
-
-The object returned by @code{stat} can be passed as a single
-parameter to the following procedures, all of which return
-integers:
-
-@table @code
-@item stat:dev
-The device containing the file.
-@item stat:ino
-The file serial number, which distinguishes this file from all
-other files on the same device.
-@item stat:mode
-The mode of the file. This includes file type information and
-the file permission bits. See @code{stat:type} and
-@code{stat:perms} below.
-@item stat:nlink
-The number of hard links to the file.
-@item stat:uid
-The user ID of the file's owner.
-@item stat:gid
-The group ID of the file.
-@item stat:rdev
-Device ID; this entry is defined only for character or block
-special files.
-@item stat:size
-The size of a regular file in bytes.
-@item stat:atime
-The last access time for the file.
-@item stat:mtime
-The last modification time for the file.
-@item stat:ctime
-The last modification time for the attributes of the file.
-@item stat:blksize
-The optimal block size for reading or writing the file, in
-bytes.
-@item stat:blocks
-The amount of disk space that the file occupies measured in
-units of 512 byte blocks.
-@end table
-
-In addition, the following procedures return the information
-from stat:mode in a more convenient form:
-
-@table @code
-@item stat:type
-A symbol representing the type of file. Possible values are
-regular, directory, symlink, block-special, char-special, fifo,
-socket and unknown
-@item stat:perms
-An integer representing the access permission bits.
-@end table
-@end deffn
-
- link
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:684
-@deffn {Scheme Procedure} link oldpath newpath
-@deffnx {C Function} scm_link (oldpath, newpath)
-Creates a new name @var{newpath} in the file system for the
-file named by @var{oldpath}. If @var{oldpath} is a symbolic
-link, the link may or may not be followed depending on the
-system.
-@end deffn
-
- rename-file
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:705
-@deffn {Scheme Procedure} rename-file oldname newname
-@deffnx {C Function} scm_rename (oldname, newname)
-Renames the file specified by @var{oldname} to @var{newname}.
-The return value is unspecified.
-@end deffn
-
- delete-file
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:732
-@deffn {Scheme Procedure} delete-file str
-@deffnx {C Function} scm_delete_file (str)
-Deletes (or "unlinks") the file specified by @var{path}.
-@end deffn
-
- mkdir
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:750
-@deffn {Scheme Procedure} mkdir path [mode]
-@deffnx {C Function} scm_mkdir (path, mode)
-Create a new directory named by @var{path}. If @var{mode} is omitted
-then the permissions of the directory file are set using the current
-umask. Otherwise they are set to the decimal value specified with
-@var{mode}. The return value is unspecified.
-@end deffn
-
- rmdir
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:778
-@deffn {Scheme Procedure} rmdir path
-@deffnx {C Function} scm_rmdir (path)
-Remove the existing directory named by @var{path}. The directory must
-be empty for this to succeed. The return value is unspecified.
-@end deffn
-
- directory-stream?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:803
-@deffn {Scheme Procedure} directory-stream? obj
-@deffnx {C Function} scm_directory_stream_p (obj)
-Return a boolean indicating whether @var{object} is a directory
-stream as returned by @code{opendir}.
-@end deffn
-
- opendir
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:814
-@deffn {Scheme Procedure} opendir dirname
-@deffnx {C Function} scm_opendir (dirname)
-Open the directory specified by @var{path} and return a directory
-stream.
-@end deffn
-
- readdir
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:831
-@deffn {Scheme Procedure} readdir port
-@deffnx {C Function} scm_readdir (port)
-Return (as a string) the next directory entry from the directory stream
-@var{stream}. If there is no remaining entry to be read then the
-end of file object is returned.
-@end deffn
-
- rewinddir
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:854
-@deffn {Scheme Procedure} rewinddir port
-@deffnx {C Function} scm_rewinddir (port)
-Reset the directory port @var{stream} so that the next call to
-@code{readdir} will return the first directory entry.
-@end deffn
-
- closedir
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:871
-@deffn {Scheme Procedure} closedir port
-@deffnx {C Function} scm_closedir (port)
-Close the directory stream @var{stream}.
-The return value is unspecified.
-@end deffn
-
- chdir
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:921
-@deffn {Scheme Procedure} chdir str
-@deffnx {C Function} scm_chdir (str)
-Change the current working directory to @var{path}.
-The return value is unspecified.
-@end deffn
-
- getcwd
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:937
-@deffn {Scheme Procedure} getcwd
-@deffnx {C Function} scm_getcwd ()
-Return the name of the current working directory.
-@end deffn
-
- select
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:1133
-@deffn {Scheme Procedure} select reads writes excepts [secs [usecs]]
-@deffnx {C Function} scm_select (reads, writes, excepts, secs, usecs)
-This procedure has a variety of uses: waiting for the ability
-to provide input, accept output, or the existence of
-exceptional conditions on a collection of ports or file
-descriptors, or waiting for a timeout to occur.
-It also returns if interrupted by a signal.
-
-@var{reads}, @var{writes} and @var{excepts} can be lists or
-vectors, with each member a port or a file descriptor.
-The value returned is a list of three corresponding
-lists or vectors containing only the members which meet the
-specified requirement. The ability of port buffers to
-provide input or accept output is taken into account.
-Ordering of the input lists or vectors is not preserved.
-
-The optional arguments @var{secs} and @var{usecs} specify the
-timeout. Either @var{secs} can be specified alone, as
-either an integer or a real number, or both @var{secs} and
-@var{usecs} can be specified as integers, in which case
-@var{usecs} is an additional timeout expressed in
-microseconds. If @var{secs} is omitted or is @code{#f} then
-select will wait for as long as it takes for one of the other
-conditions to be satisfied.
-
-The scsh version of @code{select} differs as follows:
-Only vectors are accepted for the first three arguments.
-The @var{usecs} argument is not supported.
-Multiple values are returned instead of a list.
-Duplicates in the input vectors appear only once in output.
-An additional @code{select!} interface is provided.
-@end deffn
-
- fcntl
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:1279
-@deffn {Scheme Procedure} fcntl object cmd [value]
-@deffnx {C Function} scm_fcntl (object, cmd, value)
-Apply @var{command} to the specified file descriptor or the underlying
-file descriptor of the specified port. @var{value} is an optional
-integer argument.
-
-Values for @var{command} are:
-
-@table @code
-@item F_DUPFD
-Duplicate a file descriptor
-@item F_GETFD
-Get flags associated with the file descriptor.
-@item F_SETFD
-Set flags associated with the file descriptor to @var{value}.
-@item F_GETFL
-Get flags associated with the open file.
-@item F_SETFL
-Set flags associated with the open file to @var{value}
-@item F_GETOWN
-Get the process ID of a socket's owner, for @code{SIGIO} signals.
-@item F_SETOWN
-Set the process that owns a socket to @var{value}, for @code{SIGIO} signals.
-@item FD_CLOEXEC
-The value used to indicate the "close on exec" flag with @code{F_GETFL} or
-@code{F_SETFL}.
-@end table
-@end deffn
-
- fsync
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:1316
-@deffn {Scheme Procedure} fsync object
-@deffnx {C Function} scm_fsync (object)
-Copies any unwritten data for the specified output file descriptor to disk.
-If @var{port/fd} is a port, its buffer is flushed before the underlying
-file descriptor is fsync'd.
-The return value is unspecified.
-@end deffn
-
- symlink
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:1343
-@deffn {Scheme Procedure} symlink oldpath newpath
-@deffnx {C Function} scm_symlink (oldpath, newpath)
-Create a symbolic link named @var{path-to} with the value (i.e., pointing to)
-@var{path-from}. The return value is unspecified.
-@end deffn
-
- readlink
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:1362
-@deffn {Scheme Procedure} readlink path
-@deffnx {C Function} scm_readlink (path)
-Return the value of the symbolic link named by @var{path} (a
-string), i.e., the file that the link points to.
-@end deffn
-
- lstat
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:1391
-@deffn {Scheme Procedure} lstat str
-@deffnx {C Function} scm_lstat (str)
-Similar to @code{stat}, but does not follow symbolic links, i.e.,
-it will return information about a symbolic link itself, not the
-file it points to. @var{path} must be a string.
-@end deffn
-
- copy-file
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:1415
-@deffn {Scheme Procedure} copy-file oldfile newfile
-@deffnx {C Function} scm_copy_file (oldfile, newfile)
-Copy the file specified by @var{path-from} to @var{path-to}.
-The return value is unspecified.
-@end deffn
-
- dirname
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:1460
-@deffn {Scheme Procedure} dirname filename
-@deffnx {C Function} scm_dirname (filename)
-Return the directory name component of the file name
-@var{filename}. If @var{filename} does not contain a directory
-component, @code{.} is returned.
-@end deffn
-
- basename
-@c snarfed from /home/ghouston/guile/guile-core/libguile/filesys.c:1503
-@deffn {Scheme Procedure} basename filename [suffix]
-@deffnx {C Function} scm_basename (filename, suffix)
-Return the base name of the file name @var{filename}. The
-base name is the file name without any directory components.
-If @var{suffix} is provided, and is equal to the end of
-@var{basename}, it is removed also.
-@end deffn
-
- pipe
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:202
-@deffn {Scheme Procedure} pipe
-@deffnx {C Function} scm_pipe ()
-Return a newly created pipe: a pair of ports which are linked
-together on the local machine. The @emph{car} is the input
-port and the @emph{cdr} is the output port. Data written (and
-flushed) to the output port can be read from the input port.
-Pipes are commonly used for communication with a newly forked
-child process. The need to flush the output port can be
-avoided by making it unbuffered using @code{setvbuf}.
-
-Writes occur atomically provided the size of the data in bytes
-is not greater than the value of @code{PIPE_BUF}. Note that
-the output port is likely to block if too much data (typically
-equal to @code{PIPE_BUF}) has been written but not yet read
-from the input port.
-@end deffn
-
- getgroups
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:223
-@deffn {Scheme Procedure} getgroups
-@deffnx {C Function} scm_getgroups ()
-Return a vector of integers representing the current
-supplementary group IDs.
-@end deffn
-
- getpw
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:254
-@deffn {Scheme Procedure} getpw [user]
-@deffnx {C Function} scm_getpwuid (user)
-Look up an entry in the user database. @var{obj} can be an integer,
-a string, or omitted, giving the behaviour of getpwuid, getpwnam
-or getpwent respectively.
-@end deffn
-
- setpw
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:307
-@deffn {Scheme Procedure} setpw [arg]
-@deffnx {C Function} scm_setpwent (arg)
-If called with a true argument, initialize or reset the password data
-stream. Otherwise, close the stream. The @code{setpwent} and
-@code{endpwent} procedures are implemented on top of this.
-@end deffn
-
- getgr
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:326
-@deffn {Scheme Procedure} getgr [name]
-@deffnx {C Function} scm_getgrgid (name)
-Look up an entry in the group database. @var{obj} can be an integer,
-a string, or omitted, giving the behaviour of getgrgid, getgrnam
-or getgrent respectively.
-@end deffn
-
- setgr
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:366
-@deffn {Scheme Procedure} setgr [arg]
-@deffnx {C Function} scm_setgrent (arg)
-If called with a true argument, initialize or reset the group data
-stream. Otherwise, close the stream. The @code{setgrent} and
-@code{endgrent} procedures are implemented on top of this.
-@end deffn
-
- kill
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:402
-@deffn {Scheme Procedure} kill pid sig
-@deffnx {C Function} scm_kill (pid, sig)
-Sends a signal to the specified process or group of processes.
-
-@var{pid} specifies the processes to which the signal is sent:
-
-@table @r
-@item @var{pid} greater than 0
-The process whose identifier is @var{pid}.
-@item @var{pid} equal to 0
-All processes in the current process group.
-@item @var{pid} less than -1
-The process group whose identifier is -@var{pid}
-@item @var{pid} equal to -1
-If the process is privileged, all processes except for some special
-system processes. Otherwise, all processes with the current effective
-user ID.
-@end table
-
-@var{sig} should be specified using a variable corresponding to
-the Unix symbolic name, e.g.,
-
-@defvar SIGHUP
-Hang-up signal.
-@end defvar
-
-@defvar SIGINT
-Interrupt signal.
-@end defvar
-@end deffn
-
- waitpid
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:455
-@deffn {Scheme Procedure} waitpid pid [options]
-@deffnx {C Function} scm_waitpid (pid, options)
-This procedure collects status information from a child process which
-has terminated or (optionally) stopped. Normally it will
-suspend the calling process until this can be done. If more than one
-child process is eligible then one will be chosen by the operating system.
-
-The value of @var{pid} determines the behaviour:
-
-@table @r
-@item @var{pid} greater than 0
-Request status information from the specified child process.
-@item @var{pid} equal to -1 or WAIT_ANY
-Request status information for any child process.
-@item @var{pid} equal to 0 or WAIT_MYPGRP
-Request status information for any child process in the current process
-group.
-@item @var{pid} less than -1
-Request status information for any child process whose process group ID
-is -@var{PID}.
-@end table
-
-The @var{options} argument, if supplied, should be the bitwise OR of the
-values of zero or more of the following variables:
-
-@defvar WNOHANG
-Return immediately even if there are no child processes to be collected.
-@end defvar
-
-@defvar WUNTRACED
-Report status information for stopped processes as well as terminated
-processes.
-@end defvar
-
-The return value is a pair containing:
-
-@enumerate
-@item
-The process ID of the child process, or 0 if @code{WNOHANG} was
-specified and no process was collected.
-@item
-The integer status value.
-@end enumerate
-@end deffn
-
- status:exit-val
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:483
-@deffn {Scheme Procedure} status:exit-val status
-@deffnx {C Function} scm_status_exit_val (status)
-Return the exit status value, as would be set if a process
-ended normally through a call to @code{exit} or @code{_exit},
-if any, otherwise @code{#f}.
-@end deffn
-
- status:term-sig
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:503
-@deffn {Scheme Procedure} status:term-sig status
-@deffnx {C Function} scm_status_term_sig (status)
-Return the signal number which terminated the process, if any,
-otherwise @code{#f}.
-@end deffn
-
- status:stop-sig
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:521
-@deffn {Scheme Procedure} status:stop-sig status
-@deffnx {C Function} scm_status_stop_sig (status)
-Return the signal number which stopped the process, if any,
-otherwise @code{#f}.
-@end deffn
-
- getppid
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:541
-@deffn {Scheme Procedure} getppid
-@deffnx {C Function} scm_getppid ()
-Return an integer representing the process ID of the parent
-process.
-@end deffn
-
- getuid
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:553
-@deffn {Scheme Procedure} getuid
-@deffnx {C Function} scm_getuid ()
-Return an integer representing the current real user ID.
-@end deffn
-
- getgid
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:564
-@deffn {Scheme Procedure} getgid
-@deffnx {C Function} scm_getgid ()
-Return an integer representing the current real group ID.
-@end deffn
-
- geteuid
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:578
-@deffn {Scheme Procedure} geteuid
-@deffnx {C Function} scm_geteuid ()
-Return an integer representing the current effective user ID.
-If the system does not support effective IDs, then the real ID
-is returned. @code{(feature? 'EIDs)} reports whether the
-system supports effective IDs.
-@end deffn
-
- getegid
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:595
-@deffn {Scheme Procedure} getegid
-@deffnx {C Function} scm_getegid ()
-Return an integer representing the current effective group ID.
-If the system does not support effective IDs, then the real ID
-is returned. @code{(feature? 'EIDs)} reports whether the
-system supports effective IDs.
-@end deffn
-
- setuid
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:611
-@deffn {Scheme Procedure} setuid id
-@deffnx {C Function} scm_setuid (id)
-Sets both the real and effective user IDs to the integer @var{id}, provided
-the process has appropriate privileges.
-The return value is unspecified.
-@end deffn
-
- setgid
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:625
-@deffn {Scheme Procedure} setgid id
-@deffnx {C Function} scm_setgid (id)
-Sets both the real and effective group IDs to the integer @var{id}, provided
-the process has appropriate privileges.
-The return value is unspecified.
-@end deffn
-
- seteuid
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:641
-@deffn {Scheme Procedure} seteuid id
-@deffnx {C Function} scm_seteuid (id)
-Sets the effective user ID to the integer @var{id}, provided the process
-has appropriate privileges. If effective IDs are not supported, the
-real ID is set instead -- @code{(feature? 'EIDs)} reports whether the
-system supports effective IDs.
-The return value is unspecified.
-@end deffn
-
- setegid
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:667
-@deffn {Scheme Procedure} setegid id
-@deffnx {C Function} scm_setegid (id)
-Sets the effective group ID to the integer @var{id}, provided the process
-has appropriate privileges. If effective IDs are not supported, the
-real ID is set instead -- @code{(feature? 'EIDs)} reports whether the
-system supports effective IDs.
-The return value is unspecified.
-@end deffn
-
- getpgrp
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:691
-@deffn {Scheme Procedure} getpgrp
-@deffnx {C Function} scm_getpgrp ()
-Return an integer representing the current process group ID.
-This is the POSIX definition, not BSD.
-@end deffn
-
- setpgid
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:709
-@deffn {Scheme Procedure} setpgid pid pgid
-@deffnx {C Function} scm_setpgid (pid, pgid)
-Move the process @var{pid} into the process group @var{pgid}. @var{pid} or
-@var{pgid} must be integers: they can be zero to indicate the ID of the
-current process.
-Fails on systems that do not support job control.
-The return value is unspecified.
-@end deffn
-
- setsid
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:728
-@deffn {Scheme Procedure} setsid
-@deffnx {C Function} scm_setsid ()
-Creates a new session. The current process becomes the session leader
-and is put in a new process group. The process will be detached
-from its controlling terminal if it has one.
-The return value is an integer representing the new process group ID.
-@end deffn
-
- ttyname
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:743
-@deffn {Scheme Procedure} ttyname port
-@deffnx {C Function} scm_ttyname (port)
-Return a string with the name of the serial terminal device
-underlying @var{port}.
-@end deffn
-
- ctermid
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:767
-@deffn {Scheme Procedure} ctermid
-@deffnx {C Function} scm_ctermid ()
-Return a string containing the file name of the controlling
-terminal for the current process.
-@end deffn
-
- tcgetpgrp
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:790
-@deffn {Scheme Procedure} tcgetpgrp port
-@deffnx {C Function} scm_tcgetpgrp (port)
-Return the process group ID of the foreground process group
-associated with the terminal open on the file descriptor
-underlying @var{port}.
-
-If there is no foreground process group, the return value is a
-number greater than 1 that does not match the process group ID
-of any existing process group. This can happen if all of the
-processes in the job that was formerly the foreground job have
-terminated, and no other job has yet been moved into the
-foreground.
-@end deffn
-
- tcsetpgrp
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:814
-@deffn {Scheme Procedure} tcsetpgrp port pgid
-@deffnx {C Function} scm_tcsetpgrp (port, pgid)
-Set the foreground process group ID for the terminal used by the file
-descriptor underlying @var{port} to the integer @var{pgid}.
-The calling process
-must be a member of the same session as @var{pgid} and must have the same
-controlling terminal. The return value is unspecified.
-@end deffn
-
- execl
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:869
-@deffn {Scheme Procedure} execl filename . args
-@deffnx {C Function} scm_execl (filename, args)
-Executes the file named by @var{path} as a new process image.
-The remaining arguments are supplied to the process; from a C program
-they are accessible as the @code{argv} argument to @code{main}.
-Conventionally the first @var{arg} is the same as @var{path}.
-All arguments must be strings.
-
-If @var{arg} is missing, @var{path} is executed with a null
-argument list, which may have system-dependent side-effects.
-
-This procedure is currently implemented using the @code{execv} system
-call, but we call it @code{execl} because of its Scheme calling interface.
-@end deffn
-
- execlp
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:889
-@deffn {Scheme Procedure} execlp filename . args
-@deffnx {C Function} scm_execlp (filename, args)
-Similar to @code{execl}, however if
-@var{filename} does not contain a slash
-then the file to execute will be located by searching the
-directories listed in the @code{PATH} environment variable.
-
-This procedure is currently implemented using the @code{execvp} system
-call, but we call it @code{execlp} because of its Scheme calling interface.
-@end deffn
-
- execle
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:939
-@deffn {Scheme Procedure} execle filename env . args
-@deffnx {C Function} scm_execle (filename, env, args)
-Similar to @code{execl}, but the environment of the new process is
-specified by @var{env}, which must be a list of strings as returned by the
-@code{environ} procedure.
-
-This procedure is currently implemented using the @code{execve} system
-call, but we call it @code{execle} because of its Scheme calling interface.
-@end deffn
-
- primitive-fork
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:963
-@deffn {Scheme Procedure} primitive-fork
-@deffnx {C Function} scm_fork ()
-Creates a new "child" process by duplicating the current "parent" process.
-In the child the return value is 0. In the parent the return value is
-the integer process ID of the child.
-
-This procedure has been renamed from @code{fork} to avoid a naming conflict
-with the scsh fork.
-@end deffn
-
- uname
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:983
-@deffn {Scheme Procedure} uname
-@deffnx {C Function} scm_uname ()
-Return an object with some information about the computer
-system the program is running on.
-@end deffn
-
- environ
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1013
-@deffn {Scheme Procedure} environ [env]
-@deffnx {C Function} scm_environ (env)
-If @var{env} is omitted, return the current environment (in the
-Unix sense) as a list of strings. Otherwise set the current
-environment, which is also the default environment for child
-processes, to the supplied list of strings. Each member of
-@var{env} should be of the form @code{NAME=VALUE} and values of
-@code{NAME} should not be duplicated. If @var{env} is supplied
-then the return value is unspecified.
-@end deffn
-
- tmpnam
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1051
-@deffn {Scheme Procedure} tmpnam
-@deffnx {C Function} scm_tmpnam ()
-Return a name in the file system that does not match any
-existing file. However there is no guarantee that another
-process will not create the file after @code{tmpnam} is called.
-Care should be taken if opening the file, e.g., use the
-@code{O_EXCL} open flag or use @code{mkstemp!} instead.
-@end deffn
-
- mkstemp!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1077
-@deffn {Scheme Procedure} mkstemp! tmpl
-@deffnx {C Function} scm_mkstemp (tmpl)
-Create a new unique file in the file system and returns a new
-buffered port open for reading and writing to the file.
-@var{tmpl} is a string specifying where the file should be
-created: it must end with @code{XXXXXX} and will be changed in
-place to return the name of the temporary file.
-@end deffn
-
- utime
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1102
-@deffn {Scheme Procedure} utime pathname [actime [modtime]]
-@deffnx {C Function} scm_utime (pathname, actime, modtime)
-@code{utime} sets the access and modification times for the
-file named by @var{path}. If @var{actime} or @var{modtime} is
-not supplied, then the current time is used. @var{actime} and
-@var{modtime} must be integer time values as returned by the
-@code{current-time} procedure.
-@lisp
-(utime "foo" (- (current-time) 3600))
-@end lisp
-will set the access time to one hour in the past and the
-modification time to the current time.
-@end deffn
-
- access?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1150
-@deffn {Scheme Procedure} access? path how
-@deffnx {C Function} scm_access (path, how)
-Return @code{#t} if @var{path} corresponds to an existing file
-and the current process has the type of access specified by
-@var{how}, otherwise @code{#f}. @var{how} should be specified
-using the values of the variables listed below. Multiple
-values can be combined using a bitwise or, in which case
-@code{#t} will only be returned if all accesses are granted.
-
-Permissions are checked using the real id of the current
-process, not the effective id, although it's the effective id
-which determines whether the access would actually be granted.
-
-@defvar R_OK
-test for read permission.
-@end defvar
-@defvar W_OK
-test for write permission.
-@end defvar
-@defvar X_OK
-test for execute permission.
-@end defvar
-@defvar F_OK
-test for existence of the file.
-@end defvar
-@end deffn
-
- getpid
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1164
-@deffn {Scheme Procedure} getpid
-@deffnx {C Function} scm_getpid ()
-Return an integer representing the current process ID.
-@end deffn
-
- putenv
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1181
-@deffn {Scheme Procedure} putenv str
-@deffnx {C Function} scm_putenv (str)
-Modifies the environment of the current process, which is
-also the default environment inherited by child processes.
-
-If @var{string} is of the form @code{NAME=VALUE} then it will be written
-directly into the environment, replacing any existing environment string
-with
-name matching @code{NAME}. If @var{string} does not contain an equal
-sign, then any existing string with name matching @var{string} will
-be removed.
-
-The return value is unspecified.
-@end deffn
-
- setlocale
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1223
-@deffn {Scheme Procedure} setlocale category [locale]
-@deffnx {C Function} scm_setlocale (category, locale)
-If @var{locale} is omitted, return the current value of the
-specified locale category as a system-dependent string.
-@var{category} should be specified using the values
-@code{LC_COLLATE}, @code{LC_ALL} etc.
-
-Otherwise the specified locale category is set to the string
-@var{locale} and the new value is returned as a
-system-dependent string. If @var{locale} is an empty string,
-the locale will be set using environment variables.
-@end deffn
-
- mknod
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1263
-@deffn {Scheme Procedure} mknod path type perms dev
-@deffnx {C Function} scm_mknod (path, type, perms, dev)
-Creates a new special file, such as a file corresponding to a device.
-@var{path} specifies the name of the file. @var{type} should
-be one of the following symbols:
-regular, directory, symlink, block-special, char-special,
-fifo, or socket. @var{perms} (an integer) specifies the file permissions.
-@var{dev} (an integer) specifies which device the special file refers
-to. Its exact interpretation depends on the kind of special file
-being created.
-
-E.g.,
-@lisp
-(mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
-@end lisp
-
-The return value is unspecified.
-@end deffn
-
- nice
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1309
-@deffn {Scheme Procedure} nice incr
-@deffnx {C Function} scm_nice (incr)
-Increment the priority of the current process by @var{incr}. A higher
-priority value means that the process runs less often.
-The return value is unspecified.
-@end deffn
-
- sync
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1324
-@deffn {Scheme Procedure} sync
-@deffnx {C Function} scm_sync ()
-Flush the operating system disk buffers.
-The return value is unspecified.
-@end deffn
-
- crypt
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1337
-@deffn {Scheme Procedure} crypt key salt
-@deffnx {C Function} scm_crypt (key, salt)
-Encrypt @var{key} using @var{salt} as the salt value to the
-crypt(3) library call.
-@end deffn
-
- chroot
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1358
-@deffn {Scheme Procedure} chroot path
-@deffnx {C Function} scm_chroot (path)
-Change the root directory to that specified in @var{path}.
-This directory will be used for path names beginning with
-@file{/}. The root directory is inherited by all children
-of the current process. Only the superuser may change the
-root directory.
-@end deffn
-
- getlogin
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1390
-@deffn {Scheme Procedure} getlogin
-@deffnx {C Function} scm_getlogin ()
-Return a string containing the name of the user logged in on
-the controlling terminal of the process, or @code{#f} if this
-information cannot be obtained.
-@end deffn
-
- cuserid
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1408
-@deffn {Scheme Procedure} cuserid
-@deffnx {C Function} scm_cuserid ()
-Return a string containing a user name associated with the
-effective user id of the process. Return @code{#f} if this
-information cannot be obtained.
-@end deffn
-
- getpriority
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1433
-@deffn {Scheme Procedure} getpriority which who
-@deffnx {C Function} scm_getpriority (which, who)
-Return the scheduling priority of the process, process group
-or user, as indicated by @var{which} and @var{who}. @var{which}
-is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
-or @code{PRIO_USER}, and @var{who} is interpreted relative to
-@var{which} (a process identifier for @code{PRIO_PROCESS},
-process group identifier for @code{PRIO_PGRP}, and a user
-identifier for @code{PRIO_USER}. A zero value of @var{who}
-denotes the current process, process group, or user. Return
-the highest priority (lowest numerical value) of any of the
-specified processes.
-@end deffn
-
- setpriority
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1467
-@deffn {Scheme Procedure} setpriority which who prio
-@deffnx {C Function} scm_setpriority (which, who, prio)
-Set the scheduling priority of the process, process group
-or user, as indicated by @var{which} and @var{who}. @var{which}
-is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
-or @code{PRIO_USER}, and @var{who} is interpreted relative to
-@var{which} (a process identifier for @code{PRIO_PROCESS},
-process group identifier for @code{PRIO_PGRP}, and a user
-identifier for @code{PRIO_USER}. A zero value of @var{who}
-denotes the current process, process group, or user.
-@var{prio} is a value in the range -20 and 20, the default
-priority is 0; lower priorities cause more favorable
-scheduling. Sets the priority of all of the specified
-processes. Only the super-user may lower priorities.
-The return value is not specified.
-@end deffn
-
- getpass
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1492
-@deffn {Scheme Procedure} getpass prompt
-@deffnx {C Function} scm_getpass (prompt)
-Display @var{prompt} to the standard error output and read
-a password from @file{/dev/tty}. If this file is not
-accessible, it reads from standard input. The password may be
-up to 127 characters in length. Additional characters and the
-terminating newline character are discarded. While reading
-the password, echoing and the generation of signals by special
-characters is disabled.
-@end deffn
-
- flock
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1596
-@deffn {Scheme Procedure} flock file operation
-@deffnx {C Function} scm_flock (file, operation)
-Apply or remove an advisory lock on an open file.
-@var{operation} specifies the action to be done:
-@table @code
-@item LOCK_SH
-Shared lock. More than one process may hold a shared lock
-for a given file at a given time.
-@item LOCK_EX
-Exclusive lock. Only one process may hold an exclusive lock
-for a given file at a given time.
-@item LOCK_UN
-Unlock the file.
-@item LOCK_NB
-Don't block when locking. May be specified by bitwise OR'ing
-it to one of the other operations.
-@end table
-The return value is not specified. @var{file} may be an open
-file descriptor or an open file descriptor port.
-@end deffn
-
- sethostname
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1622
-@deffn {Scheme Procedure} sethostname name
-@deffnx {C Function} scm_sethostname (name)
-Set the host name of the current processor to @var{name}. May
-only be used by the superuser. The return value is not
-specified.
-@end deffn
-
- gethostname
-@c snarfed from /home/ghouston/guile/guile-core/libguile/posix.c:1637
-@deffn {Scheme Procedure} gethostname
-@deffnx {C Function} scm_gethostname ()
-Return the host name of the current processor.
-@end deffn
-
- gethost
-@c snarfed from /home/ghouston/guile/guile-core/libguile/net_db.c:154
-@deffn {Scheme Procedure} gethost [host]
-@deffnx {Scheme Procedure} gethostbyname hostname
-@deffnx {Scheme Procedure} gethostbyaddr address
-@deffnx {C Function} scm_gethost (host)
-Look up a host by name or address, returning a host object. The
-@code{gethost} procedure will accept either a string name or an integer
-address; if given no arguments, it behaves like @code{gethostent} (see
-below). If a name or address is supplied but the address can not be
-found, an error will be thrown to one of the keys:
-@code{host-not-found}, @code{try-again}, @code{no-recovery} or
-@code{no-data}, corresponding to the equivalent @code{h_error} values.
-Unusual conditions may result in errors thrown to the
-@code{system-error} or @code{misc_error} keys.
-@end deffn
-
- getnet
-@c snarfed from /home/ghouston/guile/guile-core/libguile/net_db.c:233
-@deffn {Scheme Procedure} getnet [net]
-@deffnx {Scheme Procedure} getnetbyname net-name
-@deffnx {Scheme Procedure} getnetbyaddr net-number
-@deffnx {C Function} scm_getnet (net)
-Look up a network by name or net number in the network database. The
-@var{net-name} argument must be a string, and the @var{net-number}
-argument must be an integer. @code{getnet} will accept either type of
-argument, behaving like @code{getnetent} (see below) if no arguments are
-given.
-@end deffn
-
- getproto
-@c snarfed from /home/ghouston/guile/guile-core/libguile/net_db.c:282
-@deffn {Scheme Procedure} getproto [protocol]
-@deffnx {Scheme Procedure} getprotobyname name
-@deffnx {Scheme Procedure} getprotobynumber number
-@deffnx {C Function} scm_getproto (protocol)
-Look up a network protocol by name or by number. @code{getprotobyname}
-takes a string argument, and @code{getprotobynumber} takes an integer
-argument. @code{getproto} will accept either type, behaving like
-@code{getprotoent} (see below) if no arguments are supplied.
-@end deffn
-
- getserv
-@c snarfed from /home/ghouston/guile/guile-core/libguile/net_db.c:348
-@deffn {Scheme Procedure} getserv [name [protocol]]
-@deffnx {Scheme Procedure} getservbyname name protocol
-@deffnx {Scheme Procedure} getservbyport port protocol
-@deffnx {C Function} scm_getserv (name, protocol)
-Look up a network service by name or by service number, and return a
-network service object. The @var{protocol} argument specifies the name
-of the desired protocol; if the protocol found in the network service
-database does not match this name, a system error is signalled.
-
-The @code{getserv} procedure will take either a service name or number
-as its first argument; if given no arguments, it behaves like
-@code{getservent} (see below).
-@end deffn
-
- sethost
-@c snarfed from /home/ghouston/guile/guile-core/libguile/net_db.c:385
-@deffn {Scheme Procedure} sethost [stayopen]
-@deffnx {C Function} scm_sethost (stayopen)
-If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
-Otherwise it is equivalent to @code{sethostent stayopen}.
-@end deffn
-
- setnet
-@c snarfed from /home/ghouston/guile/guile-core/libguile/net_db.c:401
-@deffn {Scheme Procedure} setnet [stayopen]
-@deffnx {C Function} scm_setnet (stayopen)
-If @var{stayopen} is omitted, this is equivalent to @code{endnetent}.
-Otherwise it is equivalent to @code{setnetent stayopen}.
-@end deffn
-
- setproto
-@c snarfed from /home/ghouston/guile/guile-core/libguile/net_db.c:417
-@deffn {Scheme Procedure} setproto [stayopen]
-@deffnx {C Function} scm_setproto (stayopen)
-If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}.
-Otherwise it is equivalent to @code{setprotoent stayopen}.
-@end deffn
-
- setserv
-@c snarfed from /home/ghouston/guile/guile-core/libguile/net_db.c:433
-@deffn {Scheme Procedure} setserv [stayopen]
-@deffnx {C Function} scm_setserv (stayopen)
-If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
-Otherwise it is equivalent to @code{setservent stayopen}.
-@end deffn
-
- htons
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:109
-@deffn {Scheme Procedure} htons value
-@deffnx {C Function} scm_htons (value)
-Convert a 16 bit quantity from host to network byte ordering.
-@var{value} is packed into 2 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
- ntohs
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:126
-@deffn {Scheme Procedure} ntohs value
-@deffnx {C Function} scm_ntohs (value)
-Convert a 16 bit quantity from network to host byte ordering.
-@var{value} is packed into 2 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
- htonl
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:143
-@deffn {Scheme Procedure} htonl value
-@deffnx {C Function} scm_htonl (value)
-Convert a 32 bit quantity from host to network byte ordering.
-@var{value} is packed into 4 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
- ntohl
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:156
-@deffn {Scheme Procedure} ntohl value
-@deffnx {C Function} scm_ntohl (value)
-Convert a 32 bit quantity from network to host byte ordering.
-@var{value} is packed into 4 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
- inet-aton
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:176
-@deffn {Scheme Procedure} inet-aton address
-@deffnx {C Function} scm_inet_aton (address)
-Convert an IPv4 Internet address from printable string
-(dotted decimal notation) to an integer. E.g.,
-
-@lisp
-(inet-aton "127.0.0.1") @result{} 2130706433
-@end lisp
-@end deffn
-
- inet-ntoa
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:195
-@deffn {Scheme Procedure} inet-ntoa inetid
-@deffnx {C Function} scm_inet_ntoa (inetid)
-Convert an IPv4 Internet address to a printable
-(dotted decimal notation) string. E.g.,
-
-@lisp
-(inet-ntoa 2130706433) @result{} "127.0.0.1"
-@end lisp
-@end deffn
-
- inet-netof
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:215
-@deffn {Scheme Procedure} inet-netof address
-@deffnx {C Function} scm_inet_netof (address)
-Return the network number part of the given IPv4
-Internet address. E.g.,
-
-@lisp
-(inet-netof 2130706433) @result{} 127
-@end lisp
-@end deffn
-
- inet-lnaof
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:233
-@deffn {Scheme Procedure} inet-lnaof address
-@deffnx {C Function} scm_lnaof (address)
-Return the local-address-with-network part of the given
-IPv4 Internet address, using the obsolete class A/B/C system.
-E.g.,
-
-@lisp
-(inet-lnaof 2130706433) @result{} 1
-@end lisp
-@end deffn
-
- inet-makeaddr
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:251
-@deffn {Scheme Procedure} inet-makeaddr net lna
-@deffnx {C Function} scm_inet_makeaddr (net, lna)
-Make an IPv4 Internet address by combining the network number
-@var{net} with the local-address-within-network number
-@var{lna}. E.g.,
-
-@lisp
-(inet-makeaddr 127 1) @result{} 2130706433
-@end lisp
-@end deffn
-
- inet-pton
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:369
-@deffn {Scheme Procedure} inet-pton family address
-@deffnx {C Function} scm_inet_pton (family, address)
-Convert a string containing a printable network address to
-an integer address. Note that unlike the C version of this
-function,
-the result is an integer with normal host byte ordering.
-@var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
-
-@lisp
-(inet-pton AF_INET "127.0.0.1") @result{} 2130706433
-(inet-pton AF_INET6 "::1") @result{} 1
-@end lisp
-@end deffn
-
- inet-ntop
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:404
-@deffn {Scheme Procedure} inet-ntop family address
-@deffnx {C Function} scm_inet_ntop (family, address)
-Convert a network address into a printable string.
-Note that unlike the C version of this function,
-the input is an integer with normal host byte ordering.
-@var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
-
-@lisp
-(inet-ntop AF_INET 2130706433) @result{} "127.0.0.1"
-(inet-ntop AF_INET6 (- (expt 2 128) 1)) @result{}
-ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
-@end lisp
-@end deffn
-
- socket
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:449
-@deffn {Scheme Procedure} socket family style proto
-@deffnx {C Function} scm_socket (family, style, proto)
-Return a new socket port of the type specified by @var{family},
-@var{style} and @var{proto}. All three parameters are
-integers. Supported values for @var{family} are
-@code{AF_UNIX}, @code{AF_INET} and @code{AF_INET6}.
-Typical values for @var{style} are @code{SOCK_STREAM},
-@code{SOCK_DGRAM} and @code{SOCK_RAW}.
-
-@var{proto} can be obtained from a protocol name using
-@code{getprotobyname}. A value of zero specifies the default
-protocol, which is usually right.
-
-A single socket port cannot by used for communication until it
-has been connected to another socket.
-@end deffn
-
- socketpair
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:471
-@deffn {Scheme Procedure} socketpair family style proto
-@deffnx {C Function} scm_socketpair (family, style, proto)
-Return a pair of connected (but unnamed) socket ports of the
-type specified by @var{family}, @var{style} and @var{proto}.
-Many systems support only socket pairs of the @code{AF_UNIX}
-family. Zero is likely to be the only meaningful value for
-@var{proto}.
-@end deffn
-
- getsockopt
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:500
-@deffn {Scheme Procedure} getsockopt sock level optname
-@deffnx {C Function} scm_getsockopt (sock, level, optname)
-Return the value of a particular socket option for the socket
-port @var{sock}. @var{level} is an integer code for type of
-option being requested, e.g., @code{SOL_SOCKET} for
-socket-level options. @var{optname} is an integer code for the
-option required and should be specified using one of the
-symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
-
-The returned value is typically an integer but @code{SO_LINGER}
-returns a pair of integers.
-@end deffn
-
- setsockopt
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:568
-@deffn {Scheme Procedure} setsockopt sock level optname value
-@deffnx {C Function} scm_setsockopt (sock, level, optname, value)
-Set the value of a particular socket option for the socket
-port @var{sock}. @var{level} is an integer code for type of option
-being set, e.g., @code{SOL_SOCKET} for socket-level options.
-@var{optname} is an
-integer code for the option to set and should be specified using one of
-the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
-@var{value} is the value to which the option should be set. For
-most options this must be an integer, but for @code{SO_LINGER} it must
-be a pair.
-
-The return value is unspecified.
-@end deffn
-
- shutdown
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:672
-@deffn {Scheme Procedure} shutdown sock how
-@deffnx {C Function} scm_shutdown (sock, how)
-Sockets can be closed simply by using @code{close-port}. The
-@code{shutdown} procedure allows reception or transmission on a
-connection to be shut down individually, according to the parameter
-@var{how}:
-
-@table @asis
-@item 0
-Stop receiving data for this socket. If further data arrives, reject it.
-@item 1
-Stop trying to transmit data from this socket. Discard any
-data waiting to be sent. Stop looking for acknowledgement of
-data already sent; don't retransmit it if it is lost.
-@item 2
-Stop both reception and transmission.
-@end table
-
-The return value is unspecified.
-@end deffn
-
- connect
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:816
-@deffn {Scheme Procedure} connect sock fam address . args
-@deffnx {C Function} scm_connect (sock, fam, address, args)
-Initiate a connection from a socket using a specified address
-family to the address
-specified by @var{address} and possibly @var{args}.
-The format required for @var{address}
-and @var{args} depends on the family of the socket.
-
-For a socket of family @code{AF_UNIX},
-only @var{address} is specified and must be a string with the
-filename where the socket is to be created.
-
-For a socket of family @code{AF_INET},
-@var{address} must be an integer IPv4 host address and
-@var{args} must be a single integer port number.
-
-For a socket of family @code{AF_INET6},
-@var{address} must be an integer IPv6 host address and
-@var{args} may be up to three integers:
-port [flowinfo] [scope_id],
-where flowinfo and scope_id default to zero.
-
-The return value is unspecified.
-@end deffn
-
- bind
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:876
-@deffn {Scheme Procedure} bind sock fam address . args
-@deffnx {C Function} scm_bind (sock, fam, address, args)
-Assign an address to the socket port @var{sock}.
-Generally this only needs to be done for server sockets,
-so they know where to look for incoming connections. A socket
-without an address will be assigned one automatically when it
-starts communicating.
-
-The format of @var{address} and @var{args} depends
-on the family of the socket.
-
-For a socket of family @code{AF_UNIX}, only @var{address}
-is specified and must be a string with the filename where
-the socket is to be created.
-
-For a socket of family @code{AF_INET}, @var{address}
-must be an integer IPv4 address and @var{args}
-must be a single integer port number.
-
-The values of the following variables can also be used for
-@var{address}:
-
-@defvar INADDR_ANY
-Allow connections from any address.
-@end defvar
-
-@defvar INADDR_LOOPBACK
-The address of the local host using the loopback device.
-@end defvar
-
-@defvar INADDR_BROADCAST
-The broadcast address on the local network.
-@end defvar
-
-@defvar INADDR_NONE
-No address.
-@end defvar
-
-For a socket of family @code{AF_INET6}, @var{address}
-must be an integer IPv6 address and @var{args}
-may be up to three integers:
-port [flowinfo] [scope_id],
-where flowinfo and scope_id default to zero.
-
-The return value is unspecified.
-@end deffn
-
- listen
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:910
-@deffn {Scheme Procedure} listen sock backlog
-@deffnx {C Function} scm_listen (sock, backlog)
-Enable @var{sock} to accept connection
-requests. @var{backlog} is an integer specifying
-the maximum length of the queue for pending connections.
-If the queue fills, new clients will fail to connect until
-the server calls @code{accept} to accept a connection from
-the queue.
-
-The return value is unspecified.
-@end deffn
-
- accept
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:1015
-@deffn {Scheme Procedure} accept sock
-@deffnx {C Function} scm_accept (sock)
-Accept a connection on a bound, listening socket.
-If there
-are no pending connections in the queue, wait until
-one is available unless the non-blocking option has been
-set on the socket.
-
-The return value is a
-pair in which the @emph{car} is a new socket port for the
-connection and
-the @emph{cdr} is an object with address information about the
-client which initiated the connection.
-
-@var{sock} does not become part of the
-connection and will continue to accept new requests.
-@end deffn
-
- getsockname
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:1042
-@deffn {Scheme Procedure} getsockname sock
-@deffnx {C Function} scm_getsockname (sock)
-Return the address of @var{sock}, in the same form as the
-object returned by @code{accept}. On many systems the address
-of a socket in the @code{AF_FILE} namespace cannot be read.
-@end deffn
-
- getpeername
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:1064
-@deffn {Scheme Procedure} getpeername sock
-@deffnx {C Function} scm_getpeername (sock)
-Return the address that @var{sock}
-is connected to, in the same form as the object returned by
-@code{accept}. On many systems the address of a socket in the
-@code{AF_FILE} namespace cannot be read.
-@end deffn
-
- recv!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:1099
-@deffn {Scheme Procedure} recv! sock buf [flags]
-@deffnx {C Function} scm_recv (sock, buf, flags)
-Receive data from a socket port.
-@var{sock} must already
-be bound to the address from which data is to be received.
-@var{buf} is a string into which
-the data will be written. The size of @var{buf} limits
-the amount of
-data which can be received: in the case of packet
-protocols, if a packet larger than this limit is encountered
-then some data
-will be irrevocably lost.
-
-The optional @var{flags} argument is a value or
-bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
-
-The value returned is the number of bytes read from the
-socket.
-
-Note that the data is read directly from the socket file
-descriptor:
-any unread buffered port data is ignored.
-@end deffn
-
- send
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:1132
-@deffn {Scheme Procedure} send sock message [flags]
-@deffnx {C Function} scm_send (sock, message, flags)
-Transmit the string @var{message} on a socket port @var{sock}.
-@var{sock} must already be bound to a destination address. The
-value returned is the number of bytes transmitted --
-it's possible for
-this to be less than the length of @var{message}
-if the socket is
-set to be non-blocking. The optional @var{flags} argument
-is a value or
-bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
-
-Note that the data is written directly to the socket
-file descriptor:
-any unflushed buffered port data is ignored.
-@end deffn
-
- recvfrom!
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:1172
-@deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]]
-@deffnx {C Function} scm_recvfrom (sock, str, flags, start, end)
-Return data from the socket port @var{sock} and also
-information about where the data was received from.
-@var{sock} must already be bound to the address from which
-data is to be received. @code{str}, is a string into which the
-data will be written. The size of @var{str} limits the amount
-of data which can be received: in the case of packet protocols,
-if a packet larger than this limit is encountered then some
-data will be irrevocably lost.
-
-The optional @var{flags} argument is a value or bitwise OR of
-@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
-
-The value returned is a pair: the @emph{car} is the number of
-bytes read from the socket and the @emph{cdr} an address object
-in the same form as returned by @code{accept}. The address
-will given as @code{#f} if not available, as is usually the
-case for stream sockets.
-
-The @var{start} and @var{end} arguments specify a substring of
-@var{str} to which the data should be written.
-
-Note that the data is read directly from the socket file
-descriptor: any unread buffered port data is ignored.
-@end deffn
-
- sendto
-@c snarfed from /home/ghouston/guile/guile-core/libguile/socket.c:1230
-@deffn {Scheme Procedure} sendto sock message fam address . args_and_flags
-@deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags)
-Transmit the string @var{message} on the socket port
-@var{sock}. The
-destination address is specified using the @var{fam},
-@var{address} and
-@var{args_and_flags} arguments, in a similar way to the
-@code{connect} procedure. @var{args_and_flags} contains
-the usual connection arguments optionally followed by
-a flags argument, which is a value or
-bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
-
-The value returned is the number of bytes transmitted --
-it's possible for
-this to be less than the length of @var{message} if the
-socket is
-set to be non-blocking.
-Note that the data is written directly to the socket
-file descriptor:
-any unflushed buffered port data is ignored.
-@end deffn
-
- regexp?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/regex-posix.c:137
-@deffn {Scheme Procedure} regexp? obj
-@deffnx {C Function} scm_regexp_p (obj)
-Return @code{#t} if @var{obj} is a compiled regular expression,
-or @code{#f} otherwise.
-@end deffn
-
- make-regexp
-@c snarfed from /home/ghouston/guile/guile-core/libguile/regex-posix.c:182
-@deffn {Scheme Procedure} make-regexp pat . flags
-@deffnx {C Function} scm_make_regexp (pat, flags)
-Compile the regular expression described by @var{pat}, and
-return the compiled regexp structure. If @var{pat} does not
-describe a legal regular expression, @code{make-regexp} throws
-a @code{regular-expression-syntax} error.
-
-The @var{flags} arguments change the behavior of the compiled
-regular expression. The following flags may be supplied:
-
-@table @code
-@item regexp/icase
-Consider uppercase and lowercase letters to be the same when
-matching.
-@item regexp/newline
-If a newline appears in the target string, then permit the
-@samp{^} and @samp{$} operators to match immediately after or
-immediately before the newline, respectively. Also, the
-@samp{.} and @samp{[^...]} operators will never match a newline
-character. The intent of this flag is to treat the target
-string as a buffer containing many lines of text, and the
-regular expression as a pattern that may match a single one of
-those lines.
-@item regexp/basic
-Compile a basic (``obsolete'') regexp instead of the extended
-(``modern'') regexps that are the default. Basic regexps do
-not consider @samp{|}, @samp{+} or @samp{?} to be special
-characters, and require the @samp{@{...@}} and @samp{(...)}
-metacharacters to be backslash-escaped (@pxref{Backslash
-Escapes}). There are several other differences between basic
-and extended regular expressions, but these are the most
-significant.
-@item regexp/extended
-Compile an extended regular expression rather than a basic
-regexp. This is the default behavior; this flag will not
-usually be needed. If a call to @code{make-regexp} includes
-both @code{regexp/basic} and @code{regexp/extended} flags, the
-one which comes last will override the earlier one.
-@end table
-@end deffn
-
- regexp-exec
-@c snarfed from /home/ghouston/guile/guile-core/libguile/regex-posix.c:243
-@deffn {Scheme Procedure} regexp-exec rx str [start [flags]]
-@deffnx {C Function} scm_regexp_exec (rx, str, start, flags)
-Match the compiled regular expression @var{rx} against
-@code{str}. If the optional integer @var{start} argument is
-provided, begin matching from that position in the string.
-Return a match structure describing the results of the match,
-or @code{#f} if no match could be found.
-
-The @var{flags} arguments change the matching behavior.
-The following flags may be supplied:
-
-@table @code
-@item regexp/notbol
-Operator @samp{^} always fails (unless @code{regexp/newline}
-is used). Use this when the beginning of the string should
-not be considered the beginning of a line.
-@item regexp/noteol
-Operator @samp{$} always fails (unless @code{regexp/newline}
-is used). Use this when the end of the string should not be
-considered the end of a line.
-@end table
-@end deffn
-
- single-active-thread?
-@c snarfed from /home/ghouston/guile/guile-core/libguile/threads.c:79
-@deffn {Scheme Procedure} single-active-thread?
-implemented by the C function "scm_single_thread_p"
-@end deffn
-
- yield
-@c snarfed from /home/ghouston/guile/guile-core/libguile/threads.c:85
-@deffn {Scheme Procedure} yield
-implemented by the C function "scm_yield"
-@end deffn
-
- call-with-new-thread
-@c snarfed from /home/ghouston/guile/guile-core/libguile/threads.c:90
-@deffn {Scheme Procedure} call-with-new-thread
-implemented by the C function "scm_call_with_new_thread"
-@end deffn
-
- join-thread
-@c snarfed from /home/ghouston/guile/guile-core/libguile/threads.c:104
-@deffn {Scheme Procedure} join-thread
-implemented by the C function "scm_join_thread"
-@end deffn
-
- make-mutex
-@c snarfed from /home/ghouston/guile/guile-core/libguile/threads.c:109
-@deffn {Scheme Procedure} make-mutex
-implemented by the C function "scm_make_mutex"
-@end deffn
-
- lock-mutex
-@c snarfed from /home/ghouston/guile/guile-core/libguile/threads.c:112
-@deffn {Scheme Procedure} lock-mutex
-implemented by the C function "scm_lock_mutex"
-@end deffn
-
- unlock-mutex
-@c snarfed from /home/ghouston/guile/guile-core/libguile/threads.c:117
-@deffn {Scheme Procedure} unlock-mutex
-implemented by the C function "scm_unlock_mutex"
-@end deffn
-
- make-condition-variable
-@c snarfed from /home/ghouston/guile/guile-core/libguile/threads.c:123
-@deffn {Scheme Procedure} make-condition-variable
-implemented by the C function "scm_make_condition_variable"
-@end deffn
-
- wait-condition-variable
-@c snarfed from /home/ghouston/guile/guile-core/libguile/threads.c:125
-@deffn {Scheme Procedure} wait-condition-variable
-implemented by the C function "scm_wait_condition_variable"
-@end deffn
-
- signal-condition-variable
-@c snarfed from /home/ghouston/guile/guile-core/libguile/threads.c:127
-@deffn {Scheme Procedure} signal-condition-variable
-implemented by the C function "scm_signal_condition_variable"
-@end deffn
diff --git a/doc/mbapi.texi b/doc/mbapi.texi
deleted file mode 100644
index 3f53ccdb2..000000000
--- a/doc/mbapi.texi
+++ /dev/null
@@ -1,987 +0,0 @@
-\input texinfo
-@setfilename mbapi.info
-@settitle Multibyte API
-@setchapternewpage off
-
-@c Open issues:
-
-@c What's the best way to report errors? Should functions return a
-@c magic value, according to C tradition, or should they signal a
-@c Guile exception?
-
-@c
-
-
-@node Working With Multibyte Strings in C
-@chapter Working With Multibyte Strings in C
-
-Guile allows strings to contain characters drawn from a wide variety of
-languages, including many Asian, Eastern European, and Middle Eastern
-languages, in a uniform and unrestricted way. The string representation
-normally used in C code --- an array of @sc{ASCII} characters --- is not
-sufficient for Guile strings, since they may contain characters not
-present in @sc{ASCII}.
-
-Instead, Guile uses a very large character set, and encodes each
-character as a sequence of one or more bytes. We call this
-variable-width encoding a @dfn{multibyte} encoding. Guile uses this
-single encoding internally for all strings, symbol names, error
-messages, etc., and performs appropriate conversions upon input and
-output.
-
-The use of this variable-width encoding is almost invisible to Scheme
-code. Strings are still indexed by character number, not by byte
-offset; @code{string-length} still returns the length of a string in
-characters, not in bytes. @code{string-ref} and @code{string-set!} are
-no longer guaranteed to be constant-time operations, but Guile uses
-various strategies to reduce the impact of this change.
-
-However, the encoding is visible via Guile's C interface, which gives
-the user direct access to a string's bytes. This chapter explains how
-to work with Guile multibyte text in C code. Since variable-width
-encodings are clumsier to work with than simple fixed-width encodings,
-Guile provides a set of standard macros and functions for manipulating
-multibyte text to make the job easier. Furthermore, Guile makes some
-promises about the encoding which you can use in writing your own text
-processing code.
-
-While we discuss guaranteed properties of Guile's encoding, and provide
-functions to operate on its character set, we do not actually specify
-either the character set or encoding here. This is because we expect
-both of them to change in the future: currently, Guile uses the same
-encoding as GNU Emacs 20.4, but we hope to change Guile (and GNU Emacs
-as well) to use Unicode and UTF-8, with some extensions. This will make
-it more comfortable to use Guile with other systems which use UTF-8,
-like the GTk user interface toolkit.
-
-@menu
-* Multibyte String Terminology::
-* Promised Properties of the Guile Multibyte Encoding::
-* Functions for Operating on Multibyte Text::
-* Multibyte Text Processing Errors::
-* Why Guile Does Not Use a Fixed-Width Encoding::
-@end menu
-
-
-@node Multibyte String Terminology, Promised Properties of the Guile Multibyte Encoding, Working With Multibyte Strings in C, Working With Multibyte Strings in C
-@section Multibyte String Terminology
-
-In the descriptions which follow, we make the following definitions:
-@table @dfn
-
-@item byte
-A @dfn{byte} is a number between 0 and 255. It has no inherent textual
-interpretation. So 65 is a byte, not a character.
-
-@item character
-A @dfn{character} is a unit of text. It has no inherent numeric value.
-@samp{A} and @samp{.} are characters, not bytes. (This is different
-from the C language's definition of @dfn{character}; in this chapter, we
-will always use a phrase like ``the C language's @code{char} type'' when
-that's what we mean.)
-
-@item character set
-A @dfn{character set} is an invertible mapping between numbers and a
-given set of characters. @sc{ASCII} is a character set assigning
-characters to the numbers 0 through 127. It maps @samp{A} onto the
-number 65, and @samp{.} onto 46.
-
-Note that a character set maps characters onto numbers, @emph{not
-necessarily} onto bytes. For example, the Unicode character set maps
-the Greek lower-case @samp{alpha} character onto the number 945, which
-is not a byte.
-
-(This is what Internet standards would call a "coding character set".)
-
-@item encoding
-An encoding maps numbers onto sequences of bytes. For example, the
-UTF-8 encoding, defined in the Unicode Standard, would map the number
-945 onto the sequence of bytes @samp{206 177}. When using the
-@sc{ASCII} character set, every number assigned also happens to be a
-byte, so there is an obvious trivial encoding for @sc{ASCII} in bytes.
-
-(This is what Internet standards would call a "character encoding
-scheme".)
-
-@end table
-
-Thus, to turn a character into a sequence of bytes, you need a character
-set to assign a number to that character, and then an encoding to turn
-that number into a sequence of bytes.
-
-Likewise, to interpret a sequence of bytes as a sequence of characters,
-you use an encoding to extract a sequence of numbers from the bytes, and
-then a character set to turn the numbers into characters.
-
-Errors can occur while carrying out either of these processes. For
-example, under a particular encoding, a given string of bytes might not
-correspond to any number. For example, the byte sequence @samp{128 128}
-is not a valid encoding of any number under UTF-8.
-
-Having carefully defined our terminology, we will now abuse it.
-
-We will sometimes use the word @dfn{character} to refer to the number
-assigned to a character by a character set, in contexts where it's
-obvious we mean a number.
-
-Sometimes there is a close association between a particular encoding and
-a particular character set. Thus, we may sometimes refer to the
-character set and encoding together as an @dfn{encoding}.
-
-
-@node Promised Properties of the Guile Multibyte Encoding, Functions for Operating on Multibyte Text, Multibyte String Terminology, Working With Multibyte Strings in C
-@section Promised Properties of the Guile Multibyte Encoding
-
-Internally, Guile uses a single encoding for all text --- symbols,
-strings, error messages, etc. Here we list a number of helpful
-properties of Guile's encoding. It is correct to write code which
-assumes these properties; code which uses these assumptions will be
-portable to all future versions of Guile, as far as we know.
-
-@b{Every @sc{ASCII} character is encoded as a single byte from 0 to 127, in
-the obvious way.} This means that a standard C string containing only
-@sc{ASCII} characters is a valid Guile string (except for the terminator;
-Guile strings store the length explicitly, so they can contain null
-characters).
-
-@b{The encodings of non-@sc{ASCII} characters use only bytes between 128
-and 255.} That is, when we turn a non-@sc{ASCII} character into a
-series of bytes, none of those bytes can ever be mistaken for the
-encoding of an @sc{ASCII} character. This means that you can search a
-Guile string for an @sc{ASCII} character using the standard
-@code{memchr} library function. By extension, you can search for an
-@sc{ASCII} substring in a Guile string using a traditional substring
-search algorithm --- you needn't add special checks to verify encoding
-boundaries, etc.
-
-@b{No character encoding is a subsequence of any other character
-encoding.} (This is just a stronger version of the previous promise.)
-This means that you can search for occurrences of one Guile string
-within another Guile string just as if they were raw byte strings. You
-can use the stock @code{memmem} function (provided on GNU systems, at
-least) for such searches. If you don't need the ability to represent
-null characters in your text, you can still use null-termination for
-strings, and use the traditional string-handling functions like
-@code{strlen}, @code{strstr}, and @code{strcat}.
-
-@b{You can always determine the full length of a character's encoding
-from its first byte.} Guile provides the macro @code{scm_mb_len} which
-computes the encoding's length from its first byte. Given the first
-rule, you can see that @code{scm_mb_len (@var{b})}, for any @code{0 <=
-@var{b} <= 127}, returns 1.
-
-@b{Given an arbitrary byte position in a Guile string, you can always
-find the beginning and end of the character containing that byte without
-scanning too far in either direction.} This means that, if you are sure
-a byte sequence is a valid encoding of a character sequence, you can
-find character boundaries without keeping track of the beginning and
-ending of the overall string. This promise relies on the fact that, in
-addition to storing the string's length explicitly, Guile always either
-terminates the string's storage with a zero byte, or shares it with
-another string which is terminated this way.
-
-
-@node Functions for Operating on Multibyte Text, Multibyte Text Processing Errors, Promised Properties of the Guile Multibyte Encoding, Working With Multibyte Strings in C
-@section Functions for Operating on Multibyte Text
-
-Guile provides a variety of functions, variables, and types for working
-with multibyte text.
-
-@menu
-* Basic Multibyte Character Processing::
-* Finding Character Encoding Boundaries::
-* Multibyte String Functions::
-* Exchanging Guile Text With the Outside World in C::
-* Implementing Your Own Text Conversions::
-@end menu
-
-
-@node Basic Multibyte Character Processing, Finding Character Encoding Boundaries, Functions for Operating on Multibyte Text, Functions for Operating on Multibyte Text
-@subsection Basic Multibyte Character Processing
-
-Here are the essential types and functions for working with Guile text.
-Guile uses the C type @code{unsigned char *} to refer to text encoded
-with Guile's encoding.
-
-Note that any operation marked here as a ``Libguile Macro'' might
-evaluate its argument multiple times.
-
-@deftp {Libguile Type} scm_char_t
-This is a signed integral type large enough to hold any character in
-Guile's character set. All character numbers are positive.
-@end deftp
-
-@deftypefn {Libguile Macro} scm_char_t scm_mb_get (const unsigned char *@var{p})
-Return the character whose encoding starts at @var{p}. If @var{p} does
-not point at a valid character encoding, the behavior is undefined.
-@end deftypefn
-
-@deftypefn {Libguile Macro} int scm_mb_put (unsigned char *@var{p}, scm_char_t @var{c})
-Place the encoded form of the Guile character @var{c} at @var{p}, and
-return its length in bytes. If @var{c} is not a Guile character, the
-behavior is undefined.
-@end deftypefn
-
-@deftypevr {Libguile Constant} int scm_mb_max_len
-The maximum length of any character's encoding, in bytes. You may
-assume this is relatively small --- less than a dozen or so.
-@end deftypevr
-
-@deftypefn {Libguile Macro} int scm_mb_len (unsigned char @var{b})
-If @var{b} is the first byte of a character's encoding, return the full
-length of the character's encoding, in bytes. If @var{b} is not a valid
-leading byte, the behavior is undefined.
-@end deftypefn
-
-@deftypefn {Libguile Macro} int scm_mb_char_len (scm_char_t @var{c})
-Return the length of the encoding of the character @var{c}, in bytes.
-If @var{c} is not a valid Guile character, the behavior is undefined.
-@end deftypefn
-
-@deftypefn {Libguile Function} scm_char_t scm_mb_get_func (const unsigned char *@var{p})
-@deftypefnx {Libguile Function} int scm_mb_put_func (unsigned char *@var{p}, scm_char_t @var{c})
-@deftypefnx {Libguile Function} int scm_mb_len_func (unsigned char @var{b})
-@deftypefnx {Libguile Function} int scm_mb_char_len_func (scm_char_t @var{c})
-These are functions identical to the corresponding macros. You can use
-them in situations where the overhead of a function call is acceptable,
-and the cleaner semantics of function application are desireable.
-@end deftypefn
-
-
-@node Finding Character Encoding Boundaries, Multibyte String Functions, Basic Multibyte Character Processing, Functions for Operating on Multibyte Text
-@subsection Finding Character Encoding Boundaries
-
-These are functions for finding the boundaries between characters in
-multibyte text.
-
-Note that any operation marked here as a ``Libguile Macro'' might
-evaluate its argument multiple times, unless the definition promises
-otherwise.
-
-@deftypefn {Libguile Macro} int scm_mb_boundary_p (const unsigned char *@var{p})
-Return non-zero iff @var{p} points to the start of a character in
-multibyte text.
-
-This macro will evaluate its argument only once.
-@end deftypefn
-
-@deftypefn {Libguile Function} {const unsigned char *} scm_mb_floor (const unsigned char *@var{p})
-``Round'' @var{p} to the previous character boundary. That is, if
-@var{p} points to the middle of the encoding of a Guile character,
-return a pointer to the first byte of the encoding. If @var{p} points
-to the start of the encoding of a Guile character, return @var{p}
-unchanged.
-@end deftypefn
-
-@deftypefn {libguile Function} {const unsigned char *} scm_mb_ceiling (const unsigned char *@var{p})
-``Round'' @var{p} to the next character boundary. That is, if @var{p}
-points to the middle of the encoding of a Guile character, return a
-pointer to the first byte of the encoding of the next character. If
-@var{p} points to the start of the encoding of a Guile character, return
-@var{p} unchanged.
-@end deftypefn
-
-Note that it is usually not friendly for functions to silently correct
-byte offsets that point into the middle of a character's encoding. Such
-offsets almost always indicate a programming error, and they should be
-reported as early as possible. So, when you write code which operates
-on multibyte text, you should not use functions like these to ``clean
-up'' byte offsets which the originator believes to be correct; instead,
-your code should signal a @code{text:not-char-boundary} error as soon as
-it detects an invalid offset. @xref{Multibyte Text Processing Errors}.
-
-
-@node Multibyte String Functions, Exchanging Guile Text With the Outside World in C, Finding Character Encoding Boundaries, Functions for Operating on Multibyte Text
-@subsection Multibyte String Functions
-
-These functions allow you to operate on multibyte strings: sequences of
-character encodings.
-
-@deftypefn {Libguile Function} int scm_mb_count (const unsigned char *@var{p}, int @var{len})
-Return the number of Guile characters encoded by the @var{len} bytes at
-@var{p}.
-
-If the sequence contains any invalid character encodings, or ends with
-an incomplete character encoding, signal a @code{text:bad-encoding}
-error.
-@end deftypefn
-
-@deftypefn {Libguile Macro} scm_char_t scm_mb_walk (unsigned char **@var{pp})
-Return the character whose encoding starts at @code{*@var{pp}}, and
-advance @code{*@var{pp}} to the start of the next character. Return -1
-if @code{*@var{pp}} does not point to a valid character encoding.
-@end deftypefn
-
-@deftypefn {Libguile Function} {const unsigned char *} scm_mb_prev (const unsigned char *@var{p})
-If @var{p} points to the middle of the encoding of a Guile character,
-return a pointer to the first byte of the encoding. If @var{p} points
-to the start of the encoding of a Guile character, return the start of
-the previous character's encoding.
-
-This is like @code{scm_mb_floor}, but the returned pointer will always
-be before @var{p}. If you use this function to drive an iteration, it
-guarantees backward progress.
-@end deftypefn
-
-@deftypefn {Libguile Function} {const unsigned char *} scm_mb_next (const unsigned char *@var{p})
-If @var{p} points to the encoding of a Guile character, return a pointer
-to the first byte of the encoding of the next character.
-
-This is like @code{scm_mb_ceiling}, but the returned pointer will always
-be after @var{p}. If you use this function to drive an iteration, it
-guarantees forward progress.
-@end deftypefn
-
-@deftypefn {Libguile Function} {const unsigned char *} scm_mb_index (const unsigned char *@var{p}, int @var{len}, int @var{i})
-Assuming that the @var{len} bytes starting at @var{p} are a
-concatenation of valid character encodings, return a pointer to the
-start of the @var{i}'th character encoding in the sequence.
-
-This function scans the sequence from the beginning to find the
-@var{i}'th character, and will generally require time proportional to
-the distance from @var{p} to the returned address.
-
-If the sequence contains any invalid character encodings, or ends with
-an incomplete character encoding, signal a @code{text:bad-encoding}
-error.
-@end deftypefn
-
-It is common to process the characters in a string from left to right.
-However, if you fetch each character using @code{scm_mb_index}, each
-call will scan the text from the beginning, so your loop will require
-time proportional to at least the square of the length of the text. To
-avoid this poor performance, you can use an @code{scm_mb_cache}
-structure and the @code{scm_mb_index_cached} macro.
-
-@deftp {Libguile Type} {struct scm_mb_cache}
-This structure holds information that allows a string scanning operation
-to use the results from a previous scan of the string. It has the
-following members:
-@table @code
-
-@item character
-An index, in characters, into the string.
-
-@item byte
-The index, in bytes, of the start of that character.
-
-@end table
-
-In other words, @code{byte} is the byte offset of the
-@code{character}'th character of the string. Note that if @code{byte}
-and @code{character} are equal, then all characters before that point
-must have encodings exactly one byte long, and the string can be indexed
-normally.
-
-All elements of a @code{struct scm_mb_cache} structure should be
-initialized to zero before its first use, and whenever the string's text
-changes.
-@end deftp
-
-@deftypefn {Libguile Macro} const unsigned char *scm_mb_index_cached (const unsigned char *@var{p}, int @var{len}, int @var{i}, struct scm_mb_cache *@var{cache})
-@deftypefnx {Libguile Function} const unsigned char *scm_mb_index_cached_func (const unsigned char *@var{p}, int @var{len}, int @var{i}, struct scm_mb_cache *@var{cache})
-This macro and this function are identical to @code{scm_mb_index},
-except that they may consult and update *@var{cache} in order to avoid
-scanning the string from the beginning. @code{scm_mb_index_cached} is a
-macro, so it may have less overhead than
-@code{scm_mb_index_cached_func}, but it may evaluate its arguments more
-than once.
-
-Using @code{scm_mb_index_cached} or @code{scm_mb_index_cached_func}, you
-can scan a string from left to right, or from right to left, in time
-proportional to the length of the string. As long as each character
-fetched is less than some constant distance before or after the previous
-character fetched with @var{cache}, each access will require constant
-time.
-@end deftypefn
-
-Guile also provides functions to convert between an encoded sequence of
-characters, and an array of @code{scm_char_t} objects.
-
-@deftypefn {Libguile Function} scm_char_t *scm_mb_multibyte_to_fixed (const unsigned char *@var{p}, int @var{len}, int *@var{result_len})
-Convert the variable-width text in the @var{len} bytes at @var{p}
-to an array of @code{scm_char_t} values. Return a pointer to the array,
-and set @code{*@var{result_len}} to the number of elements it contains.
-The returned array is allocated with @code{malloc}, and it is the
-caller's responsibility to free it.
-
-If the text is not a sequence of valid character encodings, this
-function will signal a @code{text:bad-encoding} error.
-@end deftypefn
-
-@deftypefn {Libguile Function} unsigned char *scm_mb_fixed_to_multibyte (const scm_char_t *@var{fixed}, int @var{len}, int *@var{result_len})
-Convert the array of @code{scm_char_t} values to a sequence of
-variable-width character encodings. Return a pointer to the array of
-bytes, and set @code{*@var{result_len}} to its length, in bytes.
-
-The returned byte sequence is terminated with a zero byte, which is not
-counted in the length returned in @code{*@var{result_len}}.
-
-The returned byte sequence is allocated with @code{malloc}; it is the
-caller's responsibility to free it.
-
-If the text is not a sequence of valid character encodings, this
-function will signal a @code{text:bad-encoding} error.
-@end deftypefn
-
-
-@node Exchanging Guile Text With the Outside World in C, Implementing Your Own Text Conversions, Multibyte String Functions, Functions for Operating on Multibyte Text
-@subsection Exchanging Guile Text With the Outside World in C
-
-[[This is kind of a heavy-weight model, given that one end of the
-conversion is always going to be the Guile encoding. Any way to shorten
-things a bit?]]
-
-Guile provides functions for converting between Guile's internal text
-representation and encodings popular in the outside world. These
-functions are closely modeled after the @code{iconv} functions available
-on some systems.
-
-To convert text between two encodings, you should first call
-@code{scm_mb_iconv_open} to indicate the source and destination
-encodings; this function returns a context object which records the
-conversion to perform.
-
-Then, you should call @code{scm_mb_iconv} to actually convert the text.
-This function expects input and output buffers, and a pointer to the
-context you got from @var{scm_mb_iconv_open}. You don't need to pass
-all your input to @code{scm_mb_iconv} at once; you can invoke it on
-successive blocks of input (as you read it from a file, say), and it
-will convert as much as it can each time, indicating when you should
-grow your output buffer.
-
-An encoding may be @dfn{stateless}, or @dfn{stateful}. In most
-encodings, a contiguous group of bytes from the sequence completely
-specifies a particular character; these are stateless encodings.
-However, some encodings require you to look back an unbounded number of
-bytes in the stream to assign a meaning to a particular byte sequence;
-such encodings are stateful.
-
-For example, in the @samp{ISO-2022-JP} encoding for Japanese text, the
-byte sequence @samp{27 36 66} indicates that subsequent bytes should be
-taken in pairs and interpreted as characters from the JIS-0208 character
-set. An arbitrary number of byte pairs may follow this sequence. The
-byte sequence @samp{27 40 66} indicates that subsequent bytes should be
-interpreted as @sc{ASCII}. In this encoding, you cannot tell whether a
-given byte is an @sc{ASCII} character without looking back an arbitrary
-distance for the most recent escape sequence, so it is a stateful
-encoding.
-
-In Guile, if a conversion involves a stateful encoding, the context
-object carries any necessary state. Thus, you can have many independent
-conversions to or from stateful encodings taking place simultaneously,
-as long as each data stream uses its own context object for the
-conversion.
-
-@deftp {Libguile Type} {struct scm_mb_iconv}
-This is the type for context objects, which represent the encodings and
-current state of an ongoing text conversion. A @code{struct
-scm_mb_iconv} records the source and destination encodings, and keeps
-track of any information needed to handle stateful encodings.
-@end deftp
-
-@deftypefn {Libguile Function} {struct scm_mb_iconv *} scm_mb_iconv_open (const char *@var{tocode}, const char *@var{fromcode})
-Return a pointer to a new @code{struct scm_mb_iconv} context object,
-ready to convert from the encoding named @var{fromcode} to the encoding
-named @var{tocode}. For stateful encodings, the context object is in
-some appropriate initial state, ready for use with the
-@code{scm_mb_iconv} function.
-
-When you are done using a context object, you may call
-@code{scm_mb_iconv_close} to free it.
-
-If either @var{tocode} or @var{fromcode} is not the name of a known
-encoding, this function will signal the @code{text:unknown-conversion}
-error, described below.
-
-@c Try to use names here from the IANA list:
-@c see ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets
-Guile supports at least these encodings:
-@table @samp
-
-@item US-ASCII
-@sc{US-ASCII}, in the standard one-character-per-byte encoding.
-
-@item ISO-8859-1
-The usual character set for Western European languages, in its usual
-one-character-per-byte encoding.
-
-@item Guile-MB
-Guile's current internal multibyte encoding. The actual encoding this
-name refers to will change from one version of Guile to the next. You
-should use this when converting data between external sources and the
-encoding used by Guile objects.
-
-You should @emph{not} use this as the encoding for data presented to the
-outside world, for two reasons. 1) Its meaning will change over time,
-so data written using the @samp{guile} encoding with one version of
-Guile might not be readable with the @samp{guile} encoding in another
-version of Guile. 2) It currently corresponds to @samp{Emacs-Mule},
-which invented for Emacs's internal use, and was never intended to serve
-as an exchange medium.
-
-@item Guile-Wide
-Guile's character set, as an array of @code{scm_char_t} values.
-
-Note that this encoding is even less suitable for public use than
-@samp{Guile}, since the exact sequence of bytes depends heavily on the
-size and endianness the host system uses for @code{scm_char_t}. Using
-this encoding is very much like calling the
-@code{scm_mb_multibyte_to_fixed} or @code{scm_mb_fixed_to_multibyte}
-functions, except that @code{scm_mb_iconv} gives you more control over
-buffer allocation and management.
-
-@item Emacs-Mule
-This is the variable-length encoding for multi-lingual text by GNU
-Emacs, at least through version 20.4. You probably should not use this
-encoding, as it is designed only for Emacs's internal use. However, we
-provide it here because it's trivial to support, and some people
-probably do have @samp{emacs-mule}-format files lying around.
-
-@end table
-
-(At the moment, this list doesn't include any character sets suitable for
-external use that can actually handle multilingual data; this is
-unfortunate, as it encourages users to write data in Emacs-Mule format,
-which nobody but Emacs and Guile understands. We hope to add support
-for Unicode in UTF-8 soon, which should solve this problem.)
-
-Case is not significant in encoding names.
-
-You can define your own conversions; see @ref{Implementing Your Own Text
-Conversions}.
-@end deftypefn
-
-@deftypefn {Libguile Function} int scm_mb_have_encoding (const char *@var{encoding})
-Return a non-zero value if Guile supports the encoding named @var{encoding}[[]]
-@end deftypefn
-
-@deftypefn {Libguile Function} size_t scm_mb_iconv (struct scm_mb_iconv *@var{context}, const char **@var{inbuf}, size_t *@var{inbytesleft}, char **@var{outbuf}, size_t *@var{outbytesleft})
-Convert a sequence of characters from one encoding to another. The
-argument @var{context} specifies the encodings to use for the input and
-output, and carries state for stateful encodings; use
-@code{scm_mb_iconv_open} to create a @var{context} object for a
-particular conversion.
-
-Upon entry to the function, @code{*@var{inbuf}} should point to the
-input buffer, and @code{*@var{inbytesleft}} should hold the number of
-input bytes present in the buffer; @code{*@var{outbuf}} should point to
-the output buffer, and @code{*@var{outbytesleft}} should hold the number
-of bytes available to hold the conversion results in that buffer.
-
-Upon exit from the function, @code{*@var{inbuf}} points to the first
-unconsumed byte of input, and @code{*@var{inbytesleft}} holds the number
-of unconsumed input bytes; @code{*@var{outbuf}} points to the byte after
-the last output byte, and @code{*@var{outbyteleft}} holds the number of
-bytes left unused in the output buffer.
-
-For stateful encodings, @var{context} carries encoding state from one
-call to @code{scm_mb_iconv} to the next. Thus, successive calls to
-@var{scm_mb_iconv} which use the same context object can convert a
-stream of data one chunk at a time.
-
-If @var{inbuf} is zero or @code{*@var{inbuf}} is zero, then the call is
-taken as a request to reset the states of the input and the output
-encodings. If @var{outbuf} is non-zero and @code{*@var{outbuf}} is
-non-zero, then @code{scm_mb_iconv} stores a byte sequence in the output
-buffer to put the output encoding in its initial state. If the output
-buffer is not large enough to hold this byte sequence,
-@code{scm_mb_iconv} returns @code{scm_mb_iconv_too_big}, and leaves
-the shift states of @var{context}'s input and output encodings
-unchanged.
-
-The @code{scm_mb_iconv} function always consumes only complete
-characters or shift sequences from the input buffer, and the output
-buffer always contains a sequence of complete characters or escape
-sequences.
-
-If the input sequence contains characters which are not expressible in
-the output encoding, @code{scm_mb_iconv} converts it in an
-implementation-defined way. It may simply delete the character.
-
-Some encodings use byte sequences which do not correspond to any textual
-character. For example, the escape sequence of a stateful encoding has
-no textual meaning. When converting from such an encoding, a call to
-@code{scm_mb_iconv} might consume input but produce no output, since the
-input sequence might contain only escape sequences.
-
-Normally, @code{scm_mb_iconv} returns the number of input characters it
-could not convert perfectly to the ouput encoding. However, it may
-return one of the @code{scm_mb_iconv_} codes described below, to
-indicate an error. All of these codes are negative values.
-
-If the input sequence contains an invalid character encoding, conversion
-stops before the invalid input character, and @code{scm_mb_iconv}
-returns the constant value @code{scm_mb_iconv_bad_encoding}.
-
-If the input sequence ends with an incomplete character encoding,
-@code{scm_mb_iconv} will leave it in the input buffer, unconsumed, and
-return the constant value @code{scm_mb_iconv_incomplete_encoding}. This
-is not necessarily an error, if you expect to call @code{scm_mb_iconv}
-again with more data which might contain the rest of the encoding
-fragment.
-
-If the output buffer does not contain enough room to hold the converted
-form of the complete input text, @code{scm_mb_iconv} converts as much as
-it can, changes the input and output pointers to reflect the amount of
-text successfully converted, and then returns
-@code{scm_mb_iconv_too_big}.
-@end deftypefn
-
-Here are the status codes that might be returned by @code{scm_mb_iconv}.
-They are all negative integers.
-@table @code
-
-@item scm_mb_iconv_too_big
-The conversion needs more room in the output buffer. Some characters
-may have been consumed from the input buffer, and some characters may
-have been placed in the available space in the output buffer.
-
-@item scm_mb_iconv_bad_encoding
-@code{scm_mb_iconv} encountered an invalid character encoding in the
-input buffer. Conversion stopped before the invalid character, so there
-may be some characters consumed from the input buffer, and some
-converted text in the output buffer.
-
-@item scm_mb_iconv_incomplete_encoding
-The input buffer ends with an incomplete character encoding. The
-incomplete encoding is left in the input buffer, unconsumed. This is
-not necessarily an error, if you expect to call @code{scm_mb_iconv}
-again with more data which might contain the rest of the incomplete
-encoding.
-
-@end table
-
-
-Finally, Guile provides a function for destroying conversion contexts.
-
-@deftypefn {Libguile Function} void scm_mb_iconv_close (struct scm_mb_iconv *@var{context})
-Deallocate the conversion context object @var{context}, and all other
-resources allocated by the call to @code{scm_mb_iconv_open} which
-returned @var{context}.
-@end deftypefn
-
-
-@node Implementing Your Own Text Conversions, , Exchanging Guile Text With the Outside World in C, Functions for Operating on Multibyte Text
-@subsection Implementing Your Own Text Conversions
-
-[[note that conversions to and from Guile must produce streams
-containing only valid character encodings, or else Guile will crash]]
-
-This section describes the interface for adding your own encoding
-conversions for use with @code{scm_mb_iconv}. The interface here is
-borrowed from the GNOME Project's @file{libunicode} library.
-
-Guile's @code{scm_mb_iconv} function works by converting the input text
-to a stream of @code{scm_char_t} characters, and then converting
-those characters to the desired output encoding. This makes it easy
-for Guile to choose the appropriate conversion back ends for an
-arbitrary pair of input and output encodings, but it also means that the
-accuracy and quality of the conversions depends on the fidelity of
-Guile's internal character set to the source and destination encodings.
-Since @code{scm_mb_iconv} will be used almost exclusively for converting
-to and from Guile's internal character set, this shouldn't be a problem.
-
-To add support for a particular encoding to Guile, you must provide one
-function (called the @dfn{read} function) which converts from your
-encoding to an array of @code{scm_char_t}'s, and another function
-(called the @dfn{write} function) to convert from an array of
-@code{scm_char_t}'s back into your encoding. To convert from some
-encoding @var{a} to some other encoding @var{b}, Guile pairs up
-@var{a}'s read function with @var{b}'s write function. Each call to
-@code{scm_mb_iconv} passes text in encoding @var{a} through the read
-function, to produce an array of @code{scm_char_t}'s, and then passes
-that array to the write function, to produce text in encoding @var{b}.
-
-For stateful encodings, a read or write function can hang its own data
-structures off the conversion object, and provide its own functions to
-allocate and destroy them; this allows read and write functions to
-maintain whatever state they like.
-
-The Guile conversion back end represents each available encoding with a
-@code{struct scm_mb_encoding} object.
-
-@deftp {Libguile Type} {struct scm_mb_encoding}
-This data structure describes an encoding. It has the following
-members:
-
-@table @code
-
-@item char **names
-An array of strings, giving the various names for this encoding. The
-array should be terminated by a zero pointer. Case is not significant
-in encoding names.
-
-The @code{scm_mb_iconv_open} function searches the list of registered
-encodings for an encoding whose @code{names} array matches its
-@var{tocode} or @var{fromcode} argument.
-
-@item int (*init) (void **@var{cookie})
-An initialization function for the encoding's private data.
-@code{scm_mb_iconv_open} will call this function, passing it the address
-of the cookie for this encoding in this context. (We explain cookies
-below.) There is no way for the @code{init} function to tell whether
-the encoding will be used for reading or writing.
-
-Note that @code{init} receives a @emph{pointer} to the cookie, not the
-cookie itself. Because the type of @var{cookie} is @code{void **}, the
-C compiler will not check it as carefully as it would other types.
-
-The @code{init} member may be zero, indicating that no initialization is
-necessary for this encoding.
-
-@item int (*destroy) (void **@var{cookie})
-A deallocation function for the encoding's private data.
-@code{scm_mb_iconv_close} calls this function, passing it the address of
-the cookie for this encoding in this context. The @code{destroy}
-function should free any data the @code{init} function allocated.
-
-Note that @code{destroy} receives a @emph{pointer} to the cookie, not the
-cookie itself. Because the type of @var{cookie} is @code{void **}, the
-C compiler will not check it as carefully as it would other types.
-
-The @code{destroy} member may be zero, indicating that this encoding
-doesn't need to perform any special action to destroy its local data.
-
-@item int (*reset) (void *@var{cookie}, char **@var{outbuf}, size_t *@var{outbytesleft})
-Put the encoding into its initial shift state. Guile calls this
-function whether the encoding is being used for input or output, so this
-should take appropriate steps for both directions. If @var{outbuf} and
-@var{outbytesleft} are valid, the reset function should emit an escape
-sequence to reset the output stream to its initial state; @var{outbuf}
-and @var{outbytesleft} should be handled just as for
-@code{scm_mb_iconv}.
-
-This function can return an @code{scm_mb_iconv_} error code
-(@pxref{Exchanging Guile Text With the Outside World in C}). If it
-returns @code{scm_mb_iconv_too_big}, then the output buffer's shift
-state must be left unchanged.
-
-Note that @code{reset} receives the cookie's value itself, not a pointer
-to the cookie, as the @code{init} and @code{destroy} functions do.
-
-The @code{reset} member may be zero, indicating that this encoding
-doesn't use a shift state.
-
-@item enum scm_mb_read_result (*read) (void *@var{cookie}, const char **@var{inbuf}, size_t *@var{inbytesleft}, scm_char_t **@var{outbuf}, size_t *@var{outcharsleft})
-Read some bytes and convert into an array of Guile characters. This is
-the encoding's read function.
-
-On entry, there are *@var{inbytesleft} bytes of text at *@var{inbuf} to
-be converted, and *@var{outcharsleft} characters available at
-*@var{outbuf} to hold the results.
-
-On exit, *@var{inbytesleft} and *@var{inbuf} indicate the input bytes
-still not consumed. *@var{outcharsleft} and *@var{outbuf} indicate the
-output buffer space still not filled. (By exclusion, these indicate
-which input bytes were consumed, and which output characters were
-produced.)
-
-Return one of the @code{enum scm_mb_read_result} values, described below.
-
-Note that @code{read} receives the cookie's value itself, not a pointer
-to the cookie, as the @code{init} and @code{destroy} functions do.
-
-@item enum scm_mb_write_result (*write) (void *@var{cookie}, scm_char_t **@var{inbuf}, size_t *@var{incharsleft}, **@var{outbuf}, size_t *@var{outbytesleft})
-Convert an array of Guile characters to output bytes. This is
-the encoding's write function.
-
-On entry, there are *@var{incharsleft} Guile characters available at
-*@var{inbuf}, and *@var{outbytesleft} bytes available to store output at
-*@var{outbuf}.
-
-On exit, *@var{incharsleft} and *@var{inbuf} indicate the number of
-Guile characters left unconverted (because there was insufficient room
-in the output buffer to hold their converted forms), and
-*@var{outbytesleft} and *@var{outbuf} indicate the unused portion of the
-output buffer.
-
-Return one of the @code{scm_mb_write_result} values, described below.
-
-Note that @code{write} receives the cookie's value itself, not a pointer
-to the cookie, as the @code{init} and @code{destroy} functions do.
-
-@item struct scm_mb_encoding *next
-This is used by Guile to maintain a linked list of encodings. It is
-filled in when you call @code{scm_mb_register_encoding} to add your
-encoding to the list.
-
-@end table
-@end deftp
-
-Here is the enumerated type for the values an encoding's read function
-can return:
-
-@deftp {Libguile Type} {enum scm_mb_read_result}
-This type represents the result of a call to an encoding's read
-function. It has the following values:
-
-@table @code
-
-@item scm_mb_read_ok
-The read function consumed at least one byte of input.
-
-@item scm_mb_read_incomplete
-The data present in the input buffer does not contain a complete
-character encoding. No input was consumed, and no characters were
-produced as output. This is not necessarily an error status, if there
-is more data to pass through.
-
-@item scm_mb_read_error
-The input contains an invalid character encoding.
-
-@end table
-@end deftp
-
-Here is the enumerated type for the values an encoding's write function
-can return:
-
-@deftp {Libguile Type} {enum scm_mb_write_result}
-This type represents the result of a call to an encoding's write
-function. It has the following values:
-
-@table @code
-
-@item scm_mb_write_ok
-The write function was able to convert all the characters in @var{inbuf}
-successfully.
-
-@item scm_mb_write_too_big
-The write function filled the output buffer, but there are still
-characters in @var{inbuf} left unconsumed; @var{inbuf} and
-@var{incharsleft} indicate the unconsumed portion of the input buffer.
-
-@end table
-@end deftp
-
-
-Conversions to or from stateful encodings need to keep track of each
-encoding's current state. Each conversion context contains two
-@code{void *} variables called @dfn{cookies}, one for the input
-encoding, and one for the output encoding. These cookies are passed to
-the encodings' functions, for them to use however they please. A
-stateful encoding can use its cookie to hold a pointer to some object
-which maintains the context's current shift state. Stateless encodings
-will probably not use their cookies.
-
-The cookies' lifetime is the same as that of the context object. When
-the user calls @code{scm_mb_iconv_close} to destroy a context object,
-@code{scm_mb_iconv_close} calls the input and output encodings'
-@code{destroy} functions, passing them their respective cookies, so each
-encoding can free any data it allocated for that context.
-
-Note that, if a read or write function returns a successful result code
-like @code{scm_mb_read_ok} or @code{scm_mb_write_ok}, then the remaining
-input, together with the output, must together represent the complete
-input text; the encoding may not store any text temporarily in its
-cookie. This is because, if @code{scm_mb_iconv} returns a successful
-result to the user, it is correct for the user to assume that all the
-consumed input has been converted and placed in the output buffer.
-There is no ``flush'' operation to push any final results out of the
-encodings' buffers.
-
-Here is the function you call to register a new encoding with the
-conversion system:
-
-@deftypefn {Libguile Function} void scm_mb_register_encoding (struct scm_mb_encoding *@var{encoding})
-Add the encoding described by @code{*@var{encoding}} to the set
-understood by @code{scm_mb_iconv_open}. Once you have registered your
-encoding, you can use it by calling @code{scm_mb_iconv_open} with one of
-the names in @code{@var{encoding}->names}.
-@end deftypefn
-
-
-@node Multibyte Text Processing Errors, Why Guile Does Not Use a Fixed-Width Encoding, Functions for Operating on Multibyte Text, Working With Multibyte Strings in C
-@section Multibyte Text Processing Errors
-
-This section describes error conditions which code can signal to
-indicate problems encountered while processing multibyte text. In each
-case, the arguments @var{message} and @var{args} are an error format
-string and arguments to be substituted into the string, as accepted by
-the @code{display-error} function.
-
-@deffn Condition text:not-char-boundary func message args object offset
-By calling @var{func}, the program attempted to access a character at
-byte offset @var{offset} in the Guile object @var{object}, but
-@var{offset} is not the start of a character's encoding in @var{object}.
-
-Typically, @var{object} is a string or symbol. If the function signalling
-the error cannot find the Guile object that contains the text it is
-inspecting, it should use @code{#f} for @var{object}.
-@end deffn
-
-@deffn Condition text:bad-encoding func message args object
-By calling @var{func}, the program attempted to interpret the text in
-@var{object}, but @var{object} contains a byte sequence which is not a
-valid encoding for any character.
-@end deffn
-
-@deffn Condition text:not-guile-char func message args number
-By calling @var{func}, the program attempted to treat @var{number} as the
-number of a character in the Guile character set, but @var{number} does
-not correspond to any character in the Guile character set.
-@end deffn
-
-@deffn Condition text:unknown-conversion func message args from to
-By calling @var{func}, the program attempted to convert from an encoding
-named @var{from} to an encoding named @var{to}, but Guile does not
-support such a conversion.
-@end deffn
-
-@deftypevr {Libguile Variable} SCM scm_text_not_char_boundary
-@deftypevrx {Libguile Variable} SCM scm_text_bad_encoding
-@deftypevrx {Libguile Variable} SCM scm_text_not_guile_char
-These variables hold the scheme symbol objects whose names are the
-condition symbols above. You can use these when signalling these
-errors, instead of looking them up yourself.
-@end deftypevr
-
-
-@node Why Guile Does Not Use a Fixed-Width Encoding, , Multibyte Text Processing Errors, Working With Multibyte Strings in C
-@section Why Guile Does Not Use a Fixed-Width Encoding
-
-Multibyte encodings are clumsier to work with than encodings which use a
-fixed number of bytes for every character. For example, using a
-fixed-width encoding, we can extract the @var{i}th character of a string
-in constant time, and we can always substitute the @var{i}th character
-of a string with any other character without reallocating or copying the
-string.
-
-However, there are no fixed-width encodings which include the characters
-we wish to include, and also fit in a reasonable amount of space.
-Despite the Unicode standard's claims to the contrary, Unicode is not
-really a fixed-width encoding. Unicode uses surrogate pairs to
-represent characters outside the 16-bit range; a surrogate pair must be
-treated as a single character, but occupies two 16-bit spaces. As of
-this writing, there are already plans to assign characters to the
-surrogate character codes. Three- and four-byte encodings are
-too wasteful for a majority of Guile's users, who only need @sc{ASCII}
-and a few accented characters.
-
-Another alternative would be to have several different fixed-width
-string representations, each with a different element size. For each
-string, Guile would use the smallest element size capable of
-accomodating the string's text. This would allow users of English and
-the Western European languages to use the traditional memory-efficient
-encodings. However, if Guile has @var{n} string representations, then
-users must write @var{n} versions of any code which manipulates text
-directly --- one for each element size. And if a user wants to operate
-on two strings simultaneously, and wants to avoid testing the string
-sizes within the loop, she must make @var{n}*@var{n} copies of the loop.
-Most users will simply not bother. Instead, they will write code which
-supports only one string size, leaving us back where we started. By
-using a single internal representation, Guile makes it easier for users
-to write multilingual code.
-
-[[What about tagging each string with its encoding?
-"Every extension must be written to deal with every encoding"]]
-
-[[You don't really want to index strings anyway.]]
-
-Finally, Guile's multibyte encoding is not so bad. Unlike a two- or
-four-byte encoding, it is efficient in space for American and European
-users. Furthermore, the properties described above mean that many
-functions can be coded just as they would for a single-byte encoding;
-see @ref{Promised Properties of the Guile Multibyte Encoding}.
-
-@bye
diff --git a/doc/mltext.texi b/doc/mltext.texi
deleted file mode 100644
index 73071f501..000000000
--- a/doc/mltext.texi
+++ /dev/null
@@ -1,146 +0,0 @@
-@node Working with Multilingual Text
-@chapter Working with Multilingual Text
-
-@node Guile Character Properties, Exchanging Text With The Outside World, Multibyte String Functions, Functions for Operating on Multibyte Text
-@section Guile Character Properties
-
-These functions give information about the nature of a given Guile
-character. These are defined for any @code{scm_mb_char_t} value.
-
-@deftypefn {Libguile Function} int scm_mb_isalnum (scm_mb_char_t @var{c})
-Return non-zero iff @var{c} is an alphabetic or numeric character.
-@end deftypefn
-
-@deftypefn {Libguile Function} int scm_mb_is_alpha (scm_mb_char_t @var{c})
-Return non-zero iff @var{c} is an alphabetic character.
-@end deftypefn
-
-@deftypefn {Libguile Function} int scm_mb_iscntrl (scm_mb_char_t @var{c})
-Return non-zero iff @var{c} is a control character.
-@end deftypefn
-
-@deftypefn {Libguile Function} int scm_mb_isdigit (scm_mb_char_t @var{c})
-Return non-zero iff @var{c} is a digit.
-@end deftypefn
-
-@deftypefn {Libguile Function} int scm_mb_isgraph (scm_mb_char_t @var{c})
-Return non-zero iff @var{c} is a visible character.
-@end deftypefn
-
-@deftypefn {Libguile Function} int scm_mb_isupper (scm_mb_char_t @var{c})
-Return non-zero iff @var{c} is an upper-case character.
-@end deftypefn
-
-@deftypefn {Libguile Function} int scm_mb_islower (scm_mb_char_t @var{c})
-Return non-zero iff @var{c} is a lower-case character.
-@end deftypefn
-
-@deftypefn {Libguile Function} int scm_mb_istitle (scm_mb_char_t @var{c})
-Return non-zero iff @var{c} is a title-case character. See the Unicode
-standard for an explanation of title case.
-@end deftypefn
-
-@deftypefn {Libguile Function} int scm_mb_isprint (scm_mb_char_t @var{c})
-Return non-zero iff @var{c} is a printable character.
-@end deftypefn
-
-@deftypefn {Libguile Function} int scm_mb_ispunct (scm_mb_char_t @var{c})
-Return non-zero iff @var{c} is a punctuation character.
-@end deftypefn
-
-@deftypefn {Libguile Function} int scm_mb_isspace (scm_mb_char_t @var{c})
-Return non-zero iff @var{c} is a whitespace character.
-@end deftypefn
-
-@deftypefn {Libguile Function} int scm_mb_isxdigit (scm_mb_char_t @var{c})
-Return non-zero iff @var{c} is a hexadecimal digit.
-@end deftypefn
-
-@deftypefn {Libguile Function} int scm_mb_isdefined (scm_mb_char_t @var{c})
-Return non-zero iff @var{c} is a valid character.
-@end deftypefn
-
-@deftypefn {Libguile Function} scm_mb_char_t scm_mb_char_toupper (scm_mb_char_t @var{c})
-@deftypefnx {Libguile Function} scm_mb_char_t scm_mb_char_tolower (scm_mb_char_t @var{c})
-@deftypefnx {Libguile Function} scm_mb_char_t scm_mb_char_totitle (scm_mb_char_t @var{c})
-Convert @var{c} to upper, lower, or title case. If @var{c} has no
-equivalent in the requested case, or is already in that case, return it
-unchanged.
-@end deftypefn
-
-@deftypefn {Libguile Function} in scm_mb_digit_value (scm_mb_char_t @var{c})
-If @var{c} is a hexadecimal digit (according to
-@code{scm_mb_isxdigit}), then return its numeric value. Otherwise
-return -1.
-@end deftypefn
-
-@deftypefn {Libguile Function} in scm_mb_digit_value (scm_mb_char_t @var{c})
-If @var{c} is a digit (according to @code{scm_mb_isdigit}), then
-return its numeric value. Otherwise return -1.
-@end deftypefn
-
-
-@node Multibyte Character Tables, Multibyte Character Categories, Exchanging Text With The Outside World, Functions for Operating on Multibyte Text
-@section Multibyte Character Tables
-
-A @dfn{character table} is a table mapping @code{scm_mb_char_t} values
-onto Guile objects. Guile provides functions for creating character
-tables, setting entries, and looking up characters. Character tables
-are Guile objects, so they are managed by Guile's garbage collector.
-
-A character table can have a ``parent'' table, from which it inherits
-values for characters. If a character table @var{child}, with a parent
-table @var{parent} maps some character @var{c} to the value
-@code{SCM_UNDEFINED}, then @code{scm_c_char_table_ref (@var{child},
-@var{c})} will look up @var{c} in @var{parent}, and return the value it
-finds there.
-
-This section describes only the C API for working with character tables.
-For the Scheme-level API, see @ref{some other section}.
-
-@deftypefn {Libguile Function} scm_make_char_table (SCM @var{init}, SCM @var{parent})
-Return a new character table object which maps every character to
-@var{init}. If @var{parent} is a character table, then @var{parent} is
-the new table's parent. If @var{parent} table is @code{SCM_UNDEFINED},
-then the new table has no parent. Otherwise, signal a type error.
-@end deffn
-
-@deftypefn {Libguile Function} SCM scm_c_char_table_ref (SCM @var{table}, scm_mb_char_t @var{c})
-Look up the character @var{c} in the character table @var{table}, and
-return the value found there. If @var{table} maps @var{c} to
-@code{SCM_UNDEFINED}, and @var{table} has a parent, then look up @var{c}
-in the parent.
-
-If @var{table} is not a character table, signal an error.
-@end deftypefn
-
-@deftypefn {Libguile Function} SCM scm_c_char_table_set_x (SCM @var{table}, scm_mb_char_t @var{c}, SCM @var{value})
-Set @var{table}'s value for the character @var{c} to @var{value}.
-If @var{value} is @code{SCM_UNDEFINED}, then @var{table}'s parent's
-value will show through for @var{c}.
-
-If @var{table} is not a character table, signal an error.
-
-This function changes only @var{table} itself, never @var{table}'s
-parent.
-@end deftypefn
-
-[[this is all wrong. what about default values?]]
-
-
-
-
-
-@node Multibyte Character Categories, , Multibyte Character Tables, Functions for Operating on Multibyte Text
-@section Multibyte Character Categories
-
-[[This will describe an ADT representing subsets of the Guile character
-set.]]
-
-
-
-
-@node Exchanging Guile Text With the Outside World
-@subsection Exchanging Guile Text With the Outside World
-
-[[Scheme-level functions for converting between encodings]]
diff --git a/doc/oldfmt.c b/doc/oldfmt.c
deleted file mode 100644
index 19fbffcc5..000000000
--- a/doc/oldfmt.c
+++ /dev/null
@@ -1,218 +0,0 @@
-/* Copyright (C) 2000,2001 Free Software Foundation, Inc.
- *
- * This program 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 2, or (at your option)
- * any later version.
- *
- * This program 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 this software; see the file COPYING. If not, write to
- * the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- * Boston, MA 02111-1307 USA
- *
- * As a special exception, the Free Software Foundation gives permission
- * for additional uses of the text contained in its release of GUILE.
- *
- * The exception is that, if you link the GUILE library with other files
- * to produce an executable, this does not by itself cause the
- * resulting executable to be covered by the GNU General Public License.
- * Your use of that executable is in no way restricted on account of
- * linking the GUILE library code into it.
- *
- * This exception does not however invalidate any other reasons why
- * the executable file might be covered by the GNU General Public License.
- *
- * This exception applies only to the code released by the
- * Free Software Foundation under the name GUILE. If you copy
- * code from other Free Software Foundation releases into a copy of
- * GUILE, as the General Public License permits, the exception does
- * not apply to the code that you add in this way. To avoid misleading
- * anyone as to the status of such modified files, you must delete
- * this exception notice from them.
- *
- * If you write modifications of your own for GUILE, it is your choice
- * whether to permit this exception to apply to your modifications.
- * If you do not wish that, delete this exception notice.
- */
-
-
-
-/* From NEWS:
- *
- * * New primitive: `simple-format', affects `scm-error', scm_display_error, & scm_error message strings
- *
- * (ice-9 boot) makes `format' an alias for `simple-format' until possibly
- * extended by the more sophisticated version in (ice-9 format)
- *
- * (simple-format port message . args)
- * Write MESSAGE to DESTINATION, defaulting to `current-output-port'.
- * MESSAGE can contain ~A (was %s) and ~S (was %S) escapes. When printed,
- * the escapes are replaced with corresponding members of ARGS:
- * ~A formats using `display' and ~S formats using `write'.
- * If DESTINATION is #t, then use the `current-output-port',
- * if DESTINATION is #f, then return a string containing the formatted text.
- * Does not add a trailing newline."
- *
- * The two C procedures: scm_display_error and scm_error, as well as the
- * primitive `scm-error', now use scm_format to do their work. This means
- * that the message strings of all code must be updated to use ~A where %s
- * was used before, and ~S where %S was used before.
- *
- * During the period when there still are a lot of old Guiles out there,
- * you might want to support both old and new versions of Guile.
- *
- * There are basically two methods to achieve this. Both methods use
- * autoconf. Put
- *
- * AC_CHECK_FUNCS(scm_simple_format)
- *
- * in your configure.in.
- *
- * Method 1: Use the string concatenation features of ANSI C's
- * preprocessor.
- *
- * In C:
- *
- * #ifdef HAVE_SCM_SIMPLE_FORMAT
- * #define FMT_S "~S"
- * #else
- * #define FMT_S "%S"
- * #endif
- *
- * Then represent each of your error messages using a preprocessor macro:
- *
- * #define E_SPIDER_ERROR "There's a spider in your " ## FMT_S ## "!!!"
- *
- * In Scheme:
- *
- * (define fmt-s (if (defined? 'simple-format) "~S" "%S"))
- * (define make-message string-append)
- *
- * (define e-spider-error
- * (make-message "There's a spider in your " fmt-s "!!!"))
- *
- * Method 2: Use the oldfmt function found in doc/oldfmt.c.
- *
- * In C:
- *
- * scm_misc_error ("picnic", scm_c_oldfmt0 ("There's a spider in your ~S!!!"),
- * ...);
- *
- * In Scheme:
- *
- * (scm-error 'misc-error "picnic" (oldfmt "There's a spider in your ~S!!!")
- * ...)
- *
- */
-
-/*
- * Take a format string FROM adhering to the new standard format (~A and ~S
- * as placeholders) of length N and return a string which is adapted
- * to the format used by the Guile interpreter which you are running.
- *
- * On successive calls with similar strings but different storage, the
- * same string with same storage is returned. This is necessary since
- * the existence of a garbage collector in the system may cause the same
- * format string to be represented with different storage at different
- * calls.
- */
-
-char *
-scm_c_oldfmt (char *from, int n)
-{
-#ifdef HAVE_SCM_SIMPLE_FORMAT
- return from;
-#else
- static struct { int n; char *from; char *to; } *strings;
- static int size = 0;
- static int n_strings = 0;
- char *to;
- int i;
-
- for (i = 0; i < n_strings; ++i)
- if (n == strings[i].n && strncmp (from, strings[i].from, n) == 0)
- return strings[i].to;
-
- if (n_strings == size)
- {
- if (size == 0)
- {
- size = 10;
- strings = scm_must_malloc (size * sizeof (*strings), s_oldfmt);
- }
- else
- {
- int oldsize = size;
- size = 3 * oldsize / 2;
- strings = scm_must_realloc (strings,
- oldsize * sizeof (*strings),
- size * sizeof (*strings),
- s_oldfmt);
- }
- }
-
- strings[n_strings].n = n;
- strings[n_strings].from = strncpy (scm_must_malloc (n, s_oldfmt), from, n);
- to = strings[n_strings].to = scm_must_malloc (n + 1, s_oldfmt);
- n_strings++;
-
- for (i = 0; i < n; ++i)
- {
- if (from[i] == '~' && ++i < n)
- {
- if (from[i] == 'A')
- {
- to[i - 1] = '%';
- to[i] = 's';
- }
- else if (from[i] == 'S')
- {
- to[i - 1] = '%';
- to[i] = 'S';
- }
- else
- {
- to[i - 1] = '~';
- to[i] = from[i];
- }
- continue;
- }
- to[i] = from[i];
- }
- to[i] = '\0';
-
- return to;
-#endif
-}
-
-char *
-scm_c_oldfmt0 (char *s)
-{
-#ifdef HAVE_SCM_SIMPLE_FORMAT
- return s;
-#else
- return scm_c_oldfmt (s, strlen (s));
-#endif
-}
-
-SCM_PROC (s_oldfmt, "oldfmt", 1, 0, 0, scm_oldfmt);
-
-SCM
-scm_oldfmt (SCM s)
-{
-#ifdef HAVE_SCM_SIMPLE_FORMAT
- return s;
-#else
- int n;
- SCM_ASSERT (SCM_NIMP (s) && SCM_STRINGP (s), s, 1, s_oldfmt);
- n = SCM_LENGTH (s);
- return scm_return_first (scm_mem2string (scm_c_oldfmt (SCM_ROCHARS (s), n),
- n),
- s);
-#endif
-}
diff --git a/doc/r5rs/.cvsignore b/doc/r5rs/.cvsignore
deleted file mode 100644
index 407face4c..000000000
--- a/doc/r5rs/.cvsignore
+++ /dev/null
@@ -1,22 +0,0 @@
-Makefile
-Makefile.in
-stamp-vti
-stamp-vti.1
-*.log
-*.dvi
-*.aux
-*.toc
-*.cp
-*.fn
-*.vr
-*.tp
-*.ky
-*.pg
-*.pgs
-*.cps
-*.fns
-*.tps
-*.vrs
-*.ps
-*.info*
-*.html
diff --git a/doc/r5rs/ChangeLog b/doc/r5rs/ChangeLog
deleted file mode 100644
index 4b0973487..000000000
--- a/doc/r5rs/ChangeLog
+++ /dev/null
@@ -1,10 +0,0 @@
-2001-08-27 Neil Jerram <neil@ossau.uklinux.net>
-
- * Makefile.am (TEXINFO_TEX): Added; avoids shipping multiple copies of
- texinfo.tex in a single distribution.
-
-2001-08-27 Neil Jerram <neil@ossau.uklinux.net>
-
- The change log for files in this directory continues backwards
- from 2001-08-27 in ../ChangeLog, as all the Guile documentation
- prior to this date was contained in a single directory.
diff --git a/doc/r5rs/Makefile.am b/doc/r5rs/Makefile.am
deleted file mode 100644
index 2b3d40a67..000000000
--- a/doc/r5rs/Makefile.am
+++ /dev/null
@@ -1,26 +0,0 @@
-## Process this file with Automake to create Makefile.in
-##
-## Copyright (C) 1998 Free Software Foundation, Inc.
-##
-## This file is part of GUILE.
-##
-## GUILE 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 2, or
-## (at your option) any later version.
-##
-## GUILE 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 GUILE; see the file COPYING. If not, write
-## to the Free Software Foundation, Inc., 59 Temple Place, Suite
-## 330, Boston, MA 02111-1307 USA
-
-AUTOMAKE_OPTIONS = gnu
-
-info_TEXINFOS = r5rs.texi
-
-TEXINFO_TEX = ../ref/texinfo.tex
diff --git a/doc/r5rs/r5rs.texi b/doc/r5rs/r5rs.texi
deleted file mode 100644
index a33771190..000000000
--- a/doc/r5rs/r5rs.texi
+++ /dev/null
@@ -1,8538 +0,0 @@
-\input texinfo @c -*-texinfo-*-
-@c %**start of header
-@setfilename r5rs.info
-@settitle Revised(5) Scheme
-
-@c This copy of r5rs.texi differs from Aubrey Jaffer's master copy
-@c by a set of changes to allow the building of r5rs.dvi from r5rs.texi.
-@c Aubrey Jaffer's view - which I agree with - is that, given that
-@c people have the option of building r5rs.dvi from the original
-@c LaTeX distribution for R5RS, it is not worth fixing his master
-@c copy of r5rs.texi and the tool which autogenerates it. On the
-@c other hand, it is a marginal convenience for people to be able to
-@c build hardcopy from r5rs.texi, even if the results are less good
-@c than with the original LaTeX. Hence the following fixes.
-@c (lines 714, 725, 728, 1614, 2258): Remove invalid parentheses from
-@c @deffn statements.
-@c (line 2316): Change @deffnx to @deffn, and insert `@end deffn' to
-@c terminate preceding @deffn.
-@c (line 7320): Insert `@c ' at beginning of lines that are intended
-@c to be @ignore'd.
-@c
-@c NJ 2001/1/26
-
-@c \documentclass[twoside]{algol60}
-
-@c \pagestyle{headings}
-@c \showboxdepth=0
-
-
-
-@c \def\headertitle{Revised$^{5}$ Scheme}
-@c \def\integerversion{5}
-
-@c Sizes and dimensions
-
-@c \topmargin -.375in % Nominal distance from top of page to top of
-
-@c box containing running head.
-@c \headsep 15pt % Space between running head and text.
-
-@c \textheight 663pt % Height of text (including footnotes and figures,
-
-@c excluding running head and foot).
-
-@c \textwidth 523pt % Width of text line.
-@c \columnsep 15pt % Space between columns
-@c \columnseprule 0pt % Width of rule between columns.
-
-@c \parskip 5pt plus 2pt minus 2pt % Extra vertical space between paragraphs.
-@c \parindent 0pt % Width of paragraph indentation.
-@c \topsep 0pt plus 2pt % Extra vertical space, in addition to
-
-@c \parskip, added above and below list and
-
-@c paragraphing environments.
-
-@c \oddsidemargin -.5in % Left margin on odd-numbered pages.
-@c \evensidemargin -.5in % Left margin on even-numbered pages.
-
-@c % End of sizes and dimensions
-
-@paragraphindent 0
-@c %**end of header
-@c syncodeindex fn cp
-
-@ifinfo
-@dircategory The Algorithmic Language Scheme
-@direntry
-* R5RS: (r5rs). The Revised(5) Report on Scheme.
-@end direntry
-@end ifinfo
-
-
-@c \parindent 0pt %!! 15pt % Width of paragraph indentation.
-
- @b{20 February 1998}
-@c \hfil \today{}
-
-@c @include{first}
-@titlepage
-
-@c HTML first page
-@title Scheme
-@subtitle Revised(5) Report on the Algorithmic Language Scheme
-@c First page
-
-@c \thispagestyle{empty}
-
-@c \todo{"another" report?}
-
-
-@author R@sc{ICHARD} K@sc{ELSEY}, W@sc{ILLIAM} C@sc{LINGER, AND} J@sc{ONATHAN} R@sc{EES} (@i{Editors})
-@author H. A@sc{BELSON}
-@author R. K. D@sc{YBVIG}
-@author C. T. H@sc{AYNES}
-@author G. J. R@sc{OZAS}
-@author N. I. A@sc{DAMS IV}
-@author D. P. F@sc{RIEDMAN}
-@author E. K@sc{OHLBECKER}
-@author G. L. S@sc{TEELE} J@sc{R}.
-@author D. H. B@sc{ARTLEY}
-@author R. H@sc{ALSTEAD}
-@author D. O@sc{XLEY}
-@author G. J. S@sc{USSMAN}
-@author G. B@sc{ROOKS}
-@author C. H@sc{ANSON}
-@author K. M. P@sc{ITMAN}
-@author M. W@sc{AND}
-@author
-
-
-@c {\it Dedicated to the Memory of ALGOL 60}
-@i{Dedicated to the Memory of Robert Hieb}
-@c [For the macros in R5RS -RK]
-
-
-
-
-@unnumbered Summary
-
-
-The report gives a defining description of the programming language
-Scheme. Scheme is a statically scoped and properly tail-recursive
-dialect of the Lisp programming language invented by Guy Lewis
-Steele Jr.@: and Gerald Jay Sussman. It was designed to have an
-exceptionally clear and simple semantics and few different ways to
-form expressions. A wide variety of programming paradigms, including
-imperative, functional, and message passing styles, find convenient
-expression in Scheme.
-
-The introduction offers a brief history of the language and of
-the report.
-
-The first three chapters present the fundamental ideas of the
-language and describe the notational conventions used for describing the
-language and for writing programs in the language.
-
-Chapters @ref{Expressions} and @ref{Program structure} describe
-the syntax and semantics of expressions, programs, and definitions.
-
-Chapter @ref{Standard procedures} describes Scheme's built-in
-procedures, which include all of the language's data manipulation and
-input/output primitives.
-
-Chapter @ref{Formal syntax and semantics} provides a formal syntax for Scheme
-written in extended BNF, along with a formal denotational semantics.
-An example of the use of the language follows the formal syntax and
-semantics.
-
-The report concludes with a list of references and an
-alphabetic index.
-
-@ignore todo
-expand the summary so that it fills up the column.
-@end ignore
-
-
-@c \vfill
-@c \begin{center}
-@c {\large \bf
-@c *** DRAFT*** \\
-@c %August 31, 1989
-@c \today
-@c }\end{center}
-
-
-
-
-
-@c \addvspace{3.5pt} % don't shrink this gap
-@c \renewcommand{\tocshrink}{-3.5pt} % value determined experimentally
-
-
-
-
-
-
-@page
-
-@end titlepage
-
-@c INFO first page
-@ifinfo
-
-@c First page
-
-@c \thispagestyle{empty}
-
-@c \todo{"another" report?}
-
-
-@node top, Introduction, (dir), (dir)
-@top Revised(5) Report on the Algorithmic Language Scheme
-
-@sp 1
-
-
-@center @c begin-tabular
-@quotation
-@multitable @columnfractions 0.25 0.25 0.25 0.25
-@item
-@center R@sc{ICHARD} K@sc{ELSEY}, W@sc{ILLIAM} C@sc{LINGER, AND} J@sc{ONATHAN} R@sc{EES} (@i{Editors})
-@item H. A@sc{BELSON} @tab R. K. D@sc{YBVIG} @tab C. T. H@sc{AYNES} @tab G. J. R@sc{OZAS}
-@item N. I. A@sc{DAMS IV} @tab D. P. F@sc{RIEDMAN} @tab E. K@sc{OHLBECKER} @tab G. L. S@sc{TEELE} J@sc{R}.
-@item D. H. B@sc{ARTLEY} @tab R. H@sc{ALSTEAD} @tab D. O@sc{XLEY} @tab G. J. S@sc{USSMAN}
-@item G. B@sc{ROOKS} @tab C. H@sc{ANSON} @tab K. M. P@sc{ITMAN} @tab M. W@sc{AND}
-@item
-@end multitable
-@end quotation
-
-
-@sp 2
-
-@c {\it Dedicated to the Memory of ALGOL 60}
-@i{Dedicated to the Memory of Robert Hieb}
-@c [For the macros in R5RS -RK]
-
-@sp 3
-
-
-
-
-@majorheading Summary
-
-
-The report gives a defining description of the programming language
-Scheme. Scheme is a statically scoped and properly tail-recursive
-dialect of the Lisp programming language invented by Guy Lewis
-Steele Jr.@: and Gerald Jay Sussman. It was designed to have an
-exceptionally clear and simple semantics and few different ways to
-form expressions. A wide variety of programming paradigms, including
-imperative, functional, and message passing styles, find convenient
-expression in Scheme.
-
-The introduction offers a brief history of the language and of
-the report.
-
-The first three chapters present the fundamental ideas of the
-language and describe the notational conventions used for describing the
-language and for writing programs in the language.
-
-Chapters @ref{Expressions} and @ref{Program structure} describe
-the syntax and semantics of expressions, programs, and definitions.
-
-Chapter @ref{Standard procedures} describes Scheme's built-in
-procedures, which include all of the language's data manipulation and
-input/output primitives.
-
-Chapter @ref{Formal syntax and semantics} provides a formal syntax for Scheme
-written in extended BNF, along with a formal denotational semantics.
-An example of the use of the language follows the formal syntax and
-semantics.
-
-The report concludes with a list of references and an
-alphabetic index.
-
-@ignore todo
-expand the summary so that it fills up the column.
-@end ignore
-
-
-@c \vfill
-@c \begin{center}
-@c {\large \bf
-@c *** DRAFT*** \\
-@c %August 31, 1989
-@c \today
-@c }\end{center}
-
-
-
-
-
-@c \addvspace{3.5pt} % don't shrink this gap
-@c \renewcommand{\tocshrink}{-3.5pt} % value determined experimentally
-
-@unnumbered Contents
-
-@menu
-* Introduction::
-* Overview of Scheme::
-* Lexical conventions::
-* Basic concepts::
-* Expressions::
-* Program structure::
-* Standard procedures::
-* Formal syntax and semantics::
-* Notes::
-* Additional material::
-* Example::
-* Bibliography::
-* Index::
-@end menu
-
-
-
-
-
-@page
-
-@end ifinfo
-
-
-@c @include{intro}
-@node Introduction, Overview of Scheme, top, top
-@unnumbered Introduction
-
-@menu
-* Background::
-* Acknowledgements::
-@end menu
-
-
-
-
-Programming languages should be designed not by piling feature on top of
-feature, but by removing the weaknesses and restrictions that make additional
-features appear necessary. Scheme demonstrates that a very small number
-of rules for forming expressions, with no restrictions on how they are
-composed, suffice to form a practical and efficient programming language
-that is flexible enough to support most of the major programming
-paradigms in use today.
-
-@c Scheme has influenced the evolution of Lisp.
-Scheme
-was one of the first programming languages to incorporate first class
-procedures as in the lambda calculus, thereby proving the usefulness of
-static scope rules and block structure in a dynamically typed language.
-Scheme was the first major dialect of Lisp to distinguish procedures
-from lambda expressions and symbols, to use a single lexical
-environment for all variables, and to evaluate the operator position
-of a procedure call in the same way as an operand position. By relying
-entirely on procedure calls to express iteration, Scheme emphasized the
-fact that tail-recursive procedure calls are essentially goto's that
-pass arguments. Scheme was the first widely used programming language to
-embrace first class escape procedures, from which all previously known
-sequential control structures can be synthesized. A subsequent
-version of Scheme introduced the concept of exact and inexact numbers,
-an extension of Common Lisp's generic arithmetic.
-More recently, Scheme became the first programming language to support
-hygienic macros, which permit the syntax of a block-structured language
-to be extended in a consistent and reliable manner.
-@c A few
-@c of these innovations have recently been incorporated into Common Lisp, while
-@c others remain to be adopted.
-
-@ignore todo
-Ramsdell:
-I would like to make a few comments on presentation. The most
-important comment is about section organization. Newspaper writers
-spend most of their time writing the first three paragraphs of any
-article. This part of the article is often the only part read by
-readers, and is important in enticing readers to continue. In the
-same way, The first page is most likely to be the only page read by
-many SIGPLAN readers. If I had my choice of what I would ask them to
-read, it would be the material in section 1.1, the Semantics section
-that notes that scheme is lexically scoped, tail recursive, weakly
-typed, ... etc. I would expand on the discussion on continuations,
-as they represent one important difference between Scheme and other
-languages. The introduction, with its history of scheme, its history
-of scheme reports and meetings, and acknowledgements giving names of
-people that the reader will not likely know, is not that one page I
-would like all to read. I suggest moving the history to the back of
-the report, and use the first couple of pages to convince the reader
-that the language documented in this report is worth studying.
-
-@end ignore
-
-
-@node Background, Acknowledgements, Introduction, Introduction
-@unnumberedsec Background
-
-
-The first description of Scheme was written in
-1975 [Scheme75]. A revised report [Scheme78]
-@ignore todo
-italicize or not?
-@end ignore
- appeared in 1978, which described the evolution
-of the language as its MIT implementation was upgraded to support an
-innovative compiler [Rabbit]. Three distinct projects began in
-1981 and 1982 to use variants of Scheme for courses at MIT, Yale, and
-Indiana University [Rees82], [MITScheme], [Scheme311]. An introductory
-computer science textbook using Scheme was published in
-1984 [SICP].
-
-@c \vest As might be expected of a language used primarily for education and
-@c research, Scheme has always evolved rapidly. This was no problem when
-@c Scheme was used only within MIT, but
-As Scheme became more widespread,
-local dialects began to diverge until students and researchers
-occasionally found it difficult to understand code written at other
-sites.
-Fifteen representatives of the major implementations of Scheme therefore
-met in October 1984 to work toward a better and more widely accepted
-standard for Scheme.
-@c Participating in this workshop were Hal Abelson, Norman Adams, David
-@c Bartley, Gary Brooks, William Clinger, Daniel Friedman, Robert Halstead,
-@c Chris Hanson, Christopher Haynes, Eugene Kohlbecker, Don Oxley, Jonathan Rees,
-@c Guillermo Rozas, Gerald Jay Sussman, and Mitchell Wand. Kent Pitman
-@c made valuable contributions to the agenda for the workshop but was
-@c unable to attend the sessions.
-
-@c Subsequent electronic mail discussions and committee work completed the
-@c definition of the language.
-@c Gerry Sussman drafted the section on numbers, Chris Hanson drafted the
-@c sections on characters and strings, and Gary Brooks and William Clinger
-@c drafted the sections on input and output.
-@c William Clinger recorded the decisions of the workshop and
-@c compiled the pieces into a coherent document.
-@c The ``Revised revised report on Scheme''~\cite{RRRS}
-Their report [RRRS]
-was published at MIT and Indiana University in the summer of 1985.
-Further revision took place in the spring of 1986 [R3RS],
-@c , again accomplished
-@c almost entirely by electronic mail, resulted in the present report.
-and in the spring of 1988 [R4RS].
-The present report reflects further revisions agreed upon in a meeting
-at Xerox PARC in June 1992.
-
-@c \vest The number 3 in the title is part of the title, not a reference to
-@c a footnote. The word ``revised'' is raised to the third power because
-@c the report is a revision of a report that was already twice revised.
-
-@ignore todo
-Write an editors' note?
-@end ignore
-
-
-
-@sp 3
-
-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.
-
-
-
-
-@node Acknowledgements, , Background, Introduction
-@unnumberedsec Acknowledgements
-
-
-We would like to thank the following people for their help: Alan Bawden, Michael
-Blair, George Carrette, Andy Cromarty, Pavel Curtis, Jeff Dalton, Olivier Danvy,
-Ken Dickey, Bruce Duba, Marc Feeley,
-Andy Freeman, Richard Gabriel, Yekta G"ursel, Ken Haase, Robert
-Hieb, Paul Hudak, Morry Katz, Chris Lindblad, Mark Meyer, Jim Miller, Jim Philbin,
-John Ramsdell, Mike Shaff, Jonathan Shapiro, Julie Sussman,
-Perry Wagle, Daniel Weise, Henry Wu, and Ozan Yigit.
-We thank Carol Fessenden, Daniel
-Friedman, and Christopher Haynes for permission to use text from the Scheme 311
-version 4 reference manual. We thank Texas Instruments, Inc. for permission to
-use text from the @emph{TI Scheme Language Reference Manual}[TImanual85].
-We gladly acknowledge the influence of manuals for MIT Scheme[MITScheme],
-T[Rees84], Scheme 84[Scheme84],Common Lisp[CLtL],
-and Algol 60[Naur63].
-
-We also thank Betty Dexter for the extreme effort she put into
-setting this report in @TeX{}, and Donald Knuth for designing the program
-that caused her troubles.
-
-The Artificial Intelligence Laboratory of the
-Massachusetts Institute of Technology, the Computer Science
-Department of Indiana University, the Computer and Information
-Sciences Department of the University of Oregon, and the NEC Research
-Institute supported the preparation of this report. Support for the MIT
-work was provided in part by
-the Advanced Research Projects Agency of the Department of Defense under Office
-of Naval Research contract N00014-80-C-0505. Support for the Indiana
-University work was provided by NSF grants NCS 83-04567 and NCS
-83-03325.
-
-
-
-
-@sp 2
-
-@c \clearchapterstar{Description of the language} %\unskip\vskip -2ex
-@c @include{struct}
-
-@c 1. Structure of the language
-
-@node Overview of Scheme, Lexical conventions, Introduction, top
-@chapter Overview of Scheme
-
-@menu
-* Semantics::
-* Syntax::
-* Notation and terminology::
-@end menu
-
-
-@node Semantics, Syntax, Overview of Scheme, Overview of Scheme
-@section Semantics
-
-
-
-This section gives an overview of Scheme's semantics. A
-detailed informal semantics is the subject of
-chapters @ref{Basic concepts} through @ref{Standard procedures}. For reference
-purposes, section @ref{Formal semantics} provides a formal
-semantics of Scheme.
-
-Following Algol, Scheme is a statically scoped programming
-language. Each use of a variable is associated with a lexically
-apparent binding of that variable.
-
-Scheme has latent as opposed to manifest types. Types
-are associated with values (also called objects) rather than
-@cindex @w{object}
-with variables. (Some authors refer to languages with latent types as
-weakly typed or dynamically typed languages.) Other languages with
-latent types are APL, Snobol, and other dialects of Lisp. Languages
-with manifest types (sometimes referred to as strongly typed or
-statically typed languages) include Algol 60, Pascal, and C.
-
-All objects created in the course of a Scheme computation, including
-procedures and continuations, have unlimited extent.
-No Scheme object is ever destroyed. The reason that
-implementations of Scheme do not (usually!) run out of storage is that
-they are permitted to reclaim the storage occupied by an object if
-they can prove that the object cannot possibly matter to any future
-computation. Other languages in which most objects have unlimited
-extent include APL and other Lisp dialects.
-
-Implementations of Scheme are required to be properly tail-recursive.
-This allows the execution of an iterative computation in constant space,
-even if the iterative computation is described by a syntactically
-recursive procedure. Thus with a properly tail-recursive implementation,
-iteration can be expressed using the ordinary procedure-call
-mechanics, so that special iteration constructs are useful only as
-syntactic sugar. See section @ref{Proper tail recursion}.
-
-Scheme procedures are objects in their own right. Procedures can be
-created dynamically, stored in data structures, returned as results of
-procedures, and so on. Other languages with these properties include
-Common Lisp and ML.
-@ignore todo
-Rozas: Scheme had them first.
-@end ignore
-
-
-One distinguishing feature of Scheme is that continuations, which
-in most other languages only operate behind the scenes, also have
-``first-class'' status. Continuations are useful for implementing a
-wide variety of advanced control constructs, including non-local exits,
-backtracking, and coroutines. See section @ref{Control features}.
-
-Arguments to Scheme procedures are always passed by value, which
-means that the actual argument expressions are evaluated before the
-procedure gains control, whether the procedure needs the result of the
-evaluation or not. ML, C, and APL are three other languages that always
-pass arguments by value.
-This is distinct from the lazy-evaluation semantics of Haskell,
-or the call-by-name semantics of Algol 60, where an argument
-expression is not evaluated unless its value is needed by the
-procedure.
-
-@ignore todo
-Lisp's call by value should be explained more
-accurately. What's funny is that all values are references.
-@end ignore
-
-
-Scheme's model of arithmetic is designed to remain as independent as
-possible of the particular ways in which numbers are represented within a
-computer. In Scheme, every integer is a rational number, every rational is a
-real, and every real is a complex number. Thus the distinction between integer
-and real arithmetic, so important to many programming languages, does not
-appear in Scheme. In its place is a distinction between exact arithmetic,
-which corresponds to the mathematical ideal, and inexact arithmetic on
-approximations. As in Common Lisp, exact arithmetic is not limited to
-integers.
-
-@node Syntax, Notation and terminology, Semantics, Overview of Scheme
-@section Syntax
-
-
-Scheme, like most dialects of Lisp, employs a fully parenthesized prefix
-notation for programs and (other) data; the grammar of Scheme generates a
-sublanguage of the language used for data. An important
-consequence of this simple, uniform representation is the susceptibility of
-Scheme programs and data to uniform treatment by other Scheme programs.
-For example, the @samp{eval} procedure evaluates a Scheme program expressed
-as data.
-
-The @samp{read} procedure performs syntactic as well as lexical decomposition of
-the data it reads. The @samp{read} procedure parses its input as data
-(section @pxref{External representation}), not as program.
-
-The formal syntax of Scheme is described in section @ref{Formal syntax}.
-
-
-@node Notation and terminology, , Syntax, Overview of Scheme
-@section Notation and terminology
-
-@menu
-* Primitive; library; and optional features::
-* Error situations and unspecified behavior::
-* Entry format::
-* Evaluation examples::
-* Naming conventions::
-@end menu
-
-
-
-@node Primitive; library; and optional features, Error situations and unspecified behavior, Notation and terminology, Notation and terminology
-@subsection Primitive; library; and optional features
-
-
-
-It is required that every implementation of Scheme support all
-features that are not marked as being @dfn{optional}. Implementations are
-@cindex @w{optional}
-free to omit optional features of Scheme or to add extensions,
-provided the extensions are not in conflict with the language reported
-here. In particular, implementations must support portable code by
-providing a syntactic mode that preempts no lexical conventions of this
-report.
-
-To aid in understanding and implementing Scheme, some features are marked
-as @dfn{library}. These can be easily implemented in terms of the other,
-@cindex @w{library}
-primitive, features. They are redundant in the strict sense of
-the word, but they capture common patterns of usage, and are therefore
-provided as convenient abbreviations.
-
-@node Error situations and unspecified behavior, Entry format, Primitive; library; and optional features, Notation and terminology
-@subsection Error situations and unspecified behavior
-
-
-
-@cindex @w{error}
-When speaking of an error situation, this report uses the phrase ``an
-error is signalled'' to indicate that implementations must detect and
-report the error. If such wording does not appear in the discussion of
-an error, then implementations are not required to detect or report the
-error, though they are encouraged to do so. An error situation that
-implementations are not required to detect is usually referred to simply
-as ``an error.''
-
-For example, it is an error for a procedure to be passed an argument that
-the procedure is not explicitly specified to handle, even though such
-domain errors are seldom mentioned in this report. Implementations may
-extend a procedure's domain of definition to include such arguments.
-
-This report uses the phrase ``may report a violation of an
-implementation restriction'' to indicate circumstances under which an
-implementation is permitted to report that it is unable to continue
-execution of a correct program because of some restriction imposed by the
-implementation. Implementation restrictions are of course discouraged,
-but implementations are encouraged to report violations of implementation
-restrictions.
-@cindex @w{implementation restriction}
-
-For example, an implementation may report a violation of an
-implementation restriction if it does not have enough storage to run a
-program.
-
-If the value of an expression is said to be ``unspecified,'' then
-the expression must evaluate to some object without signalling an error,
-but the value depends on the implementation; this report explicitly does
-not say what value should be returned.
-@cindex @w{unspecified}
-
-@ignore todo
-Talk about unspecified behavior vs. unspecified values.
-@end ignore
-
-
-@ignore todo
-Look at KMP's situations paper.
-@end ignore
-
-
-
-@node Entry format, Evaluation examples, Error situations and unspecified behavior, Notation and terminology
-@subsection Entry format
-
-
-Chapters @ref{Expressions} and @ref{Standard procedures} are organized
-into entries. Each entry describes one language feature or a group of
-related features, where a feature is either a syntactic construct or a
-built-in procedure. An entry begins with one or more header lines of the form
-
-
-@noindent
-@deffn {@var{category}} @var{template}
-
-@end deffn
-
-for required, primitive features, or
-
-
-@noindent
-@deffn {@var{qualifier} @var{category}} @var{template}
-
-@end deffn
-
-where @var{qualifier} is either ``library'' or ``optional'' as defined
- in section @ref{Primitive; library; and optional features}.
-
-If @var{category} is ``syntax'', the entry describes an expression
-type, and the template gives the syntax of the expression type.
-Components of expressions are designated by syntactic variables, which
-are written using angle brackets, for example, @r{<expression>},
-@r{<variable>}. Syntactic variables should be understood to denote segments of
-program text; for example, @r{<expression>} stands for any string of
-characters which is a syntactically valid expression. The notation
-
-@format
- @r{<thing1>} @dots{}
-@end format
-
-indicates zero or more occurrences of a @r{<thing>}, and
-
-@format
- @r{<thing1>} @r{<thing2>} @dots{}
-@end format
-
-indicates one or more occurrences of a @r{<thing>}.
-
-If @var{category} is ``procedure'', then the entry describes a procedure, and
-the header line gives a template for a call to the procedure. Argument
-names in the template are @var{italicized}. Thus the header line
-
-
-@noindent
-@deffn {procedure} vector-ref @var{vector} @var{k}
-
-@end deffn
-
-indicates that the built-in procedure @t{vector-ref} takes
-two arguments, a vector @var{vector} and an exact non-negative integer
-@var{k} (see below). The header lines
-
-
-@noindent
-
-@deffn {procedure} make-vector @var{k}
-
-
-@deffnx {procedure} make-vector @var{k} @var{fill}
-
-@end deffn
-
-indicate that the @t{make-vector} procedure must be defined to take
-either one or two arguments.
-
-
-It is an error for an operation to be presented with an argument that it
-is not specified to handle. For succinctness, we follow the convention
-that if an argument name is also the name of a type listed in
-section @ref{Disjointness of types}, then that argument must be of the named type.
-For example, the header line for @t{vector-ref} given above dictates that the
-first argument to @t{vector-ref} must be a vector. The following naming
-conventions also imply type restrictions:
-@c \newcommand{\foo}[1]{\vr{#1}, \vri{#1}, $\ldots$ \vrj{#1}, $\ldots$}
-
-
-@center @c begin-tabular
-@quotation
-@table @asis
-@item @var{obj}
-any object
-@item @var{list}, @var{list1}, @dots{} @var{listj}, @dots{}
-list (see section @pxref{Pairs and lists})
-@item @var{z}, @var{z1}, @dots{} @var{zj}, @dots{}
-complex number
-@item @var{x}, @var{x1}, @dots{} @var{xj}, @dots{}
-real number
-@item @var{y}, @var{y1}, @dots{} @var{yj}, @dots{}
-real number
-@item @var{q}, @var{q1}, @dots{} @var{qj}, @dots{}
-rational number
-@item @var{n}, @var{n1}, @dots{} @var{nj}, @dots{}
-integer
-@item @var{k}, @var{k1}, @dots{} @var{kj}, @dots{}
-exact non-negative integer
-@item
-@end table
-@end quotation
-
-
-
-
-@ignore todo
-Provide an example entry??
-@end ignore
-
-
-
-@node Evaluation examples, Naming conventions, Entry format, Notation and terminology
-@subsection Evaluation examples
-
-
-The symbol ``@result{}'' used in program examples should be read
-``evaluates to.'' For example,
-
-
-@example
-
-(* 5 8) ==> 40
-
-@end example
-
-
-means that the expression @t{(* 5 8)} evaluates to the object @t{40}.
-Or, more precisely: the expression given by the sequence of characters
-``@t{(* 5 8)}'' evaluates, in the initial environment, to an object
-that may be represented externally by the sequence of characters ``@t{40}''. See section @ref{External representations} for a discussion of external
-representations of objects.
-
-@node Naming conventions, , Evaluation examples, Notation and terminology
-@subsection Naming conventions
-
-
-By convention, the names of procedures that always return a boolean
-value usually end
-in ``@code{?}''. Such procedures are called predicates.
-@vindex @w{?}
-
-By convention, the names of procedures that store values into previously
-allocated locations (see section @pxref{Storage model}) usually end in
-``@code{!}''.
-@vindex @w{!}
-Such procedures are called mutation procedures.
-By convention, the value returned by a mutation procedure is unspecified.
-
-By convention, ``@code{->}'' appears within the names of procedures that
-@vindex @w{->}
-take an object of one type and return an analogous object of another type.
-For example, @samp{list->vector} takes a list and returns a vector whose
-elements are the same as those of the list.
-
-
-
-@ignore todo
-Terms that need defining: thunk, command (what else?).
-@end ignore
-
-
-@c @include{lex}
-
-@c Lexical structure
-
-@c %\vfill\eject
-@node Lexical conventions, Basic concepts, Overview of Scheme, top
-@chapter Lexical conventions
-
-@menu
-* Identifiers::
-* Whitespace and comments::
-* Other notations::
-@end menu
-
-
-This section gives an informal account of some of the lexical
-conventions used in writing Scheme programs. For a formal syntax of
-Scheme, see section @ref{Formal syntax}.
-
-Upper and lower case forms of a letter are never distinguished
-except within character and string constants. For example, @samp{Foo} is
-the same identifier as @samp{FOO}, and @t{#x1AB} is the same number as
-@t{#X1ab}.
-
-@node Identifiers, Whitespace and comments, Lexical conventions, Lexical conventions
-@section Identifiers
-
-
-
-Most identifiers allowed by other programming
-@cindex @w{identifier}
-languages are also acceptable to Scheme. The precise rules for forming
-identifiers vary among implementations of Scheme, but in all
-implementations a sequence of letters, digits, and ``extended alphabetic
-characters'' that begins with a character that cannot begin a number is
-an identifier. In addition, @code{+}, @code{-}, and @code{...} are identifiers.
-@vindex @w{...}
-@vindex @w{-}
-@vindex @w{+}
-Here are some examples of identifiers:
-
-
-@example
-
-lambda q
-list->vector soup
-+ V17a
-<=? a34kTMNs
-the-word-recursion-has-many-meanings
-
-@end example
-
-
-Extended alphabetic characters may be used within identifiers as if
-they were letters. The following are extended alphabetic characters:
-
-
-@example
-
-! $ % & * + - . / : < = > ? @@ ^ _ ~
-@end example
-
-
-See section @ref{Lexical structure} for a formal syntax of identifiers.
-
-Identifiers have two uses within Scheme programs:
-
-
-@itemize @bullet
-
-@item
-Any identifier may be used as a variable
-or as a syntactic keyword
-(see sections @pxref{Variables; syntactic keywords; and regions} and @pxref{Macros}).
-
-@item
-When an identifier appears as a literal or within a literal
-(see section @pxref{Literal expressions}), it is being used to denote a @emph{symbol}
-(see section @pxref{Symbols}).
-
-
-@end itemize
-
-@cindex @w{syntactic keyword}
-@cindex @w{variable}
-
-@c \label{keywordsection}
-@c The following identifiers are syntactic keywords, and should not be used
-@c as variables:
-
-@c \begin{scheme}
-@c => do or
-@c and else quasiquote
-@c begin if quote
-@c case lambda set!
-@c cond let unquote
-@c define let* unquote-splicing
-@c delay letrec%
-@c \end{scheme}
-
-@c Some implementations allow all identifiers, including syntactic
-@c keywords, to be used as variables. This is a compatible extension to
-@c the language, but ambiguities in the language result when the
-@c restriction is relaxed, and the ways in which these ambiguities are
-@c resolved vary between implementations.
-
-
-@node Whitespace and comments, Other notations, Identifiers, Lexical conventions
-@section Whitespace and comments
-
-
-@dfn{Whitespace} characters are spaces and newlines.
-@cindex @w{Whitespace}
-(Implementations typically provide additional whitespace characters such
-as tab or page break.) Whitespace is used for improved readability and
-as necessary to separate tokens from each other, a token being an
-indivisible lexical unit such as an identifier or number, but is
-otherwise insignificant. Whitespace may occur between any two tokens,
-but not within a token. Whitespace may also occur inside a string,
-where it is significant.
-
-A semicolon (@t{;}) indicates the start of a
-comment. The comment continues to the
-@cindex @w{;}
-@cindex @w{comment}
-end of the line on which the semicolon appears. Comments are invisible
-to Scheme, but the end of the line is visible as whitespace. This
-prevents a comment from appearing in the middle of an identifier or
-number.
-
-
-@example
-
-;;; The FACT procedure computes the factorial
-;;; of a non-negative integer.
-(define fact
- (lambda (n)
- (if (= n 0)
- 1 ;Base case: return 1
- (* n (fact (- n 1))))))
-
-@end example
-
-
-
-@node Other notations, , Whitespace and comments, Lexical conventions
-@section Other notations
-
-
-@ignore todo
-Rewrite?
-@end ignore
-
-
-For a description of the notations used for numbers, see
-section @ref{Numbers}.
-
-
-@table @t
-
-
-@item @t{.@: + -}
-These are used in numbers, and may also occur anywhere in an identifier
-except as the first character. A delimited plus or minus sign by itself
-is also an identifier.
-A delimited period (not occurring within a number or identifier) is used
-in the notation for pairs (section @pxref{Pairs and lists}), and to indicate a
-rest-parameter in a formal parameter list (section @pxref{Procedures}).
-A delimited sequence of three successive periods is also an identifier.
-
-@item @t{( )}
-Parentheses are used for grouping and to notate lists
-(section @pxref{Pairs and lists}).
-
-@item @t{'}
-The single quote character is used to indicate literal data (section @pxref{Literal expressions}).
-
-@item @t{`}
-The backquote character is used to indicate almost-constant
-data (section @pxref{Quasiquotation}).
-
-@item @t{, ,@@}
-The character comma and the sequence comma at-sign are used in conjunction
-with backquote (section @pxref{Quasiquotation}).
-
-@item @t{"}
-The double quote character is used to delimit strings (section @pxref{Strings}).
-
-@item \
-Backslash is used in the syntax for character constants
-(section @pxref{Characters}) and as an escape character within string
-constants (section @pxref{Strings}).
-
-@c A box used because \verb is not allowed in command arguments.
-
-@item @w{@t{[ ] @{ @} |}}
-Left and right square brackets and curly braces and vertical bar
-are reserved for possible future extensions to the language.
-
-@item #
- Sharp sign is used for a variety of purposes depending on
-the character that immediately follows it:
-
-@item @t{#t} @t{#f}
-These are the boolean constants (section @pxref{Booleans}).
-
-@item #\
-This introduces a character constant (section @pxref{Characters}).
-
-@item #@t{(}
-This introduces a vector constant (section @pxref{Vectors}). Vector constants
-are terminated by @t{)} .
-
-@item @t{#e #i #b #o #d #x}
-These are used in the notation for numbers (section @pxref{Syntax of numerical constants}).
-
-@end table
-
-
-@c @include{basic}
-
-@c \vfill\eject
-@node Basic concepts, Expressions, Lexical conventions, top
-@chapter Basic concepts
-
-@menu
-* Variables; syntactic keywords; and regions::
-* Disjointness of types::
-* External representations::
-* Storage model::
-* Proper tail recursion::
-@end menu
-
-
-
-@node Variables; syntactic keywords; and regions, Disjointness of types, Basic concepts, Basic concepts
-@section Variables; syntactic keywords; and regions
-
-
-
-
-An identifier may name a type of syntax, or it may name
-@cindex @w{identifier}
-a location where a value can be stored. An identifier that names a type
-of syntax is called a @emph{syntactic keyword}
-@cindex @w{syntactic keyword}
-and is said to be @emph{bound} to that syntax. An identifier that names a
-location is called a @emph{variable} and is said to be
-@cindex @w{variable}
-@emph{bound} to that location. The set of all visible
-bindings in effect at some point in a program is
-@cindex @w{binding}
-known as the @emph{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.
-
-@ignore todo
-Define ``assigned'' and ``unassigned'' perhaps?
-@end ignore
-
-
-@ignore todo
-In programs without side effects, one can safely pretend that the
-variables are bound directly to the arguments. Or:
-In programs without @code{set!}, one can safely pretend that the
-@vindex @w{set!}
-variable is bound directly to the value.
-@end ignore
-
-
-Certain expression types are used to create new kinds of syntax
-and 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 @emph{binding constructs}.
-
-@cindex @w{binding construct}
-Those that bind syntactic keywords are listed in section @ref{Macros}.
-The most fundamental of the variable binding constructs is the
-@samp{lambda} expression, because all other variable binding constructs
-can be explained in terms of @samp{lambda} expressions. The other
-variable binding constructs are @samp{let}, @samp{let*}, @samp{letrec},
-and @samp{do} expressions (see sections @pxref{Procedures}, @pxref{Binding constructs}, and
-@pxref{Iteration}).
-
-@c Note: internal definitions not mentioned here.
-
-Like Algol and Pascal, and unlike most other dialects of Lisp
-except for Common Lisp, Scheme is a statically scoped 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
-@cindex @w{region}
-the binding is visible. The region is determined by the particular
-binding construct that establishes the binding; if the binding is
-established by a @samp{lambda} expression, for example, then its region
-is the entire @samp{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 top level environment, if any
-(chapters @pxref{Expressions} and @pxref{Standard procedures}); if there is no
-binding for the identifier,
-it is said to be @dfn{unbound}.
-@cindex @w{top level environment}
-@cindex @w{bound}
-@cindex @w{unbound}
-
-@ignore todo
-Mention that some implementations have multiple top level environments?
-@end ignore
-
-
-@ignore todo
-Pitman sez: needs elaboration in case of @t{(let ...)}
-@end ignore
-
-
-@ignore todo
-Pitman asks: say something about vars created after scheme starts?
-@t{(define x 3) (define (f) x) (define (g) y) (define y 4)}
-Clinger replies: The language was explicitly
-designed to permit a view in which no variables are created after
-Scheme starts. In files, you can scan out the definitions beforehand.
-I think we're agreed on the principle that interactive use should
-approximate that behavior as closely as possible, though we don't yet
-agree on which programming environment provides the best approximation.
-@end ignore
-
-
-@node Disjointness of types, External representations, Variables; syntactic keywords; and regions, Basic concepts
-@section Disjointness of types
-
-
-
-No object satisfies more than one of the following predicates:
-
-
-@example
-
-boolean? pair?
-symbol? number?
-char? string?
-vector? port?
-procedure?
-
-@end example
-
-
-These predicates define the types @emph{boolean}, @emph{pair}, @emph{symbol}, @emph{number}, @emph{char} (or @emph{character}), @emph{string}, @emph{vector}, @emph{port}, and @emph{procedure}. The empty list is a special
-object of its own type; it satisfies none of the above predicates.
-
-@vindex symbol?
-@vindex pair?
-@vindex boolean?
-@cindex @w{type}
-
-@vindex vector?
-@vindex string?
-@vindex char?
-@vindex number?
-
-@cindex @w{empty list}
-@vindex procedure?
-@vindex port?
-
-Although there is a separate boolean type,
-any Scheme value can be used as a boolean value for the purpose of a
-conditional test. As explained in section @ref{Booleans}, all
-values count as true in such a test except for @t{#f}.
-@c and possibly the empty list.
-@c The only value that is guaranteed to count as
-@c false is \schfalse{}. It is explicitly unspecified whether the empty list
-@c counts as true or as false.
-This report uses the word ``true'' to refer to any
-Scheme value except @t{#f}, and the word ``false'' to refer to
-@t{#f}.
-@cindex @w{false}
-@cindex @w{true}
-
-@node External representations, Storage model, Disjointness of types, Basic concepts
-@section External representations
-
-
-
-An important concept in Scheme (and Lisp) is that of the @emph{external
-representation} of an object as a sequence of characters. For example,
-an external representation of the integer 28 is the sequence of
-characters ``@t{28}'', and an external representation of a list consisting
-of the integers 8 and 13 is the sequence of characters ``@t{(8 13)}''.
-
-The external representation of an object is not necessarily unique. The
-integer 28 also has representations ``@t{#e28.000}'' and ``@t{#x1c}'', and the
-list in the previous paragraph also has the representations ``@t{( 08 13
-)}'' and ``@t{(8 .@: (13 .@: ()))}'' (see section @pxref{Pairs and lists}).
-
-Many objects have standard external representations, but some, such as
-procedures, do not have standard representations (although particular
-implementations may define representations for them).
-
-An external representation may be written in a program to obtain the
-corresponding object (see @samp{quote}, section @pxref{Literal expressions}).
-
-External representations can also be used for input and output. The
-procedure @samp{read} (section @pxref{Input}) parses external
-representations, and the procedure @samp{write} (section @pxref{Output})
-generates them. Together, they provide an elegant and powerful
-input/output facility.
-
-Note that the sequence of characters ``@t{(+ 2 6)}'' is @emph{not} an
-external representation of the integer 8, even though it @emph{is} an
-expression evaluating to the integer 8; rather, it is an external
-representation of a three-element list, the elements of which are the symbol
-@t{+} and the integers 2 and 6. Scheme's syntax has the property that
-any sequence of characters that is an expression is also the external
-representation of 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 denote data or program, but it is also a source of power,
-since it facilitates writing programs such as interpreters and
-compilers that treat programs as data (or vice versa).
-
-The syntax of external representations of various kinds of objects
-accompanies the description of the primitives for manipulating the
-objects in the appropriate sections of chapter @ref{Standard procedures}.
-
-@node Storage model, Proper tail recursion, External representations, Basic concepts
-@section Storage model
-
-
-
-Variables and objects such as pairs, vectors, and strings implicitly
-denote locations or sequences of locations. A string, for
-@cindex @w{location}
-example, denotes as many locations as there are characters in the string.
-(These locations need not correspond to a full machine word.) A new value may be
-stored into one of these locations using the @t{string-set!} procedure, but
-the string continues to denote the same locations as before.
-
-An object fetched from a location, by a variable reference or by
-a procedure such as @samp{car}, @samp{vector-ref}, or @samp{string-ref}, is
-equivalent in the sense of @code{eqv?}
-@c and \ide{eq?} ??
-(section @pxref{Equivalence predicates})
-@vindex @w{eqv?}
-to the object last stored in the location before the fetch.
-
-Every location is marked to show whether it is in use.
-No variable or object ever refers to a location that is not in use.
-Whenever this report speaks of storage being allocated for a variable
-or object, what is meant is that an appropriate number of locations are
-chosen from the set of locations that are not in use, and the chosen
-locations are marked to indicate that they are now in use before the variable
-or object is made to denote them.
-
-In many systems it is desirable for constants (i.e. the values of
-@cindex @w{constant}
-literal expressions) to reside in read-only-memory. To express this, it is
-convenient to imagine that every object that denotes locations is associated
-with a flag telling whether that object is mutable or
-@cindex @w{mutable}
-immutable. In such systems literal constants and the strings
-@cindex @w{immutable}
-returned by @code{symbol->string} are immutable objects, while all objects
-@vindex @w{symbol->string}
-created by the other procedures listed in this report are mutable. It is an
-error to attempt to store a new value into a location that is denoted by an
-immutable object.
-
-@node Proper tail recursion, , Storage model, Basic concepts
-@section Proper tail recursion
-
-
-
-Implementations of Scheme are required to be
-@emph{properly tail-recursive}.
-@cindex @w{proper tail recursion}
-Procedure calls that occur in certain syntactic
-contexts defined below are `tail calls'. A Scheme implementation is
-properly tail-recursive if it supports an unbounded number of active
-tail calls. A call is @emph{active} if the called procedure may still
-return. Note that this includes calls that may be returned from either
-by the current continuation or by continuations captured earlier by
-@samp{call-with-current-continuation} that are later invoked.
-In the absence of captured continuations, calls could
-return at most once and the active calls would be those that had not
-yet returned.
-A formal definition of proper tail recursion can be found
-in [propertailrecursion].
-
-
-@quotation
-@emph{Rationale:}
-
-Intuitively, no space is needed for an active tail call because the
-continuation that is used in the tail call has the same semantics as the
-continuation passed to the procedure containing the call. Although an improper
-implementation might use a new continuation in the call, a return
-to this new continuation would be followed immediately by a return
-to the continuation passed to the procedure. A properly tail-recursive
-implementation returns to that continuation directly.
-
-Proper tail recursion was one of the central ideas in Steele and
-Sussman's original version of Scheme. Their first Scheme interpreter
-implemented both functions and actors. Control flow was expressed using
-actors, which differed from functions in that they passed their results
-on to another actor instead of returning to a caller. In the terminology
-of this section, each actor finished with a tail call to another actor.
-
-Steele and Sussman later observed that in their interpreter the code
-for dealing with actors was identical to that for functions and thus
-there was no need to include both in the language.
-
-@end quotation
-
-
-A @emph{tail call} is a procedure call that occurs
-@cindex @w{tail call}
-in a @emph{tail context}. Tail contexts are defined inductively. Note
-that a tail context is always determined with respect to a particular lambda
-expression.
-
-
-
-@itemize @bullet
-
-@item
-The last expression within the body of a lambda expression,
-shown as @r{<tail expression>} below, occurs in a tail context.
-
-@format
-@t{(lambda <formals>
- <definition>* <expression>* <tail expression>)
-}
-
-@end format
-
-
-
-@item
-If one of the following expressions is in a tail context,
-then the subexpressions shown as <tail expression> are in a tail context.
-These were derived from rules in the grammar given in
-chapter @ref{Formal syntax and semantics} by replacing some occurrences of <expression>
-with <tail expression>. Only those rules that contain tail contexts
-are shown here.
-
-
-@format
-@t{(if <expression> <tail expression> <tail expression>)
-(if <expression> <tail expression>)
-
-(cond <cond clause>+)
-(cond <cond clause>* (else <tail sequence>))
-
-(case <expression>
- <case clause>+)
-(case <expression>
- <case clause>*
- (else <tail sequence>))
-
-(and <expression>* <tail expression>)
-(or <expression>* <tail expression>)
-
-(let (<binding spec>*) <tail body>)
-(let <variable> (<binding spec>*) <tail body>)
-(let* (<binding spec>*) <tail body>)
-(letrec (<binding spec>*) <tail body>)
-
-(let-syntax (<syntax spec>*) <tail body>)
-(letrec-syntax (<syntax spec>*) <tail body>)
-
-(begin <tail sequence>)
-
-(do (<iteration spec>*)
- (<test> <tail sequence>)
- <expression>*)
-
-@r{where}
-
-<cond clause> --> (<test> <tail sequence>)
-<case clause> --> ((<datum>*) <tail sequence>)
-
-<tail body> --> <definition>* <tail sequence>
-<tail sequence> --> <expression>* <tail expression>
-}
-
-@end format
-
-
-
-@item
-If a @samp{cond} expression is in a tail context, and has a clause of
-the form @samp{(@r{<expression1>} => @r{<expression2>})}
-then the (implied) call to
-the procedure that results from the evaluation of @r{<expression2>} is in a
-tail context. @r{<expression2>} itself is not in a tail context.
-
-
-@end itemize
-
-
-Certain built-in procedures are also required to perform tail calls.
-The first argument passed to @code{apply} and to
-@vindex @w{apply}
-@code{call-with-current-continuation}, and the second argument passed to
-@vindex @w{call-with-current-continuation}
-@code{call-with-values}, must be called via a tail call.
-@vindex @w{call-with-values}
-Similarly, @code{eval} must evaluate its argument as if it
-@vindex @w{eval}
-were in tail position within the @code{eval} procedure.
-@vindex @w{eval}
-
-In the following example the only tail call is the call to @samp{f}.
-None of the calls to @samp{g} or @samp{h} are tail calls. The reference to
-@samp{x} is in a tail context, but it is not a call and thus is not a
-tail call.
-
-@example
-
-(lambda ()
- (if (g)
- (let ((x (h)))
- x)
- (and (g) (f))))
-
-@end example
-
-
-
-@quotation
-@emph{Note:}
-Implementations are allowed, but not required, to
-recognize that some non-tail calls, such as the call to @samp{h}
-above, can be evaluated as though they were tail calls.
-In the example above, the @samp{let} expression could be compiled
-as a tail call to @samp{h}. (The possibility of @samp{h} returning
-an unexpected number of values can be ignored, because in that
-case the effect of the @samp{let} is explicitly unspecified and
-implementation-dependent.)
-@end quotation
-
-
-
-@c @include{expr}
-
-@c \vfill\eject
-@node Expressions, Program structure, Basic concepts, top
-@chapter Expressions
-
-@menu
-* Primitive expression types::
-* Derived expression types::
-* Macros::
-@end menu
-
-
-
-@c \newcommand{\syntax}{{\em Syntax: }}
-@c \newcommand{\semantics}{{\em Semantics: }}
-
-@c [Deleted for R5RS because of multiple-value returns. -RK]
-@c A Scheme expression is a construct that returns a value, such as a
-@c variable reference, literal, procedure call, or conditional.
-
-Expression types are categorized as @emph{primitive} or @emph{derived}.
-Primitive expression types include variables and procedure calls.
-Derived expression types are not semantically primitive, but can instead
-be defined as macros.
-With the exception of @samp{quasiquote}, whose macro definition is complex,
-the derived expressions are classified as library features.
-Suitable definitions are given in section @ref{Derived expression type}.
-
-@node Primitive expression types, Derived expression types, Expressions, Expressions
-@section Primitive expression types
-
-@menu
-* Variable references::
-* Literal expressions::
-* Procedure calls::
-* Procedures::
-* Conditionals::
-* Assignments::
-@end menu
-
-
-
-@node Variable references, Literal expressions, Primitive expression types, Primitive expression types
-@subsection Variable references
-
-
-
-@deffn {syntax} @r{<variable>}
-
-
-An expression consisting of a variable
-@cindex @w{variable}
-(section @pxref{Variables; syntactic keywords; and regions}) is a variable reference. The value of
-the variable reference is the value stored in the location to which the
-variable is bound. It is an error to reference an
-unbound variable.
-@cindex @w{unbound}
-
-
-@format
-@t{(define x 28)
-x ==> 28
-}
-@end format
-
-@end deffn
-
-@node Literal expressions, Procedure calls, Variable references, Primitive expression types
-@subsection Literal expressions
-
-
-
-
-@deffn {syntax} quote @r{<datum>}
-
-@deffnx {syntax} @t{'}@r{<datum>}
-
-
-@deffnx {syntax} @r{<constant>}
-
-
-@samp{(quote @r{<datum>})} evaluates to @r{<datum>}.
-@cindex @w{'}
-@r{<Datum>}
-may be any external representation of a Scheme object (see
-section @pxref{External representations}). This notation is used to include literal
-constants in Scheme code.
-
-
-@format
-@t{
-(quote a) ==> a
-(quote #(a b c)) ==> #(a b c)
-(quote (+ 1 2)) ==> (+ 1 2)
-}
-@end format
-
-
-@samp{(quote @r{<datum>})} may be abbreviated as
-@t{'}@r{<datum>}. The two notations are equivalent in all
-respects.
-
-
-@format
-@t{'a ==> a
-'#(a b c) ==> #(a b c)
-'() ==> ()
-'(+ 1 2) ==> (+ 1 2)
-'(quote a) ==> (quote a)
-''a ==> (quote a)
-}
-@end format
-
-
-Numerical constants, string constants, character constants, and boolean
-constants evaluate ``to themselves''; they need not be quoted.
-
-
-@format
-@t{'"abc" ==> "abc"
-"abc" ==> "abc"
-'145932 ==> 145932
-145932 ==> 145932
-'#t ==> #t
-#t ==> #t
-}
-@end format
-
-
-As noted in section @ref{Storage model}, it is an error to alter a constant
-(i.e. the value of a literal expression) using a mutation procedure like
-@samp{set-car!} or @samp{string-set!}.
-
-@end deffn
-
-
-@node Procedure calls, Procedures, Literal expressions, Primitive expression types
-@subsection Procedure calls
-
-
-
-@deffn {syntax} @r{<operator>} @r{<operand1>} @dots{},
-
-
-A procedure call is written by simply enclosing in parentheses
-expressions for the procedure to be called and the arguments to be
-passed to it. The operator and operand expressions are evaluated (in an
-unspecified order) and the resulting procedure is passed the resulting
-arguments.
-@cindex @w{procedure call}
-@cindex @w{call}
-
-@format
-@t{
-(+ 3 4) ==> 7
-((if #f + *) 3 4) ==> 12
-}
-@end format
-
-
-A number of procedures are available as the values of variables in the
-initial environment; for example, the addition and multiplication
-procedures in the above examples are the values of the variables @samp{+}
-and @samp{*}. New procedures are created by evaluating lambda expressions
-(see section @pxref{Procedures}).
-@ignore todo
-At Friedman's request, flushed mention of other ways.
-@end ignore
-
-@c or definitions (see section~\ref{define}).
-
-Procedure calls may return any number of values (see @code{values} in
-@vindex @w{values}
-section @pxref{Control features}). With the exception of @samp{values}
-the procedures available in the initial environment return one
-value or, for procedures such as @samp{apply}, pass on the values returned
-by a call to one of their arguments.
-
-Procedure calls are also called @emph{combinations}.
-
-@cindex @w{combination}
-
-
-@quotation
-@emph{Note:} In contrast to other dialects of Lisp, the order of
-evaluation is unspecified, and the operator expression and the operand
-expressions are always evaluated with the same evaluation rules.
-@end quotation
-
-
-
-@quotation
-@emph{Note:}
-Although the order of evaluation is otherwise unspecified, the effect of
-any concurrent evaluation of the operator and operand expressions is
-constrained to be consistent with some sequential order of evaluation.
-The order of evaluation may be chosen differently for each procedure call.
-@end quotation
-
-
-
-@quotation
-@emph{Note:} In many dialects of Lisp, the empty combination, @t{()}, is a legitimate expression. In Scheme, combinations must have at
-least one subexpression, so @t{()} is not a syntactically valid
-expression.
-@ignore todo
-Dybvig: ``it should be obvious from the syntax.''
-@end ignore
-
-@end quotation
-
-
-@ignore todo
-Freeman:
-I think an explanation as to why evaluation order is not specified
-should be included. It should not include any reference to parallel
-evaluation. Does any existing compiler generate better code because
-the evaluation order is unspecified? Clinger: yes: T3, MacScheme v2,
-probably MIT Scheme and Chez Scheme. But that's not the main reason
-for leaving the order unspecified.
-@end ignore
-
-
-@end deffn
-
-
-@node Procedures, Conditionals, Procedure calls, Primitive expression types
-@subsection Procedures
-
-
-
-
-@deffn {syntax} lambda @r{<formals>} @r{<body>}
-
-@emph{Syntax:}
-@r{<Formals>} should be a formal arguments list as described below,
-and @r{<body>} should be a sequence of one or more expressions.
-
-@emph{Semantics:}
-A lambda expression evaluates to a procedure. The environment in
-effect when the lambda expression was evaluated is remembered as part of the
-procedure. When the procedure is later called with some actual
-arguments, the environment in which the lambda expression was evaluated will
-be extended by binding the variables in the formal argument list to
-fresh locations, the corresponding actual argument values will be stored
-in those locations, and the expressions in the body of the lambda expression
-will be evaluated sequentially in the extended environment.
-The result(s) of the last expression in the body will be returned as
-the result(s) of the procedure call.
-
-
-@format
-@t{(lambda (x) (+ x x)) ==> @emph{}a procedure
-((lambda (x) (+ x x)) 4) ==> 8
-
-(define reverse-subtract
- (lambda (x y) (- y x)))
-(reverse-subtract 7 10) ==> 3
-
-(define add4
- (let ((x 4))
- (lambda (y) (+ x y))))
-(add4 6) ==> 10
-}
-@end format
-
-
-@r{<Formals>} should have one of the following forms:
-
-
-
-@itemize @bullet
-
-@item
-@t{(@r{<variable1>} @dots{},)}:
-The procedure takes a fixed number of arguments; when the procedure is
-called, the arguments will be stored in the bindings of the
-corresponding variables.
-
-@item
-@r{<variable>}:
-The procedure takes any number of arguments; when the procedure is
-called, the sequence of actual arguments is converted into a newly
-allocated list, and the list is stored in the binding of the
-@r{<variable>}.
-
-@item
-@t{(@r{<variable1>} @dots{}, @r{<variable_n>} @b{.}
-@r{<variable_n+1>})}:
-If a space-delimited period precedes the last variable, then
-the procedure takes n or more arguments, where n is the
-number of formal arguments before the period (there must
-be at least one).
-The value stored in the binding of the last variable will be a
-newly allocated
-list of the actual arguments left over after all the other actual
-arguments have been matched up against the other formal arguments.
-
-@end itemize
-
-
-It is an error for a @r{<variable>} to appear more than once in
-@r{<formals>}.
-
-
-@format
-@t{((lambda x x) 3 4 5 6) ==> (3 4 5 6)
-((lambda (x y . z) z)
- 3 4 5 6) ==> (5 6)
-}
-@end format
-
-
-Each procedure created as the result of evaluating a lambda expression is
-(conceptually) tagged
-with a storage location, in order to make @code{eqv?} and
-@vindex @w{eqv?}
-@code{eq?} work on procedures (see section @pxref{Equivalence predicates}).
-@vindex @w{eq?}
-
-@end deffn
-
-
-@node Conditionals, Assignments, Procedures, Primitive expression types
-@subsection Conditionals
-
-
-
-@deffn {syntax} if @r{<test>} @r{<consequent>} @r{<alternate>}
-@deffnx {syntax} if @r{<test>} @r{<consequent>}
-@c \/ if hyper = italic
-
-@emph{Syntax:}
-@r{<Test>}, @r{<consequent>}, and @r{<alternate>} may be arbitrary
-expressions.
-
-@emph{Semantics:}
-An @samp{if} expression is evaluated as follows: first,
-@r{<test>} is evaluated. If it yields a true value (see
-@cindex @w{true}
-section @pxref{Booleans}), then @r{<consequent>} is evaluated and
-its value(s) is(are) returned. Otherwise @r{<alternate>} is evaluated and its
-value(s) is(are) returned. If @r{<test>} yields a false value and no
-@r{<alternate>} is specified, then the result of the expression is
-unspecified.
-
-
-@format
-@t{(if (> 3 2) 'yes 'no) ==> yes
-(if (> 2 3) 'yes 'no) ==> no
-(if (> 3 2)
- (- 3 2)
- (+ 3 2)) ==> 1
-}
-@end format
-
-
-@end deffn
-
-
-@node Assignments, , Conditionals, Primitive expression types
-@subsection Assignments
-
-
-
-
-@deffn {syntax} set! @r{<variable>} @r{<expression>}
-
-@r{<Expression>} is evaluated, and the resulting value is stored in
-the location to which @r{<variable>} is bound. @r{<Variable>} must
-be bound either in some region enclosing the @samp{set!} expression
-@cindex @w{region}
-or at top level. The result of the @samp{set!} expression is
-unspecified.
-
-
-@format
-@t{(define x 2)
-(+ x 1) ==> 3
-(set! x 4) ==> @emph{unspecified}
-(+ x 1) ==> 5
-}
-@end format
-
-
-@end deffn
-
-
-@node Derived expression types, Macros, Primitive expression types, Expressions
-@section Derived expression types
-
-@menu
-* Conditional::
-* Binding constructs::
-* Sequencing::
-* Iteration::
-* Delayed evaluation::
-* Quasiquotation::
-@end menu
-
-
-
-The constructs in this section are hygienic, as discussed in
-section @ref{Macros}.
-For reference purposes, section @ref{Derived expression type} gives macro definitions
-that will convert most of the constructs described in this section
-into the primitive constructs described in the previous section.
-
-@ignore todo
-Mention that no definition of backquote is provided?
-@end ignore
-
-
-@node Conditional, Binding constructs, Derived expression types, Derived expression types
-@subsection Conditionals
-
-
-
-@deffn {library syntax} cond <clause1> <clause2> @dots{},
-
-@emph{Syntax:}
-Each @r{<clause>} should be of the form
-
-@format
-@t{(@r{<test>} @r{<expression1>} @dots{},)
-}
-@end format
-
-where @r{<test>} is any expression. Alternatively, a @r{<clause>} may be
-of the form
-
-@format
-@t{(@r{<test>} => @r{<expression>})
-}
-@end format
-
-The last @r{<clause>} may be
-an ``else clause,'' which has the form
-
-@format
-@t{(else @r{<expression1>} @r{<expression2>} @dots{},)@r{.}
-}
-@end format
-
-
-@cindex @w{else}
-
-@cindex @w{=>}
-
-@emph{Semantics:}
-A @samp{cond} expression is evaluated by evaluating the @r{<test>}
-expressions of successive @r{<clause>}s in order until one of them
-evaluates to a true value (see
-@cindex @w{true}
-section @pxref{Booleans}). When a @r{<test>} evaluates to a true
-value, then the remaining @r{<expression>}s in its @r{<clause>} are
-evaluated in order, and the result(s) of the last @r{<expression>} in the
-@r{<clause>} is(are) returned as the result(s) of the entire @samp{cond}
-expression. If the selected @r{<clause>} contains only the
-@r{<test>} and no @r{<expression>}s, then the value of the
-@r{<test>} is returned as the result. If the selected @r{<clause>} uses the
-@code{=>} alternate form, then the @r{<expression>} is evaluated.
-@vindex @w{=>}
-Its value must be a procedure that accepts one argument; this procedure is then
-called on the value of the @r{<test>} and the value(s) returned by this
-procedure is(are) returned by the @samp{cond} expression.
-If all @r{<test>}s evaluate
-to false values, and there is no else clause, then the result of
-the conditional expression is unspecified; if there is an else
-clause, then its @r{<expression>}s are evaluated, and the value(s) of
-the last one is(are) returned.
-
-
-@format
-@t{(cond ((> 3 2) 'greater)
- ((< 3 2) 'less)) ==> greater
-
-(cond ((> 3 3) 'greater)
- ((< 3 3) 'less)
- (else 'equal)) ==> equal
-
-(cond ((assv 'b '((a 1) (b 2))) => cadr)
- (else #f)) ==> 2
-}
-@end format
-
-
-
-@end deffn
-
-
-
-@deffn {library syntax} case @r{<key>} <clause1> <clause2> @dots{},
-
-@emph{Syntax:}
-@r{<Key>} may be any expression. Each @r{<clause>} should have
-the form
-
-@format
-@t{((@r{<datum1>} @dots{},) @r{<expression1>} @r{<expression2>} @dots{},)@r{,}
-}
-@end format
-
-where each @r{<datum>} is an external representation of some object.
-All the @r{<datum>}s must be distinct.
-The last @r{<clause>} may be an ``else clause,'' which has the form
-
-@format
-@t{(else @r{<expression1>} @r{<expression2>} @dots{},)@r{.}
-}
-@end format
-
-
-@vindex else
-
-@emph{Semantics:}
-A @samp{case} expression is evaluated as follows. @r{<Key>} is
-evaluated and its result is compared against each @r{<datum>}. If the
-result of evaluating @r{<key>} is equivalent (in the sense of
-@samp{eqv?}; see section @pxref{Equivalence predicates}) to a @r{<datum>}, then the
-expressions in the corresponding @r{<clause>} are evaluated from left
-to right and the result(s) of the last expression in the @r{<clause>} is(are)
-returned as the result(s) of the @samp{case} expression. If the result of
-evaluating @r{<key>} is different from every @r{<datum>}, then if
-there is an else clause its expressions are evaluated and the
-result(s) of the last is(are) the result(s) of the @samp{case} expression;
-otherwise the result of the @samp{case} expression is unspecified.
-
-
-@format
-@t{(case (* 2 3)
- ((2 3 5 7) 'prime)
- ((1 4 6 8 9) 'composite)) ==> composite
-(case (car '(c d))
- ((a) 'a)
- ((b) 'b)) ==> @emph{unspecified}
-(case (car '(c d))
- ((a e i o u) 'vowel)
- ((w y) 'semivowel)
- (else 'consonant)) ==> consonant
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {library syntax} and <test1> @dots{},
-
-The @r{<test>} expressions are evaluated from left to right, and the
-value of the first expression that evaluates to a false value (see
-section @pxref{Booleans}) is returned. Any remaining expressions
-are not evaluated. If all the expressions evaluate to true values, the
-value of the last expression is returned. If there are no expressions
-then @t{#t} is returned.
-
-
-@format
-@t{(and (= 2 2) (> 2 1)) ==> #t
-(and (= 2 2) (< 2 1)) ==> #f
-(and 1 2 'c '(f g)) ==> (f g)
-(and) ==> #t
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {library syntax} or <test1> @dots{},
-
-The @r{<test>} expressions are evaluated from left to right, and the value of the
-first expression that evaluates to a true value (see
-section @pxref{Booleans}) is returned. Any remaining expressions
-are not evaluated. If all expressions evaluate to false values, the
-value of the last expression is returned. If there are no
-expressions then @t{#f} is returned.
-
-
-@format
-@t{(or (= 2 2) (> 2 1)) ==> #t
-(or (= 2 2) (< 2 1)) ==> #t
-(or #f #f #f) ==> #f
-(or (memq 'b '(a b c))
- (/ 3 0)) ==> (b c)
-}
-@end format
-
-
-@end deffn
-
-
-@node Binding constructs, Sequencing, Conditional, Derived expression types
-@subsection Binding constructs
-
-
-The three binding constructs @samp{let}, @samp{let*}, and @samp{letrec}
-give Scheme a block structure, like Algol 60. The syntax of the three
-constructs is identical, but they differ in the regions they establish
-@cindex @w{region}
-for their variable bindings. In a @samp{let} expression, the initial
-values are computed before any of the variables become bound; in a
-@samp{let*} expression, the bindings and evaluations are performed
-sequentially; while in a @samp{letrec} expression, all the bindings are in
-effect while their initial values are being computed, thus allowing
-mutually recursive definitions.
-
-
-@deffn {library syntax} let @r{<bindings>} @r{<body>}
-
-@emph{Syntax:}
-@r{<Bindings>} should have the form
-
-@format
-@t{((@r{<variable1>} @r{<init1>}) @dots{},)@r{,}
-}
-@end format
-
-where each @r{<init>} is an expression, and @r{<body>} should be a
-sequence of one or more expressions. It is
-an error for a @r{<variable>} to appear more than once in the list of variables
-being bound.
-
-@emph{Semantics:}
-The @r{<init>}s are evaluated in the current environment (in some
-unspecified order), the @r{<variable>}s are bound to fresh locations
-holding the results, the @r{<body>} is evaluated in the extended
-environment, and the value(s) of the last expression of @r{<body>}
-is(are) returned. Each binding of a @r{<variable>} has @r{<body>} as its
-region.
-@cindex @w{region}
-
-
-@format
-@t{(let ((x 2) (y 3))
- (* x y)) ==> 6
-
-(let ((x 2) (y 3))
- (let ((x 7)
- (z (+ x y)))
- (* z x))) ==> 35
-}
-@end format
-
-
-See also named @samp{let}, section @ref{Iteration}.
-
-@end deffn
-
-
-
-@deffn {library syntax} let* @r{<bindings>} @r{<body>}
-
-
-@emph{Syntax:}
-@r{<Bindings>} should have the form
-
-@format
-@t{((@r{<variable1>} @r{<init1>}) @dots{},)@r{,}
-}
-@end format
-
-and @r{<body>} should be a sequence of
-one or more expressions.
-
-@emph{Semantics:}
-@samp{Let*} is similar to @samp{let}, but the bindings are performed
-sequentially from left to right, and the region of a binding indicated
-@cindex @w{region}
-by @samp{(@r{<variable>} @r{<init>})} is that part of the @samp{let*}
-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.
-
-
-@format
-@t{(let ((x 2) (y 3))
- (let* ((x 7)
- (z (+ x y)))
- (* z x))) ==> 70
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {library syntax} letrec @r{<bindings>} @r{<body>}
-
-@emph{Syntax:}
-@r{<Bindings>} should have the form
-
-@format
-@t{((@r{<variable1>} @r{<init1>}) @dots{},)@r{,}
-}
-@end format
-
-and @r{<body>} should be a sequence of
-one or more expressions. It is an error for a @r{<variable>} to appear more
-than once in the list of variables being bound.
-
-@emph{Semantics:}
-The @r{<variable>}s are bound to fresh locations holding undefined
-values, the @r{<init>}s are evaluated in the resulting environment (in
-some unspecified order), each @r{<variable>} is assigned to the result
-of the corresponding @r{<init>}, the @r{<body>} is evaluated in the
-resulting environment, and the value(s) of the last expression in
-@r{<body>} is(are) returned. Each binding of a @r{<variable>} has the
-entire @samp{letrec} expression as its region, making it possible to
-@cindex @w{region}
-define mutually recursive procedures.
-
-
-@format
-@t{(letrec ((even?
- (lambda (n)
- (if (zero? n)
- #t
- (odd? (- n 1)))))
- (odd?
- (lambda (n)
- (if (zero? n)
- #f
- (even? (- n 1))))))
- (even? 88))
- ==> #t
-}
-@end format
-
-
-One restriction on @samp{letrec} is very important: it must be possible
-to evaluate each @r{<init>} without assigning or referring to the value of any
-@r{<variable>}. If this restriction is violated, then it is an error. The
-restriction is necessary because Scheme passes arguments by value rather than by
-name. In the most common uses of @samp{letrec}, all the @r{<init>}s are
-lambda expressions and the restriction is satisfied automatically.
-
-@c \todo{use or uses? --- Jinx.}
-
-@end deffn
-
-
-@node Sequencing, Iteration, Binding constructs, Derived expression types
-@subsection Sequencing
-
-
-
-@deffn {library syntax} begin <expression1> <expression2> @dots{},
-
-The @r{<expression>}s are evaluated sequentially from left to right,
-and the value(s) of the last @r{<expression>} is(are) returned. This
-expression type is used to sequence side effects such as input and
-output.
-
-
-@format
-@t{(define x 0)
-
-(begin (set! x 5)
- (+ x 1)) ==> 6
-
-(begin (display "4 plus 1 equals ")
- (display (+ 4 1))) ==> @emph{unspecified}
- @emph{and prints} 4 plus 1 equals 5
-}
-@end format
-
-
-@end deffn
-
-
-@node Iteration, Delayed evaluation, Sequencing, Derived expression types
-@subsection Iteration
-
-@c \unsection
-
-
-@noindent
-
-@deffn {library syntax} do ((@r{<variable1>} @r{<init1>} @r{<step1>}) @dots{}) (@r{<test>} @r{<expression>} @dots{}) @r{<command>} @dots{}
-@cindex @w{do}
-
-@samp{Do} is an iteration construct. It specifies a set of variables to
-be bound, how they are to be initialized at the start, and how they are
-to be updated on each iteration. When a termination condition is met,
-the loop exits after evaluating the @r{<expression>}s.
-
-@samp{Do} expressions are evaluated as follows:
-The @r{<init>} expressions are evaluated (in some unspecified order),
-the @r{<variable>}s are bound to fresh locations, the results of the
-@r{<init>} expressions are stored in the bindings of the
-@r{<variable>}s, and then the iteration phase begins.
-
-Each iteration begins by evaluating @r{<test>}; if the result is
-false (see section @pxref{Booleans}), then the @r{<command>}
-expressions are evaluated in order for effect, the @r{<step>}
-expressions are evaluated in some unspecified order, the
-@r{<variable>}s are bound to fresh locations, the results of the
-@r{<step>}s are stored in the bindings of the
-@r{<variable>}s, and the next iteration begins.
-
-If @r{<test>} evaluates to a true value, then the
-@r{<expression>}s are evaluated from left to right and the value(s) of
-the last @r{<expression>} is(are) returned. If no @r{<expression>}s
-are present, then the value of the @samp{do} expression is unspecified.
-
-The region of the binding of a @r{<variable>}
-@cindex @w{region}
-consists of the entire @samp{do} expression except for the @r{<init>}s.
-It is an error for a @r{<variable>} to appear more than once in the
-list of @samp{do} variables.
-
-A @r{<step>} may be omitted, in which case the effect is the
-same as if @samp{(@r{<variable>} @r{<init>} @r{<variable>})} had
-been written instead of @samp{(@r{<variable>} @r{<init>})}.
-
-
-@format
-@t{(do ((vec (make-vector 5))
- (i 0 (+ i 1)))
- ((= i 5) vec)
- (vector-set! vec i i)) ==> #(0 1 2 3 4)
-
-(let ((x '(1 3 5 7 9)))
- (do ((x x (cdr x))
- (sum 0 (+ sum (car x))))
- ((null? x) sum))) ==> 25
-}
-@end format
-
-
-@c \end{entry}
-@end deffn
-
-
-@deffn {library syntax} let @r{<variable>} @r{<bindings>} @r{<body>}
-
-
-``Named @samp{let}'' is a variant on the syntax of @code{let} which provides
-@vindex @w{let}
-a more general looping construct than @samp{do} and may also be used to express
-recursions.
-It has the same syntax and semantics as ordinary @samp{let}
-except that @r{<variable>} is bound within @r{<body>} to a procedure
-whose formal arguments are the bound variables and whose body is
-@r{<body>}. Thus the execution of @r{<body>} may be repeated by
-invoking the procedure named by @r{<variable>}.
-
-@c | <-- right margin
-
-@format
-@t{(let loop ((numbers '(3 -2 1 6 -5))
- (nonneg '())
- (neg '()))
- (cond ((null? numbers) (list nonneg neg))
- ((>= (car numbers) 0)
- (loop (cdr numbers)
- (cons (car numbers) nonneg)
- neg))
- ((< (car numbers) 0)
- (loop (cdr numbers)
- nonneg
- (cons (car numbers) neg)))))
- ==> ((6 1 3) (-5 -2))
-}
-@end format
-
-
-@end deffn
-
-
-@node Delayed evaluation, Quasiquotation, Iteration, Derived expression types
-@subsection Delayed evaluation
-
-
-
-@deffn {library syntax} delay @r{<expression>}
-
-@ignore todo
-Fix.
-@end ignore
-
-
-The @samp{delay} construct is used together with the procedure @code{force} to
-@vindex @w{force}
-implement @dfn{lazy evaluation} or @dfn{call by need}.
-@cindex @w{call by need}
-@cindex @w{lazy evaluation}
-@t{(delay @r{<expression>})} returns an object called a
-@dfn{promise} which at some point in the future may be asked (by
-@cindex @w{promise}
-the @samp{force} procedure)
-@ignore todo
-Bartley's white lie; OK?
-@end ignore
- to evaluate
-@r{<expression>}, and deliver the resulting value.
-The effect of @r{<expression>} returning multiple values
-is unspecified.
-
-See the description of @samp{force} (section @pxref{Control features}) for a
-more complete description of @samp{delay}.
-
-@end deffn
-
-
-@node Quasiquotation, , Delayed evaluation, Derived expression types
-@subsection Quasiquotation
-
-
-
-
-@deffn {syntax} quasiquote @r{<qq template>}
-
-@deffnx {syntax} @t{`}@r{<qq template>}
-
-
-``Backquote'' or ``quasiquote'' expressions are useful
-@cindex @w{backquote}
-for constructing a list or vector structure when most but not all of the
-desired structure is known in advance. If no
-commas appear within the @r{<qq template>}, the result of
-@cindex @w{comma}
-evaluating
-@t{`}@r{<qq template>} is equivalent to the result of evaluating
-@t{'}@r{<qq template>}. If a comma appears within the
-@cindex @w{,}
-@r{<qq template>}, however, the expression following the comma is
-evaluated (``unquoted'') and its result is inserted into the structure
-instead of the comma and the expression. If a comma appears followed
-immediately by an at-sign (@@), then the following
-@cindex @w{,@@}
-expression must evaluate to a list; the opening and closing parentheses
-of the list are then ``stripped away'' and the elements of the list are
-inserted in place of the comma at-sign expression sequence. A comma
-at-sign should only appear within a list or vector @r{<qq template>}.
-
-@c struck: "(in the sense of {\cf equal?})" after "equivalent"
-
-
-@format
-@t{`(list ,(+ 1 2) 4) ==> (list 3 4)
-(let ((name 'a)) `(list ,name ',name))
- ==> (list a (quote a))
-`(a ,(+ 1 2) ,@@(map abs '(4 -5 6)) b)
- ==> (a 3 4 5 6 b)
-`((@samp{foo} ,(- 10 3)) ,@@(cdr '(c)) . ,(car '(cons)))
- ==> ((foo 7) . cons)
-`#(10 5 ,(sqrt 4) ,@@(map sqrt '(16 9)) 8)
- ==> #(10 5 2 4 3 8)
-}
-@end format
-
-
-Quasiquote forms may be nested. Substitutions are made only for
-unquoted components appearing at the same nesting level
-as the outermost backquote. The nesting level increases by one inside
-each successive quasiquotation, and decreases by one inside each
-unquotation.
-
-
-@format
-@t{`(a `(b ,(+ 1 2) ,(foo ,(+ 1 3) d) e) f)
- ==> (a `(b ,(+ 1 2) ,(foo 4 d) e) f)
-(let ((name1 'x)
- (name2 'y))
- `(a `(b ,,name1 ,',name2 d) e))
- ==> (a `(b ,x ,'y d) e)
-}
-@end format
-
-
-The two notations
- @t{`}@r{<qq template>} and @t{(quasiquote @r{<qq template>})}
- are identical in all respects.
- @samp{,@r{<expression>}} is identical to @samp{(unquote @r{<expression>})},
- and
- @samp{,@@@r{<expression>}} is identical to @samp{(unquote-splicing @r{<expression>})}.
-The external syntax generated by @code{write} for two-element lists whose
-@vindex @w{write}
-car is one of these symbols may vary between implementations.
-
-@cindex @w{`}
-
-
-@format
-@t{(quasiquote (list (unquote (+ 1 2)) 4))
- ==> (list 3 4)
-'(quasiquote (list (unquote (+ 1 2)) 4))
- ==> `(list ,(+ 1 2) 4)
- @emph{}i.e., (quasiquote (list (unquote (+ 1 2)) 4))
-}
-@end format
-
-
-Unpredictable behavior can result if any of the symbols
-@code{quasiquote}, @code{unquote}, or @code{unquote-splicing} appear in
-@vindex @w{unquote-splicing}
-@vindex @w{unquote}
-@vindex @w{quasiquote}
-positions within a @r{<qq template>} otherwise than as described above.
-
-@end deffn
-
-@node Macros, , Derived expression types, Expressions
-@section Macros
-
-@menu
-* Binding constructs for syntactic keywords::
-* Pattern language::
-@end menu
-
-
-
-Scheme programs can define and use new derived expression types,
- called @emph{macros}.
-@cindex @w{macro}
-Program-defined expression types have the syntax
-
-@example
-
-(@r{<keyword>} @r{<datum>} ...)
-
-@end example
-
-where @r{<keyword>} is an identifier that uniquely determines the
-expression type. This identifier is called the @emph{syntactic
-keyword}, or simply @emph{keyword}, of the macro. The
-@cindex @w{macro keyword}
-@cindex @w{keyword}
-@cindex @w{syntactic keyword}
-number of the @r{<datum>}s, and their syntax, depends on the
-expression type.
-
-Each instance of a macro is called a @emph{use}
-@cindex @w{macro use}
-of the macro.
-The set of rules that specifies
-how a use of a macro is transcribed into a more primitive expression
-is called the @emph{transformer}
-@cindex @w{macro transformer}
-of the macro.
-
-The macro definition facility consists of two parts:
-
-
-
-@itemize @bullet
-
-@item
-A set of expressions used to establish that certain identifiers
-are macro keywords, associate them with macro transformers, and control
-the scope within which a macro is defined, and
-
-@item
-a pattern language for specifying macro transformers.
-
-@end itemize
-
-
-The syntactic keyword of a macro may shadow variable bindings, and local
-variable bindings may shadow keyword bindings. All macros
-@cindex @w{keyword}
-defined using the pattern language are ``hygienic'' and ``referentially
-transparent'' and thus preserve Scheme's lexical scoping [Kohlbecker86], [
-hygienic], [Bawden88], [macrosthatwork], [syntacticabstraction]:
-
-@cindex @w{hygienic}
-
-@cindex @w{referentially transparent}
-
-
-
-
-@itemize @bullet
-
-
-@item
-If a macro transformer inserts a binding for an identifier
-(variable or keyword), the identifier will in effect be renamed
-throughout its scope to avoid conflicts with other identifiers.
-Note that a @code{define} at top level may or may not introduce a binding;
-see section @ref{Definitions}.
-
-@item
-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.
-
-
-@end itemize
-
-@vindex @w{define}
-
-@c The low-level facility permits non-hygienic macros to be written,
-@c and may be used to implement the high-level pattern language.
-
-@c The fourth section describes some features that would make the
-@c low-level macro facility easier to use directly.
-
-@node Binding constructs for syntactic keywords, Pattern language, Macros, Macros
-@subsection Binding constructs for syntactic keywords
-
-
-
-@samp{Let-syntax} and @samp{letrec-syntax} are
-analogous to @samp{let} and @samp{letrec}, but they bind
-syntactic keywords to macro transformers instead of binding variables
-to locations that contain values. Syntactic keywords may also be
-bound at top level; see section @ref{Syntax definitions}.
-
-
-@deffn {syntax} let-syntax @r{<bindings>} @r{<body>}
-
-@emph{Syntax:}
-@r{<Bindings>} should have the form
-
-@format
-@t{((@r{<keyword>} @r{<transformer spec>}) @dots{},)
-}
-@end format
-
-Each @r{<keyword>} is an identifier,
-each @r{<transformer spec>} is an instance of @samp{syntax-rules}, and
-@r{<body>} should be a sequence of one or more expressions. It is an error
-for a @r{<keyword>} to appear more than once in the list of keywords
-being bound.
-
-@emph{Semantics:}
-The @r{<body>} is expanded in the syntactic environment
-obtained by extending the syntactic environment of the
-@samp{let-syntax} expression with macros whose keywords are
-the @r{<keyword>}s, bound to the specified transformers.
-Each binding of a @r{<keyword>} has @r{<body>} as its region.
-
-
-@format
-@t{(let-syntax ((when (syntax-rules ()
- ((when test stmt1 stmt2 ...)
- (if test
- (begin stmt1
- stmt2 ...))))))
- (let ((if #t))
- (when if (set! if 'now))
- if)) ==> now
-
-(let ((x 'outer))
- (let-syntax ((m (syntax-rules () ((m) x))))
- (let ((x 'inner))
- (m)))) ==> outer
-}
-@end format
-
-
-@end deffn
-
-
-@deffn {syntax} letrec-syntax @r{<bindings>} @r{<body>}
-
-@emph{Syntax:}
-Same as for @samp{let-syntax}.
-
-@emph{Semantics:}
- The @r{<body>} is expanded in the syntactic environment obtained by
-extending the syntactic environment of the @samp{letrec-syntax}
-expression with macros whose keywords are the
-@r{<keyword>}s, bound to the specified transformers.
-Each binding of a @r{<keyword>} has the @r{<bindings>}
-as well as the @r{<body>} within its region,
-so the transformers can
-transcribe expressions into uses of the macros
-introduced by the @samp{letrec-syntax} expression.
-
-
-@format
-@t{(letrec-syntax
- ((my-or (syntax-rules ()
- ((my-or) #f)
- ((my-or e) e)
- ((my-or e1 e2 ...)
- (let ((temp e1))
- (if temp
- temp
- (my-or e2 ...)))))))
- (let ((x #f)
- (y 7)
- (temp 8)
- (let odd?)
- (if even?))
- (my-or x
- (let temp)
- (if y)
- y))) ==> 7
-}
-@end format
-
-
-@end deffn
-
-@node Pattern language, , Binding constructs for syntactic keywords, Macros
-@subsection Pattern language
-
-
-
-A @r{<transformer spec>} has the following form:
-
-
-@deffn {} syntax-rules @r{<literals>} @r{<syntax rule>} @dots{},
-
-@emph{Syntax:}
-@r{<Literals>} is a list of identifiers and each @r{<syntax rule>}
-should be of the form
-
-@format
-@t{(@r{<pattern>} @r{<template>})
-}
-@end format
-
-The @r{<pattern>} in a @r{<syntax rule>} is a list @r{<pattern>}
-that begins with the keyword for the macro.
-
-A @r{<pattern>} is either an identifier, a constant, or one of the
-following
-
-@format
-@t{(@r{<pattern>} @dots{})
-(@r{<pattern>} @r{<pattern>} @dots{} . @r{<pattern>})
-(@r{<pattern>} @dots{} @r{<pattern>} @r{<ellipsis>})
-#(@r{<pattern>} @dots{})
-#(@r{<pattern>} @dots{} @r{<pattern>} @r{<ellipsis>})
-}
-@end format
-
-and a template is either an identifier, a constant, or one of the following
-
-@format
-@t{(@r{<element>} @dots{})
-(@r{<element>} @r{<element>} @dots{} . @r{<template>})
-#(@r{<element>} @dots{})
-}
-@end format
-
-where an @r{<element>} is a @r{<template>} optionally
-followed by an @r{<ellipsis>} and
-an @r{<ellipsis>} is the identifier ``@samp{...}'' (which cannot be used as
-an identifier in either a template or a pattern).
-@vindex ...
-
-@emph{Semantics:} An instance of @samp{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
-@samp{syntax-rules} is matched against the patterns contained in the
-@r{<syntax rule>}s, beginning with the leftmost @r{<syntax rule>}.
-When a match is found, the macro use is transcribed hygienically
-according to the template.
-
-An identifier that appears in the pattern of a @r{<syntax rule>} is
-a @emph{pattern variable}, unless it is the keyword that begins the pattern,
-is listed in @r{<literals>}, or is the identifier ``@samp{...}''.
-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
-@r{<pattern>}.
-
-The keyword at the beginning of the pattern in a
-@r{<syntax rule>} is not involved in the matching and
-is not considered a pattern variable or literal identifier.
-
-
-@quotation
-@emph{Rationale:}
-The scope of the keyword is determined by the expression or syntax
-definition that binds it to the associated macro transformer.
-If the keyword were a pattern variable or literal
-identifier, then
-the template that follows the pattern would be within its scope
-regardless of whether the keyword were bound by @samp{let-syntax}
-or by @samp{letrec-syntax}.
-@end quotation
-
-
-Identifiers that appear in @r{<literals>} are interpreted as literal
-identifiers to be matched against corresponding subforms of the input.
-A subform
-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 equal and both have no lexical binding.
-
-@c [Bill Rozas suggested the term "noise word" for these literal
-@c identifiers, but in their most interesting uses, such as a setf
-@c macro, they aren't noise words at all. -- Will]
-
-A subpattern followed by @samp{...} can match zero or more elements of the
-input. It is an error for @samp{...} to appear in @r{<literals>}.
-Within a pattern the identifier @samp{...} must follow the last element of
-a nonempty sequence of subpatterns.
-
-More formally, an input form F matches a pattern P if and only if:
-
-
-
-@itemize @bullet
-
-@item
-P is a non-literal identifier; or
-
-@item
-P is a literal identifier and F is an identifier with the same
-binding; or
-
-@item
-P is a list @samp{(P_1 @dots{} P_n)} and F is a
-list of n
-forms that match P_1 through P_n, respectively; or
-
-@item
-P is an improper list
-@samp{(P_1 P_2 @dots{} P_n . P_n+1)}
-and F is a list or
-improper list of n or more forms that match P_1 through P_n,
-respectively, and whose nth ``cdr'' matches P_n+1; or
-
-@item
-P is of the form
-@samp{(P_1 @dots{} P_n P_n+1 <ellipsis>)}
-where <ellipsis> is the identifier @samp{...}
-and F is
-a proper list of at least n forms, the first n of which match
-P_1 through P_n, respectively, and each remaining element of F
-matches P_n+1; or
-
-@item
-P is a vector of the form @samp{#(P_1 @dots{} P_n)}
-and F is a vector
-of n forms that match P_1 through P_n; or
-
-@item
-P is of the form
-@samp{#(P_1 @dots{} P_n P_n+1 <ellipsis>)}
-where <ellipsis> is the identifier @samp{...}
-and F is a vector of n
-or more forms the first n of which match
-P_1 through P_n, respectively, and each remaining element of F
-matches P_n+1; or
-
-@item
-P is a datum and F is equal to P in the sense of
-the @samp{equal?} procedure.
-
-@end 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.
-
-When a macro use is transcribed according to the template of the
-matching @r{<syntax rule>}, pattern variables that occur in the
-template are replaced by the subforms they match in the input.
-Pattern variables that occur in subpatterns followed by one or more
-instances of the identifier
-@samp{...} are allowed only in subtemplates that are
-followed by as many instances of @samp{...}.
-They are replaced in the
-output by all of the subforms they match in the input, distributed as
-indicated. It is an error if the output cannot be built up as
-specified.
-
-@c %% This description of output construction is very vague. It should
-@c %% probably be formalized, but that is not easy...
-
-Identifiers that appear in the template but are not pattern variables
-or the identifier
-@samp{...} 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
-@samp{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.
-
-As an example, if @code{let} and @code{cond} are defined as in
-@vindex @w{cond}
-@vindex @w{let}
-section @ref{Derived expression type} then they are hygienic (as required) and
-the following is not an error.
-
-
-@format
-@t{(let ((=> #f))
- (cond (#t => 'ok))) ==> ok
-}
-@end format
-
-
-The macro transformer for @samp{cond} recognizes @samp{=>}
-as a local variable, and hence an expression, and not as the
-top-level identifier @samp{=>}, which the macro transformer treats
-as a syntactic keyword. Thus the example expands into
-
-
-@format
-@t{(let ((=> #f))
- (if #t (begin => 'ok)))
-}
-@end format
-
-
-instead of
-
-
-@format
-@t{(let ((=> #f))
- (let ((temp #t))
- (if temp ('ok temp))))
-}
-@end format
-
-
-which would result in an invalid procedure call.
-
-@end deffn
-
-
-@page
-
-@c @include{prog}
-@node Program structure, Standard procedures, Expressions, top
-@chapter Program structure
-
-@menu
-* Programs::
-* Definitions::
-* Syntax definitions::
-@end menu
-
-
-
-@node Programs, Definitions, Program structure, Program structure
-@section Programs
-
-
-A Scheme program consists of a sequence of expressions, definitions,
-and syntax definitions.
-Expressions are described in chapter @ref{Expressions};
-definitions and syntax definitions are the subject of the rest of the
-present chapter.
-
-Programs are typically stored in files or entered interactively to a
-running Scheme system, although other paradigms are possible;
-questions of user interface lie outside the scope of this report.
-(Indeed, Scheme would still be useful as a notation for expressing
-computational methods even in the absence of a mechanical
-implementation.)
-
-Definitions and syntax definitions occurring at the top level of a program
-can be interpreted
-declaratively.
-They cause bindings to be created in the top level
-environment or modify the value of existing top-level bindings.
-Expressions occurring at the top level of a program are
-interpreted imperatively; they are executed in order when the program is
-invoked or loaded, and typically perform some kind of initialization.
-
-At the top level of a program @t{(begin @r{<form1>} @dots{},)} is
-equivalent to the sequence of expressions, definitions, and syntax definitions
-that form the body of the @code{begin}.
-@vindex @w{begin}
-
-@ignore todo
-Cromarty, etc.: disclaimer about top level?
-@end ignore
-
-
-@node Definitions, Syntax definitions, Programs, Program structure
-@section Definitions
-
-@menu
-* Top level definitions::
-* Internal definitions::
-@end menu
-
-
-
-Definitions are valid in some, but not all, contexts where expressions
-are allowed. They are valid only at the top level of a @r{<program>}
-and at the beginning of a @r{<body>}.
-
-@cindex @w{definition}
-
-A definition should have one of the following forms:
-@cindex @w{define}
-
-
-
-@itemize @bullet
-
-
-@item @t{(define @r{<variable>} @r{<expression>})}
-
-@item @t{(define (@r{<variable>} @r{<formals>}) @r{<body>})}
-
-@r{<Formals>} should be either a
-sequence of zero or more variables, or a sequence of one or more
-variables followed by a space-delimited period and another variable (as
-in a lambda expression). This form is equivalent to
-
-@example
-
-(define @r{<variable>}
- (lambda (@r{<formals>}) @r{<body>}))@r{.}
-
-@end example
-
-
-@item @t{(define (@r{<variable>} .@: @r{<formal>}) @r{<body>})}
-
-@r{<Formal>} should be a single
-variable. This form is equivalent to
-
-@example
-
-(define @r{<variable>}
- (lambda @r{<formal>} @r{<body>}))@r{.}
-
-@end example
-
-
-
-@end itemize
-
-
-@node Top level definitions, Internal definitions, Definitions, Definitions
-@subsection Top level definitions
-
-
-At the top level of a program, a definition
-
-@example
-
-(define @r{<variable>} @r{<expression>})
-
-@end example
-
-has essentially the same effect as the assignment expression
-
-@example
-
-(set! @r{<variable>} @r{<expression>})
-
-@end example
-
-if @r{<variable>} is bound. If @r{<variable>} is not bound,
-however, then the definition will bind @r{<variable>} to a new
-location before performing the assignment, whereas it would be an error
-to perform a @samp{set!} on an unbound variable.
-@cindex @w{unbound}
-
-
-@example
-
-(define add3
- (lambda (x) (+ x 3)))
-(add3 3) ==> 6
-(define first car)
-(first '(1 2)) ==> 1
-
-@end example
-
-
-Some implementations of Scheme use an initial environment in
-which all possible variables are bound to locations, most of
-which contain undefined values. Top level definitions in
-such an implementation are truly equivalent to assignments.
-
-@ignore todo
-Rozas: equal time for opposition semantics?
-@end ignore
-
-
-
-@node Internal definitions, , Top level definitions, Definitions
-@subsection Internal definitions
-
-
-
-Definitions may occur at the
-beginning of a @r{<body>} (that is, the body of a @code{lambda},
-@vindex @w{lambda}
-@code{let}, @code{let*}, @code{letrec}, @code{let-syntax}, or @code{letrec-syntax}
-@vindex @w{letrec-syntax}
-@vindex @w{let-syntax}
-@vindex @w{letrec}
-@vindex @w{let*}
-@vindex @w{let}
-expression or that of a definition of an appropriate form).
-Such definitions are known as @emph{internal definitions} as opposed to the top level definitions described above.
-@cindex @w{internal definition}
-The variable defined by an internal definition is local to the
-@r{<body>}. That is, @r{<variable>} is bound rather than assigned,
-and the region of the binding is the entire @r{<body>}. For example,
-
-
-@example
-
-(let ((x 5))
- (define foo (lambda (y) (bar x y)))
- (define bar (lambda (a b) (+ (* a b) a)))
- (foo (+ x 3))) ==> 45
-
-@end example
-
-
-A @r{<body>} containing internal definitions can always be converted
-into a completely equivalent @samp{letrec} expression. For example, the
-@samp{let} expression in the above example is equivalent to
-
-
-@example
-
-(let ((x 5))
- (letrec ((foo (lambda (y) (bar x y)))
- (bar (lambda (a b) (+ (* a b) a))))
- (foo (+ x 3))))
-
-@end example
-
-
-Just as for the equivalent @samp{letrec} expression, it must be
-possible to evaluate each @r{<expression>} of every internal
-definition in a @r{<body>} without assigning or referring to
-the value of any @r{<variable>} being defined.
-
-Wherever an internal definition may occur
-@t{(begin @r{<definition1>} @dots{},)}
-is equivalent to the sequence of definitions
-that form the body of the @code{begin}.
-@vindex @w{begin}
-
-@node Syntax definitions, , Definitions, Program structure
-@section Syntax definitions
-
-
-Syntax definitions are valid only at the top level of a @r{<program>}.
-
-@cindex @w{syntax definition}
-They have the following form:
-@cindex @w{define-syntax}
-
-@t{(define-syntax @r{<keyword>} @r{<transformer spec>})}
-
-@r{<Keyword>} is an identifier, and
-the @r{<transformer spec>} should be an instance of @code{syntax-rules}.
-@vindex @w{syntax-rules}
-The top-level syntactic environment is extended by binding the
-@r{<keyword>} to the specified transformer.
-
-There is no @samp{define-syntax} analogue of internal definitions.
-
-@c [Rationale flushed because it may or may not be true and isn't the
-@c real rationale anyway. -RK]
-@c \begin{rationale}
-@c As discussed below, the syntax and scope rules for syntax definitions
-@c can give rise to syntactic ambiguities when syntactic keywords are
-@c shadowed.
-@c Further ambiguities would arise if {\cf define-syntax}
-@c were permitted at the beginning of a \meta{body}, with scope
-@c rules analogous to those for internal definitions.
-@c \end{rationale}
-
-@c It is an error for a program to contain more than one top-level
-@c \meta{definition} or \meta{syntax definition} of any identifier.
-
-@c [I flushed this because it isn't an error for a program to
-@c contain more than one top-level definition of an identifier,
-@c and I didn't want to introduce any gratuitous incompatibilities
-@c with the existing Scheme language. -- Will]
-
-Although macros may expand into definitions and syntax definitions in
-any context that permits them, it is an error for a definition or syntax
-definition to shadow a syntactic keyword whose meaning is needed to
-determine whether some form in the group of forms that contains the
-shadowing definition is in fact a definition, or, for internal definitions,
-is needed to determine the boundary between the group and the expressions
-that follow the group. For example, the following are errors:
-
-
-@example
-
-(define define 3)
-
-(begin (define begin list))
-
-(let-syntax
- ((foo (syntax-rules ()
- ((foo (proc args ...) body ...)
- (define proc
- (lambda (args ...)
- body ...))))))
- (let ((x 3))
- (foo (plus x y) (+ x y))
- (define foo x)
- (plus foo x)))
-
-@end example
-
-
-
-
-@c @include{procs}
-
-@c Initial environment
-
-@c \vfill\eject
-@node Standard procedures, Formal syntax and semantics, Program structure, top
-@chapter Standard procedures
-
-@menu
-* Equivalence predicates::
-* Numbers::
-* Other data types::
-* Control features::
-* Eval::
-* Input and output::
-@end menu
-
-
-
-
-
-@cindex @w{initial environment}
-
-@cindex @w{top level environment}
-
-@cindex @w{library procedure}
-
-This chapter describes Scheme's built-in procedures. The initial (or
-``top level'') Scheme environment starts out with a number of variables
-bound to locations containing useful values, most of which are primitive
-procedures that manipulate data. For example, the variable @samp{abs} is
-bound to (a location initially containing) a procedure of one argument
-that computes the absolute value of a number, and the variable @samp{+}
-is bound to a procedure that computes sums. Built-in procedures that
-can easily be written in terms of other built-in procedures are identified as
-``library procedures''.
-
-A program may use a top-level definition to bind any variable. It may
-subsequently alter any such binding by an assignment (see @pxref{Assignments}).
-These operations do not modify the behavior of Scheme's built-in
-procedures. Altering any top-level binding that has not been introduced by a
-definition has an unspecified effect on the behavior of the built-in procedures.
-
-@node Equivalence predicates, Numbers, Standard procedures, Standard procedures
-@section Equivalence predicates
-
-
-
-A @dfn{predicate} is a procedure that always returns a boolean
-@cindex @w{predicate}
-value (@t{#t} or @t{#f}). An @dfn{equivalence predicate} is
-@cindex @w{equivalence predicate}
-the computational analogue of a mathematical equivalence relation (it is
-symmetric, reflexive, and transitive). Of the equivalence predicates
-described in this section, @samp{eq?} is the finest or most
-discriminating, and @samp{equal?} is the coarsest. @samp{Eqv?} is
-slightly less discriminating than @samp{eq?}.
-@ignore todo
-Pitman doesn't like
-this paragraph. Lift the discussion from the Maclisp manual. Explain
-why there's more than one predicate.
-@end ignore
-
-
-
-
-@deffn {procedure} eqv? obj1 obj2
-
-The @samp{eqv?} procedure defines a useful equivalence relation on objects.
-Briefly, it returns @t{#t} if @var{obj1} and @var{obj2} should
-normally be regarded as the same object. This relation is left slightly
-open to interpretation, but the following partial specification of
-@samp{eqv?} holds for all implementations of Scheme.
-
-The @samp{eqv?} procedure returns @t{#t} if:
-
-
-
-@itemize @bullet
-
-@item
-@var{obj1} and @var{obj2} are both @t{#t} or both @t{#f}.
-
-@item
-@var{obj1} and @var{obj2} are both symbols and
-
-
-@format
-@t{(string=? (symbol->string obj1)
- (symbol->string obj2))
- ==> #t
-}
-@end format
-
-
-
-@quotation
-@emph{Note:}
-This assumes that neither @var{obj1} nor @var{obj2} is an ``uninterned
-symbol'' as alluded to in section @ref{Symbols}. This report does
-not presume to specify the behavior of @samp{eqv?} on implementation-dependent
-extensions.
-@end quotation
-
-
-@item
-@var{obj1} and @var{obj2} are both numbers, are numerically
-equal (see @samp{=}, section @pxref{Numbers}), and are either both
-exact or both inexact.
-
-@item
-@var{obj1} and @var{obj2} are both characters and are the same
-character according to the @samp{char=?} procedure
-(section @pxref{Characters}).
-
-@item
-both @var{obj1} and @var{obj2} are the empty list.
-
-@item
-@var{obj1} and @var{obj2} are pairs, vectors, or strings that denote the
-same locations in the store (section @pxref{Storage model}).
-
-@item
-@var{obj1} and @var{obj2} are procedures whose location tags are
-equal (section @pxref{Procedures}).
-
-@end itemize
-
-@cindex @w{inexact}
-@cindex @w{exact}
-
-The @samp{eqv?} procedure returns @t{#f} if:
-
-
-
-@itemize @bullet
-
-@item
-@var{obj1} and @var{obj2} are of different types
-(section @pxref{Disjointness of types}).
-
-@item
-one of @var{obj1} and @var{obj2} is @t{#t} but the other is
-@t{#f}.
-
-@item
-@var{obj1} and @var{obj2} are symbols but
-
-
-@format
-@t{(string=? (symbol->string @var{obj1})
- (symbol->string @var{obj2}))
- ==> #f
-}
-@end format
-
-
-@item
-one of @var{obj1} and @var{obj2} is an exact number but the other
-is an inexact number.
-
-@item
-@var{obj1} and @var{obj2} are numbers for which the @samp{=}
-procedure returns @t{#f}.
-
-@item
-@var{obj1} and @var{obj2} are characters for which the @samp{char=?}
-procedure returns @t{#f}.
-
-@item
-one of @var{obj1} and @var{obj2} is the empty list but the other
-is not.
-
-@item
-@var{obj1} and @var{obj2} are pairs, vectors, or strings that denote
-distinct locations.
-
-@item
-@var{obj1} and @var{obj2} are procedures that would behave differently
-(return different value(s) or have different side effects) for some arguments.
-
-
-@end itemize
-
-
-
-@format
-@t{(eqv? 'a 'a) ==> #t
-(eqv? 'a 'b) ==> #f
-(eqv? 2 2) ==> #t
-(eqv? '() '()) ==> #t
-(eqv? 100000000 100000000) ==> #t
-(eqv? (cons 1 2) (cons 1 2)) ==> #f
-(eqv? (lambda () 1)
- (lambda () 2)) ==> #f
-(eqv? #f 'nil) ==> #f
-(let ((p (lambda (x) x)))
- (eqv? p p)) ==> #t
-}
-@end format
-
-
-The following examples illustrate cases in which the above rules do
-not fully specify the behavior of @samp{eqv?}. All that can be said
-about such cases is that the value returned by @samp{eqv?} must be a
-boolean.
-
-
-@format
-@t{(eqv? "" "") ==> @emph{unspecified}
-(eqv? '#() '#()) ==> @emph{unspecified}
-(eqv? (lambda (x) x)
- (lambda (x) x)) ==> @emph{unspecified}
-(eqv? (lambda (x) x)
- (lambda (y) y)) ==> @emph{unspecified}
-}
-@end format
-
-
-The next set of examples shows the use of @samp{eqv?} with procedures
-that have local state. @samp{Gen-counter} must return a distinct
-procedure every time, since each procedure has its own internal counter.
-@samp{Gen-loser}, however, returns equivalent procedures each time, since
-the local state does not affect the value or side effects of the
-procedures.
-
-
-@format
-@t{(define gen-counter
- (lambda ()
- (let ((n 0))
- (lambda () (set! n (+ n 1)) n))))
-(let ((g (gen-counter)))
- (eqv? g g)) ==> #t
-(eqv? (gen-counter) (gen-counter))
- ==> #f
-(define gen-loser
- (lambda ()
- (let ((n 0))
- (lambda () (set! n (+ n 1)) 27))))
-(let ((g (gen-loser)))
- (eqv? g g)) ==> #t
-(eqv? (gen-loser) (gen-loser))
- ==> @emph{unspecified}
-
-(letrec ((f (lambda () (if (eqv? f g) 'both 'f)))
- (g (lambda () (if (eqv? f g) 'both 'g))))
- (eqv? f g))
- ==> @emph{unspecified}
-
-(letrec ((f (lambda () (if (eqv? f g) 'f 'both)))
- (g (lambda () (if (eqv? f g) 'g 'both))))
- (eqv? f g))
- ==> #f
-}
-@end format
-
-
-@c Objects of distinct types must never be regarded as the same object,
-@c except that \schfalse{} and the empty list\index{empty list} are permitted to
-@c be identical.
-
-@c \begin{scheme}
-@c (eqv? '() \schfalse) \ev \unspecified%
-@c \end{scheme}
-
-Since it is an error to modify constant objects (those returned by
-literal expressions), implementations are permitted, though not
-required, to share structure between constants where appropriate. Thus
-the value of @samp{eqv?} on constants is sometimes
-implementation-dependent.
-
-
-@format
-@t{(eqv? '(a) '(a)) ==> @emph{unspecified}
-(eqv? "a" "a") ==> @emph{unspecified}
-(eqv? '(b) (cdr '(a b))) ==> @emph{unspecified}
-(let ((x '(a)))
- (eqv? x x)) ==> #t
-}
-@end format
-
-
-
-@quotation
-@emph{Rationale:}
-The above definition of @samp{eqv?} allows implementations latitude in
-their treatment of procedures and literals: implementations are free
-either to detect or to fail to detect that two procedures or two literals
-are equivalent to each other, and can decide whether or not to
-merge representations of equivalent objects by using the same pointer or
-bit pattern to represent both.
-@end quotation
-
-
-@end deffn
-
-
-
-@deffn {procedure} eq? obj1 obj2
-
-@samp{Eq?} is similar to @samp{eqv?} except that in some cases it is
-capable of discerning distinctions finer than those detectable by
-@samp{eqv?}.
-
-@samp{Eq?} and @samp{eqv?} are guaranteed to have the same
-behavior on symbols, booleans, the empty list, pairs, procedures,
-and non-empty
-strings and vectors. @samp{Eq?}'s behavior on numbers and characters is
-implementation-dependent, but it will always return either true or
-false, and will return true only when @samp{eqv?} would also return
-true. @samp{Eq?} may also behave differently from @samp{eqv?} on empty
-vectors and empty strings.
-
-
-@format
-@t{(eq? 'a 'a) ==> #t
-(eq? '(a) '(a)) ==> @emph{unspecified}
-(eq? (list 'a) (list 'a)) ==> #f
-(eq? "a" "a") ==> @emph{unspecified}
-(eq? "" "") ==> @emph{unspecified}
-(eq? '() '()) ==> #t
-(eq? 2 2) ==> @emph{unspecified}
-(eq? #\A #\A) ==> @emph{unspecified}
-(eq? car car) ==> #t
-(let ((n (+ 2 3)))
- (eq? n n)) ==> @emph{unspecified}
-(let ((x '(a)))
- (eq? x x)) ==> #t
-(let ((x '#()))
- (eq? x x)) ==> #t
-(let ((p (lambda (x) x)))
- (eq? p p)) ==> #t
-}
-@end format
-
-
-@ignore todo
-Needs to be explained better above. How can this be made to be
-not confusing? A table maybe?
-@end ignore
-
-
-
-@quotation
-@emph{Rationale:} It will usually be possible to implement @samp{eq?} much
-more efficiently than @samp{eqv?}, for example, as a simple pointer
-comparison instead of as some more complicated operation. One reason is
-that it may not be possible to compute @samp{eqv?} of two numbers in
-constant time, whereas @samp{eq?} implemented as pointer comparison will
-always finish in constant time. @samp{Eq?} may be used like @samp{eqv?}
-in applications using procedures to implement objects with state since
-it obeys the same constraints as @samp{eqv?}.
-@end quotation
-
-
-@end deffn
-
-
-
-@deffn {library procedure} equal? obj1 obj2
-
-@samp{Equal?} recursively compares the contents of pairs, vectors, and
-strings, applying @samp{eqv?} on other objects such as numbers and symbols.
-A rule of thumb is that objects are generally @samp{equal?} if they print
-the same. @samp{Equal?} may fail to terminate if its arguments are
-circular data structures.
-
-
-@format
-@t{(equal? 'a 'a) ==> #t
-(equal? '(a) '(a)) ==> #t
-(equal? '(a (b) c)
- '(a (b) c)) ==> #t
-(equal? "abc" "abc") ==> #t
-(equal? 2 2) ==> #t
-(equal? (make-vector 5 'a)
- (make-vector 5 'a)) ==> #t
-(equal? (lambda (x) x)
- (lambda (y) y)) ==> @emph{unspecified}
-}
-@end format
-
-
-@end deffn
-
-
-@node Numbers, Other data types, Equivalence predicates, Standard procedures
-@section Numbers
-
-@menu
-* Numerical types::
-* Exactness::
-* Implementation restrictions::
-* Syntax of numerical constants::
-* Numerical operations::
-* Numerical input and output::
-@end menu
-
-
-
-@cindex @w{number}
-
-@c %R4%% The excessive use of the code font in this section was
-@c confusing, somewhat obnoxious, and inconsistent with the rest
-@c of the report and with parts of the section itself. I added
-@c a \tupe no-op, and changed most old uses of \type to \tupe,
-@c to make it easier to change the fonts back if people object
-@c to the change.
-
-@c \newcommand{\type}[1]{{\it#1}}
-@c \newcommand{\tupe}[1]{{#1}}
-
-Numerical computation has traditionally been neglected by the Lisp
-community. Until Common Lisp there was no carefully thought out
-strategy for organizing numerical computation, and with the exception of
-the MacLisp system [Pitman83] little effort was made to
-execute numerical code efficiently. This report recognizes the excellent work
-of the Common Lisp committee and accepts many of their recommendations.
-In some ways this report simplifies and generalizes their proposals in a manner
-consistent with the purposes of Scheme.
-
-It is important to distinguish between the mathematical numbers, the
-Scheme numbers that attempt to model them, the machine representations
-used to implement the Scheme numbers, and notations used to write numbers.
-This report uses the types @i{number}, @i{complex}, @i{real},
-@i{rational}, and @i{integer} to refer to both mathematical numbers
-and Scheme numbers. Machine representations such as fixed point and
-floating point are referred to by names such as @i{fixnum} and
-@i{flonum}.
-
-@c %R4%% I did some reorganizing here to move the discussion of mathematical
-@c numbers before the discussion of the Scheme numbers, hoping that this
-@c would help to motivate the discussion of representation independence.
-
-@node Numerical types, Exactness, Numbers, Numbers
-@subsection Numerical types
-
-
-
-@cindex @w{numerical types}
-
-@c %R4%% A Scheme system provides data of type \type{number}, which is the most
-@c general numerical type supported by that system.
-@c \type{Number} is
-@c likely to be a complicated union type implemented in terms of
-@c \type{fixnum}s, \type{bignum}s, \type{flonum}s, and so forth, but this
-@c should not be apparent to a naive user. What the user should see is
-@c that the usual operations on numbers produce the mathematically
-@c expected results, within the limits of the implementation.
-
-@c %R4%% I rewrote the following paragraph to make the various levels of
-@c the tower into subsets of each other, instead of relating them by
-@c injections. I think the injections tended to put people in the frame
-@c of mind of thinking about coercions between non-overlapping numeric
-@c types in mainstream programming languages.
-
-Mathematically, numbers may be arranged into a tower of subtypes
-@c %R4%% with injections relating adjacent levels of the tower:
-in which each level is a subset of the level above it:
-
-@format
- @r{number}
- @r{complex}
- @r{real}
- @r{rational}
- @r{integer}
-@end format
-
-
-For example, 3 is an integer. Therefore 3 is also a rational,
-a real, and a complex. 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?}, @code{real?}, @code{rational?},
-@vindex @w{rational?}
-@vindex @w{real?}
-@vindex @w{complex?}
-@vindex @w{number?}
-and @code{integer?}.
-@vindex @w{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.
-
-@c %R4%% I moved "Implementations of Scheme are not required to implement
-@c the whole tower..." to the subsection on implementation restrictions.
-
-Scheme's numerical operations treat numbers as abstract data, as
-independent of their representation as possible. Although an implementation
-of Scheme may use fixnum, flonum, and perhaps other representations for
-numbers, this should not be apparent to a casual programmer writing
-simple programs.
-
-It is necessary, however, to distinguish between numbers that are
-represented exactly and those that may 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.
-
-@node Exactness, Implementation restrictions, Numerical types, Numbers
-@subsection Exactness
-
-
-@c %R4%% I tried to direct the following paragraph away from philosophizing
-@c about the exactness of mathematical numbers, and toward philosophizing
-@c about the exactness of Scheme numbers.
-
-
-@cindex @w{exactness}
-Scheme numbers are either @i{exact} or @i{inexact}. A number is
-@r{exact} if it was written as an exact constant or was derived from
-@r{exact} numbers using only @r{exact} operations. A number is
-@r{inexact} if it was written as an inexact constant,
-@c %R4%% models a quantity (e.g., a measurement) known only approximately,
-if it was
-derived using @r{inexact} ingredients, or if it was derived using
-@r{inexact} operations. Thus @r{inexact}ness is a contagious
-property of a number.
-@c %R4%% The rest of this paragraph (from R3RS) has been dropped.
-
-If two implementations produce @r{exact} results for a
-computation that did not involve @r{inexact} intermediate results,
-the two ultimate results will be mathematically equivalent. This is
-generally not true of computations involving @r{inexact} numbers
-since approximate methods such as floating point arithmetic may be used,
-but it is the duty of each implementation to make the result as close as
-practical to the mathematically ideal result.
-
-Rational operations such as @samp{+} should always produce
-@r{exact} results when given @r{exact} arguments.
-@c %R4%%If an implementation is
-@c unable to represent an \tupe{exact} result (for example, if it does not
-@c support infinite precision integers and rationals)
-If the operation is unable to produce an @r{exact} result,
-then it may either report the violation of an implementation restriction
-or it may silently coerce its
-result to an @r{inexact} value.
-@c %R4%%Such a coercion may cause an error later.
-See section @ref{Implementation restrictions}.
-
-With the exception of @code{inexact->exact}, the operations described in
-@vindex @w{inexact->exact}
-this section must generally return inexact results when given any inexact
-arguments. An operation may, however, return an @r{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 @r{exact} zero
-may produce an @r{exact} zero result, even if the other argument is
-@r{inexact}.
-
-@node Implementation restrictions, Syntax of numerical constants, Exactness, Numbers
-@subsection Implementation restrictions
-
-
-
-@cindex @w{implementation restriction}
-
-Implementations of Scheme are not required to implement the whole
-tower of subtypes given in section @ref{Numerical types},
-but they must implement a coherent subset consistent with both the
-purposes of the implementation and the spirit of the Scheme language.
-For example, an implementation in which all numbers are @r{real}
-may still be quite useful.
-
-Implementations may also support only a limited range of numbers of
-any type, subject to the requirements of this section. The supported
-range for @r{exact} numbers of any type may be different from the
-supported range for @r{inexact} numbers of that type. For example,
-an implementation that uses flonums to represent all its
-@r{inexact} @r{real} numbers may
-support a practically unbounded range of @r{exact} @r{integer}s
-and @r{rational}s
-while limiting the range of @r{inexact} @r{real}s (and therefore
-the range of @r{inexact} @r{integer}s and @r{rational}s)
-to the dynamic range of the flonum format.
-Furthermore
-the gaps between the representable @r{inexact} @r{integer}s and
-@r{rational}s are
-likely to be very large in such an implementation as the limits of this
-range are approached.
-
-An implementation of Scheme must support exact integers
-throughout the range of numbers that may be used for indexes of
-lists, vectors, and strings or that may result from computing the length of a
-list, vector, or string. The @code{length}, @code{vector-length},
-@vindex @w{vector-length}
-@vindex @w{length}
-and @code{string-length} procedures must return an exact
-@vindex @w{string-length}
-integer, and it is an error to use anything but an exact integer as an
-index. Furthermore any integer constant within the index range, if
-expressed by an exact integer syntax, will indeed be read as an exact
-integer, regardless of any implementation restrictions that may apply
-outside this range. Finally, the procedures listed below will always
-return an exact integer result provided all their arguments are exact integers
-and the mathematically expected result is representable as an exact integer
-within the implementation:
-
-
-@example
-
-+ - *
-quotient remainder modulo
-max min abs
-numerator denominator gcd
-lcm floor ceiling
-truncate round rationalize
-expt
-
-@end example
-
-
-Implementations are encouraged, but not required, to support
-@r{exact} @r{integer}s and @r{exact} @r{rational}s of
-practically unlimited size and precision, and to implement the
-above procedures and the @samp{/} procedure in
-such a way that they always return @r{exact} results when given @r{exact}
-arguments. If one of these procedures is unable to deliver an @r{exact}
-result when given @r{exact} arguments, then it may either report a
-violation of an
-implementation restriction or it may silently coerce its result to an
-@r{inexact} number. Such a coercion may cause an error later.
-
-@c %R4%% I moved this stuff here.
-@c It seems to me that the only thing that this requires is that
-@c implementations that support inexact numbers have to have both
-@c exact and inexact representations for the integers 0 through 15.
-@c If that's what it's saying, I'd rather say it that way.
-@c On the other hand, letting the limit be as small as 15 sounds a
-@c tad silly, though I think I understand how that number was arrived at.
-@c (Or is 35 the number?)
-
-@c Implementations are encouraged, but not required, to support \tupe{inexact}
-@c numbers. For any implementation that supports \tupe{inexact} numbers,
-@c there is a subset of the integers for which there are both \tupe{exact} and
-@c \tupe{inexact} representations. This subset must include all non-negative
-@c integers up to some limit specified by the implementation. This limit
-@c must be 16 or greater. The
-@c \ide{exact\coerce{}inexact} and \ide{inexact\coerce{}exact}
-@c procedures implement the natural one-to-one correspondence between
-@c the \tupe{inexact} and \tupe{exact} integers within this range.
-
-An implementation may use floating point and other approximate
-representation strategies for @r{inexact} numbers.
-@c %R4%% The following sentence seemed a bit condescending as well as
-@c awkward. It didn't seem to be very enforceable, so I flushed it.
-
-@c This is not to
-@c say that implementors need not use the best known algorithms for
-@c \tupe{inexact} computations---only that approximate methods of high
-@c quality are allowed.
-
-This report recommends, but does not require, that the IEEE 32-bit
-and 64-bit floating point standards be followed by implementations that use
-flonum representations, and that implementations using
-other representations should match or exceed the precision achievable
-using these floating point standards [IEEE].
-
-In particular, implementations that use flonum representations
-must follow these rules: A @r{flonum} result
-must be represented with at least as much precision as is used to express any of
-the inexact arguments to that operation. It is desirable (but not required) for
-potentially inexact operations such as @samp{sqrt}, when applied to @r{exact}
-arguments, to produce @r{exact} answers whenever possible (for example the
-square root of an @r{exact} 4 ought to be an @r{exact} 2).
-If, however, an
-@r{exact} number is operated upon so as to produce an @r{inexact} result
-(as by @samp{sqrt}), and if the result is represented as a @r{flonum}, then
-the most precise @r{flonum} format available must be used; but if the result
-is represented in some other way then the representation must have at least as
-much precision as the most precise @r{flonum} format available.
-
-Although Scheme allows a variety of written
-@c %R4%% representations of
-notations for
-numbers, any particular implementation may support only some of them.
-@c %R4%%
-For example, an implementation in which all numbers are @r{real}
-need not support the rectangular and polar notations for complex
-numbers. If an implementation encounters an @r{exact} numerical constant that
-it cannot represent as an @r{exact} number, then it may either report a
-violation of an implementation restriction or it may silently represent the
-constant by an @r{inexact} number.
-
-
-@node Syntax of numerical constants, Numerical operations, Implementation restrictions, Numbers
-@subsection Syntax of numerical constants
-
-
-
-@c @@@@LOSE@@@@
-
-@c %R4%% I removed the following paragraph in an attempt to tighten up
-@c this subsection. Except for its first sentence, which I moved to
-@c the subsection on implementation restrictions, I think its content
-@c is implied by the rest of the section.
-
-@c Although Scheme allows a variety of written representations of numbers,
-@c any particular implementation may support only some of them.
-@c These syntaxes are intended to be purely notational; any kind of number
-@c may be written in any form that the user deems convenient. Of course,
-@c writing 1/7 as a limited-precision decimal fraction will not express the
-@c number exactly, but this approximate form of expression may be just what
-@c the user wants to see.
-
-The syntax of the written representations for numbers is described formally in
-section @ref{Lexical structure}. Note that case is not significant in numerical
-constants.
-
-@c %R4%% See section~\ref{numberformats} for many examples.
-
-A number may be written in binary, octal, decimal, or
-hexadecimal by the use of a radix prefix. The radix prefixes are @samp{#b} (binary), @samp{#o} (octal), @samp{#d} (decimal), and @samp{#x} (hexadecimal). With
-@vindex #x
-@vindex #d
-@vindex #o
-@vindex #b
-no radix prefix, a number is assumed to be expressed in decimal.
-
-A
-@c %R4%%
-@c simple
-numerical constant may be specified to be either @r{exact} or
-@r{inexact} by a prefix. The prefixes are @samp{#e}
-@vindex #e
-for @r{exact}, and @samp{#i} for @r{inexact}. An exactness
-@vindex #i
-prefix may appear before or after any radix prefix that is used. If
-the written representation of a number has no exactness prefix, the
-constant may be either @r{inexact} or @r{exact}. It is
-@r{inexact} if it contains a decimal point, an
-exponent, or a ``#'' character in the place of a digit,
-otherwise it is @r{exact}.
-@c %R4%% With our new syntax, the following sentence is redundant:
-
-@c The written representation of a
-@c compound number, such as a ratio or a complex, is exact if and only if
-@c all of its constituents are exact.
-
-In systems with @r{inexact} numbers
-of varying precisions it may be useful to specify
-the precision of a constant. For this purpose, numerical constants
-may be written with an exponent marker that indicates the
-desired precision of the @r{inexact}
-representation. The letters @samp{s}, @samp{f},
-@samp{d}, and @samp{l} specify the use of @var{short}, @var{single},
-@var{double}, and @var{long} precision, respectively. (When fewer
-than four internal
-@c %R4%%\tupe{flonum}
-@r{inexact}
-representations exist, the four size
-specifications are mapped onto those available. For example, an
-implementation with two internal representations may map short and
-single together and long and double together.) In addition, the
-exponent marker @samp{e} specifies the default precision for the
-implementation. The default precision has at least as much precision
-as @var{double}, but
-implementations may wish to allow this default to be set by the user.
-
-
-@example
-
-3.14159265358979F0
- @r{Round to single ---} 3.141593
-0.6L0
- @r{Extend to long ---} .600000000000000
-
-@end example
-
-
-
-@node Numerical operations, Numerical input and output, Syntax of numerical constants, Numbers
-@subsection Numerical operations
-
-
-The reader is referred to section @ref{Entry format} for a summary
-of the naming conventions used to specify restrictions on the types of
-arguments to numerical routines.
-@c %R4%% The following sentence has already been said twice, and the
-@c term "exactness-preserving" is no longer defined by the Report.
-
-@c Remember that
-@c an exactness-preserving operation may coerce its result to inexact if the
-@c implementation is unable to represent it exactly.
-The examples used in this section assume that any numerical constant written
-using an @r{exact} notation is indeed represented as an @r{exact}
-number. Some examples also assume that certain numerical constants written
-using an @r{inexact} notation can be represented without loss of
-accuracy; the @r{inexact} constants were chosen so that this is
-likely to be true in implementations that use flonums to represent
-inexact numbers.
-
-@ignore todo
-Scheme provides the usual set of operations for manipulating
-numbers, etc.
-@end ignore
-
-
-
-@deffn {procedure} number? obj
-@deffnx {procedure} complex? obj
-@deffnx {procedure} real? obj
-@deffnx {procedure} rational? obj
-@deffnx {procedure} integer? obj
-
-These numerical type predicates can be applied to any kind of
-argument, including non-numbers. They return @t{#t} if the object is
-of the named type, and otherwise they return @t{#f}.
-In general, if a type predicate is true of a number then all higher
-type predicates are also true of that number. Consequently, if a type
-predicate is false of a number, then all lower type predicates are
-also false of that number.
-@c %R4%% The new section on implementation restrictions subsumes:
-@c Not every system
-@c supports all of these types; for example, it is entirely possible to have a
-@c Scheme system that has only \tupe{integer}s. Nonetheless every implementation
-@c of Scheme must have all of these predicates.
-
-If @var{z} is an inexact complex number, then @samp{(real? @var{z})} is true if
-and only if @samp{(zero? (imag-part @var{z}))} is true. If @var{x} is an inexact
-real number, then @samp{(integer? @var{x})} is true if and only if
-@samp{(= @var{x} (round @var{x}))}.
-
-
-@format
-@t{(complex? 3+4i) ==> #t
-(complex? 3) ==> #t
-(real? 3) ==> #t
-(real? -2.5+0.0i) ==> #t
-(real? #e1e10) ==> #t
-(rational? 6/10) ==> #t
-(rational? 6/3) ==> #t
-(integer? 3+0i) ==> #t
-(integer? 3.0) ==> #t
-(integer? 8/4) ==> #t
-}
-@end format
-
-
-
-@quotation
-@emph{Note:}
-The behavior of these type predicates on @r{inexact} numbers
-is unreliable, since any inaccuracy may affect the result.
-@end quotation
-
-
-
-@quotation
-@emph{Note:}
-In many implementations the @code{rational?} procedure will be the same
-@vindex @w{rational?}
-as @code{real?}, and the @code{complex?} procedure will be the same as
-@vindex @w{complex?}
-@vindex @w{real?}
-@code{number?}, but unusual implementations may be able to represent
-@vindex @w{number?}
-some irrational numbers exactly or may extend the number system to
-support some kind of non-complex numbers.
-@end quotation
-
-
-@end deffn
-
-
-@deffn {procedure} exact? @var{z}
-@deffnx {procedure} inexact? @var{z}
-
-These numerical predicates provide tests for the exactness of a
-quantity. For any Scheme number, precisely one of these predicates
-is true.
-
-@end deffn
-
-
-
-@deffn {procedure} = z1 z2 z3 @dots{},
-@deffnx {procedure} < x1 x2 x3 @dots{},
-@deffnx {procedure} > x1 x2 x3 @dots{},
-@deffnx {procedure} <= x1 x2 x3 @dots{},
-@deffnx {procedure} >= x1 x2 x3 @dots{},
-
-@c - Some implementations allow these procedures to take many arguments, to
-@c - facilitate range checks.
-These procedures return @t{#t} if their arguments are (respectively):
-equal, monotonically increasing, monotonically decreasing,
-monotonically nondecreasing, or monotonically nonincreasing.
-
-These predicates are required to be transitive.
-
-
-@quotation
-@emph{Note:}
-The traditional implementations of these predicates in Lisp-like
-languages are not transitive.
-@end quotation
-
-
-
-@quotation
-@emph{Note:}
-While it is not an error to compare @r{inexact} numbers using these
-predicates, the results may be unreliable because a small inaccuracy
-may affect the result; this is especially true of @code{=} and @code{zero?}.
-@vindex @w{zero?}
-@vindex @w{=}
-When in doubt, consult a numerical analyst.
-@end quotation
-
-
-@end deffn
-
-
-@deffn {library procedure} zero? @var{z}
-@deffnx {library procedure} positive? @var{x}
-@deffnx {library procedure} negative? @var{x}
-@deffnx {library procedure} odd? @var{n}
-@deffnx {library procedure} even? @var{n}
-
-These numerical predicates test a number for a particular property,
-returning @t{#t} or @t{#f}. See note above.
-
-@end deffn
-
-
-@deffn {library procedure} max x1 x2 @dots{},
-@deffnx {library procedure} min x1 x2 @dots{},
-
-These procedures return the maximum or minimum of their arguments.
-
-
-@format
-@t{(max 3 4) ==> 4 ; exact
-(max 3.9 4) ==> 4.0 ; inexact
-}
-@end format
-
-
-
-@quotation
-@emph{Note:}
-If any argument is inexact, then the result will also be inexact (unless
-the procedure can prove that the inaccuracy is not large enough to affect the
-result, which is possible only in unusual implementations). If @samp{min} or
-@samp{max} is used to compare numbers of mixed exactness, and the numerical
-value of the result cannot be represented as an inexact number without loss of
-accuracy, then the procedure may report a violation of an implementation
-restriction.
-@end quotation
-
-
-@end deffn
-
-
-
-@deffn {procedure} + z1 @dots{},
-@deffnx {procedure} * z1 @dots{},
-
-These procedures return the sum or product of their arguments.
-@c - These procedures are exactness preserving.
-
-
-@format
-@t{(+ 3 4) ==> 7
-(+ 3) ==> 3
-(+) ==> 0
-(* 4) ==> 4
-(*) ==> 1
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {procedure} - z1 z2
-@deffnx {procedure} - @var{z}
-@deffnx {optional procedure} - z1 z2 @dots{},
-@deffnx {procedure} / z1 z2
-@deffnx {procedure} / @var{z}
-@deffnx {optional procedure} / z1 z2 @dots{},
-
-With two or more arguments, these procedures return the difference or
-quotient of their arguments, associating to the left. With one argument,
-however, they return the additive or multiplicative inverse of their argument.
-@c - These procedures are exactness preserving, except that division may
-@c - coerce its result to inexact in implementations that do not support
-@c - \tupe{ratnum}s.
-
-
-@format
-@t{(- 3 4) ==> -1
-(- 3 4 5) ==> -6
-(- 3) ==> -3
-(/ 3 4 5) ==> 3/20
-(/ 3) ==> 1/3
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {library procedure} abs x
-
-@samp{Abs} returns the absolute value of its argument.
-@c - {\cf Abs} is exactness preserving when its argument is real.
-
-@format
-@t{(abs -7) ==> 7
-}
-@end format
-
-@end deffn
-
-
-
-@deffn {procedure} quotient n1 n2
-@deffnx {procedure} remainder n1 n2
-@deffnx {procedure} modulo n1 n2
-
-These procedures implement number-theoretic (integer)
-division. @var{n2} should be non-zero. All three procedures
-return integers. If @var{n1}/@var{n2} is an integer:
-
-@format
-@t{ (quotient @var{n1} @var{n2}) ==> @var{n1}/@var{n2}
- (remainder @var{n1} @var{n2}) ==> 0
- (modulo @var{n1} @var{n2}) ==> 0
-}
-@end format
-
-If @var{n1}/@var{n2} is not an integer:
-
-@format
-@t{ (quotient @var{n1} @var{n2}) ==> @var{n_q}
- (remainder @var{n1} @var{n2}) ==> @var{n_r}
- (modulo @var{n1} @var{n2}) ==> @var{n_m}
-}
-@end format
-
-where @var{n_q} is @var{n1}/@var{n2} rounded towards zero,
-0 < |@var{n_r}| < |@var{n2}|, 0 < |@var{n_m}| < |@var{n2}|,
-@var{n_r} and @var{n_m} differ from @var{n1} by a multiple of @var{n2},
-@var{n_r} has the same sign as @var{n1}, and
-@var{n_m} has the same sign as @var{n2}.
-
-From this we can conclude that for integers @var{n1} and @var{n2} with
-@var{n2} not equal to 0,
-
-@format
-@t{ (= @var{n1} (+ (* @var{n2} (quotient @var{n1} @var{n2}))
- (remainder @var{n1} @var{n2})))
- ==> #t
-}
-@end format
-
-provided all numbers involved in that computation are exact.
-
-
-@format
-@t{(modulo 13 4) ==> 1
-(remainder 13 4) ==> 1
-
-(modulo -13 4) ==> 3
-(remainder -13 4) ==> -1
-
-(modulo 13 -4) ==> -3
-(remainder 13 -4) ==> 1
-
-(modulo -13 -4) ==> -1
-(remainder -13 -4) ==> -1
-
-(remainder -13 -4.0) ==> -1.0 ; inexact
-}
-@end format
-
-@end deffn
-
-
-@deffn {library procedure} gcd n1 @dots{},
-@deffnx {library procedure} lcm n1 @dots{},
-
-These procedures return the greatest common divisor or least common
-multiple of their arguments. The result is always non-negative.
-@c - These procedures are exactness preserving.
-
-@c %R4%% I added the inexact example.
-
-@format
-@t{(gcd 32 -36) ==> 4
-(gcd) ==> 0
-(lcm 32 -36) ==> 288
-(lcm 32.0 -36) ==> 288.0 ; inexact
-(lcm) ==> 1
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {procedure} numerator @var{q}
-@deffnx {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 0 is defined to be 1.
-@c - The remarks about denominators are new.
-@c - Clearly, they are exactness-preserving procedures.
-
-@ignore todo
-More description and examples needed.
-@end ignore
-
-
-@format
-@t{(numerator (/ 6 4)) ==> 3
-(denominator (/ 6 4)) ==> 2
-(denominator
- (exact->inexact (/ 6 4))) ==> 2.0
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {procedure} floor x
-@deffnx {procedure} ceiling x
-@deffnx {procedure} truncate x
-@deffnx {procedure} round x
-
-
-These procedures return integers.
-@samp{Floor} returns the largest integer not larger than @var{x}.
-@samp{Ceiling} returns the smallest integer not smaller than @var{x}.
-@samp{Truncate} returns the integer closest to @var{x} whose absolute
-value is not larger than the absolute value of @var{x}. @samp{Round} returns the
-closest integer to @var{x}, rounding to even when @var{x} is halfway between two
-integers.
-
-
-@quotation
-@emph{Rationale:}
-@samp{Round} rounds to even for consistency with the default rounding
-mode specified by the IEEE floating point standard.
-@end quotation
-
-
-
-@quotation
-@emph{Note:}
-If the argument to one of these procedures is inexact, then the result
-will also be inexact. If an exact value is needed, the
-result should be passed to the @samp{inexact->exact} procedure.
-@end quotation
-
-
-
-@format
-@t{(floor -4.3) ==> -5.0
-(ceiling -4.3) ==> -4.0
-(truncate -4.3) ==> -4.0
-(round -4.3) ==> -4.0
-
-(floor 3.5) ==> 3.0
-(ceiling 3.5) ==> 4.0
-(truncate 3.5) ==> 3.0
-(round 3.5) ==> 4.0 ; inexact
-
-(round 7/2) ==> 4 ; exact
-(round 7) ==> 7
-}
-@end format
-
-
-@end deffn
-
-
-@deffn {library procedure} rationalize x y
-@c - \proto{rationalize}{ x}{procedure}
-
-
-@samp{Rationalize} returns the @emph{simplest} rational number
-differing from @var{x} by no more than @var{y}. A rational number r_1 is
-@emph{simpler} than another rational number
-@cindex @w{simplest rational}
-r_2 if r_1 = p_1/q_1 and r_2 = p_2/q_2 (in lowest terms) and |p_1|<= |p_2| and |q_1| <= |q_2|. Thus 3/5 is simpler than 4/7.
-Although not all rationals are comparable in this ordering (consider 2/7
-and 3/5) any interval contains a rational number that is simpler than
-every other rational number in that interval (the simpler 2/5 lies
-between 2/7 and 3/5). Note that 0 = 0/1 is the simplest rational of
-all.
-
-
-@format
-@t{(rationalize
- (inexact->exact .3) 1/10) ==> 1/3 ; exact
-(rationalize .3 1/10) ==> #i1/3 ; inexact
-}
-@end format
-
-
-@end deffn
-
-
-@deffn {procedure} exp @var{z}
-@deffnx {procedure} log @var{z}
-@deffnx {procedure} sin @var{z}
-@deffnx {procedure} cos @var{z}
-@deffnx {procedure} tan @var{z}
-@deffnx {procedure} asin @var{z}
-@deffnx {procedure} acos @var{z}
-@deffnx {procedure} atan @var{z}
-@deffnx {procedure} atan @var{y} @var{x}
-
-These procedures are part of every implementation that supports
-@c %R4%%
-general
-real numbers; they compute the usual transcendental functions. @samp{Log}
-computes the natural logarithm of @var{z} (not the base ten logarithm).
-@samp{Asin}, @samp{acos}, and @samp{atan} compute arcsine (sin^-1),
-arccosine (cos^-1), and arctangent (tan^-1), respectively.
-The two-argument variant of @samp{atan} computes @t{(angle
-(make-rectangular @var{x} @var{y}))} (see below), even in implementations
-that don't support general complex numbers.
-
-In general, the mathematical functions log, arcsine, arccosine, and
-arctangent are multiply defined.
-The value of log z is defined to be the one whose imaginary
-part lies in the range from -pi (exclusive) to pi (inclusive).
-log 0 is undefined.
-With log defined this way, the values of sin^-1 z, cos^-1 z,
-and tan^-1 z are according to the following formulae:
-
-
-@center sin^-1 z = -i log (i z + sqrt1 - z^2)
-
-
-
-@center cos^-1 z = pi / 2 - sin^-1 z
-
-
-
-@center tan^-1 z = (log (1 + i z) - log (1 - i z)) / (2 i)
-
-
-The above specification follows [CLtL], which in turn
-cites [Penfield81]; refer to these sources for more detailed
-discussion of branch cuts, boundary conditions, and implementation of
-these functions. When it is possible these procedures produce a real
-result from a real argument.
-
-@c %R4%%
-
-@ignore todo
-The cited references are likely to change their branch cuts
-soon to allow for the possibility of distinct positive and negative
-zeroes, as in IEEE floating point. We may not want to follow those
-changes, since we may want a complex number with zero imaginary part
-(whether positive or negative zero) to be treated as a real. I don't
-think there are any better standards for complex arithmetic than the
-ones cited, so we're really on our own here.
-@end ignore
-
-
-@end deffn
-
-
-
-@deffn {procedure} sqrt @var{z}
-
-Returns the principal square root of @var{z}. The result will have
-either positive real part, or zero real part and non-negative imaginary
-part.
-@end deffn
-
-
-
-@deffn {procedure} expt z1 z2
-
-Returns @var{z1} raised to the power @var{z2}. For z_1 ~= 0
-
-
-@center z_1^z_2 = e^z_2 log z_1
-
-0^z is 1 if z = 0 and 0 otherwise.
-@end deffn
-
-@c - \begin{entry}{%-
-@c - \proto{approximate}{ z x}{procedure}}
-@c -
-@c - Returns an approximation to \vr{z} in a representation whose precision is
-@c - the same as that
-@c - of the representation of \vr{x}, which must be an inexact number. The
-@c - result is always inexact.
-@c -
-@c - \begin{scheme}
-@c - (approximate 3.1415926535 1F10)
-@c - \ev 3.14159F0
-@c - (approximate 3.1415926535 \#I65535)
-@c - \ev \#I3
-@c - (approximate 3.14F0 1L8)
-@c - \ev 3.14L0
-@c - (approximate 3.1415926535F0 1L8)
-@c - \ev 3.14159L0
-@c - \end{scheme}
-@c - \end{entry}
-
-
-
-
-@deffn {procedure} make-rectangular x1 x2
-@deffnx {procedure} make-polar x3 x4
-@deffnx {procedure} real-part @var{z}
-@deffnx {procedure} imag-part @var{z}
-@deffnx {procedure} magnitude @var{z}
-@deffnx {procedure} angle @var{z}
-
-These procedures are part of every implementation that supports
-@c %R4%%
-general
-complex numbers. Suppose @var{x1}, @var{x2}, @var{x3}, and @var{x4} are
-real numbers and @var{z} is a complex number such that
-
-
-@center @var{z} = @var{x1} + @var{x2}@w{i} = @var{x3} . e^@w{i} @var{x4}
-
-Then
-
-@format
-@t{(make-rectangular @var{x1} @var{x2}) ==> @var{z}
-(make-polar @var{x3} @var{x4}) ==> @var{z}
-(real-part @var{z}) ==> @var{x1}
-(imag-part @var{z}) ==> @var{x2}
-(magnitude @var{z}) ==> |@var{x3}|
-(angle @var{z}) ==> x_angle
-}
-@end format
-
-where -pi < x_angle <= pi with x_angle = @var{x4} + 2pi n
-for some integer n.
-
-
-@quotation
-@emph{Rationale:}
-@samp{Magnitude} is the same as @code{abs} for a real argument,
-@vindex @w{abs}
-but @samp{abs} must be present in all implementations, whereas
-@samp{magnitude} need only be present in implementations that support
-general complex numbers.
-@end quotation
-
-
-@end deffn
-
-
-
-@deffn {procedure} exact->inexact @var{z}
-@deffnx {procedure} inexact->exact @var{z}
-
-@samp{Exact->inexact} returns an @r{inexact} representation of @var{z}.
-The value returned is the
-@r{inexact} number that is numerically closest to the argument.
-@c %R4%%For
-@c \tupe{exact} arguments which have no reasonably close \tupe{inexact} equivalent,
-@c it is permissible to signal an error.
-If an @r{exact} argument has no reasonably close @r{inexact} equivalent,
-then a violation of an implementation restriction may be reported.
-
-@samp{Inexact->exact} returns an @r{exact} representation of
-@var{z}. The value returned is the @r{exact} number that is numerically
-closest to the argument.
-@c %R4%% For \tupe{inexact} arguments which have no
-@c reasonably close \tupe{exact} equivalent, it is permissible to signal
-@c an error.
-If an @r{inexact} argument has no reasonably close @r{exact} equivalent,
-then a violation of an implementation restriction may be reported.
-
-@c %R%% I moved this to the section on implementation restrictions.
-@c For any implementation that supports \tupe{inexact} quantities,
-@c there is a subset of the integers for which there are both \tupe{exact} and
-@c \tupe{inexact} representations. This subset must include the non-negative
-@c integers up to a limit specified by the implementation. The limit
-@c must be big enough to represent all digits in reasonable radices, and
-@c may correspond to some natural word size for the implementation. For
-@c such integers, these procedures implement the natural one-to-one
-@c correspondence between the representations.
-
-These procedures implement the natural one-to-one correspondence between
-@r{exact} and @r{inexact} integers throughout an
-implementation-dependent range. See section @ref{Implementation restrictions}.
-
-@end deffn
-
-@sp 3
-
-@node Numerical input and output, , Numerical operations, Numbers
-@subsection Numerical input and output
-
-
-
-@deffn {procedure} number->string z
-@deffnx {procedure} number->string z radix
-
-@var{Radix} must be an exact integer, either 2, 8, 10, or 16. If omitted,
-@var{radix} defaults to 10.
-The procedure @samp{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
-
-@format
-@t{(let ((number @var{number})
- (radix @var{radix}))
- (eqv? number
- (string->number (number->string number
- radix)
- radix)))
-}
-@end format
-
-is true. It is an error if no possible result makes this expression true.
-
-If @var{z} is inexact, the 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
-true [howtoprint], [howtoread];
-otherwise the format of the result is unspecified.
-
-The result returned by @samp{number->string}
-never contains an explicit radix prefix.
-
-
-@quotation
-@emph{Note:}
-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.
-@end quotation
-
-
-
-@quotation
-@emph{Rationale:}
-If @var{z} is an inexact number represented using flonums, and
-the 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 non-flonum representations.
-@end quotation
-
-
-@end deffn
-
-
-
-@deffn {procedure} string->number string
-@deffnx {procedure} string->number string radix
-
-@c %R4%% I didn't include the (string->number string radix exactness)
-@c case, since I haven't heard any resolution of the coding to be used
-@c for the third argument.
-
-Returns a number of the maximally precise representation expressed by the
-given @var{string}. @var{Radix} must be an exact integer, either 2, 8, 10,
-or 16. If supplied, @var{radix} is a default radix that may be overridden
-by an explicit radix prefix in @var{string} (e.g. @t{"#o177"}). If @var{radix}
-is not supplied, then the default radix is 10. If @var{string} is not
-a syntactically valid notation for a number, then @samp{string->number}
-returns @t{#f}.
-
-
-@format
-@t{(string->number "100") ==> 100
-(string->number "100" 16) ==> 256
-(string->number "1e2") ==> 100.0
-(string->number "15##") ==> 1500.0
-}
-@end format
-
-
-
-@quotation
-@emph{Note:}
-The domain of @samp{string->number} may be restricted by implementations
-in the following ways. @samp{String->number} is permitted to return
-@t{#f} whenever @var{string} contains an explicit radix prefix.
-If all numbers supported by an implementation are real, then
-@samp{string->number} is permitted to return @t{#f} whenever
-@var{string} uses the polar or rectangular notations for complex
-numbers. If all numbers are integers, then
-@samp{string->number} may return @t{#f} whenever
-the fractional notation is used. If all numbers are exact, then
-@samp{string->number} may return @t{#f} whenever
-an exponent marker or explicit exactness prefix is used, or if
-a @t{#} appears in place of a digit. If all inexact
-numbers are integers, then
-@samp{string->number} may return @t{#f} whenever
-a decimal point is used.
-@end quotation
-
-
-@end deffn
-
-@node Other data types, Control features, Numbers, Standard procedures
-@section Other data types
-
-@menu
-* Booleans::
-* Pairs and lists::
-* Symbols::
-* Characters::
-* Strings::
-* Vectors::
-@end menu
-
-
-This section describes operations on some of Scheme's non-numeric data types:
-booleans, pairs, lists, symbols, characters, strings and vectors.
-
-@node Booleans, Pairs and lists, Other data types, Other data types
-@subsection Booleans
-
-
-
-The standard boolean objects for true and false are written as
-@t{#t} and @t{#f}. What really
-@vindex #f
-@vindex #t
-matters, though, are the objects that the Scheme conditional expressions
-(@samp{if}, @samp{cond}, @samp{and}, @samp{or}, @samp{do}) treat as
-true or false. The phrase ``a true value''
-@cindex @w{false}
-@cindex @w{true}
-(or sometimes just ``true'') means any object treated as true by the
-conditional expressions, and the phrase ``a false value'' (or
-@cindex @w{false}
-``false'') means any object treated as false by the conditional expressions.
-
-Of all the standard Scheme values, only @t{#f}
-@c is guaranteed to count
-counts as false in conditional expressions.
-@c It is not
-@c specified whether the empty list\index{empty list} counts as false
-@c or as true in conditional expressions.
-Except for @t{#f},
-@c and possibly the empty list,
-all standard Scheme values, including @t{#t},
-pairs, the empty list, symbols, numbers, strings, vectors, and procedures,
-count as true.
-
-@c \begin{note}
-@c In some implementations the empty list counts as false, contrary
-@c to the above.
-@c Nonetheless a few examples in this report assume that the
-@c empty list counts as true, as in \cite{IEEEScheme}.
-@c \end{note}
-
-@c \begin{rationale}
-@c For historical reasons some implementations regard \schfalse{} and the
-@c empty list as the same object. These implementations therefore cannot
-@c make the empty list count as true in conditional expressions.
-@c \end{rationale}
-
-
-@quotation
-@emph{Note:}
-Programmers accustomed to other dialects of Lisp should be aware that
-Scheme distinguishes both @t{#f} and the empty list
-@cindex @w{empty list}
-from the symbol @code{nil}.
-@vindex @w{nil}
-@end quotation
-
-
-Boolean constants evaluate to themselves, so they do not need to be quoted
-in programs.
-
-
-@example
-
-#t ==> #t
-#f ==> #f
-'#f ==> #f
-
-@end example
-
-
-
-
-@deffn {library procedure} not obj
-
-@samp{Not} returns @t{#t} if @var{obj} is false, and returns
-@t{#f} otherwise.
-
-
-@format
-@t{(not #t) ==> #f
-(not 3) ==> #f
-(not (list 3)) ==> #f
-(not #f) ==> #t
-(not '()) ==> #f
-(not (list)) ==> #f
-(not 'nil) ==> #f
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {library procedure} boolean? obj
-
-@samp{Boolean?} returns @t{#t} if @var{obj} is either @t{#t} or
-@t{#f} and returns @t{#f} otherwise.
-
-
-@format
-@t{(boolean? #f) ==> #t
-(boolean? 0) ==> #f
-(boolean? '()) ==> #f
-}
-@end format
-
-
-@end deffn
-
-
-@node Pairs and lists, Symbols, Booleans, Other data types
-@subsection Pairs and lists
-
-
-
-A @dfn{pair} (sometimes called a @dfn{dotted pair}) is a
-@cindex @w{dotted pair}
-@cindex @w{pair}
-record structure with two fields called the car and cdr fields (for
-historical reasons). Pairs are created by the procedure @samp{cons}.
-The car and cdr fields are accessed by the procedures @samp{car} and
-@samp{cdr}. The car and cdr fields are assigned by the procedures
-@samp{set-car!} and @samp{set-cdr!}.
-
-Pairs are used primarily to represent lists. A list can
-be defined recursively as either the empty list or a pair whose
-@cindex @w{empty list}
-cdr is a list. More precisely, the set of lists is defined as the smallest
-set @var{X} such that
-
-
-
-@itemize @bullet
-
-@item
-The empty list is in @var{X}.
-@item
-If @var{list} is in @var{X}, then any pair whose cdr field contains
-@var{list} is also in @var{X}.
-
-@end 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
-@cindex @w{empty list}
-(it is not a pair); it has no elements and its length is zero.
-
-
-@quotation
-@emph{Note:}
-The above definitions imply that all lists have finite length and are
-terminated by the empty list.
-@end quotation
-
-
-The most general notation (external representation) for Scheme pairs is
-the ``dotted'' notation @w{@samp{(@var{c1} .@: @var{c2})}} where
-@var{c1} is the value of the car field and @var{c2} is the value of the
-cdr field. For example @samp{(4 .@: 5)} is a pair whose car is 4 and whose
-cdr is 5. Note that @samp{(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 @t{()} . For example,
-@cindex @w{empty list}
-
-
-@example
-
-(a b c d e)
-
-@end example
-
-
-and
-
-
-@example
-
-(a . (b . (c . (d . (e . ())))))
-
-@end example
-
-
-are equivalent notations for a list of symbols.
-
-A chain of pairs not ending in the empty list is called an
-@dfn{improper list}. Note that an improper list is not a list.
-@cindex @w{improper list}
-The list and dotted notations can be combined to represent
-improper lists:
-
-
-@example
-
-(a b c . d)
-
-@end example
-
-
-is equivalent to
-
-
-@example
-
-(a . (b . (c . d)))
-
-@end example
-
-
-Whether a given pair is a list depends upon what is stored in the cdr
-field. When the @code{set-cdr!} procedure is used, an object can be a
-@vindex @w{set-cdr!}
-list one moment and not the next:
-
-
-@example
-
-(define x (list 'a 'b 'c))
-(define y x)
-y ==> (a b c)
-(list? y) ==> #t
-(set-cdr! x 4) ==> @emph{unspecified}
-x ==> (a . 4)
-(eqv? x y) ==> #t
-y ==> (a . 4)
-(list? y) ==> #f
-(set-cdr! x x) ==> @emph{unspecified}
-(list? x) ==> #f
-
-@end example
-
-
-@c It is often convenient to speak of a homogeneous list of objects
-@c of some particular data type, as for example \hbox{\cf (1 2 3)} is a list of
-@c integers. To be more precise, suppose \var{D} is some data type. (Any
-@c predicate defines a data type consisting of those objects of which the
-@c predicate is true.) Then
-
-@c \begin{itemize}
-@c \item The empty list is a list of \var{D}.
-@c \item If \var{list} is a list of \var{D}, then any pair whose cdr is
-@c \var{list} and whose car is an element of the data type \var{D} is also a
-@c list of \var{D}.
-@c \item There are no other lists of \var{D}.
-@c \end{itemize}
-
-Within literal expressions and representations of objects read by the
-@code{read} procedure, the forms @t{'}@r{<datum>},
-@vindex '
-@vindex @w{read}
-@t{`}@r{<datum>}, @t{,}@r{<datum>}, and
-@vindex ,
-@t{,@@}@r{<datum>} denote two-ele@-ment lists whose first elements are
-the symbols @code{quote}, @code{quasiquote}, @w{@code{unquote}}, and
-@vindex @w{unquote}
-@vindex @w{quasiquote}
-@vindex @w{quote}
-@code{unquote-splicing}, respectively. The second element in each case
-@vindex @w{unquote-splicing}
-is @r{<datum>}. This convention is supported so that arbitrary Scheme
-programs may be represented as lists.
-@ignore todo
-Can or need this be stated
-more carefully?
-@end ignore
- That is, according to Scheme's grammar, every
-<expression> is also a <datum> (see section @pxref{External representation}).
-Among other things, this permits the use of the @samp{read} procedure to
-parse Scheme programs. See section @ref{External representations}.
-
-
-
-@deffn {procedure} pair? obj
-
-@samp{Pair?} returns @t{#t} if @var{obj} is a pair, and otherwise
-returns @t{#f}.
-
-
-@format
-@t{(pair? '(a . b)) ==> #t
-(pair? '(a b c)) ==> #t
-(pair? '()) ==> #f
-(pair? '#(a b)) ==> #f
-}
-@end format
-
-@end deffn
-
-
-
-@deffn {procedure} cons obj1 obj2
-
-Returns a newly allocated pair whose car is @var{obj1} and whose cdr is
-@var{obj2}. The pair is guaranteed to be different (in the sense of
-@samp{eqv?}) from every existing object.
-
-
-@format
-@t{(cons 'a '()) ==> (a)
-(cons '(a) '(b c d)) ==> ((a) b c d)
-(cons "a" '(b c)) ==> ("a" b c)
-(cons 'a 3) ==> (a . 3)
-(cons '(a b) 'c) ==> ((a b) . c)
-}
-@end format
-
-@end deffn
-
-
-
-@deffn {procedure} car pair
-
-@ignore nodomain
-@var{Pair} must be a pair.
-@end ignore
-
-Returns the contents of the car field of @var{pair}. Note that it is an
-error to take the car of the empty list.
-@cindex @w{empty list}
-
-
-@format
-@t{(car '(a b c)) ==> a
-(car '((a) b c d)) ==> (a)
-(car '(1 . 2)) ==> 1
-(car '()) ==> @emph{error}
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {procedure} cdr pair
-
-@ignore nodomain
-@var{Pair} must be a pair.
-@end ignore
-
-Returns the contents of the cdr field of @var{pair}.
-Note that it is an error to take the cdr of the empty list.
-
-
-@format
-@t{(cdr '((a) b c d)) ==> (b c d)
-(cdr '(1 . 2)) ==> 2
-(cdr '()) ==> @emph{error}
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {procedure} set-car! pair obj
-
-@ignore nodomain
-@var{Pair} must be a pair.
-@end ignore
-
-Stores @var{obj} in the car field of @var{pair}.
-The value returned by @samp{set-car!} is unspecified.
-@c <!>
-@c This procedure can be very confusing if used indiscriminately.
-
-
-@format
-@t{(define (f) (list 'not-a-constant-list))
-(define (g) '(constant-list))
-(set-car! (f) 3) ==> @emph{unspecified}
-(set-car! (g) 3) ==> @emph{error}
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {procedure} set-cdr! pair obj
-
-@ignore nodomain
-@var{Pair} must be a pair.
-@end ignore
-
-Stores @var{obj} in the cdr field of @var{pair}.
-The value returned by @samp{set-cdr!} is unspecified.
-@c <!>
-@c This procedure can be very confusing if used indiscriminately.
-
-@end deffn
-
-
-
-
-
-
-@deffn {library procedure} caar pair
-@deffnx {library procedure} cadr pair
-
-@deffnx { @w{ @dots{}}} @w{ @dots{}}
-
-@deffnx {library procedure} cdddar pair
-@deffnx {library procedure} cddddr pair
-
-These procedures are compositions of @samp{car} and @samp{cdr}, where
-for example @samp{caddr} could be defined by
-
-
-@format
-@t{(define caddr (lambda (x) (car (cdr (cdr x)))))@r{.}
-}
-@end format
-
-
-Arbitrary compositions, up to four deep, are provided. There are
-twenty-eight of these procedures in all.
-
-@end deffn
-
-
-
-@deffn {library procedure} null? obj
-
-Returns @t{#t} if @var{obj} is the empty list,
-@cindex @w{empty list}
-otherwise returns @t{#f}.
-
-@c \begin{note}
-@c In implementations in which the empty
-@c list is the same as \schfalse{}, {\cf null?} will return \schtrue{}
-@c if \var{obj} is \schfalse{}.
-@c \end{note}
-
-@end deffn
-
-
-@deffn {library procedure} list? obj
-
-Returns @t{#t} if @var{obj} is a list, otherwise returns @t{#f}.
-By definition, all lists have finite length and are terminated by
-the empty list.
-
-
-@format
-@t{ (list? '(a b c)) ==> #t
- (list? '()) ==> #t
- (list? '(a . b)) ==> #f
- (let ((x (list 'a)))
- (set-cdr! x x)
- (list? x)) ==> #f
-}
-@end format
-
-@end deffn
-
-
-
-@deffn {library procedure} list @var{obj} @dots{},
-
-Returns a newly allocated list of its arguments.
-
-
-@format
-@t{(list 'a (+ 3 4) 'c) ==> (a 7 c)
-(list) ==> ()
-}
-@end format
-
-@end deffn
-
-
-
-@deffn {library procedure} length list
-
-@ignore nodomain
-@var{List} must be a list.
-@end ignore
-
-Returns the length of @var{list}.
-
-
-@format
-@t{(length '(a b c)) ==> 3
-(length '(a (b) (c d e))) ==> 3
-(length '()) ==> 0
-}
-@end format
-
-@end deffn
-
-
-
-@deffn {library procedure} append list @dots{},
-
-@ignore nodomain
-All @var{list}s should be lists.
-@end ignore
-
-Returns a list consisting of the elements of the first @var{list}
-followed by the elements of the other @var{list}s.
-
-
-@format
-@t{(append '(x) '(y)) ==> (x y)
-(append '(a) '(b c d)) ==> (a b c d)
-(append '(a (b)) '((c))) ==> (a (b) (c))
-}
-@end format
-
-
-The resulting list is always newly allocated, except that it shares
-structure with the last @var{list} argument. The last argument may
-actually be any object; an improper list results if the last argument is not a
-proper list.
-@ignore todo
-This is pretty awkward. I should get Bartley to fix this.
-@end ignore
-
-
-
-@format
-@t{(append '(a b) '(c . d)) ==> (a b c . d)
-(append '() 'a) ==> a
-}
-@end format
-
-@end deffn
-
-
-
-@deffn {library procedure} reverse list
-
-@ignore nodomain
-@var{List} must be a list.
-@end ignore
-
-Returns a newly allocated list consisting of the elements of @var{list}
-in reverse order.
-
-
-@format
-@t{(reverse '(a b c)) ==> (c b a)
-(reverse '(a (b c) d (e (f))))
- ==> ((e (f)) d (b c) a)
-}
-@end format
-
-@end deffn
-
-
-
-@deffn {library procedure} list-tail list @var{k}
-
-Returns the sublist of @var{list} obtained by omitting the first @var{k}
-elements. It is an error if @var{list} has fewer than @var{k} elements.
-@samp{List-tail} could be defined by
-
-
-@format
-@t{(define list-tail
- (lambda (x k)
- (if (zero? k)
- x
- (list-tail (cdr x) (- k 1)))))
-}
-@end format
-
-@end deffn
-
-
-
-@deffn {library procedure} list-ref list @var{k}
-
-Returns the @var{k}th element of @var{list}. (This is the same
-as the car of @t{(list-tail @var{list} @var{k})}.)
-It is an error if @var{list} has fewer than @var{k} elements.
-
-
-@format
-@t{(list-ref '(a b c d) 2) ==> c
-(list-ref '(a b c d)
- (inexact->exact (round 1.8)))
- ==> c
-}
-@end format
-
-@end deffn
-
-
-@c \begin{entry}{%
-@c \proto{last-pair}{ list}{library procedure}}
-
-@c Returns the last pair in the nonempty, possibly improper, list \var{list}.
-@c {\cf Last-pair} could be defined by
-
-@c \begin{scheme}
-@c (define last-pair
-@c (lambda (x)
-@c (if (pair? (cdr x))
-@c (last-pair (cdr x))
-@c x)))%
-@c \end{scheme}
-
-@c \end{entry}
-
-
-
-@deffn {library procedure} memq obj list
-@deffnx {library procedure} memv obj list
-@deffnx {library procedure} member obj list
-
-These procedures return the first sublist of @var{list} whose car is
-@var{obj}, where the sublists of @var{list} are the non-empty lists
-returned by @t{(list-tail @var{list} @var{k})} for @var{k} less
-than the length of @var{list}. If
-@var{obj} does not occur in @var{list}, then @t{#f} (not the empty list) is
-returned. @samp{Memq} uses @samp{eq?} to compare @var{obj} with the elements of
-@var{list}, while @samp{memv} uses @samp{eqv?} and @samp{member} uses @samp{equal?}.
-
-
-@format
-@t{(memq 'a '(a b c)) ==> (a b c)
-(memq 'b '(a b c)) ==> (b c)
-(memq 'a '(b c d)) ==> #f
-(memq (list 'a) '(b (a) c)) ==> #f
-(member (list 'a)
- '(b (a) c)) ==> ((a) c)
-(memq 101 '(100 101 102)) ==> @emph{unspecified}
-(memv 101 '(100 101 102)) ==> (101 102)
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {library procedure} assq obj alist
-@deffnx {library procedure} assv obj alist
-@deffnx {library procedure} assoc obj alist
-
-@var{Alist} (for ``association list'') must be a list of
-pairs. These procedures find the first pair in @var{alist} whose car field is @var{obj},
-and returns that pair. If no pair in @var{alist} has @var{obj} as its
-car, then @t{#f} (not the empty list) is returned. @samp{Assq} uses
-@samp{eq?} to compare @var{obj} with the car fields of the pairs in @var{alist},
-while @samp{assv} uses @samp{eqv?} and @samp{assoc} uses @samp{equal?}.
-
-
-@format
-@t{(define e '((a 1) (b 2) (c 3)))
-(assq 'a e) ==> (a 1)
-(assq 'b e) ==> (b 2)
-(assq 'd e) ==> #f
-(assq (list 'a) '(((a)) ((b)) ((c))))
- ==> #f
-(assoc (list 'a) '(((a)) ((b)) ((c))))
- ==> ((a))
-(assq 5 '((2 3) (5 7) (11 13)))
- ==> @emph{unspecified}
-(assv 5 '((2 3) (5 7) (11 13)))
- ==> (5 7)
-}
-@end format
-
-
-
-
-@quotation
-@emph{Rationale:}
-Although they are ordinarily used as predicates,
-@samp{memq}, @samp{memv}, @samp{member}, @samp{assq}, @samp{assv}, and @samp{assoc} do not
-have question marks in their names because they return useful values rather
-than just @t{#t} or @t{#f}.
-@end quotation
-
-@end deffn
-
-
-@node Symbols, Characters, Pairs and lists, Other data types
-@subsection Symbols
-
-
-
-Symbols are objects whose usefulness rests on the fact that two
-symbols are identical (in the sense of @samp{eqv?}) if and only if their
-names are spelled the same way. This is exactly the property needed to
-represent identifiers in programs, and so most
-@cindex @w{identifier}
-implementations of Scheme use them internally for that purpose. Symbols
-are useful for many other applications; for instance, they may be used
-the way enumerated values are used in Pascal.
-
-The rules for writing a symbol are exactly the same as the rules for
-writing an identifier; see sections @ref{Identifiers}
-and @ref{Lexical structure}.
-
-It is guaranteed that any symbol that has been returned as part of
-a literal expression, or read using the @samp{read} procedure, and
-subsequently written out using the @samp{write} procedure, will read back
-in as the identical symbol (in the sense of @samp{eqv?}). The
-@samp{string->symbol} procedure, however, can create symbols for
-which this write/read invariance may not hold because their names
-contain special characters or letters in the non-standard case.
-
-
-@quotation
-@emph{Note:}
-Some implementations of Scheme have a feature known as ``slashification''
-in order to guarantee write/read invariance for all symbols, but
-historically the most important use of this feature has been to
-compensate for the lack of a string data type.
-
-Some implementations also have ``uninterned symbols'', which
-defeat write/read invariance even in implementations with slashification,
-and also generate exceptions to the rule that two symbols are the same
-if and only if their names are spelled the same.
-@end quotation
-
-
-
-
-@deffn {procedure} symbol? obj
-
-Returns @t{#t} if @var{obj} is a symbol, otherwise returns @t{#f}.
-
-
-@format
-@t{(symbol? 'foo) ==> #t
-(symbol? (car '(a b))) ==> #t
-(symbol? "bar") ==> #f
-(symbol? 'nil) ==> #t
-(symbol? '()) ==> #f
-(symbol? #f) ==> #f
-}
-@end format
-
-@end deffn
-
-
-
-@deffn {procedure} symbol->string symbol
-
-Returns the name of @var{symbol} as a string. If the symbol was part of
-an object returned as the value of a literal expression
-(section @pxref{Literal expressions}) or by a call to the @samp{read} procedure,
-and its name contains alphabetic characters, then the string returned
-will contain characters in the implementation's preferred standard
-case---some implementations will prefer upper case, others lower case.
-If the symbol was returned by @samp{string->symbol}, the case of
-characters in the string returned will be the same as the case in the
-string that was passed to @samp{string->symbol}. It is an error
-to apply mutation procedures like @code{string-set!} to strings returned
-@vindex @w{string-set!}
-by this procedure.
-
-The following examples assume that the implementation's standard case is
-lower case:
-
-
-@format
-@t{(symbol->string 'flying-fish)
- ==> "flying-fish"
-(symbol->string 'Martin) ==> "martin"
-(symbol->string
- (string->symbol "Malvina"))
- ==> "Malvina"
-}
-@end format
-
-@end deffn
-
-
-
-@deffn {procedure} string->symbol string
-
-Returns the symbol whose name is @var{string}. This procedure can
-create symbols with names containing special characters or letters in
-the non-standard case, but it is usually a bad idea to create such
-symbols because in some implementations of Scheme they cannot be read as
-themselves. See @samp{symbol->string}.
-
-The following examples assume that the implementation's standard case is
-lower case:
-
-
-@format
-@t{(eq? 'mISSISSIppi 'mississippi)
- ==> #t
-(string->symbol "mISSISSIppi")
- ==>
- @r{}the symbol with name "mISSISSIppi"
-(eq? 'bitBlt (string->symbol "bitBlt"))
- ==> #f
-(eq? 'JollyWog
- (string->symbol
- (symbol->string 'JollyWog)))
- ==> #t
-(string=? "K. Harper, M.D."
- (symbol->string
- (string->symbol "K. Harper, M.D.")))
- ==> #t
-}
-@end format
-
-
-@end deffn
-
-
-@node Characters, Strings, Symbols, Other data types
-@subsection Characters
-
-
-
-Characters are objects that represent printed characters such as
-letters and digits.
-@c There is no requirement that the data type of
-@c characters be disjoint from other data types; implementations are
-@c encouraged to have a separate character data type, but may choose to
-@c represent characters as integers, strings, or some other type.
-Characters are written using the notation #\@r{<character>}
-or #\@r{<character name>}.
-For example:
-
-
-
-@center @c begin-tabular
-@quotation
-@table @asis
-@item @t{#\a}
-; lower case letter
-@item @t{#\A}
-; upper case letter
-@item @t{#\(}
-; left parenthesis
-@item @t{#\ }
-; the space character
-@item @t{#\space}
-; the preferred way to write a space
-@item @t{#\newline}
-; the newline character
-@item
-@end table
-@end quotation
-
-
-
-
-Case is significant in #\@r{<character>}, but not in
-#\@r{<character name>}.
-@c \hyper doesn't
-
-@c allow a linebreak
-If @r{<character>} in
-#\@r{<character>} is alphabetic, then the character
-following @r{<character>} must be a delimiter character such as a
-space or parenthesis. This rule resolves the ambiguous case where, for
-example, the sequence of characters ``@t{#\ space}''
-could be taken to be either a representation of the space character or a
-representation of the character ``@t{#\ s}'' followed
-by a representation of the symbol ``@t{pace}.''
-
-@ignore todo
-Fix
-@end ignore
-
-Characters written in the #\ notation are self-evaluating.
-That is, they do not have to be quoted in programs.
-@c The \sharpsign\backwhack{}
-@c notation is not an essential part of Scheme, however. Even implementations
-@c that support the \sharpsign\backwhack{} notation for input do not have to
-@c support it for output.
-
-Some of the procedures that operate on characters ignore the
-difference between upper case and lower case. The procedures that
-ignore case have @w{``@t{-ci}''} (for ``case
-insensitive'') embedded in their names.
-
-
-
-@deffn {procedure} char? obj
-
-Returns @t{#t} if @var{obj} is a character, otherwise returns @t{#f}.
-
-@end deffn
-
-
-
-@deffn {procedure} char=? char1 char2
-@deffnx {procedure} char<? char1 char2
-@deffnx {procedure} char>? char1 char2
-@deffnx {procedure} char<=? char1 char2
-@deffnx {procedure} char>=? char1 char2
-
-
-@ignore nodomain
-Both @var{char1} and @var{char2} must be characters.
-@end ignore
-
-These procedures impose a total ordering on the set of characters. It
-is guaranteed that under this ordering:
-
-
-
-@itemize @bullet
-
-@item
-The upper case characters are in order. For example, @samp{(char<? #\A #\B)} returns @t{#t}.
-@item
-The lower case characters are in order. For example, @samp{(char<? #\a #\b)} returns @t{#t}.
-@item
-The digits are in order. For example, @samp{(char<? #\0 #\9)} returns @t{#t}.
-@item
-Either all the digits precede all the upper case letters, or vice versa.
-@item
-Either all the digits precede all the lower case letters, or vice versa.
-
-@end itemize
-
-
-Some implementations may generalize these procedures to take more than
-two arguments, as with the corresponding numerical predicates.
-
-@end deffn
-
-
-
-@deffn {library procedure} char-ci=? char1 char2
-@deffnx {library procedure} char-ci<? char1 char2
-@deffnx {library procedure} char-ci>? char1 char2
-@deffnx {library procedure} char-ci<=? char1 char2
-@deffnx {library procedure} char-ci>=? char1 char2
-
-@ignore nodomain
-Both @var{char1} and @var{char2} must be characters.
-@end ignore
-
-These procedures are similar to @samp{char=?} et cetera, but they treat
-upper case and lower case letters as the same. For example, @samp{(char-ci=? #\A #\a)} returns @t{#t}. Some
-implementations may generalize these procedures to take more than two
-arguments, as with the corresponding numerical predicates.
-
-@end deffn
-
-
-
-@deffn {library procedure} char-alphabetic? char
-@deffnx {library procedure} char-numeric? char
-@deffnx {library procedure} char-whitespace? char
-@deffnx {library procedure} char-upper-case? letter
-@deffnx {library procedure} char-lower-case? letter
-
-These procedures return @t{#t} if their arguments are alphabetic,
-numeric, whitespace, upper case, or lower case characters, respectively,
-otherwise they return @t{#f}. The following remarks, which are specific to
-the ASCII character set, are intended only as a guide: The alphabetic characters
-are the 52 upper and lower case letters. The numeric characters are the
-ten decimal digits. The whitespace characters are space, tab, line
-feed, form feed, and carriage return.
-@end deffn
-
-
-@c %R4%%\begin{entry}{%
-@c \proto{char-upper-case?}{ letter}{procedure}
-@c \proto{char-lower-case?}{ letter}{procedure}}
-
-@c \domain{\var{Letter} must be an alphabetic character.}
-@c These procedures return \schtrue{} if their arguments are upper case or
-@c lower case characters, respectively, otherwise they return \schfalse.
-@c \end{entry}
-
-
-
-@deffn {procedure} char->integer char
-@deffnx {procedure} integer->char @var{n}
-
-Given a character, @samp{char->integer} returns an exact integer
-representation of the character. Given an exact integer that is the image of
-a character under @samp{char->integer}, @samp{integer->char}
-returns that character. These procedures implement order-preserving isomorphisms
-between the set of characters under the @code{char<=?} ordering and some
-@vindex @w{char<=?}
-subset of the integers under the @samp{<=} ordering. That is, if
-
-
-@format
-@t{(char<=? @var{a} @var{b}) @result{} #t @r{}and (<= @var{x} @var{y}) @result{} #t
-}
-@end format
-
-
-
-@noindent
- and @var{x} and @var{y} are in the domain of
-@samp{integer->char}, then
-
-
-@format
-@t{(<= (char->integer @var{a})
- (char->integer @var{b})) ==> #t
-
-(char<=? (integer->char @var{x})
- (integer->char @var{y})) ==> #t
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {library procedure} char-upcase char
-@deffnx {library procedure} char-downcase char
-
-@ignore nodomain
-@var{Char} must be a character.
-@end ignore
-
-These procedures return a character @var{char2} such that @samp{(char-ci=? @var{char} @var{char2})}. In addition, if @var{char} is
-alphabetic, then the result of @samp{char-upcase} is upper case and the
-result of @samp{char-downcase} is lower case.
-
-@end deffn
-
-
-@node Strings, Vectors, Characters, Other data types
-@subsection Strings
-
-
-
-Strings are sequences of characters.
-@c In some implementations of Scheme
-@c they are immutable; other implementations provide destructive procedures
-@c such as {\cf string-set!}\ that alter string objects.
-Strings are written as sequences of characters enclosed within doublequotes
-(@samp{"}). A doublequote can be written inside a string only by escaping
-it with a backslash (\), as in
-
-
-@example
-
-"The word \"recursion\" has many meanings."
-
-@end example
-
-
-A backslash can be written inside a string only by escaping it with another
-backslash. Scheme does not specify the effect of a backslash within a
-string that is not followed by a doublequote or backslash.
-
-A string constant may continue from one line to the next, but
-the exact contents of such a string are unspecified.
-@c this is
-@c usually a bad idea because
-@c the exact effect may vary from one computer
-@c system to another.
-
-The @emph{length} of a string is the number of characters that it
-contains. This number is an exact, non-negative integer that is fixed when the
-string is created. The @dfn{valid indexes} of a string are the
-@cindex @w{valid indexes}
-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.
-
-In phrases such as ``the characters of @var{string} beginning with
-index @var{start} and ending with index @var{end},'' it is understood
-that the index @var{start} is inclusive and the index @var{end} is
-exclusive. Thus if @var{start} and @var{end} are the same index, a null
-substring is referred to, and if @var{start} is zero and @var{end} is
-the length of @var{string}, then the entire string is referred to.
-
-Some of the procedures that operate on strings ignore the
-difference between upper and lower case. The versions that ignore case
-have @w{``@samp{-ci}''} (for ``case insensitive'') embedded in their
-names.
-
-
-
-@deffn {procedure} string? obj
-
-Returns @t{#t} if @var{obj} is a string, otherwise returns @t{#f}.
-@end deffn
-
-
-
-@deffn {procedure} make-string @var{k}
-@deffnx {procedure} make-string @var{k} char
-
-@c \domain{\vr{k} must be a non-negative integer, and \var{char} must be
-@c a character.}
-@samp{Make-string} returns a newly allocated string of
-length @var{k}. 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.
-
-@end deffn
-
-
-@deffn {library procedure} string char @dots{},
-
-Returns a newly allocated string composed of the arguments.
-
-@end deffn
-
-
-@deffn {procedure} string-length string
-
-Returns the number of characters in the given @var{string}.
-@end deffn
-
-
-
-@deffn {procedure} string-ref string @var{k}
-
-@var{k} must be a valid index of @var{string}.
-@samp{String-ref} returns character @var{k} of @var{string} using zero-origin indexing.
-@end deffn
-
-
-
-@deffn {procedure} string-set! string k char
-
-
-@c \var{String} must be a string,
-@var{k} must be a valid index of @var{string}
-@c , and \var{char} must be a character
-.
-@samp{String-set!} stores @var{char} in element @var{k} of @var{string}
-and returns an unspecified value.
-@c <!>
-
-
-@format
-@t{(define (f) (make-string 3 #\*))
-(define (g) "***")
-(string-set! (f) 0 #\?) ==> @emph{unspecified}
-(string-set! (g) 0 #\?) ==> @emph{error}
-(string-set! (symbol->string 'immutable)
- 0
- #\?) ==> @emph{error}
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {library procedure} string=? string1 string2
-@deffnx {library procedure} string-ci=? string1 string2
-
-Returns @t{#t} if the two strings are the same length and contain the same
-characters in the same positions, otherwise returns @t{#f}.
-@samp{String-ci=?} treats
-upper and lower case letters as though they were the same character, but
-@samp{string=?} treats upper and lower case as distinct characters.
-
-@end deffn
-
-
-
-@deffn {library procedure} string<? string1 string2
-@deffnx {library procedure} string>? string1 string2
-@deffnx {library procedure} string<=? string1 string2
-@deffnx {library procedure} string>=? string1 string2
-@deffnx {library procedure} string-ci<? string1 string2
-@deffnx {library procedure} string-ci>? string1 string2
-@deffnx {library procedure} string-ci<=? string1 string2
-@deffnx {library procedure} string-ci>=? string1 string2
-
-These procedures are the lexicographic extensions to strings of the
-corresponding orderings on characters. For example, @samp{string<?} is
-the lexicographic ordering on strings induced by the ordering
-@samp{char<?} 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.
-
-Implementations may generalize these and the @samp{string=?} and
-@samp{string-ci=?} procedures to take more than two arguments, as with
-the corresponding numerical predicates.
-
-@end deffn
-
-
-
-@deffn {library procedure} substring string start end
-
-@var{String} must be a string, and @var{start} and @var{end}
-must be exact integers satisfying
-
-
-@center 0 <= @var{start} <= @var{end} <= @w{@t{(string-length @var{string})@r{.}}}
-
-@samp{Substring} 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).
-@end deffn
-
-
-
-@deffn {library procedure} string-append @var{string} @dots{},
-
-Returns a newly allocated string whose characters form the concatenation of the
-given strings.
-
-@end deffn
-
-
-
-@deffn {library procedure} string->list string
-@deffnx {library procedure} list->string list
-
-@samp{String->list} returns a newly allocated list of the
-characters that make up the given string. @samp{List->string}
-returns a newly allocated string formed from the characters in the list
-@var{list}, which must be a list of characters. @samp{String->list}
-and @samp{list->string} are
-inverses so far as @samp{equal?} is concerned.
-@c Implementations that provide
-@c destructive operations on strings should ensure that the result of
-@c {\cf list\coerce{}string} is newly allocated.
-
-@end deffn
-
-
-
-@deffn {library procedure} string-copy string
-
-Returns a newly allocated copy of the given @var{string}.
-
-@end deffn
-
-
-
-@deffn {library procedure} string-fill! string char
-
-Stores @var{char} in every element of the given @var{string} and returns an
-unspecified value.
-@c <!>
-
-@end deffn
-
-
-@node Vectors, , Strings, Other data types
-@subsection Vectors
-
-
-
-Vectors are heterogenous structures whose elements are indexed
-by integers. A vector typically occupies less space than a list
-of the same length, and the average time required 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 indexes} of a
-@cindex @w{valid indexes}
-vector are the exact non-negative integers 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 @t{#(@var{obj} @dots{},)}.
-For example, a vector of length 3 containing the number zero in element
-0, the list @samp{(2 2 2 2)} in element 1, and the string @samp{"Anna"} in
-element 2 can be written as following:
-
-
-@example
-
-#(0 (2 2 2 2) "Anna")
-
-@end example
-
-
-Note that this is the external representation of a vector, not an
-expression evaluating to a vector. Like list constants, vector
-constants must be quoted:
-
-
-@example
-
-'#(0 (2 2 2 2) "Anna")
- ==> #(0 (2 2 2 2) "Anna")
-
-@end example
-
-
-@ignore todo
-Pitman sez: The visual similarity to lists is bound to be confusing
-to some. Elaborate on the distinction.
-@end ignore
-
-
-
-
-@deffn {procedure} vector? obj
-
-Returns @t{#t} if @var{obj} is a vector, otherwise returns @t{#f}.
-@end deffn
-
-
-
-@deffn {procedure} make-vector k
-@deffnx {procedure} make-vector k fill
-
-Returns 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 unspecified.
-
-@end deffn
-
-
-
-@deffn {library procedure} vector obj @dots{},
-
-Returns a newly allocated vector whose elements contain the given
-arguments. Analogous to @samp{list}.
-
-
-@format
-@t{(vector 'a 'b 'c) ==> #(a b c)
-}
-@end format
-
-@end deffn
-
-
-
-@deffn {procedure} vector-length vector
-
-Returns the number of elements in @var{vector} as an exact integer.
-@end deffn
-
-
-
-@deffn {procedure} vector-ref vector k
-
-@var{k} must be a valid index of @var{vector}.
-@samp{Vector-ref} returns the contents of element @var{k} of
-@var{vector}.
-
-
-@format
-@t{(vector-ref '#(1 1 2 3 5 8 13 21)
- 5)
- ==> 8
-(vector-ref '#(1 1 2 3 5 8 13 21)
- (let ((i (round (* 2 (acos -1)))))
- (if (inexact? i)
- (inexact->exact i)
- i)))
- ==> 13
-}
-@end format
-
-@end deffn
-
-
-
-@deffn {procedure} vector-set! vector k obj
-
-@var{k} must be a valid index of @var{vector}.
-@samp{Vector-set!} stores @var{obj} in element @var{k} of @var{vector}.
-The value returned by @samp{vector-set!} is unspecified.
-@c <!>
-
-
-@format
-@t{(let ((vec (vector 0 '(2 2 2 2) "Anna")))
- (vector-set! vec 1 '("Sue" "Sue"))
- vec)
- ==> #(0 ("Sue" "Sue") "Anna")
-
-(vector-set! '#(0 1 2) 1 "doe")
- ==> @emph{error} ; constant vector
-}
-@end format
-
-@end deffn
-
-
-
-@deffn {library procedure} vector->list vector
-@deffnx {library procedure} list->vector list
-
-@samp{Vector->list} returns a newly allocated list of the objects contained
-in the elements of @var{vector}. @samp{List->vector} returns a newly
-created vector initialized to the elements of the list @var{list}.
-
-
-@format
-@t{(vector->list '#(dah dah didah))
- ==> (dah dah didah)
-(list->vector '(dididit dah))
- ==> #(dididit dah)
-}
-@end format
-
-@end deffn
-
-
-
-@deffn {library procedure} vector-fill! vector fill
-
-Stores @var{fill} in every element of @var{vector}.
-The value returned by @samp{vector-fill!} is unspecified.
-@c <!>
-
-@end deffn
-
-
-@node Control features, Eval, Other data types, Standard procedures
-@section Control features
-
-
-
-@c Intro flushed; not very a propos any more.
-@c Procedures should be discussed somewhere, however.
-
-This chapter describes various primitive procedures which control the
-flow of program execution in special ways.
-The @samp{procedure?} predicate is also described here.
-
-@ignore todo
-@t{Procedure?} doesn't belong in a section with the name
-``control features.'' What to do?
-@end ignore
-
-
-
-@deffn {procedure} procedure? obj
-
-Returns @t{#t} if @var{obj} is a procedure, otherwise returns @t{#f}.
-
-
-@format
-@t{(procedure? car) ==> #t
-(procedure? 'car) ==> #f
-(procedure? (lambda (x) (* x x)))
- ==> #t
-(procedure? '(lambda (x) (* x x)))
- ==> #f
-(call-with-current-continuation procedure?)
- ==> #t
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {procedure} apply proc arg1 @dots{} args
-
-@var{Proc} must be a procedure and @var{args} must be a list.
-Calls @var{proc} with the elements of the list
-@samp{(append (list @var{arg1} @dots{},) @var{args})} as the actual
-arguments.
-
-
-@format
-@t{(apply + (list 3 4)) ==> 7
-
-(define compose
- (lambda (f g)
- (lambda args
- (f (apply g args)))))
-
-((compose sqrt *) 12 75) ==> 30
-}
-@end format
-
-@end deffn
-
-
-
-@deffn {library procedure} map proc list1 list2 @dots{},
-
-The @var{list}s must be lists, and @var{proc} must be a
-procedure taking as many arguments as there are @i{list}s
-and returning a single value. If more
-than one @var{list} is given, then they must all be the same length.
-@samp{Map} applies @var{proc} element-wise to the elements of the
-@var{list}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{list}s is unspecified.
-
-
-@format
-@t{(map cadr '((a b) (d e) (g h)))
- ==> (b e h)
-
-(map (lambda (n) (expt n n))
- '(1 2 3 4 5))
- ==> (1 4 27 256 3125)
-
-(map + '(1 2 3) '(4 5 6)) ==> (5 7 9)
-
-(let ((count 0))
- (map (lambda (ignored)
- (set! count (+ count 1))
- count)
- '(a b))) ==> (1 2) @var{or} (2 1)
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {library procedure} for-each proc list1 list2 @dots{},
-
-The arguments to @samp{for-each} are like the arguments to @samp{map}, but
-@samp{for-each} calls @var{proc} for its side effects rather than for its
-values. Unlike @samp{map}, @samp{for-each} is guaranteed to call @var{proc} on
-the elements of the @var{list}s in order from the first element(s) to the
-last, and the value returned by @samp{for-each} is unspecified.
-
-
-@format
-@t{(let ((v (make-vector 5)))
- (for-each (lambda (i)
- (vector-set! v i (* i i)))
- '(0 1 2 3 4))
- v) ==> #(0 1 4 9 16)
-}
-@end format
-
-
-@end deffn
-
-
-
-@deffn {library procedure} force promise
-
-Forces the value of @var{promise} (see @code{delay},
-@vindex @w{delay}
-section @pxref{Delayed evaluation}). If no value has been computed for
-@cindex @w{promise}
-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.
-@c without any recomputation.
-@c [As pointed out by Marc Feeley, the "without any recomputation"
-@c isn't necessarily true. --Will]
-
-
-@format
-@t{(force (delay (+ 1 2))) ==> 3
-(let ((p (delay (+ 1 2))))
- (list (force p) (force p)))
- ==> (3 3)
-
-(define a-stream
- (letrec ((next
- (lambda (n)
- (cons n (delay (next (+ n 1)))))))
- (next 0)))
-(define head car)
-(define tail
- (lambda (stream) (force (cdr stream))))
-
-(head (tail (tail a-stream)))
- ==> 2
-}
-@end format
-
-
-@samp{Force} and @samp{delay} are mainly intended for programs written in
-functional style. The following examples should not be considered to
-illustrate good programming style, but they illustrate the property that
-only one value is computed for a promise, no matter how many times it is
-forced.
-@c the value of a promise is computed at most once.
-@c [As pointed out by Marc Feeley, it may be computed more than once,
-@c but as I observed we can at least insist that only one value be
-@c used! -- Will]
-
-
-@format
-@t{(define count 0)
-(define p
- (delay (begin (set! count (+ count 1))
- (if (> count x)
- count
- (force p)))))
-(define x 5)
-p ==> @i{}a promise
-(force p) ==> 6
-p ==> @i{}a promise, still
-(begin (set! x 10)
- (force p)) ==> 6
-}
-@end format
-
-
-Here is a possible implementation of @samp{delay} and @samp{force}.
-Promises are implemented here as procedures of no arguments,
-and @samp{force} simply calls its argument:
-
-
-@format
-@t{(define force
- (lambda (object)
- (object)))
-}
-@end format
-
-
-We define the expression
-
-
-@format
-@t{(delay @r{<expression>})
-}
-@end format
-
-
-to have the same meaning as the procedure call
-
-
-@format
-@t{(make-promise (lambda () @r{<expression>}))@r{}
-}
-@end format
-
-
-as follows
-
-
-@format
-@t{(define-syntax delay
- (syntax-rules ()
- ((delay expression)
- (make-promise (lambda () expression))))),
-}
-@end format
-
-
-where @samp{make-promise} is defined as follows:
-
-@c \begin{scheme}
-@c (define make-promise
-@c (lambda (proc)
-@c (let ((already-run? \schfalse) (result \schfalse))
-@c (lambda ()
-@c (cond ((not already-run?)
-@c (set! result (proc))
-@c (set! already-run? \schtrue)))
-@c result))))%
-@c \end{scheme}
-
-
-@format
-@t{(define make-promise
- (lambda (proc)
- (let ((result-ready? #f)
- (result #f))
- (lambda ()
- (if result-ready?
- result
- (let ((x (proc)))
- (if result-ready?
- result
- (begin (set! result-ready? #t)
- (set! result x)
- result))))))))
-}
-@end format
-
-
-
-@quotation
-@emph{Rationale:}
-A promise may refer to its own value, as in the last example above.
-Forcing such a promise may cause the promise to be forced a second time
-before the value of the first force has been computed.
-This complicates the definition of @samp{make-promise}.
-@end quotation
-
-
-Various extensions to this semantics of @samp{delay} and @samp{force}
-are supported in some implementations:
-
-
-
-@itemize @bullet
-
-@item
-Calling @samp{force} on an object that is not a promise may simply
-return the object.
-
-@item
-It may be the case that there is no means by which a promise can be
-operationally distinguished from its forced value. That is, expressions
-like the following may evaluate to either @t{#t} or to @t{#f},
-depending on the implementation:
-
-
-@format
-@t{(eqv? (delay 1) 1) ==> @emph{unspecified}
-(pair? (delay (cons 1 2))) ==> @emph{unspecified}
-}
-@end format
-
-
-@item
-Some implementations may implement ``implicit forcing,'' where
-the value of a promise is forced by primitive procedures like @samp{cdr}
-and @samp{+}:
-
-
-@format
-@t{(+ (delay (* 3 7)) 13) ==> 34
-}
-@end format
-
-
-@end itemize
-
-@end deffn
-
-
-@deffn {procedure} call-with-current-continuation proc
-
- @var{Proc} must be a procedure of one
-argument. The procedure @samp{call-with-current-continuation} packages
-up the current continuation (see the rationale below) as an ``escape
-procedure'' and passes it as an argument to
-@cindex @w{escape procedure}
-@var{proc}. The escape procedure is a Scheme procedure that, if it is
-later called, will abandon whatever continuation is in effect at that later
-time and will instead use the continuation that was in effect
-when the escape procedure was created. Calling the escape procedure
-may cause the invocation of @var{before} and @var{after} thunks installed using
-@code{dynamic-wind}.
-@vindex @w{dynamic-wind}
-
-The escape procedure accepts the same number of arguments as the continuation to
-the original call to @t{call-with-current-continuation}.
-Except for continuations created by the @samp{call-with-values}
-procedure, all continuations take exactly one value. The
-effect of passing no value or more than one value to continuations
-that were not created by @t{call-with-values} is unspecified.
-
-The escape procedure that is passed to @var{proc} has
-unlimited extent just like any other procedure in Scheme. It may be stored
-in variables or data structures and may be called as many times as desired.
-
-The following examples show only the most common ways in which
-@samp{call-with-current-continuation} is used. If all real uses were as
-simple as these examples, there would be no need for a procedure with
-the power of @samp{call-with-current-continuation}.
-
-
-@format
-@t{(call-with-current-continuation
- (lambda (exit)
- (for-each (lambda (x)
- (if (negative? x)
- (exit x)))
- '(54 0 37 -3 245 19))
- #t)) ==> -3
-
-(define list-length
- (lambda (obj)
- (call-with-current-continuation
- (lambda (return)
- (letrec ((r
- (lambda (obj)
- (cond ((null? obj) 0)
- ((pair? obj)
- (+ (r (cdr obj)) 1))
- (else (return #f))))))
- (r obj))))))
-
-(list-length '(1 2 3 4)) ==> 4
-
-(list-length '(a b . c)) ==> #f
-}
-@end format
-
-
-
-@quotation
-@emph{Rationale:}
-
-A common use of @samp{call-with-current-continuation} is for
-structured, non-local exits from loops or procedure bodies, but in fact
-@samp{call-with-current-continuation} is extremely useful for implementing a
-wide variety of advanced control structures.
-
-Whenever a Scheme expression is evaluated there is a
-@dfn{continuation} wanting the result of the expression. The continuation
-@cindex @w{continuation}
-represents an entire (default) future for the computation. If the expression is
-evaluated at top level, for example, then the continuation might take the
-result, print it on the screen, prompt for the next input, evaluate it, and
-so on forever. Most of the time the continuation includes actions
-specified by user code, as in a continuation that will take the result,
-multiply it by the value stored in a local variable, add seven, and give
-the answer to the top level continuation to be printed. Normally these
-ubiquitous continuations are hidden behind the scenes and programmers do not
-think much about them. On rare occasions, however, a programmer may
-need to deal with continuations explicitly.
-@samp{Call-with-current-continuation} allows Scheme programmers to do
-that by creating a procedure that acts just like the current
-continuation.
-
-Most programming languages incorporate one or more special-purpose
-escape constructs with names like @t{exit}, @w{@samp{return}}, or
-even @t{goto}. In 1965, however, Peter Landin [Landin65]
-invented a general purpose escape operator called the J-operator. John
-Reynolds [Reynolds72] described a simpler but equally powerful
-construct in 1972. The @samp{catch} special form described by Sussman
-and Steele in the 1975 report on Scheme is exactly the same as
-Reynolds's construct, though its name came from a less general construct
-in MacLisp. Several Scheme implementors noticed that the full power of the
-@code{catch} construct could be provided by a procedure instead of by a
-@vindex @w{catch}
-special syntactic construct, and the name
-@samp{call-with-current-continuation} was coined in 1982. This name is
-descriptive, but opinions differ on the merits of such a long name, and
-some people use the name @code{call/cc} instead.
-@vindex @w{call/cc}
-@end quotation
-
-
-@end deffn
-
-
-@deffn {procedure} values obj @dots{}
-
-Delivers all of its arguments to its continuation.
-Except for continuations created by the @code{call-with-values}
-@vindex @w{call-with-values}
-procedure, all continuations take exactly one value.
-@t{Values} might be defined as follows:
-
-@format
-@t{(define (values . things)
- (call-with-current-continuation
- (lambda (cont) (apply cont things))))
-}
-@end format
-
-
-@end deffn
-
-
-@deffn {procedure} call-with-values producer consumer
-
-Calls its @var{producer} argument with no values and
-a continuation that, when passed some values, calls the
-@var{consumer} procedure with those values as arguments.
-The continuation for the call to @var{consumer} is the
-continuation of the call to @t{call-with-values}.
-
-
-@format
-@t{(call-with-values (lambda () (values 4 5))
- (lambda (a b) b))
- ==> 5
-
-(call-with-values * -) ==> -1
-}
-@end format
-
-
-@end deffn
-
-
-@deffn {procedure} dynamic-wind before thunk after
-
-Calls @var{thunk} without arguments, returning the result(s) of this call.
-@var{Before} and @var{after} are called, also without arguments, as required
-by the following rules (note that in the absence of calls to continuations
-captured using @code{call-with-current-continuation} the three arguments are
-@vindex @w{call-with-current-continuation}
-called once each, in order). @var{Before} is called whenever execution
-enters the dynamic extent of the call to @var{thunk} and @var{after} is called
-whenever it exits that dynamic extent. The dynamic extent of a procedure
-call is the period between when the call is initiated and when it
-returns. In Scheme, because of @samp{call-with-current-continuation}, the
-dynamic extent of a call may not be a single, connected time period.
-It is defined as follows:
-
-
-@itemize @bullet
-
-@item
-The dynamic extent is entered when execution of the body of the
-called procedure begins.
-
-@item
-The dynamic extent is also entered when execution is not within
-the dynamic extent and a continuation is invoked that was captured
-(using @samp{call-with-current-continuation}) during the dynamic extent.
-
-@item
-It is exited when the called procedure returns.
-
-@item
-It is also exited when execution is within the dynamic extent and
-a continuation is invoked that was captured while not within the
-dynamic extent.
-
-@end itemize
-
-
-If a second call to @samp{dynamic-wind} occurs within the dynamic extent of the
-call to @var{thunk} and then a continuation is invoked in such a way that the
-@var{after}s from these two invocations of @samp{dynamic-wind} are both to be
-called, then the @var{after} associated with the second (inner) call to
-@samp{dynamic-wind} is called first.
-
-If a second call to @samp{dynamic-wind} occurs within the dynamic extent of the
-call to @var{thunk} and then a continuation is invoked in such a way that the
-@var{before}s from these two invocations of @samp{dynamic-wind} are both to be
-called, then the @var{before} associated with the first (outer) call to
-@samp{dynamic-wind} is called first.
-
-If invoking a continuation requires calling the @var{before} from one call
-to @samp{dynamic-wind} and the @var{after} from another, then the @var{after}
-is called first.
-
-The effect of using a captured continuation to enter or exit the dynamic
-extent of a call to @var{before} or @var{after} is undefined.
-
-
-@format
-@t{(let ((path '())
- (c #f))
- (let ((add (lambda (s)
- (set! path (cons s path)))))
- (dynamic-wind
- (lambda () (add 'connect))
- (lambda ()
- (add (call-with-current-continuation
- (lambda (c0)
- (set! c c0)
- 'talk1))))
- (lambda () (add 'disconnect)))
- (if (< (length path) 4)
- (c 'talk2)
- (reverse path))))
-
- ==> (connect talk1 disconnect
- connect talk2 disconnect)
-}
-@end format
-
-@end deffn
-
-@node Eval, Input and output, Control features, Standard procedures
-@section Eval
-
-
-
-@deffn {procedure} eval expression environment-specifier
-
-Evaluates @var{expression} in the specified environment and returns its value.
-@var{Expression} must be a valid Scheme expression represented as data,
-and @var{environment-specifier} must be a value returned by one of the
-three procedures described below.
-Implementations may extend @samp{eval} to allow non-expression programs
-(definitions) as the first argument and to allow other
-values as environments, with the restriction that @samp{eval} is not
-allowed to create new bindings in the environments associated with
-@samp{null-environment} or @samp{scheme-report-environment}.
-
-
-@format
-@t{(eval '(* 7 3) (scheme-report-environment 5))
- ==> 21
-
-(let ((f (eval '(lambda (f x) (f x x))
- (null-environment 5))))
- (f + 10))
- ==> 20
-}
-@end format
-
-
-@end deffn
-
-
-@deffn {procedure} scheme-report-environment version
-@deffnx {procedure} null-environment version
-
-@var{Version} must be the exact integer @samp{5},
-corresponding to this revision of the Scheme report (the
-Revised^5 Report on Scheme).
-@samp{Scheme-report-environment} returns a specifier for an
-environment that is empty except for all bindings defined in
-this report that are either required or both optional and
-supported by the implementation. @samp{Null-environment} returns
-a specifier for an environment that is empty except for the
-(syntactic) bindings for all syntactic keywords defined in
-this report that are either required or both optional and
-supported by the implementation.
-
-Other values of @var{version} can be used to specify environments
-matching past revisions of this report, but their support is not
-required. An implementation will signal an error if @var{version}
-is neither @samp{5} nor another value supported by
-the implementation.
-
-The effect of assigning (through the use of @samp{eval}) a variable
-bound in a @samp{scheme-report-environment}
-(for example @samp{car}) is unspecified. Thus the environments specified
-by @samp{scheme-report-environment} may be immutable.
-
-@end deffn
-
-
-@deffn {optional procedure} interaction-environment
-
-This procedure returns a specifier for the environment that
-contains imple@-men@-ta@-tion-defined bindings, typically a superset of
-those listed in the report. The intent is that this procedure
-will return the environment in which the implementation would evaluate
-expressions dynamically typed by the user.
-
-@end deffn
-
-@node Input and output, , Eval, Standard procedures
-@section Input and output
-
-@menu
-* Ports::
-* Input::
-* Output::
-* System interface::
-@end menu
-
-
-@node Ports, Input, Input and output, Input and output
-@subsection Ports
-
-
-
-Ports represent input and output devices. To Scheme, an input port is a
-Scheme object that can deliver characters upon command, while an output port
-is a Scheme object that can accept characters.
-@cindex @w{port}
-
-@ignore todo
-Haase: Mention that there are alternatives to files?
-@end ignore
-
-
-
-@deffn {library procedure} call-with-input-file string proc
-@deffnx {library procedure} call-with-output-file string proc
-
-@var{String} should be a string naming a file, and
-@var{proc} should be a procedure that accepts one argument.
-For @samp{call-with-input-file},
-the file should already exist; for
-@samp{call-with-output-file},
-the effect is unspecified if the file
-already exists. These procedures call @var{proc} with one argument: the
-port obtained by opening the named file for input or output. If the
-file cannot be opened, an error is signalled. If @var{proc} returns,
-then the port is closed automatically and the value(s) yielded by the
-@var{proc} is(are) returned. If @var{proc} does not return, then
-the port will not be closed automatically unless it is possible to
-prove that the port will never again be used for a read or write
-operation.
-@c Scheme
-@c will not close the port unless it can prove that the port will never
-@c again be used for a read or write operation.
-
-
-@quotation
-@emph{Rationale:}
-Because Scheme's escape procedures have unlimited extent, it is
-possible to escape from the current continuation but later to escape back in.
-If implementations were permitted to close the port on any escape from the
-current continuation, then it would be impossible to write portable code using
-both @samp{call-with-current-continuation} and @samp{call-with-input-file} or
-@samp{call-with-output-file}.
-@ignore todo
-Pitman wants more said here; maybe encourage users to call
-@var{close-foo-port}; maybe talk about process switches (?).
-@end ignore
-
-@end quotation
-
-@end deffn
-
-
-
-@deffn {procedure} input-port? obj
-@deffnx {procedure} output-port? obj
-
-Returns @t{#t} if @var{obj} is an input port or output port
-respectively, otherwise returns @t{#f}.
-
-@ignore todo
-Won't necessarily return true after port is closed.
-@end ignore
-
-
-@end deffn
-
-
-
-@deffn {procedure} current-input-port
-@deffnx {procedure} current-output-port
-
-Returns the current default input or output port.
-
-@end deffn
-
-
-
-@deffn {optional procedure} with-input-from-file string thunk
-@deffnx {optional procedure} with-output-to-file string thunk
-
-@var{String} should be a string naming a file, and
-@var{proc} should be a procedure of no arguments.
-For @samp{with-input-from-file},
-the file should already exist; for
-@samp{with-output-to-file},
-the effect is unspecified if the file
-already exists.
-The file is opened for input or output, an input or output port
-connected to it is made the default value returned by
-@samp{current-input-port} or @samp{current-output-port}
-(and is used by @t{(read)}, @t{(write @var{obj})}, and so forth),
-and the
-@var{thunk} is called with no arguments. When the @var{thunk} returns,
-the port is closed and the previous default is restored.
-@samp{With-input-from-file} and @samp{with-output-to-file} return(s) the
-value(s) yielded by @var{thunk}.
-If an escape procedure
-is used to escape from the continuation of these procedures, their
-behavior is implementation dependent.
-
-@ignore todo
-OK this with authors??
-@end ignore
-
-@c current continuation changes in such a way
-@c as to make it doubtful that the \var{thunk} will ever return.
-
-@ignore todo
-Freeman:
-Throughout this section I wanted to see ``the value of @t{(current-input-port)}''
-instead of ``the value returned by @var{current-input-port}''. (Same for
-@var{current-output-port}.)
-@end ignore
-
-
-
-@end deffn
-
-
-
-@deffn {procedure} open-input-file filename
-
-Takes a string naming an existing file and returns an input port capable of
-delivering characters from the file. If the file cannot be opened, an error is
-signalled.
-
-@end deffn
-
-
-
-@deffn {procedure} open-output-file filename
-
-Takes a string naming an output file to be created and returns an output
-port capable of writing characters to a new file by that name. If the file
-cannot be opened, an error is signalled. If a file with the given name
-already exists, the effect is unspecified.
-
-@end deffn
-
-
-
-@deffn {procedure} close-input-port port
-@deffnx {procedure} close-output-port port
-
-Closes the file associated with @var{port}, rendering the @var{port}
-incapable of delivering or accepting characters.
-@ignore todo
-But maybe a no-op
-on some ports, e.g. terminals or editor buffers.
-@end ignore
-
-These routines have no effect if the file has already been closed.
-The value returned is unspecified.
-
-@ignore todo
-Ramsdell: Some note is needed explaining why there are two
-different close procedures.
-@end ignore
-
-
-@ignore todo
-A port isn't necessarily still a port after it has been closed?
-@end ignore
-
-
-@end deffn
-
-
-@node Input, Output, Ports, Input and output
-@subsection Input
-
-
-
-
-@noindent
- @w{ }
-@c ???
-@sp 5
-@ignore todo
-The input routines have some things in common, maybe explain here.
-@end ignore
-
-
-
-@deffn {library procedure} read
-@deffnx {library procedure} read port
-
-@samp{Read} converts external representations of Scheme objects into the
-objects themselves. That is, it is a parser for the nonterminal
-<datum> (see sections @pxref{External representation} and
-@pxref{Pairs and lists}). @samp{Read} returns the next
-object parsable from the given input @var{port}, updating @var{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.
-@ignore todo
-
-@end ignore
- 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 is signalled.
-
-The @var{port} argument may be omitted, in which case it defaults to the
-value returned by @samp{current-input-port}. It is an error to read from
-a closed port.
-@end deffn
-
-
-@deffn {procedure} read-char
-@deffnx {procedure} read-char port
-
-Returns the next character available from the input @var{port}, updating
-the @var{port} to point to the following character. If no more characters
-are available, an end of file object is returned. @var{Port} may be
-omitted, in which case it defaults to the value returned by @samp{current-input-port}.
-
-@end deffn
-
-
-
-@deffn {procedure} peek-char
-@deffnx {procedure} peek-char port
-
-Returns the next character available from the input @var{port},
-@emph{without} updating
-the @var{port} to point to the following character. If no more characters
-are available, an end of file object is returned. @var{Port} may be
-omitted, in which case it defaults to the value returned by @samp{current-input-port}.
-
-
-@quotation
-@emph{Note:}
-The value returned by a call to @samp{peek-char} is the same as the
-value that would have been returned by a call to @samp{read-char} with the
-same @var{port}. The only difference is that the very next call to
-@samp{read-char} or @samp{peek-char} on that @var{port} will return the
-value returned by the preceding call to @samp{peek-char}. In particular, a call
-to @samp{peek-char} on an interactive port will hang waiting for input
-whenever a call to @samp{read-char} would have hung.
-@end quotation
-
-
-@end deffn
-
-
-
-@deffn {procedure} eof-object? obj
-
-Returns @t{#t} if @var{obj} is an end of file object, otherwise returns
-@t{#f}. The precise set of end of file objects will vary among
-implementations, but in any case no end of file object will ever be an object
-that can be read in using @samp{read}.
-
-@end deffn
-
-
-
-@deffn {procedure} char-ready?
-@deffnx {procedure} char-ready? port
-
-Returns @t{#t} if a character is ready on the input @var{port} and
-returns @t{#f} otherwise. If @samp{char-ready} returns @t{#t} then
-the next @samp{read-char} operation on the given @var{port} is guaranteed
-not to hang. If the @var{port} is at end of file then @samp{char-ready?}
-returns @t{#t}. @var{Port} may be omitted, in which case it defaults to
-the value returned by @samp{current-input-port}.
-
-
-@quotation
-@emph{Rationale:}
-@samp{Char-ready?} exists to make it possible for a program to
-accept characters from interactive ports without getting stuck waiting for
-input. Any input editors associated with such ports must ensure that
-characters whose existence has been asserted by @samp{char-ready?} cannot
-be rubbed out. If @samp{char-ready?} were to return @t{#f} at end of
-file, a port at end of file would be indistinguishable from an interactive
-port that has no ready characters.
-@end quotation
-
-@end deffn
-
-
-@node Output, System interface, Input, Input and output
-@subsection Output
-
-
-
-@c We've got to put something here to fix the indentation!!
-
-@noindent
- @w{}
-@sp 5
-
-
-@deffn {library procedure} write obj
-@deffnx {library procedure} write obj port
-
-Writes a written representation of @var{obj} to the given @var{port}. Strings
-that appear in the written representation are enclosed in doublequotes, and
-within those strings backslash and doublequote characters are
-escaped by backslashes.
-Character objects are written using the @samp{#\} notation.
-@samp{Write} returns an unspecified value. The
-@var{port} argument may be omitted, in which case it defaults to the value
-returned by @samp{current-output-port}.
-
-@end deffn
-
-
-
-@deffn {library procedure} display obj
-@deffnx {library procedure} display obj port
-
-Writes a representation of @var{obj} to the given @var{port}. Strings
-that appear in the written representation are not enclosed in
-doublequotes, and no characters are escaped within those strings. Character
-objects appear in the representation as if written by @samp{write-char}
-instead of by @samp{write}. @samp{Display} returns an unspecified value.
-The @var{port} argument may be omitted, in which case it defaults to the
-value returned by @samp{current-output-port}.
-
-
-@quotation
-@emph{Rationale:}
-@samp{Write} is intended
-for producing mach@-ine-readable output and @samp{display} is for producing
-human-readable output. Implementations that allow ``slashification''
-within symbols will probably want @samp{write} but not @samp{display} to
-slashify funny characters in symbols.
-@end quotation
-
-@end deffn
-
-
-
-@deffn {library procedure} newline
-@deffnx {library procedure} newline port
-
-Writes an end of line to @var{port}. Exactly how this is done differs
-from one operating system to another. Returns an unspecified value.
-The @var{port} argument may be omitted, in which case it defaults to the
-value returned by @samp{current-output-port}.
-
-@end deffn
-
-
-
-@deffn {procedure} write-char char
-@deffnx {procedure} write-char char port
-
-Writes the character @var{char} (not an external representation of the
-character) to the given @var{port} and returns an unspecified value. The
-@var{port} argument may be omitted, in which case it defaults to the value
-returned by @samp{current-output-port}.
-
-@end deffn
-
-
-@node System interface, , Output, Input and output
-@subsection System interface
-
-
-Questions of system interface generally fall outside of the domain of this
-report. However, the following operations are important enough to
-deserve description here.
-
-
-
-@deffn {optional procedure} load filename
-
-@ignore todo
-Fix
-@end ignore
-
-
-@c \domain{\var{Filename} should be a string naming an existing file
-@c containing Scheme source code.} The {\cf load} procedure reads
-@var{Filename} should be a string naming an existing file
-containing Scheme source code. The @samp{load} procedure reads
-expressions and definitions from the file and evaluates them
-sequentially. It is unspecified whether the results of the expressions
-are printed. The @samp{load} procedure does not affect the values
-returned by @samp{current-input-port} and @samp{current-output-port}.
-@samp{Load} returns an unspecified value.
-
-
-@quotation
-@emph{Rationale:}
-For portability, @samp{load} must operate on source files.
-Its operation on other kinds of files necessarily varies among
-implementations.
-@end quotation
-
-@end deffn
-
-
-
-@deffn {optional procedure} transcript-on filename
-@deffnx {optional procedure} transcript-off
-
-@var{Filename} must be a string naming an output file to be
-created. The effect of @samp{transcript-on} is to open the named file
-for output, and to cause a transcript of subsequent interaction between
-the user and the Scheme system to be written to the file. The
-transcript is ended by a call to @samp{transcript-off}, which closes the
-transcript file. Only one transcript may be in progress at any time,
-though some implementations may relax this restriction. The values
-returned by these procedures are unspecified.
-
-@c \begin{note}
-@c These procedures are redundant in some systems, but
-@c systems that need them should provide them.
-@c \end{note}
-@end deffn
-
-@page
-
-@c @include{syn}
-@node Formal syntax and semantics, Notes, Standard procedures, top
-@chapter Formal syntax and semantics
-
-@menu
-* Formal syntax::
-* Formal semantics::
-* Derived expression type::
-@end menu
-
-
-
-This chapter provides formal descriptions of what has already been
-described informally in previous chapters of this report.
-
-@ignore todo
-Allow grammar to say that else clause needn't be last?
-@end ignore
-
-
-
-@node Formal syntax, Formal semantics, Formal syntax and semantics, Formal syntax and semantics
-@section Formal syntax
-
-@menu
-* Lexical structure::
-* External representation::
-* Expression::
-* Quasiquotations::
-* Transformers::
-* Programs and definitions::
-@end menu
-
-
-
-This section provides a formal syntax for Scheme written in an extended
-BNF.
-
-All spaces in the grammar are for legibility. Case is insignificant;
-for example, @samp{#x1A} and @samp{#X1a} are equivalent. <empty>
-stands for the empty string.
-
-The following extensions to BNF are used to make the description more
-concise: <thing>* means zero or more occurrences of
-<thing>; and <thing>+ means at least one
-<thing>.
-
-
-@node Lexical structure, External representation, Formal syntax, Formal syntax
-@subsection Lexical structure
-
-
-This section describes how individual tokens (identifiers,
-@cindex @w{token}
-numbers, etc.) are formed from sequences of characters. The following
-sections describe how expressions and programs are formed from sequences
-of tokens.
-
-<Intertoken space> may occur on either side of any token, but not
-within a token.
-
-Tokens which require implicit termination (identifiers, numbers,
-characters, and dot) may be terminated by any <delimiter>, but not
-necessarily by anything else.
-
-The following five characters are reserved for future extensions to the
-language: @t{[ ] @{ @} |}
-
-
-@format
-@t{<token> --> <identifier> | <boolean> | <number>
-@cindex @w{identifier}
- | <character> | <string>
- | ( | ) | #( | @t{'} | @t{`} | , | ,@@ | @b{.}
-<delimiter> --> <whitespace> | ( | ) | " | ;
-<whitespace> --> <space or newline>
-<comment> --> ; <@r{all subsequent characters up to a}
- @r{line break>}
-@cindex @w{comment}
-<atmosphere> --> <whitespace> | <comment>
-<intertoken space> --> <atmosphere>*}
-
-@end format
-
-
-
-
-
-
-@c This is a kludge, but \multicolumn doesn't work in tabbing environments.
-
-
-
-@format
-@t{<identifier> --> <initial> <subsequent>*
- | <peculiar identifier>
-<initial> --> <letter> | <special initial>
-<letter> --> a | b | c | ... | z
-
-<special initial> --> ! | $ | % | & | * | / | : | < | =
- | > | ? | ^ | _ | ~
-<subsequent> --> <initial> | <digit>
- | <special subsequent>
-<digit> --> 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
-<special subsequent> --> + | - | .@: | @@
-<peculiar identifier> --> + | - | ...
-<syntactic keyword> --> <expression keyword>
-@cindex @w{syntactic keyword}
-@cindex @w{keyword}
- | else | => | define
- | unquote | unquote-splicing
-<expression keyword> --> quote | lambda | if
- | set! | begin | cond | and | or | case
- | let | let* | letrec | do | delay
- | quasiquote
-
-@w{@samp{<variable> @result{} <}}@r{any <identifier> that isn't}
-@cindex @w{variable}
- @w{ @r{also a <syntactic keyword>>}}
-
-<boolean> --> #t | #f
-<character> --> #\ <any character>
- | #\ <character name>
-<character name> --> space | newline
-
-<string> --> " <string element>* "
-<string element> --> <any character other than " or \>
- | \" | \\ }
-
-@end format
-
-
-
-
-
-
-
-@format
-@t{<number> --> <num 2>| <num 8>
- | <num 10>| <num 16>
-}
-
-@end format
-
-
-
-The following rules for <num R>, <complex R>, <real
-R>, <ureal R>, <uinteger R>, and <prefix R>
-should be replicated for @w{R = 2, 8, 10,}
-and 16. There are no rules for <decimal 2>, <decimal
-8>, and <decimal 16>, which means that numbers containing
-decimal points or exponents must be in decimal radix.
-@ignore todo
-Mark Meyer and David Bartley want to fix this. (What? -- Will)
-@end ignore
-
-
-
-@format
-@t{<num R> --> <prefix R> <complex R>
-<complex R> --> <real R> | <real R> @@ <real R>
- | <real R> + <ureal R> i | <real R> - <ureal R> i
- | <real R> + i | <real R> - i
- | + <ureal R> i | - <ureal R> i | + i | - i
-<real R> --> <sign> <ureal R>
-<ureal R> --> <uinteger R>
- | <uinteger R> / <uinteger R>
- | <decimal R>
-<decimal 10> --> <uinteger 10> <suffix>
- | . <digit 10>+ #* <suffix>
- | <digit 10>+ . <digit 10>* #* <suffix>
- | <digit 10>+ #+ . #* <suffix>
-<uinteger R> --> <digit R>+ #*
-<prefix R> --> <radix R> <exactness>
- | <exactness> <radix R>
-}
-
-@end format
-
-
-
-
-@format
-@t{<suffix> --> <empty>
- | <exponent marker> <sign> <digit 10>+
-<exponent marker> --> e | s | f | d | l
-<sign> --> <empty> | + | -
-<exactness> --> <empty> | #i | #e
-@vindex #e
-@vindex #i
-<radix 2> --> #b
-@vindex #b
-<radix 8> --> #o
-@vindex #o
-<radix 10> --> <empty> | #d
-<radix 16> --> #x
-@vindex #x
-<digit 2> --> 0 | 1
-<digit 8> --> 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7
-<digit 10> --> <digit>
-<digit 16> --> <digit 10> | a | b | c | d | e | f }
-
-@end format
-
-
-
-@ignore todo
-Mark Meyer of TI sez, shouldn't we allow @t{1e3/2}?
-@end ignore
-
-
-
-@node External representation, Expression, Lexical structure, Formal syntax
-@subsection External representations
-
-
-
-<Datum> is what the @code{read} procedure (section @pxref{Input})
-@vindex @w{read}
-successfully parses. Note that any string that parses as an
-<ex@-pres@-sion> will also parse as a <datum>.
-
-
-@format
-@t{<datum> --> <simple datum> | <compound datum>
-<simple datum> --> <boolean> | <number>
- | <character> | <string> | <symbol>
-<symbol> --> <identifier>
-<compound datum> --> <list> | <vector>
-<list> --> (<datum>*) | (<datum>+ .@: <datum>)
- | <abbreviation>
-<abbreviation> --> <abbrev prefix> <datum>
-<abbrev prefix> --> ' | ` | , | ,@@
-<vector> --> #(<datum>*) }
-
-@end format
-
-
-
-
-@node Expression, Quasiquotations, External representation, Formal syntax
-@subsection Expressions
-
-
-
-@format
-@t{<expression> --> <variable>
- | <literal>
- | <procedure call>
- | <lambda expression>
- | <conditional>
- | <assignment>
- | <derived expression>
- | <macro use>
- | <macro block>
-
-<literal> --> <quotation> | <self-evaluating>
-<self-evaluating> --> <boolean> | <number>
- | <character> | <string>
-<quotation> --> '<datum> | (quote <datum>)
-<procedure call> --> (<operator> <operand>*)
-<operator> --> <expression>
-<operand> --> <expression>
-
-<lambda expression> --> (lambda <formals> <body>)
-<formals> --> (<variable>*) | <variable>
- | (<variable>+ .@: <variable>)
-<body> --> <definition>* <sequence>
-<sequence> --> <command>* <expression>
-<command> --> <expression>
-
-<conditional> --> (if <test> <consequent> <alternate>)
-<test> --> <expression>
-<consequent> --> <expression>
-<alternate> --> <expression> | <empty>
-
-<assignment> --> (set! <variable> <expression>)
-
-<derived expression> -->
- (cond <cond clause>+)
- | (cond <cond clause>* (else <sequence>))
- | (case <expression>
- <case clause>+)
- | (case <expression>
- <case clause>*
- (else <sequence>))
- | (and <test>*)
- | (or <test>*)
- | (let (<binding spec>*) <body>)
- | (let <variable> (<binding spec>*) <body>)
- | (let* (<binding spec>*) <body>)
- | (letrec (<binding spec>*) <body>)
- | (begin <sequence>)
- | (do (<iteration spec>*)
- (<test> <do result>)
- <command>*)
- | (delay <expression>)
- | <quasiquotation>
-
-<cond clause> --> (<test> <sequence>)
- | (<test>)
- | (<test> => <recipient>)
-<recipient> --> <expression>
-<case clause> --> ((<datum>*) <sequence>)
-<binding spec> --> (<variable> <expression>)
-<iteration spec> --> (<variable> <init> <step>)
- | (<variable> <init>)
-<init> --> <expression>
-<step> --> <expression>
-<do result> --> <sequence> | <empty>
-
-<macro use> --> (<keyword> <datum>*)
-<keyword> --> <identifier>
-
-<macro block> -->
- (let-syntax (<syntax spec>*) <body>)
- | (letrec-syntax (<syntax spec>*) <body>)
-<syntax spec> --> (<keyword> <transformer spec>)
-
-}
-
-@end format
-
-
-
-@node Quasiquotations, Transformers, Expression, Formal syntax
-@subsection Quasiquotations
-
-
-The following grammar for quasiquote expressions is not context-free.
-It is presented as a recipe for generating an infinite number of
-production rules. Imagine a copy of the following rules for D = 1, 2,3, @dots{}. D keeps track of the nesting depth.
-
-
-@format
-@t{<quasiquotation> --> <quasiquotation 1>
-<qq template 0> --> <expression>
-<quasiquotation D> --> `<qq template D>
- | (quasiquote <qq template D>)
-<qq template D> --> <simple datum>
- | <list qq template D>
- | <vector qq template D>
- | <unquotation D>
-<list qq template D> --> (<qq template or splice D>*)
- | (<qq template or splice D>+ .@: <qq template D>)
- | '<qq template D>
- | <quasiquotation D+1>
-<vector qq template D> --> #(<qq template or splice D>*)
-<unquotation D> --> ,<qq template D-1>
- | (unquote <qq template D-1>)
-<qq template or splice D> --> <qq template D>
- | <splicing unquotation D>
-<splicing unquotation D> --> ,@@<qq template D-1>
- | (unquote-splicing <qq template D-1>) }
-
-@end format
-
-
-
-In <quasiquotation>s, a <list qq template D> can sometimes
-be confused with either an <un@-quota@-tion D> or a <splicing
-un@-quo@-ta@-tion D>. The interpretation as an
-<un@-quo@-ta@-tion> or <splicing
-un@-quo@-ta@-tion D> takes precedence.
-
-@node Transformers, Programs and definitions, Quasiquotations, Formal syntax
-@subsection Transformers
-
-
-
-@format
-@t{<transformer spec> -->
- (syntax-rules (<identifier>*) <syntax rule>*)
-<syntax rule> --> (<pattern> <template>)
-<pattern> --> <pattern identifier>
- | (<pattern>*)
- | (<pattern>+ . <pattern>)
- | (<pattern>* <pattern> <ellipsis>)
- | #(<pattern>*)
- | #(<pattern>* <pattern> <ellipsis>)
- | <pattern datum>
-<pattern datum> --> <string>
- | <character>
- | <boolean>
- | <number>
-<template> --> <pattern identifier>
- | (<template element>*)
- | (<template element>+ . <template>)
- | #(<template element>*)
- | <template datum>
-<template element> --> <template>
- | <template> <ellipsis>
-<template datum> --> <pattern datum>
-<pattern identifier> --> <any identifier except @samp{...}>
-<ellipsis> --> <the identifier @samp{...}>
-}
-
-@end format
-
-
-
-@node Programs and definitions, , Transformers, Formal syntax
-@subsection Programs and definitions
-
-
-
-@format
-@t{<program> --> <command or definition>*
-<command or definition> --> <command>
- | <definition>
- | <syntax definition>
- | (begin <command or definition>+)
-<definition> --> (define <variable> <expression>)
- | (define (<variable> <def formals>) <body>)
- | (begin <definition>*)
-<def formals> --> <variable>*
- | <variable>* .@: <variable>
-<syntax definition> -->
- (define-syntax <keyword> <transformer spec>)
-}
-
-@end format
-
-
-
-@node Formal semantics, Derived expression type, Formal syntax, Formal syntax and semantics
-@section Formal semantics
-
-
-This section provides a formal denotational semantics for the primitive
-expressions of Scheme and selected built-in procedures. The concepts
-and notation used here are described in @sc{[Stoy77]}.
-
-@quotation
-@emph{Note:} The formal semantics section was written in La@TeX{} which
-is incompatible with @TeX{}info. See the Formal semantics section of
-the original document from which this was derived.
-@end quotation
-
-
-@c @include{derive}
-@node Derived expression type, , Formal semantics, Formal syntax and semantics
-@section Derived expression types
-
-
-
-This section gives macro definitions for the derived expression types in
-terms of the primitive expression types (literal, variable, call, @samp{lambda},
-@samp{if}, @samp{set!}). See section @ref{Control features} for a possible
-definition of @samp{delay}.
-
-
-@example
-
-(define-syntax cond
- (syntax-rules (else =>)
- ((cond (else result1 result2 ...))
- (begin result1 result2 ...))
- ((cond (test => result))
- (let ((temp test))
- (if temp (result temp))))
- ((cond (test => result) clause1 clause2 ...)
- (let ((temp test))
- (if temp
- (result temp)
- (cond clause1 clause2 ...))))
- ((cond (test)) test)
- ((cond (test) clause1 clause2 ...)
- (let ((temp test))
- (if temp
- temp
- (cond clause1 clause2 ...))))
- ((cond (test result1 result2 ...))
- (if test (begin result1 result2 ...)))
- ((cond (test result1 result2 ...)
- clause1 clause2 ...)
- (if test
- (begin result1 result2 ...)
- (cond clause1 clause2 ...)))))
-
-@end example
-
-
-
-@example
-
-(define-syntax case
- (syntax-rules (else)
- ((case (key ...)
- clauses ...)
- (let ((atom-key (key ...)))
- (case atom-key clauses ...)))
- ((case key
- (else result1 result2 ...))
- (begin result1 result2 ...))
- ((case key
- ((atoms ...) result1 result2 ...))
- (if (memv key '(atoms ...))
- (begin result1 result2 ...)))
- ((case key
- ((atoms ...) result1 result2 ...)
- clause clauses ...)
- (if (memv key '(atoms ...))
- (begin result1 result2 ...)
- (case key clause clauses ...)))))
-
-@end example
-
-
-
-@example
-
-(define-syntax and
- (syntax-rules ()
- ((and) #t)
- ((and test) test)
- ((and test1 test2 ...)
- (if test1 (and test2 ...) #f))))
-
-@end example
-
-
-
-@example
-
-(define-syntax or
- (syntax-rules ()
- ((or) #f)
- ((or test) test)
- ((or test1 test2 ...)
- (let ((x test1))
- (if x x (or test2 ...))))))
-
-@end example
-
-
-
-@example
-
-(define-syntax let
- (syntax-rules ()
- ((let ((name val) ...) body1 body2 ...)
- ((lambda (name ...) body1 body2 ...)
- val ...))
- ((let tag ((name val) ...) body1 body2 ...)
- ((letrec ((tag (lambda (name ...)
- body1 body2 ...)))
- tag)
- val ...))))
-
-@end example
-
-
-
-@example
-
-(define-syntax let*
- (syntax-rules ()
- ((let* () body1 body2 ...)
- (let () body1 body2 ...))
- ((let* ((name1 val1) (name2 val2) ...)
- body1 body2 ...)
- (let ((name1 val1))
- (let* ((name2 val2) ...)
- body1 body2 ...)))))
-
-@end example
-
-
-The following @samp{letrec} macro uses the symbol @samp{<undefined>}
-in place of an expression which returns something that when stored in
-a location makes it an error to try to obtain the value stored in the
-location (no such expression is defined in Scheme).
-A trick is used to generate the temporary names needed to avoid
-specifying the order in which the values are evaluated.
-This could also be accomplished by using an auxiliary macro.
-
-
-@example
-
-(define-syntax letrec
- (syntax-rules ()
- ((letrec ((var1 init1) ...) body ...)
- (letrec "generate temp names"
- (var1 ...)
- ()
- ((var1 init1) ...)
- body ...))
- ((letrec "generate temp names"
- ()
- (temp1 ...)
- ((var1 init1) ...)
- body ...)
- (let ((var1 <undefined>) ...)
- (let ((temp1 init1) ...)
- (set! var1 temp1)
- ...
- body ...)))
- ((letrec "generate temp names"
- (x y ...)
- (temp ...)
- ((var1 init1) ...)
- body ...)
- (letrec "generate temp names"
- (y ...)
- (newtemp temp ...)
- ((var1 init1) ...)
- body ...))))
-
-@end example
-
-
-
-@example
-
-(define-syntax begin
- (syntax-rules ()
- ((begin exp ...)
- ((lambda () exp ...)))))
-
-@end example
-
-
-The following alternative expansion for @samp{begin} does not make use of
-the ability to write more than one expression in the body of a lambda
-expression. In any case, note that these rules apply only if the body
-of the @samp{begin} contains no definitions.
-
-
-@example
-
-(define-syntax begin
- (syntax-rules ()
- ((begin exp)
- exp)
- ((begin exp1 exp2 ...)
- (let ((x exp1))
- (begin exp2 ...)))))
-
-@end example
-
-
-The following definition
-of @samp{do} uses a trick to expand the variable clauses.
-As with @samp{letrec} above, an auxiliary macro would also work.
-The expression @samp{(if #f #f)} is used to obtain an unspecific
-value.
-
-
-@example
-
-(define-syntax do
- (syntax-rules ()
- ((do ((var init step ...) ...)
- (test expr ...)
- command ...)
- (letrec
- ((loop
- (lambda (var ...)
- (if test
- (begin
- (if #f #f)
- expr ...)
- (begin
- command
- ...
- (loop (do "step" var step ...)
- ...))))))
- (loop init ...)))
- ((do "step" x)
- x)
- ((do "step" x y)
- y)))
-
-@end example
-
-
-@c `a = Q_1[a]
-@c `(a b c ... . z) = `(a . (b c ...))
-@c `(a . b) = (append Q*_0[a] `b)
-@c `(a) = Q*_0[a]
-@c Q*_0[a] = (list 'a)
-@c Q*_0[,a] = (list a)
-@c Q*_0[,@a] = a
-@c Q*_0[`a] = (list 'quasiquote Q*_1[a])
-@c `#(a b ...) = (list->vector `(a b ...))
-@c ugh.
-
-@page
-
-@c @include{notes}
-@node Notes, Additional material, Formal syntax and semantics, top
-@unnumbered Notes
-
-@menu
-* Language changes::
-@end menu
-
-
-
-@ignore todo
-Perhaps this section should be made to disappear.
-Can these remarks be moved somewhere else?
-@end ignore
-
-
-@node Language changes, , Notes, Notes
-@unnumberedsec Language changes
-
-
-
-This section enumerates the changes that have been made to Scheme since
-the ``Revised^4 report'' [R4RS] was published.
-
-
-
-@itemize @bullet
-
-
-@item
-The report is now a superset of the IEEE standard for Scheme
-[IEEEScheme]: implementations that conform to the report will
-also conform to the standard. This required the following changes:
-
-
-@itemize @bullet
-
-
-@item
-The empty list is now required to count as true.
-
-@item
-The classification of features as essential or inessential has been
-removed. There are now three classes of built-in procedures: primitive,
-library, and optional. The optional procedures are @samp{load},
-@samp{with-input-from-file}, @samp{with-output-to-file},
-@samp{transcript-on}, @samp{transcript-off}, and
-@samp{interaction-environment},
-and @samp{-} and @samp{/} with more than two arguments.
-None of these are in the IEEE standard.
-
-@item
-Programs are allowed to redefine built-in procedures. Doing so
-will not change the behavior of other built-in procedures.
-
-@end itemize
-
-
-@item
-@emph{Port} has been added to the list of disjoint types.
-
-@item
-The macro appendix has been removed. High-level macros are now part
-of the main body of the report. The rewrite rules for derived expressions
-have been replaced with macro definitions. There are no reserved identifiers.
-
-@item
-@samp{Syntax-rules} now allows vector patterns.
-
-@item
-Multiple-value returns, @samp{eval}, and @samp{dynamic-wind} have
-been added.
-
-@item
-The calls that are required to be implemented in a properly tail-recursive
-fashion are defined explicitly.
-
-@item
-`@samp{@@}' can be used within identifiers. `@samp{|}' is reserved
-for possible future extensions.
-
-
-@end itemize
-
-
-@c %R4%%
-@c \subsection*{Keywords as variable names}
-
-@c Some implementations allow arbitrary syntactic
-@c keywords \index{keyword}\index{syntactic keyword}to be used as variable
-@c names, instead of reserving them, as this report would have
-@c it.\index{variable} But this creates ambiguities in the interpretation
-@c of expressions: for example, in the following, it's not clear whether
-@c the expression {\tt (if 1 2 3)} should be treated as a procedure call or
-@c as a conditional.
-
-@c \begin{scheme}
-@c (define if list)
-@c (if 1 2 3) \ev 2 {\em{}or} (1 2 3)%
-@c \end{scheme}
-
-@c These ambiguities are usually resolved in some consistent way within any
-@c given implementation, but no particular treatment stands out as being
-@c clearly superior to any other, so these situations were excluded for the
-@c purposes of this report.
-
-@c %R4%%
-@c \subsection*{Macros}
-
-@c Scheme does not have any standard facility for defining new kinds of
-@c expressions.\index{macros}
-
-@c \vest The ability to alter the syntax of the language creates
-@c numerous problems. All current implementations of Scheme have macro
-@c facilities that solve those problems to one degree or another, but the
-@c solutions are quite different and it isn't clear at this time which
-@c solution is best, or indeed whether any of the solutions are truly
-@c adequate. Rather than standardize, we are encouraging implementations
-@c to continue to experiment with different solutions.
-
-@c \vest The main problems with traditional macros are: They must be
-@c defined to the system before any code using them is loaded; this is a
-@c common source of obscure bugs. They are usually global; macros can be
-@c made to follow lexical scope rules \todo{flushed: ``as in Common
-@c Lisp's {\tt macrolet}''; OK?}, but many people find the resulting scope rules
-@c confusing. Unless they are written very carefully, macros are
-@c vulnerable to inadvertent capture of free variables; to get around this,
-@c for example, macros may have to generate code in which procedure values
-@c appear as quoted constants. There is a similar problem with syntactic
-@c keywords if the keywords of special forms are not reserved. If keywords
-@c are reserved, then either macros introduce new reserved words,
-@c invalidating old code, or else special forms defined by the programmer
-@c do not have the same status as special forms defined by the system.
-
-@c \todo{Refer to Pitman's special forms paper.}
-@c \todo{Pitman sez: Discuss importance of having a small number of special forms
-@c so that programs can inspect each other.}
-
-@ignore todo
-Move cwcc history back here? --- Andy Cromarty is concerned about
-confusion over who the audience is.
-@end ignore
-
-
-@ignore todo
-Cromarty:
-23. NOTES, p.35ff.: This material should stay somehow. We need to
- make it clear that R^3 Scheme is not being touted as Yet Another
- Ultimate Solution To The Programming Language Problem, but rather
- as a snapshot of a *process* of good design, for which not all
- answers have yet been found. We also ought to use the opportunity
- for publicity afforded us by SIGPLAN to advertise some of the thorny
- unsolved problems that need further research, and encourage
- language designers to work on them.
-@end ignore
-
-
-@c @include{repository}
-@node Additional material, Example, Notes, top
-@unnumbered Additional material
-
-
-The Internet Scheme Repository at
-
-@center
-@center @url{http://www.cs.indiana.edu/scheme-repository/}
-@center
-
-contains an extensive Scheme bibliography, as well as papers,
-programs, implementations, and other material related to Scheme.
-
-@page
-
-@c @include{example}
-
-@node Example, Bibliography, Additional material, top
-@unnumbered Example
-
-@c -*- Mode: Lisp; Package: SCHEME; Syntax: Common-lisp -*-
-
-
-@samp{Integrate-system} integrates the system
-
-
-@center y_k^^ = f_k(y_1, y_2, @dots{}, y_n), k = 1, @dots{}, n
-
-of differential equations with the method of Runge-Kutta.
-
-The parameter @t{system-derivative} is a function that takes a system
-state (a vector of values for the state variables y_1, @dots{}, y_n)
-and produces a system derivative (the values y_1^^, @dots{},y_n^^). The parameter @t{initial-state} provides an initial
-system state, and @t{h} is an initial guess for the length of the
-integration step.
-
-The value returned by @samp{integrate-system} is an infinite stream of
-system states.
-
-
-@example
-
-(define integrate-system
- (lambda (system-derivative initial-state h)
- (let ((next (runge-kutta-4 system-derivative h)))
- (letrec ((states
- (cons initial-state
- (delay (map-streams next
- states)))))
- states))))
-
-@end example
-
-
-@samp{Runge-Kutta-4} takes a function, @t{f}, that produces a
-system derivative from a system state. @samp{Runge-Kutta-4}
-produces a function that takes a system state and
-produces a new system state.
-
-
-@example
-
-(define runge-kutta-4
- (lambda (f h)
- (let ((*h (scale-vector h))
- (*2 (scale-vector 2))
- (*1/2 (scale-vector (/ 1 2)))
- (*1/6 (scale-vector (/ 1 6))))
- (lambda (y)
- ;; y @r{}is a system state
- (let* ((k0 (*h (f y)))
- (k1 (*h (f (add-vectors y (*1/2 k0)))))
- (k2 (*h (f (add-vectors y (*1/2 k1)))))
- (k3 (*h (f (add-vectors y k2)))))
- (add-vectors y
- (*1/6 (add-vectors k0
- (*2 k1)
- (*2 k2)
- k3))))))))
-@c |--------------------------------------------------|
-
-(define elementwise
- (lambda (f)
- (lambda vectors
- (generate-vector
- (vector-length (car vectors))
- (lambda (i)
- (apply f
- (map (lambda (v) (vector-ref v i))
- vectors)))))))
-
-@c |--------------------------------------------------|
-(define generate-vector
- (lambda (size proc)
- (let ((ans (make-vector size)))
- (letrec ((loop
- (lambda (i)
- (cond ((= i size) ans)
- (else
- (vector-set! ans i (proc i))
- (loop (+ i 1)))))))
- (loop 0)))))
-
-(define add-vectors (elementwise +))
-
-(define scale-vector
- (lambda (s)
- (elementwise (lambda (x) (* x s)))))
-
-@end example
-
-
-@samp{Map-streams} is analogous to @samp{map}: it applies its first
-argument (a procedure) to all the elements of its second argument (a
-stream).
-
-
-@example
-
-(define map-streams
- (lambda (f s)
- (cons (f (head s))
- (delay (map-streams f (tail s))))))
-
-@end example
-
-
-Infinite streams are implemented as pairs whose car holds the first
-element of the stream and whose cdr holds a promise to deliver the rest
-of the stream.
-
-
-@example
-
-(define head car)
-(define tail
- (lambda (stream) (force (cdr stream))))
-
-@end example
-
-
-@sp 6
-The following illustrates the use of @samp{integrate-system} in
-integrating the system
-
-
-@center C dv_C / dt = -i_L - v_C / R
-
-
-
-@center L di_L / dt = v_C
-
-which models a damped oscillator.
-
-
-@example
-
-(define damped-oscillator
- (lambda (R L C)
- (lambda (state)
- (let ((Vc (vector-ref state 0))
- (Il (vector-ref state 1)))
- (vector (- 0 (+ (/ Vc (* R C)) (/ Il C)))
- (/ Vc L))))))
-
-(define the-states
- (integrate-system
- (damped-oscillator 10000 1000 .001)
- '#(1 0)
- .01))
-
-@end example
-
-
-@ignore todo
-Show some output?
-@end ignore
-
-
-@c (letrec ((loop (lambda (s)
-@c (newline)
-@c (write (head s))
-@c (loop (tail s)))))
-@c (loop the-states))
-
-@c #(1 0)
-@c #(0.99895054 9.994835e-6)
-@c #(0.99780226 1.9978681e-5)
-@c #(0.9965554 2.9950552e-5)
-@c #(0.9952102 3.990946e-5)
-@c #(0.99376684 4.985443e-5)
-@c #(0.99222565 5.9784474e-5)
-@c #(0.9905868 6.969862e-5)
-@c #(0.9888506 7.9595884e-5)
-@c #(0.9870173 8.94753e-5)
-
-@page
-
-@c \newpage % Put bib on it's own page (it's just one)
-@c \twocolumn[\vspace{-.18in}]% Last bib item was on a page by itself.
-@c \renewcommand{\bibname}{References}
-@c @include{bib}
-
-@c My reference for proper reference format is:
-@c Mary-Claire van Leunen.
-@c {\em A Handbook for Scholars.}
-@c Knopf, 1978.
-@c I think the references list would look better in ``open'' format,
-@c i.e. with the three blocks for each entry appearing on separate
-@c lines. I used the compressed format for SIGPLAN in the interest of
-@c space. In open format, when a block runs over one line,
-@c continuation lines should be indented; this could probably be done
-@c using some flavor of latex list environment. Maybe the right thing
-@c to do in the long run would be to convert to Bibtex, which probably
-@c does the right thing, since it was implemented by one of van
-@c Leunen's colleagues at DEC SRC.
-@c -- Jonathan
-
-@c I tried to follow Jonathan's format, insofar as I understood it.
-@c I tried to order entries lexicographically by authors (with singly
-@c authored papers first), then by date.
-@c In some cases I replaced a technical report or conference paper
-@c by a subsequent journal article, but I think there are several
-@c more such replacements that ought to be made.
-@c -- Will, 1991.
-
-@c This is just a personal remark on your question on the RRRS:
-@c The language CUCH (Curry-Church) was implemented by 1964 and
-@c is a practical version of the lambda-calculus (call-by-name).
-@c One reference you may find in Formal Language Description Languages
-@c for Computer Programming T.~B.~Steele, 1965 (or so).
-@c -- Matthias Felleisen
-
-@c Rather than try to keep the bibliography up-to-date, which is hopeless
-@c given the time between updates, I replaced the bulk of the references
-@c with a pointer to the Scheme Repository. Ozan Yigit's bibliography in
-@c the repository is a superset of the R4RS one.
-@c The bibliography now contains only items referenced within the report.
-@c -- Richard, 1996.
-
-@node Bibliography, Index, Example, top
-@unnumbered Bibliography
-
-
-@itemize @bullet
-@c 999
-
-
-@item [SICP]
-@pindex SICP
-Harold Abelson and Gerald Jay Sussman with Julie Sussman.
-@emph{Structure and Interpretation of Computer Programs, second edition.}
-MIT Press, Cambridge, 1996.
-
-@item [Bawden88]
-@c new
-Alan Bawden and Jonathan Rees.
-@pindex Bawden88
-Syntactic closures.
-In @emph{Proceedings of the 1988 ACM Symposium on Lisp and
- Functional Programming}, pages 86--95.
-
-@item [howtoprint]
-@pindex howtoprint
-Robert G. Burger and R. Kent Dybvig.
-Printing floating-point numbers quickly and accurately.
-In @emph{Proceedings of the ACM SIGPLAN '96 Conference
- on Programming Language Design and Implementation}, pages 108--116.
-
-@item [RRRS]
-@pindex RRRS
-William Clinger, editor.
-The revised revised report on Scheme, or an uncommon Lisp.
-MIT Artificial Intelligence Memo 848, August 1985.
-Also published as Computer Science Department Technical Report 174,
- Indiana University, June 1985.
-
-@item [howtoread]
-@c new
-William Clinger.
-@pindex howtoread
-How to read floating point numbers accurately.
-In @emph{Proceedings of the ACM SIGPLAN '90 Conference
- on Programming Language Design and Implementation}, pages 92--101.
-Proceedings published as @emph{SIGPLAN Notices} 25(6), June 1990.
-
-@item [R4RS]
-@pindex R4RS
-William Clinger and Jonathan Rees, editors.
-The revised^4 report on the algorithmic language Scheme.
-In @emph{ACM Lisp Pointers} 4(3), pages 1--55, 1991.
-
-@item [macrosthatwork]
-@c new
-William Clinger and Jonathan Rees.
-@pindex macrosthatwork
-Macros that work.
-In @emph{Proceedings of the 1991 ACM Conference on Principles of
- Programming Languages}, pages 155--162.
-
-@item [propertailrecursion]
-@c new
-William Clinger.
-@pindex propertailrecursion
-Proper Tail Recursion and Space Efficiency.
-To appear in @emph{Proceedings of the 1998 ACM Conference on Programming
- Language Design and Implementation}, June 1998.
-
-@item [syntacticabstraction]
-@pindex syntacticabstraction
-R. Kent Dybvig, Robert Hieb, and Carl Bruggeman.
-Syntactic abstraction in Scheme.
-@emph{Lisp and Symbolic Computation} 5(4):295--326, 1993.
-
-@item [Scheme311]
-@pindex Scheme311
-Carol Fessenden, William Clinger, Daniel P. Friedman, and Christopher Haynes.
-Scheme 311 version 4 reference manual.
-Indiana University Computer Science Technical Report 137, February 1983.
-Superseded by [Scheme84].
-
-@item [Scheme84]
-@pindex Scheme84
-D. Friedman, C. Haynes, E. Kohlbecker, and M. Wand.
-Scheme 84 interim reference manual.
-Indiana University Computer Science Technical Report 153, January 1985.
-
-@item [IEEE]
-@pindex IEEE
-@emph{IEEE Standard 754-1985. IEEE Standard for Binary Floating-Point
-Arithmetic.} IEEE, New York, 1985.
-
-@item [IEEEScheme]
-@pindex IEEEScheme
-@emph{IEEE Standard 1178-1990. IEEE Standard for the Scheme
- Programming Language.} IEEE, New York, 1991.
-
-@item [Kohlbecker86]
-@pindex Kohlbecker86
-Eugene E. Kohlbecker Jr.
-@emph{Syntactic Extensions in the Programming Language Lisp.}
-PhD thesis, Indiana University, August 1986.
-
-@item [hygienic]
-@pindex hygienic
-Eugene E. Kohlbecker Jr., Daniel P. Friedman, Matthias Felleisen, and Bruce Duba.
-Hygienic macro expansion.
-In @emph{Proceedings of the 1986 ACM Conference on Lisp
- and Functional Programming}, pages 151--161.
-
-@item [Landin65]
-@pindex Landin65
-Peter Landin.
-A correspondence between Algol 60 and Church's lambda notation: Part I.
-@emph{Communications of the ACM} 8(2):89--101, February 1965.
-
-@item [MITScheme]
-@pindex MITScheme
-MIT Department of Electrical Engineering and Computer Science.
-Scheme manual, seventh edition.
-September 1984.
-
-@item [Naur63]
-@pindex Naur63
-Peter Naur et al.
-Revised report on the algorithmic language Algol 60.
-@emph{Communications of the ACM} 6(1):1--17, January 1963.
-
-@item [Penfield81]
-@pindex Penfield81
-Paul Penfield, Jr.
-Principal values and branch cuts in complex APL.
-In @emph{APL '81 Conference Proceedings,} pages 248--256.
-ACM SIGAPL, San Francisco, September 1981.
-Proceedings published as @emph{APL Quote Quad} 12(1), ACM, September 1981.
-
-@item [Pitman83]
-@pindex Pitman83
-Kent M. Pitman.
-The revised MacLisp manual (Saturday evening edition).
-MIT Laboratory for Computer Science Technical Report 295, May 1983.
-
-@item [Rees82]
-@pindex Rees82
-Jonathan A. Rees and Norman I. Adams IV.
-T: A dialect of Lisp or, lambda: The ultimate software tool.
-In @emph{Conference Record of the 1982 ACM Symposium on Lisp and
- Functional Programming}, pages 114--122.
-
-@item [Rees84]
-@pindex Rees84
-Jonathan A. Rees, Norman I. Adams IV, and James R. Meehan.
-The T manual, fourth edition.
-Yale University Computer Science Department, January 1984.
-
-@item [R3RS]
-@pindex R3RS
-Jonathan Rees and William Clinger, editors.
-The revised^3 report on the algorithmic language Scheme.
-In @emph{ACM SIGPLAN Notices} 21(12), pages 37--79, December 1986.
-
-@item [Reynolds72]
-@pindex Reynolds72
-John Reynolds.
-Definitional interpreters for higher order programming languages.
-In @emph{ACM Conference Proceedings}, pages 717--740.
-ACM,
-@ignore todo
-month?
-@end ignore
- 1972.
-
-@item [Scheme78]
-@pindex Scheme78
-Guy Lewis Steele Jr. and Gerald Jay Sussman.
-The revised report on Scheme, a dialect of Lisp.
-MIT Artificial Intelligence Memo 452, January 1978.
-
-@item [Rabbit]
-@pindex Rabbit
-Guy Lewis Steele Jr.
-Rabbit: a compiler for Scheme.
-MIT Artificial Intelligence Laboratory Technical Report 474, May 1978.
-
-@item [CLtL]
-@pindex CLtL
-Guy Lewis Steele Jr.
-@emph{Common Lisp: The Language, second edition.}
-Digital Press, Burlington MA, 1990.
-
-@item [Scheme75]
-@pindex Scheme75
-Gerald Jay Sussman and Guy Lewis Steele Jr.
-Scheme: an interpreter for extended lambda calculus.
-MIT Artificial Intelligence Memo 349, December 1975.
-
-@item [Stoy77]
-@pindex Stoy77
-Joseph E. Stoy.
-@emph{Denotational Semantics: The Scott-Strachey Approach to
- Programming Language Theory.}
-MIT Press, Cambridge, 1977.
-
-@item [TImanual85]
-@pindex TImanual85
-Texas Instruments, Inc.
-TI Scheme Language Reference Manual.
-Preliminary version 1.0, November 1985.
-
-@end itemize
-
-
-
-
-@page
-
-
-@c Adjustment to avoid having the last index entry on a page by itself.
-@c \addtolength{\baselineskip}{-0.1pt}
-
-@node Index, , Bibliography, top
-@unnumbered Alphabetic index of definitions of concepts, keywords, and procedures
-
-
-
-The principal entry for each term, procedure, or keyword is listed
-first, separated from the other entries by a semicolon.
-
-@sp 6
-
-@unnumberedsec Concepts
-@printindex cp
-@page
-@unnumberedsec Procedures
-@printindex fn
-
-@ifinfo
-@unnumberedsec References
-@printindex pg
-@end ifinfo
-
-
-@contents
-@bye
diff --git a/doc/recipe-guidelines.txt b/doc/recipe-guidelines.txt
deleted file mode 100644
index adf8d5c7d..000000000
--- a/doc/recipe-guidelines.txt
+++ /dev/null
@@ -1,80 +0,0 @@
- -*-text-*-
-
-Guidelines for contributions to the Guile Recipes manual
---------------------------------------------------------
-
-1. Licensing
-
-Contributions must be licensed under the GNU Free Documentation
-License (GFDL) or the GNU General Public License (GPL).
-
-2. Copyright
-
-Contributors are encouraged, but not required, to assign the copyright
-for their contribution to the FSF. `not required' also covers the
-case where a contributor has every intention of assigning copyright,
-but the process is simply taking a little time. Note that:
-
-- If you assign your copyright, other people (who have also assigned
- copyright) can make non-trivial enhancements to your contribution
- without any difficulties arising. If you don't assign copyright for
- contribution, it complicates the ownership picture if other people
- make non-trivial changes to it; and if the burden of tracking
- copyright ownership becomes too great, it will be easier simply to
- remove that contribution from the manual.
-
-- If it transpires that non-assigned copyrights turn out to be a bad
- thing (for whatever reason), the maintainers reserve the right to
- remove non-assigned contributions from the manual.
-
-3. Manual organization
-
-Each contribution has its own chapter and lives in its own Texinfo
-file. Chapters in related areas may be grouped together, but maybe
-not. Instead, the introduction to the manual will contain references
-to chapters, and the introductory text will group those references
-appropriately.
-
-4. Copyright ownership
-
-Given this organization, ownership for copyright purposes is
-straightforward. Each Texinfo file is either owned by its
-contributor, or assigned to the FSF.
-
-Every contribution's chapter should begin with a statement of who
-contributed it, who owns the copyright, and its license (GFDL or
-GPL). These statements should appear in the printed and online
-documentation -- i.e. they are _not_ comments.
-
-5. Documentation vs. code
-
-Contributed material should be informative and helpful, and should fit
-in with the manual syntax. In general, this means that a
-straightforward lump of code is _not_ good enough -- it also needs the
-statements mentioned above, introduction, explanation or
-documentation, Texinfo markup, etc.
-
-Note that the maintainers may be able to accept a contribution that
-requires substantial extra work if copyright for that contribution has
-been assigned to the FSF. Where copyright has not been assigned, the
-contribution has to be already finished by its author.
-
-6. Good indexing
-
-In practice, the manual index will be a very important tool for
-someone looking for an example that is useful to them. So please give
-some thought to good indexing in your contribution.
-
-7. Submissions
-
-To submit material for inclusion in Guile Recipes, please send your
-contribution to the guile-sources mailing list
-<guile-sources@gnu.org>.
-
-As far as past material is concerned, I do have an archive of material
-that I will ask people about including individually, but it would make
-things easier for me if people resubmitted past material to
-guile-sources anyway.
-
---
-Neil Jerram <neil@ossau.uklinux.net> April 20th 2001
diff --git a/doc/ref/.cvsignore b/doc/ref/.cvsignore
deleted file mode 100644
index dd408965c..000000000
--- a/doc/ref/.cvsignore
+++ /dev/null
@@ -1,26 +0,0 @@
-*.aux
-*.cp
-*.cps
-*.dvi
-*.fn
-*.fns
-*.ge
-*.html
-*.info*
-*.ky
-*.log
-*.pg
-*.ps
-*.rn
-*.rns
-*.toc
-*.tp
-*.tps
-*.vr
-*.vrs
-Makefile
-Makefile.in
-autoconf-macros.texi
-stamp-vti
-stamp-vti.1
-version.texi
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog
deleted file mode 100644
index 88d4c02d8..000000000
--- a/doc/ref/ChangeLog
+++ /dev/null
@@ -1,610 +0,0 @@
-2002-08-02 Gary Houston <ghouston@arglist.com>
-
- * scheme-modules.texi: split "Scheme and modules" into
- "provide and require" and "Environments". Mention R5RS
- environments.
-
-2002-07-16 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-options.texi (Debugger options): New subsection
- describing stack overflow and what to do about it.
-
-2002-07-10 Gary Houston <ghouston@arglist.com>
-
- * scheme-modules.texi (Compiled Code Modules): Removed description
- of scm_register_module_xxx, which no longer exists. A description
- of current techniques is needed.
-
-2002-05-09 Marius Vollmer <mvo@zagadka.ping.de>
-
- * scheme-data.texi (Numbers): Added description of the new values
- +inf.0, -inf.0 and +nan.0.
-
- * posix.texi (Runtime Environment): Added entries for 'setenv' and
- 'unsetenv'.
-
-2002-04-28 Marius Vollmer <mvo@zagadka.ping.de>
-
- * gh.texi, data-rep.texi: Moved `@deftyp {Data type} SCM' line
- from gh.texi to data-rep.texi. Both files already had similar
- descriptions for SCM. Given that gh.texi is deprecated, looking
- up `SCM' in the index should take one to the primary location
- rather than deprecated section. Hence this change. Added
- `@deftp' for scm_t_bits data type so that a proper index entry is
- added for this. Thanks to Richard Y. Kim!
-
- * data-rep.texi (Subrs): Changed scm_make_gsubr to
- scm_c_define_gsubr. Thanks to Richard Y. Kim!
-
-2002-04-24 Marius Vollmer <mvo@zagadka.ping.de>
-
- * srfi-modules.texi (SRFI-13 Miscellaneous): Updated docs of
- string-tokenize.
-
-2002-04-20 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-intro.texi (Scheme Layout), scm.texi (Reference Layout):
- Node moved from a to b.
-
- * guile.texi (Scheme Intro, Basic Ideas, Guile Scripting, Command
- Line Handling, Debugging Features, Autoconf Support, Miscellaneous
- Tools, Further Reading): Moved to new Part II.
-
- * preface.texi (Manual Layout): Part numbers updated accordingly.
-
- * guile.texi (Top): Move API Overview node to beginning of Guile
- API Reference part.
- (Part II: Writing and Running Guile Scheme): New part; will
- contain content from `Programming with Guile' that pertains to
- writing and using Guile on the Scheme level.
-
- * scm.texi (API Overview): Renamed from `Guile API'.
-
- * guile.texi (Top), scheme-modules.texi (Included Guile Modules):
- Debugger User Interface node renamed Debugging Features.
-
- * debugging.texi (Stacks and Frames): Node deleted; non-duplicated
- material moved to scheme-debug.texi.
- (Debugging Features): Renamed from `Debugger User Interface'.
-
- * scheme-debug.texi (Debugging): Rename chapter `Debugging
- Infrastructure' and reorganize its contents.
-
- * scheme-debug.texi (Debugging), scheme-control.texi (Handling
- Errors): Move display-error to error-focussed section.
-
- * scheme-debug.texi (Debugging), debugging.texi (Backtrace): Move
- backtrace to user-level debugging chapter.
-
- * scheme-debug.texi (Debugging), scheme-procedures.texi (Procedure
- Properties): Move procedure-name, procedure-source and
- procedure-environment to procedures chapter.
-
- * scheme-debug.texi (Debugging), scheme-memory.texi (Memory
- Blocks): Move malloc-stats to memory management chapter.
-
- * scheme-procedures.texi (Syntax Rules): Remove mention of
- use-modules for loading syncase; only use-syntax really works.
- Thanks to Panagiotis Vossos for spotting this.
-
- * program.texi (Scheme vs C): New node, with existing material
- taken from chapter intro.
- (Programming Overview): New intro para to introduce example of
- Guile integration:
- (Extending Dia): New node.
-
-2002-04-17 Marius Vollmer <mvo@zagadka.ping.de>
-
- * Makefile.am (CLEANFILES): Added guile.cps, guile.fns, guile.rns,
- guile.tps, guile.vrs, guile.tmp.
-
-2002-04-01 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-intro.texi (Scheme Layout): Remove reference to defunct
- Guile Extensions index.
-
- * guile.texi: Removed Guile Extensions index.
-
- * scheme-indices.texi (Guile Extensions Index): Removed.
-
- * guile.texi: Remove vgone, vdeprecated, vchanged and vnote
- macros; they're not actually useful after all. Update copyright
- years.
-
- * scheme-compound.texi (Vectors): Make subsections into nodes.
- (Vectors): Review, slightly reorg and clarify docs in this
- section.
-
- * scheme-data.texi (Symbols): Reorganized node substructure and
- added lots of explanatory text around the @deffn's.
-
-2002-03-29 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-modules.texi (Variables): Mention obarrays.
-
- * scheme-data.texi (Symbol Tables, Symbol Props): Remove vgone
- markers for deprecated symbol items.
- (Symbol Props): Remove doc for obsolete 2 arg version of
- symbol-interned?.
- (String Miscellanea): Removed, since it only contained duplicate
- doc for string-ci->symbol.
- (Symbol Tables): Move doc for gensym to Symbol Primitives; rest of
- section removed.
-
- * posix.texi (Ports and File Descriptors), scheme-evaluation.texi
- (Fly Evaluation): Remove vgone markers for close-all-ports-except,
- eval2 and read-and-eval!.
-
- * data-rep.texi (Describing a New Type), scheme-compound.texi
- (Append/Reverse), scheme-procedures.texi (Internal Macros):
- Trivial updates to sync with stable branch.
-
-2002-03-27 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-compound.texi (List Searching): Remove docs for
- `scm_sloppy_mem*', which no longer exist.
-
-2002-03-24 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile.texi (Top), intro.texi (What is Guile?, The Basic Guile
- Package): Use @ifnottex instead of @ifinfo, so that HTML
- generation works correctly.
-
-2002-03-24 Marius Vollmer <mvo@zagadka.ping.de>
-
- * tools.texi: Updated to reflect changes to the guile-snarf tool.
-
-2002-03-16 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-utility.texi (Hooks): Further updates. New material on
- GC hooks.
-
- * scheme-evaluation.texi (Fly Evaluation): Note disappearance of
- eval2 and read-and-eval!.
-
- * deprecated.texi (Deprecated): Remove docs about previously
- deprecated items that have now been removed.
-
-2002-03-15 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * tools.texi (guile-1.4 guile-snarf): Remove this node.
- (How guile-snarf works): Update usage and description to
- no longer mention "--compat=1.4" and instead "-d" and "-D".
- (Macros guile-snarf recognizes): Add list of deprecated macros
- and blurb. Add cindex for deprecated macros.
-
-2002-03-15 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-utility.texi (Hooks): Reviewed and updated.
-
- * scheme-options.texi (Feature Tracking): New section.
-
- * scheme-data.texi (Arithmetic, Primitive Numerics): Add
- description of corresponding C functions.
-
- * scheme-utility.texi (Object Properties): Revamp documentation on
- object properties.
-
- * scheme-memory.texi (Weak References): Update reference to Object
- Properties node.
-
- * guile.texi: Add macros for describing version information.
-
- * scheme-data.texi, scheme-debug.texi, scheme-io.texi,
- scheme-procedures.texi: Automatic updates from snarfed libguile
- docstrings.
-
-2002-03-13 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * Makefile.am (guile_toc.html): Look for guile.texi in $(srcdir).
-
- * tools.texi (How guile-snarf works): Mention "--compat=1.4", and
- new processing steps. Update usage example, makefile frag.
-
- (guile-1.4 guile-snarf): New subsubsection under
- "Init Snarfing with guile-snarf".
-
-2002-03-12 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-compound.texi, scheme-data.texi, new-docstrings.texi:
- Automatic updates from snarfed libguile docstrings.
-
- * data-rep.texi, guile.texi, scheme-evaluation.texi,
- scheme-options.texi, scheme-translation.texi: Various minor
- enhancements ported from the stable CVS branch.
-
-2002-03-08 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * tools.texi (Miscellaneous Tools): New node/chapter.
- (Snarfing, Init Snarfing with guile-snarf, How guile-snarf works,
- Macros guile-snarf recognizes, Doc Snarfing): New nodes/(sub)sections.
- (Executable Modules): Now a section under "Miscellaneous Tools".
-
- * guile.texi (Miscellaneous Tools): Add under "Part II".
- Implement by including tools.texi.
-
- * Makefile.am (guile_TEXINFOS): Add tools.texi.
-
-2002-03-07 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * tools.texi: New file.
-
-2002-03-03 Neil Jerram <neil@ossau.uklinux.net>
-
- * autoconf.texi (Autoconf Background): Insert missing `of'.
-
-2002-03-01 Dirk Herrmann <D.Herrmann@tu-bs.de>
-
- * api.txt, data-rep.texi: Renamed the struct scm_cell to
- scm_t_cell.
-
- * data-rep.texi: Renamed scm_alloc_cell to scm_cell and
- scm_alloc_double_cell to scm_double_cell.
-
-2002-03-01 Marius Vollmer <mvo@zagadka.ping.de>
-
- * scheme-memory.texi (Upgrading from scm_must_malloc et al): New
- section.
-
-2002-02-28 Marius Vollmer <mvo@zagadka.ping.de>
-
- * data-rep.texi: Use scm_gc_malloc and scm_gc_free instead of
- scm_must_malloc and free in example code. Updated text for the
- new memory management functions.
-
- * scheme-debug.texi (malloc-stats): Refer to scm_gc_malloc instead
- of to scm_must_malloc.
-
-2002-02-27 Stefan Jahn <stefan@lkcc.org>
-
- * gh.texi (scm transition summary): Documented some more
- gh equivalents and removed appropriate FIXME's.
-
-2002-02-26 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * Makefile.am: Update path to pre-inst-guile automake frag.
-
-2002-02-24 Rob Browning <rlb@defaultvalue.org>
-
- * .cvsignore: add autoconf-macros.texi.
-
- * Makefile.am (CLEANFILES): add autoconf-macros.texi.
-
-2002-02-19 Marius Vollmer <mvo@zagadka.ping.de>
-
- * scheme-memory.texi (Memory Blocks): New section.
-
-2002-02-05 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * Makefile.am: Include $(top_srcdir)/pre-inst-guile.am.
-
- (GUILE): Delete var.
- (autoconf-macros.texi): Use $(preinstguiletool).
-
-2002-02-04 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * autoconf.texi (Autofrisk, Using Autofrisk): New sections.
- (Autoconf Support): Add new sections to menu.
-
-2002-02-04 Marius Vollmer <marius.vollmer@uni-dortmund.de>
-
- * scheme-data.texi (Symbol Uninterned): Added node.
-
-2002-01-29 Stefan Jahn <stefan@lkcc.org>
-
- * gh.texi (scm transition summary): Documented gh equivalents
- `scm_c_string2str', `scm_c_substring2str' and `scm_c_symbol2str'
- and removed the appropriate FIXME's.
-
-2002-01-14 Marius Vollmer <marius.vollmer@uni-dortmund.de>
-
- * Makefile.am (autoconf-macros.texi): Also set GUILE_LOAD_PATH
- when invoking the uninstalled guile executable.
-
-2002-01-09 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * Makefile.am (autoconf-macros.texi): Fix build bug:
- Write this file to srcdir. Thanks to I. N. Golubev.
-
-2002-01-08 Gary Houston <ghouston@arglist.com>
-
- * Makefile.am: attempt to use guile from $(top_builddir)/libguile
- when building autoconf-macros.texi. There are still problems with
- modules and running makeinfo when builddir != srcdir.
-
-2002-01-08 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * data-rep.texi, gh.texi, guile.texi, intro.texi,
- misc-modules.texi, new-docstrings.texi, posix.texi, program.texi,
- repl-modules.texi, scheme-binding.texi, scheme-compound.texi,
- scheme-control.texi, scheme-data.texi, scheme-debug.texi,
- scheme-ideas.texi, scheme-io.texi, scheme-memory.texi,
- scheme-modules.texi, scheme-procedures.texi,
- scheme-translation.texi, scheme-utility.texi, scm.texi, slib.texi,
- srfi-modules.texi: Spell check. Thanks to Fabrice Bauzac.
-
-2002-01-07 Neil Jerram <neil@ossau.uklinux.net>
-
- * intro.texi (Linking Programs With Guile): Fix typo (superfluous
- `do'). Thanks to Fabrice Bauzac.
-
-2002-01-05 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * intro.texi: Spell check. Thanks to Fabrice Bauzac.
-
-2002-01-02 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * guile.texi (Part II): Add "Autoconf Support"; include
- autoconf.texi.
-
- * Makefile.am (guile_TEXINFOS): Add autoconf.texi and
- autoconf-macros.texi.
- (autoconf.texi, autoconf-macros.texi): New rules.
-
- * autoconf.texi: New file.
-
-2001-12-22 Marius Vollmer <mvo@zagadka.ping.de>
-
- * scheme-compound.texi (Alist Example): Changed "Bismarck" to
- "Pierre". Thanks to Ron Peterson!
-
-2001-12-22 Neil Jerram <neil@ossau.uklinux.net>
-
- * program.texi (Programming Overview): Chapter renamed from
- `Programming Options'; some new material added.
-
-2001-12-07 Neil Jerram <neil@ossau.uklinux.net>
-
- * scm.texi (Guile API): Renamed from `Scheme Primitives' and
- broadened so that this chapter discusses the Guile API as a whole.
-
- * program.texi (Available Functionality): Revise so that text
- reads better.
-
- * guile.texi (Programming Intro): New introductory text.
-
- * scheme-ideas.texi (Definition): Reorder reference bullets in
- ascending page number order.
-
-2001-12-04 Martin Grabmueller <mg@glug.org>
-
- * scheme-procedures.texi (Optional Arguments): Typo fix: wither ->
- either.
-
-2001-12-01 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi (Hooks): Moved into scheme-utility.texi.
-
- * Makefile.am (guile_TEXINFOS): Added scheme-compound.texi.
-
- * scheme-data.texi (Variables): Node moved to modules chapter.
- (Symbol Read Syntax): New node, with syntax-related material taken
- from old Symbols node.
- (Symbol Primitives): Renamed from `Symbols'.
- (Symbols and Variables): Renamed to `Symbols'.
- (Symbol Props): Renamed from `Symbol Tables'.
- (Symbols): General review, improvements and additional material
- throughout this section.
- (Other Data Types): New material: links to object types documented
- elsewhere. Also renamed node to `Other Types'.
- (Data Types): Split into two: `Simple Data Types' and `Compound
- Data Types'. Introductory blurbs rewritten accordingly.
-
- * guile.texi: Updated Notes comment.
-
- * scheme-data.texi (Rx Interface): Node moved to Guile Modules
- part, as the Rx interface is not core Guile.
-
-2001-11-30 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi (String Miscellanea): Removed, moving doc for
- string-ci->symbol into the node on Symbols.
-
- * Makefile.am (ETAGS_ARGS): Added.
-
- * scheme-data.texi (Symbol Tables): Removed doc for gentemp,
- intern-symbol, string->obarray-symbol, symbol-binding,
- symbol-bound?, symbol-set!, unintern-symbol, symbol-interned?; all
- of which no longer exist.
-
-2001-11-25 Thien-Thi Nguyen <ttn@glug.org>
-
- * posix.texi: Fix spelling. Thanks to Chris Cramer.
- Reword `getpass' intro blurb.
-
-2001-11-23 Neil Jerram <neil@ossau.uklinux.net>
-
- * program.texi (Program Control): Remove spurious placeholder
- text.
-
-2001-11-20 Thien-Thi Nguyen <ttn@glug.org>
-
- * scheme-options.texi (Install Config):
- Tweak `%load-path' verb to not imply it's a proc.
- Add documentation for `%guile-build-info'.
-
-2001-11-19 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi (Symbol Tables), new-docstrings.texi: Removed
- doc for builtin-bindings (no longer exists).
- (Variables): Expanded existing description of variables. Removed
- doc for builtin-variable (no longer exists).
-
- * scheme-binding.texi (Top Level): New docs for define, scm_define
- and scm_c_define. Also clarified point about interchangeability
- of define and set!.
-
-2001-11-18 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi (Vectors): Autoupdate docs for
- vector-move-left! and vector-move-right!.
-
-2001-11-16 Neil Jerram <neil@ossau.uklinux.net>
-
- * debugging.texi, deprecated.texi, intro.texi, misc-modules.texi,
- new-docstrings.texi, posix.texi, scheme-binding.texi,
- scheme-control.texi, scheme-data.texi, scheme-debug.texi,
- scheme-evaluation.texi, scheme-io.texi, scheme-memory.texi,
- scheme-modules.texi, scheme-options.texi, scheme-procedures.texi,
- scheme-scheduling.texi, scheme-translation.texi,
- scheme-utility.texi, script-getopt.texi, srfi-modules.texi: Change
- category for "primitive" and "procedure" @deffn's to {Scheme
- Procedure}; add @deffnx lines for {C Function}s; automatic updates
- from libguile docstring changes.
-
- * scheme-memory.texi (Garbage Collection): Removed doc for removed
- `unhash-name'.
-
-2001-11-14 Thien-Thi Nguyen <ttn@glug.org>
-
- * scheme-procedures.texi: Spell "library" correctly.
-
-2001-11-13 Neil Jerram <neil@ossau.uklinux.net>
-
- * new-docstrings.texi, scheme-data.texi: Merge recent doc
- improvements from stable branch.
-
- * scheme-options.texi: Automatic updates from docstring changes in
- libguile's C source code.
-
-2001-11-12 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi (Vtables, Structure Basics): Automatic doc
- updates for struct? and struct-vtable?.
- (String Searching): Add missing "for". Thanks to Scott Lenser.
-
-2001-11-08 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile.texi (Top): Added new chapter `Programming Options'.
-
- * program.texi: New file.
-
- * Makefile.am (guile_TEXINFOS): Added program.texi.
-
-2001-11-07 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-memory.texi, scheme-io.texi, scheme-debug.texi,
- scheme-data.texi, scheme-binding.texi, posix.texi,
- new-docstrings.texi: Automatic updates from improved libguile
- docstrings.
-
-2001-11-04 Neil Jerram <neil@ossau.uklinux.net>
-
- * preface.texi: Use MANUAL_EDITION variable.
- (Manual Layout): Updated to reflect reorg.
-
- * guile.texi (MANUAL_EDITION): New variable, with value
- incremented from 1.0 to 1.1 to reflect the reorg described here.
- (Top): Use MANUAL_EDITION variable.
-
- * scheme-indices.texi (R5RS Index, Guile Extensions Index): Use
- @unnumbered rather than @chapter for these indices.
-
- * guile.texi (Top): A little top-level reshuffling, with the aims
- that: (1) the `Guile Scheme' (reference) part of the manual
- becomes the `Guile API Reference', and covers both Scheme and C
- interfaces; (2) non-API-reference material such as the `Basic
- Ideas in Scheme' chapter is collected together to form a new part
- `Programming with Guile'. This new part will contain general
- documentation on using and programming Guile in both Scheme and C,
- including - for example - awareness of GC when C programming, how
- to use the snarf macros, how to debug ...
- (Top): Move inclusion of scheme-indices.texi so that all indices
- appear together in the printed manual.
-
- * Makefile.am (guile_TEXINFOS): Removed appendices.texi, added
- debugging.texi.
-
- * appendices.texi: Removed.
-
- * debugging.texi (Debugger User Interface): New file, same as the
- material that used to be in appendices.texi, but now a chapter in
- Part II rather than an appendix.
-
- * appendices.texi (Obtaining and Installing Guile): Moved to
- become a chapter in ...
- * intro.texi: ... Part I: Introduction to Guile.
-
- * scm.texi (I/O Extensions): Moved to become a section of ...
- * scheme-io.texi (Input and Output): ... this chapter.
-
- * scm.texi (Handling Errors): Moved to become a section of ...
- * scheme-control.texi (Control Mechanisms): ... this chapter.
-
-2001-11-06 Thien-Thi Nguyen <ttn@glug.org>
-
- * srfi-modules.texi (SRFI-19, SRFI-19 Constants, SRFI-19 Current
- time and clock resolution, SRFI-19 Time object and accessors,
- SRFI-19 Time comparison procedures, SRFI-19 Time arithmetic
- procedures, SRFI-19 Date object and accessors, SRFI-19
- Time/Date/Julian Day/Modified Julian Day converters, SRFI-19 Date
- to string/string to date converters): New nodes.
- (SRFI Support): Add "SRFI-19" to menu.
-
-2001-11-06 Marius Vollmer <mvo@zagadka.ping.de>
-
- * scripts.texi: Document `--debug' and `--no-debug'.
-
-2001-10-27 Gary Houston <ghouston@arglist.com>
-
- * guile.texi, scsh.texi: removed obsolete guile-scsh material
- and updated links (I don't know if it should remain in the
- main menu. It's like slib I think.)
-
- * minor updates to the slib installation notes.
-
-2001-10-05 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-evaluation.texi (Fly Evaluation): Removed documentation
- for `read-and-eval!' and `eval2'. (Thanks to Alex Schroeder for
- noticing that they'd disappeared!)
-
-2001-10-05 Thien-Thi Nguyen <ttn@glug.org>
-
- * scheme-io.texi (Writing): Add entry for `display'.
- Include in R5RS Index. Thanks to Alex Schroeder for suggestion.
-
-2001-09-26 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * srfi-modules.texi (SRFI-13): Tyop fix.
- (SRFI-13): Changed paragraph about bindings both in the code and
- in SRFI-13.
-
- * misc-modules.texi (Formatted Output): Tyop fix.
- (Formatted Output): Document ~g properly.
-
- Thanks to Alex Schroeder for pointing out the typos and sending
- suggestions.
-
-2001-09-25 Thien-Thi Nguyen <ttn@glug.org>
-
- * scheme-procedures.texi (Syntax Rules): Add `cindex' directive.
- Thanks to suggestion by Alex Schroeder.
-
-2001-08-30 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile.texi (Top): Group all index nodes together so that
- `Info-index' works more effectively in Info. Thanks to Eric
- Hanchrow for the report and fix.
-
- * scheme-data.texi (Random, String Syntax, String Modification,
- Regular Expressions), scheme-ideas.texi (Definition),
- scheme-modules.texi (Dynamic Linking and Compiled Code Modules),
- scm.texi (Transforming Scheme name to C name, Port
- Implementation): Various typo fixes and clarifications merged from
- the stable CVS branch.
-
-2001-08-27 Neil Jerram <neil@ossau.uklinux.net>
-
- * intro.texi: Merged wording fixes from stable CVS branch.
-
- * Makefile.am (guile_TEXINFOS): Remove ../AUTHORS.
-
- * guile.texi: Incorporate text previously in separate AUTHORS
- file.
-
-2001-08-27 Neil Jerram <neil@ossau.uklinux.net>
-
- The change log for files in this directory continues backwards
- from 2001-08-27 in ../ChangeLog, as all the Guile documentation
- prior to this date was contained in a single directory.
diff --git a/doc/ref/ChangeLog-guile-doc-ref b/doc/ref/ChangeLog-guile-doc-ref
deleted file mode 100644
index 3d2cc4e09..000000000
--- a/doc/ref/ChangeLog-guile-doc-ref
+++ /dev/null
@@ -1,890 +0,0 @@
-2001-03-09 Neil Jerram <neil@ossau.uklinux.net>
-
- Moving texinfo files from guile-doc/ref into guile-core/doc:
-
- * env.texi, indices.texi, mbapi.texi, mltext.texi, scripts.texi,
- scsh.texi, tcltk.texi, hierarchy.txt, scheme-indices.texi,
- slib.texi, deprecated.texi, scheme-binding.texi, appendices.texi,
- scheme-intro.texi, goops.texi, extend.texi, gh.texi, intro.texi,
- preface.texi, scm.texi, goops-tutorial.texi, hierarchy.eps,
- r4rs.texi, r5rs.texi, texinfo.tex, scheme-reading.texi,
- data-rep.texi, scheme-utility.texi, posix.texi,
- scheme-control.texi, scheme-debug.texi, scheme-evaluation.texi,
- scheme-io.texi, scheme-memory.texi, scheme-modules.texi,
- scheme-options.texi, scheme-procedures.texi,
- scheme-scheduling.texi, scheme-translation.texi, guile.texi,
- scheme-data.texi, scheme-ideas.texi, expect.texi: Removed.
-
-2001-02-28 Gary Houston <ghouston@arglist.com>
-
- * expect.texi (Expect): add missing eof? argument in example code.
-
-2001-02-27 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile.texi, scheme-data.texi, scheme-ideas.texi: Remove the code
- that set paragraph indent to zero, then add @noindent to several
- places that need not to be indented.
-
-2001-02-24 Neil Jerram <neil@ossau.uklinux.net>
-
- * posix.texi (File System, Time), scheme-control.texi
- (Exceptions), scheme-data.texi (Complex, Primitive Numerics,
- Random, String Fun, Symbols and Variables, Lists, Bit Vectors,
- Hooks), scheme-debug.texi (Debugging), scheme-evaluation.texi
- (Reader Extensions, Scheme Read, Fly Evaluation, Loading,
- Evaluator Options), scheme-io.texi (Reading, Writing, Default
- Ports, File Ports), scheme-memory.texi (Garbage Collection,
- Guardians, Objects), scheme-modules.texi (The Guile module
- system), scheme-options.texi (Install Config),
- scheme-procedures.texi (Procedure Properties, Procedures with
- Setters), scheme-scheduling.texi (Arbiters, Asyncs),
- scheme-translation.texi (Emacs Lisp Support): Automatic docstring
- updates.
-
- * scheme-io.texi (Binary IO): New node.
-
- * scheme-control.texi (Multiple Values): New node.
-
-2001-02-23 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-utility.texi (Sorting), scheme-procedures.texi (Procedure
- Properties), scheme-memory.texi (Guardians), scheme-io.texi
- (Line/Delimited), scheme-data.texi (String Fun, Symbols and
- Variables, Vtables), posix.texi (Ports and File Descriptors, File
- System, Network Sockets and Communication): Automatic docstring
- updates.
-
-2001-02-15 Neil Jerram <neil@ossau.uklinux.net>
-
- * data-rep.texi: Preserve, in comments beginning `@c essay',
- material from the standalone version of this essay which is very
- soon to be retired from its current location at
- guile-core/doc/data-rep.texi.
-
- * data-rep.texi: Incorporate recent changes to smob example
- documentation from the standalone version of this essay.
-
-2001-02-02 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-reading.texi (Further Reading): Add reference to online
- version of SICP.
-
-2001-01-27 Neil Jerram <neil@ossau.uklinux.net>
-
- Further changes to get everything to build to dvi with the latest
- texinfo.tex.
-
- * texinfo.tex: Replaced by latest version from ftp.gnu.org.
-
- * r5rs.texi (Binding constructs): Remove @c inside @t{...} at
- lines 2207-2209.
- (Lexical structure): Remove @c inside @t{...} at line 7517.
-
- * r4rs.texi (Example): Remove @c inside @t{...} at lines 6557 and
- 6569.
-
-2001-01-26 Neil Jerram <neil@ossau.uklinux.net>
-
- * scm.texi (Handling Errors): Improved markup.
- (snarfing): Deleted.
-
- * data-rep.texi: File copied here from sources directory and
- integrated into the reference manual structure.
-
- * extend.texi (Libguile Intro): New file, new node, to introduce
- new Part.
-
- * guile.texi: Merged Parts V and VI into a single Part: "Extending
- Applications Using Guile". Improved some top level node names and
- descriptions. Include extend.texi and data-rep.texi.
-
- * preface.texi (Manual Layout): Updated according to merge of
- Parts V and VI.
-
- * gh.texi: Restructured into a single chapter.
-
- * scm.texi (C Port Interface, Port Implementation): Moved here
- from scheme-io.texi.
-
- * scheme-io.texi (Default Ports): Renamed from `Port
- Environment'.
- (Port Internals): Contents moved to scm.texi.
-
- * r5rs.texi: Changes to allow building of r5rs.dvi from r5rs.texi.
- Aubrey Jaffer's view - which I agree with - is that, given that
- people have the option of building r5rs.dvi from the original
- LaTeX distribution for R5RS, it is not worth fixing his master
- copy of r5rs.texi and the tool which autogenerates it. On the
- other hand, it is a marginal convenience for people to be able to
- build hardcopy from r5rs.texi, even if the results are less good
- than with the original LaTeX. Hence the following fixes.
- (lines 714, 725, 728, 1614, 2258): Remove invalid parentheses from
- @deffn statements.
- (line 2316): Change @deffnx to @deffn, and insert `@end deffn' to
- terminate preceding @deffn.
- (line 7320): Insert `@c ' at beginning of lines that are intended
- to be @ignore'd.
-
- * guile.texi, r4rs.texi, r5rs.texi: Align @direntry descriptions
- to start in column 32.
-
-2001-01-24 Neil Jerram <neil@ossau.uklinux.net>
-
- * intro.texi: Licensing and Layout material moved to
- preface.texi.
- (Whirlwind Tour): New chapter as top level for preexisting
- sections.
-
- * guile.texi: Various minor changes to improve the structure at
- the beginning of the reference manual.
-
- * preface.texi: New file, to split out "prefatory material".
- Initially with Licensing and Layout material taken from
- intro.texi.
-
- * Makefile.am (dist_texis): Add preface.texi.
-
-2001-01-19 Neil Jerram <neil@ossau.uklinux.net>
-
- * intro.texi: Change R4RS everywhere to R5RS.
- (What is Guile?): Change "compiling" to "translating".
-
-2001-01-07 Neil Jerram <neil@ossau.uklinux.net>
-
- * appendices.texi (Internals): Content merged into Symbols and
- Variables node of scheme-data.texi.
- (Reporting Bugs): Moved to manual Part I.
-
- * guile.texi: Inserted new Part for `Guile Modules' as distinct
- from core Guile Scheme language/features. Other parts renumbered
- correspondingly. Module chapters moved into new part.
-
- * intro.texi (Reporting Bugs): Node moved here from
- appendices.texi.
-
- * posix.texi (POSIX): Node name changed from `POSIX System Calls
- and Networking'.
-
- * scheme-data.texi (Symbols and Variables): Added texinfo markup
- to docstrings that didn't have it. Expanded snarfed argument
- names like `o' and `s' to `obarray' and `string'.
-
- * scheme-debug.texi (Debugging): Node name changed from `Internal
- Debugging Interface'.
-
- * scheme-evaluation.texi (Fly Evaluation): Moved doc for
- `interaction-environment' here (previously under module doc).
-
- * scheme-memory.texi: Structure reorganization.
-
- * scheme-modules.texi: Structure reorganization. Removed empty
- subsections `First-class Variables' and `First-class Modules'.
-
- * scheme-options.texi (Options and Config): Node name changed from
- `Options'.
- (Install Config) Node name changed from `Configuration Data'.
-
- * scheme-scheduling.texi (Scheduling): Node name changed from
- `Threads and Dynamic Roots'.
-
- * scheme-translation.texi (Translation): New top level node for
- translation documentation.
-
-2001-01-05 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-exceptions.texi: Removed.
-
- * Makefile.am (dist_texis): Removed scheme-exceptions.texi.
-
- * guile.texi (Top): Renamed/redescribed some top level nodes. No
- longer include scheme-exceptions.texi.
-
- * scheme-control.texi: Merge material that was previously in
- scheme-exceptions.texi.
-
- * posix.texi: Updated close-port reference.
-
- * scheme-binding.texi, scheme-control.texi,
- scheme-evaluation.texi, scheme-intro.texi, scheme-io.texi,
- scheme-procedures.texi, scheme-utility.texi: Massaged into desired
- structure.
-
- * scheme-data.texi (Generic Data Types): Changed to "Data Types".
- (Numbers) Introduction streamlined.
- (Complex Numbers) New material.
-
-2001-01-05 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi, scheme-io.texi, scheme-memory.texi,
- scheme-options.texi: Where a single docstring documents more than
- one primitive, add a docstring comment for each additionally
- documented primitive.
-
- * scheme-modules.texi: Update docstring for dynamic-func.
-
- * scheme-data.texi (Numbers, Numerical Tower, Integers, Reals and
- Rationals, Number Syntax): New material.
-
- * deprecated.texi (Deprecated): Remove obsolete MD5 comment line.
-
-2000-12-12 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi (Numbers): Documentation added for scientific
- functions.
-
- * Makefile.am (dist_texis): Updated following split of scheme.texi
- into per-chapter files.
-
-2000-12-07 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi (Booleans): Written.
- (Numbers): Introduction written, primitives organized into
- subsections.
-
-2000-12-06 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi (Generic Data Types): Added chapter
- introduction.
- (Bitwise Operations, Random): Moved underneath Numbers.
- (Other Data Types): New placeholder section for data types that
- are documented elsewhere.
-
- * scheme-indices.texi, scheme-reading.texi: Added Local Variables
- block.
-
-2000-12-06 Neil Jerram <neil@ossau.uklinux.net>
-
- This change replaces scheme.texi, which is unmanageably large, by
- a set of smaller one-per-chapter files. The set and ordering of
- the new files reflects the intended top level structure of the
- Guile Scheme part of the reference manual. This structure is not
- yet all reflected in the combined Texinfo/Info, though, because I
- haven't yet fixed the @node levels appropriately.
-
- * scheme.texi: Removed, after dividing content into new files.
-
- * scheme-procedures.texi, scheme-utility.texi,
- scheme-binding.texi, scheme-control.texi, scheme-io.texi,
- scheme-evaluation.texi, scheme-exceptions.texi,
- scheme-memory.texi, scheme-modules.texi, scheme-scheduling.texi,
- scheme-options.texi, scheme-translation.texi, scheme-debug.texi,
- slib.texi: New files.
-
- * guile.texi: @include new files instead of scheme.texi. Reorder
- existing top level nodes.
-
-2000-12-01 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi: Remove @page breaks (following demotion).
-
- * guile.texi (Top), scheme-ideas.texi: Demote everything one level
- so that previous chapters About Data, About Procedures, About
- Expressions and About Closure are now combined into a single
- Scheme Ideas chapter. Add overall chapter introduction. Fix up
- top level nodes accordingly.
-
- * guile.texi (Top), scheme.texi, scheme-data.texi: Gather material
- for Generic Data Types chapter into a new file
- (scheme-data.texi). @include new file in guile.texi. Fix up top
- level nodes accordingly. (This changes demotes all the affected
- material by one level, except for that which was already grouped
- together under the Data Structures node.)
-
- * guile.texi (Top): @include new files.
-
- * scheme-intro.texi, scheme-ideas.texi: New files.
-
- * scheme.texi (Guile and R5RS Scheme): Moved introductory chapter
- to its own file (scheme-intro.texi).
- (About Closure) Chapter completed.
- (About Data, About Procedures, About Expressions, About Closure):
- Ideas chapters moved to their own file (scheme-ideas.texi);
- scheme.texi was just getting too large!
-
-2000-11-09 Gary Houston <ghouston@arglist.com>
-
- * posix.texi (Ports and File Descriptors): updated
- close-all-ports-except.
-
-2000-11-07 Gary Houston <ghouston@arglist.com>
-
- * posix.texi (Ports and File Descriptors): added dup2, close-fdes
- and port-for-each.
- (Pipes): synchronise open-input-pipe, open-output-pipe with
- popen.scm.
-
-2000-11-04 Gary Houston <ghouston@arglist.com>
-
- * scheme.texi (Generic Port Operations): "port?" added.
-
-2000-11-03 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme.texi (About Expressions): New material about evaluation
- and program execution.
-
- * scheme.texi (About Procedures): Minor textual improvements.
-
-2000-10-29 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme.texi (About Expressions, About Closure): Placeholder
- structure for remaining introductory Scheme material.
-
- * guile.texi (Top): Shorten some menu item lines to fit on a
- single console line.
-
-2000-10-28 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-indices.texi (R5RS Index, Guile Extensions Index): Print
- new indices.
-
- * guile.texi: Define new R5RS and Guile extension indices.
-
-2000-10-27 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme.texi (Guile and R5RS Scheme): Filled in examples of Guile
- extensions.
- (About Procedures): New introductory material.
-
- * scheme-reading.texi: New file.
-
- * scheme-indices.texi: New file.
-
- * intro.texi (Scripting Examples): Added @* to fix TeX overfull
- hboxes (twice).
- (end of file): Added Local Variables block for TeX-master
- variable.
-
- * scheme.texi (R4RS Scheme): Node changed to "Guile and R5RS
- Scheme". Content changed to indicate that we plan to document
- both standard Scheme and Guile extensions.
- (About Data, About Procedures, About Expressions): New Scheme
- introductory material chapters.
- (Options): Moved material on Options into its own chapter.
- (Coding With Keywords): New subsection; extends material on use of
- keywords to include examples of and references to (ice-9 optargs).
- (passim): Change many uses of @example to @lisp, since the
- formatting seems to come out better in TeX.
- (Optional Arguments): New placeholder chapter (empty).
- (end of file): Added Local Variables block for TeX-master
- variable.
-
- * guile.texi (Top): "R4RS Scheme" node changed to "Guile and R5RS
- Scheme". Added Scheme introductory chapters: About Data, About
- Procedures and About Expressions. New Options chapter for options
- material. New Optional Arguments chapter as placeholder for
- (ice-9 optargs) material. New chapter for "Further Reading". New
- chapters for indices showing what is standard Scheme and what is
- Guile extension.
-
-2000-10-25 Mikael Djurfeldt <mdj@linnaeus.mit.edu>
-
- * Makefile.am: Added goops.texi and new files to dist_texis.
-
- * goops.texi, goops-tutorial.texi, hierarchy.eps, hierarchy.txt:
- New files.
-
-2000-10-15 Neil Jerram <neil@ossau.uklinux.net>
-
- * gh.texi (Starting and controlling the interpreter): Removed
- obsolete note about boot-9.scm not being loaded by gh_enter.
- (Thanks to Chris Cramer for pointing this out.)
-
-2000-10-06 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile.texi, scheme.texi, posix.texi: Simplified docstring
- comments: (i) they new refer to the Texinfo-format file that is
- generated by snarfing when libguile is built, rather than to
- individual C files in the libguile source; (ii) there is no longer
- a need to keep MD5 digest values for the corresponding source
- docstring, since I'm now using a different mechanism for keeping
- track of source material changes.
-
- * scheme.texi (Lists): Use "@example" in docstring for append.
-
- * guile.texi, scheme.texi (Primitive Properties): New chapter,
- documenting new primitive property primitives.
-
-2000-09-22 Neil Jerram <neil@ossau.uklinux.net>
-
- * scm.texi (I/O internals): Add full stops (periods) after
- standalone uses of @xref.
-
- * scheme.texi (Structure Layout): Doc for make-struct-layout
- changed to remove reference to "read-only" strings, which no
- longer exist.
- (Structure Basics): Use @pxref rather than @xref for parenthetical
- reference.
- (Dynamic Roots): Use @code rather than @var for code, in doc for
- call-with-dynamic-root.
- (Low level thread primitives): Ditto call-with-new-thread.
- (Higher level thread procedures): Ditto call-with-new-thread.
- (Symbols and Variables): Docs for gensym and symbol-hash updated
- according to libguile changes.
-
- * posix.texi (Generic Port Operations): Synchronized docstring
- for unread-string.
-
- * gh.texi (Defining new Scheme procedures in C): Avoid texinfo
- warning by using @code rather than @var for code.
-
- * scheme.texi: Lots more docstring comments added, and docs
- synchronized with libguile source.
- (interaction-environment, make-struct, make-vtable-vtable): Newer,
- better doc taken from source file.
- (cons-source): New docstring written.
- (Vectors): New section added.
- (Random, Symbols and Variables): New chapters.
-
- * posix.texi: Lots more docstring comments added.
- (pipe, tzset) Newer, better documentation taken from source file.
-
- * deprecated.texi: New file, for documenting features that are
- deprecated and so planned to disappear.
-
- * guile.texi (Procedures, Reading and Writing, Random, Sorting,
- Symbols and Variables, Deprecated): New chapters in the Scheme
- part of the reference manual, to hold docstrings that don't
- currently fit anywhere else.
-
-2000-08-28 Neil Jerram <neil@ossau.uklinux.net>
-
- * posix.texi (Pipes): open-pipe and close-pipe are procedures (in
- ice-9/popen.scm), not primitives.
-
- * scheme.texi (Generic Port Operations): Remove doc for
- port-revealed and set-port-revealed!, since these are covered in
- posix.texi.
-
- * posix.texi: Inserted docstring synchronization comments and
- synchronized docstrings for all primitives defined in posix.c,
- simpos.c, scmsigs.c, stime.c.
- (Ports and File Descriptors) Similarly synchronized port-revealed
- and set-port-revealed!.
-
-2000-08-25 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme.texi: Lots more docstrings added.
-
- * guile.texi (Top): More new chapters: Pairs, Objects, Guardians,
- Emacs Lisp Support.
-
- * scheme.texi (Numbers): New chapter containing docs (many still
- empty right now) for numerical primitives.
-
- * guile.texi (Top): Add chapter for numerical primitives.
-
-2000-08-18 Neil Jerram <neil@ossau.uklinux.net>
-
- * posix.texi (Ports and File Descriptors): Docstring for select
- substantially changed by update from libguile source.
-
- * scheme.texi, posix.texi: Lots more primitive docstrings added.
-
- * guile.texi (Top): Removed empty Reflection chapter, added new
- Hooks chapter.
-
- * scheme.texi: Added docstrings for all Guile primitives from
- libguile files from arbiters.c to error.c.
- (Reflection): Empty chapter removed.
-
- * guile.texi (Top): New chapters "Booleans" and "Equality"
- (temporary - until we improve the overall organization).
-
- * scheme.texi (Uniform Arrays): Fix "indentical" typo.
-
-2000-08-12 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme.texi: Removed superfluous "@c docstring end" markers -
- docstring.el now uses "@end deffn" to find the end of the
- docstring.
- Added a lot more docstring comments, and synced up docstrings with
- libguile - all libguile primitives documented in scheme.texi now
- have docstring comments and are up to date.
- (Evaluation): Updated docstring for eval and eval-string (now
- R5RS-compliant).
-
- * intro.texi (Guile Scripts): Added a couple of blank lines.
-
-2000-08-11 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme.texi: Add docstring comments and sync up existing
- docstrings with libguile source - complete as far as Association
- Lists.
- (Keywords): Fill out and improve documentation about
- keywords.
-
- * guile.texi: Set paragraph indent to zero.
-
-2000-08-07 Neil Jerram <neil@ossau.uklinux.net>
-
- * scm.texi (libguile error handling): Add note (text supplied by
- Gary Houston) giving a pointer on how to do C exception handling
- since scm_error_callback was removed.
-
-2000-08-01 Dirk Herrmann <D.Herrmann@tu-bs.de>
-
- * scm.texi (libguile error handling): Removed reference to
- scm_error_callback, which is not available any more since
- guile-1.3. Thanks to Juli-Manel Merino Vidal and to Gary Houston
- for pointing this out.
-
-2000-07-31 Neil Jerram <neil@ossau.uklinux.net>
-
- * scm.texi (Relationship between Scheme and C functions):
- Expand. (Contributed by Thien-Thi Nguyen <ttn@gnu.org>.)
-
-2000-07-30 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme.texi (Association Lists): New, more complete
- documentation.
- * guile.texi: New top-level manual file based on guile-ref.texi
- but modified to reflect the better organization suggested in
- sources/jimb-org.texi.
- * expect.texi: New file to separate out Expect doc.
- * indices.texi: New file to separate indices from appendices.
- * intro.texi: Invoking Guile and Meta Switch nodes moved to Guile
- Scripting part (scripts.texi). Manual layout node moved to end of
- introduction.
- * posix.texi: All nodes downgraded one level. Expect, SCSH and
- Tcl/Tk nodes moved to dedicated files.
- * scheme.texi: Stuff moved around in accordance with
- sources/jimb-org.texi reorganization (cvs diff totally confused,
- I'm afraid).
- * scsh.texi: New file to separate out SCSH doc.
- * scripts.texi: New file to separate out Guile scripting doc.
- * tcltk.texi: New file to separate out Tcl/Tk interface doc.
- * Makefile.am: Changed guile-ref to guile; more distribution
- texis.
- * Makefile.in: Changed guile-ref to guile; more distribution
- texis.
-
-
-2000-05-14 Marius Vollmer <mvo@zagadka.ping.de>
-
- * posix.texi (Conventions): Added example on how to retrieve errno
- value from a system-exception. Thanks to Eric Hanchrow!
-
-2000-05-04 Marius Vollmer <mvo@zagadka.ping.de>
-
- * intro.texi: Added chapter about Guile's license.
- * guile-ref.texi: Updated menu.
-
-1999-12-15 Gary Houston <ghouston@freewire.co.uk>
-
- * scheme.texi (SLIB installation): new node.
-
-1999-12-06 Gary Houston <ghouston@freewire.co.uk>
-
- * r4rs.texi: tweaked the dircategory/direntry for compatibility
- with the r5 version.
- guile-ref.texi: tweaked the dircategory.
- * Makefile.am (info_TEXINFOS): add r5rs.texi.
- * r5rs.texi: new file, lifted from Aubrey Jaffer's site.
-
-1999-12-04 Gary Houston <ghouston@freewire.co.uk>
-
- * scheme.texi (Generic Port Operations): add "port-closed?".
-
-1999-11-22 Jim Blandy <jimb@savonarola.red-bean.com>
-
- * mbapi.texi: Don't promise any behavior on ill-formed text.
-
-1999-11-19 Gary Houston <ghouston@freewire.co.uk>
-
- * scheme.texi: rewrote the intros in the array nodes.
-
-1999-11-18 Gary Houston <ghouston@freewire.co.uk>
-
- * posix.texi (Network Sockets and Communication): add htons etc.
- (Ports and File Descriptors, Network Sockets and Communication):
- suggest setvbuf instead of duplicate-port for converting
- unbuffered ports to buffered.
-
- * scheme.texi (Uniform Array): add missing array types to the
- table.
-
-1999-11-17 Gary Houston <ghouston@freewire.co.uk>
-
- * posix.texi (Network Databases): updated.
-
-1999-10-24 Gary Houston <ghouston@freewire.co.uk>
-
- * scheme.texi (String Ports): add with-output-to-string and
- with-input-from-string.
- (Port Implementation): update for ptob seek.
-
-1999-10-18 Gary Houston <ghouston@freewire.co.uk>
-
- * scheme.texi (C Port Interface): update the description of
- the rw_random port flag.
-
-1999-09-22 Gary Houston <ghouston@freewire.co.uk>
-
- * scheme.texi: added a bit of documentation for port internals.
-
-1999-09-12 Gary Houston <ghouston@easynet.co.uk>
-
- * posix.texi (File System): make that "directory-stream?".
-
-1999-09-11 Gary Houston <ghouston@easynet.co.uk>
-
- * posix.texi (File System): added "directory?".
-
-1999-09-06 James Blandy <jimb@mule.m17n.org>
-
- * mbapi.texi, mltext.texi: New files, describing interfaces for
- dealing with multilingual code.
-
-1999-07-25 Gary Houston <ghouston@easynet.co.uk>
-
- * scheme.texi, posix.texi: updated for changes in the I/O system
- and expect macros.
-
-1999-01-25 Mark Galassi <rosalia@cygnus.com>
-
- * scheme.texi (General option interface): applied a typo fix.
- Thanks to Eric Hanchrow (offby1@blarg.net).
-
-1998-11-01 Mark Galassi <rosalia@cygnus.com>
-
- * scheme.texi (Weak References): incorporated David Lutterkort's
- chapter on Weak References, which is based on Mikael's email
- message exchange with with Michael Livshin.
-
-1998-10-29 Jim Blandy <jimb@zwingli.cygnus.com>
-
- * scheme.texi: Corrected shell commands in example. (Thanks to
- Chris Bitmead.)
-
-1998-10-25 Mikael Djurfeldt <mdj@barbara.nada.kth.se>
-
- * gh.texi (C to Scheme, Scheme to C): Completed entries about
- vector conversions.
-
-1998-08-26 Mark Galassi <rosalia@cygnus.com>
-
- * gh.texi (Starting and controlling the interpreter): modified the
- gh_enter() docs in response to some good comments from Dirk
- Herrmann: now they address the issue of loading ice-9/boot-9.scm,
- and include Dirk's hackaround for the problem until we fix it
- properly.
-
-1998-04-29 Mark Galassi <rosalia@cygnus.com>
-
- * scheme.texi (Dynamic Linking from Marius): added Marius's new
- chapter on dynamic linking; there is still a section in dynamic
- linking (written by Tim maybe?), and I have to examine how to
- resolve that.
-
-1998-03-30 Mikael Djurfeldt <mdj@nada.kth.se>
-
- * scheme.texi (Port Operations): Changed entry for port-column and
- port-line. (Thanks to Per Bothner.)
-
-1998-02-02 Mikael Djurfeldt <mdj@mdj.nada.kth.se>
-
- * scheme.texi (Exceptions): Adjusted documentation to reflect the
- removal of the (catch #f ...) mechanism.
-
-1998-01-28 Mark Galassi <rosalia@nis.lanl.gov>
-
- * guile-ref.texi: changed @dircategory to "Scheme Programming".
- It seems to be the consensus.
-
-1998-01-20 Mikael Djurfeldt <mdj@mdj.nada.kth.se>
-
- * gh.texi (C to Scheme): Added documentation for gh_doubles2scm
- and gh_doubles2dvect.
- (Scheme to C): Added documentation for gh_scm2doubles.
-
-1998-01-15 Mark Galassi <rosalia@nis.lanl.gov>
-
- * gh.texi (Calling Scheme procedures from C): removed
- gh_make_subr() since Mikael pointed out that it is gone from
- Guile. I don't remember its history any more, but I don't think
- anyone is missing it.
-
-1998-01-03 Tim Pierce <twp@skepsis.com>
-
- * scheme.texi (Evaluation): Several corrections supplied by MDJ.
-
-Sat Dec 27 19:02:36 1997 Tim Pierce <twp@skepsis.com>
-
- * appendices.texi (Internals, Symbols): New nodes.
- * scheme.texi (Configuration Data): New node.
-
-1997-12-27 Tim Pierce <twp@skepsis.com>
-
- * guile-ref.texi (Bitwise Operations): New description.
-
-1997-12-24 Tim Pierce <twp@skepsis.com>
-
- * scheme.texi (Port Operations, Evaluation): New nodes.
-
-1997-12-13 Tim Pierce <twp@skepsis.com>
-
- * scheme.texi, posix.texi: Documented each procedure as `procedure',
- `primitive' or `syntax' as appropriate.
- (Records): Change record-type-field-names to record-type-fields.
- (Low level thread primitives): Change with-new-thread to
- call-with-new-thread.
-
-Sun Dec 7 22:47:22 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * posix.texi (Processes): add "system" procedure.
-
-1997-11-23 Mark Galassi <rosalia@cygnus.com>
-
- * gh.texi (Starting and controlling the interpreter): added
- documentation for gh_repl() -- gh_repl() has changed since I saw
- the scm_shell() routine.
-
-1997-11-19 Tim Pierce <twp@twp.tezcat.com>
-
- * scheme.texi (String Fun): New node.
- (Hash Tables): Added `get-handle' and `create-handle!' docs.
-
- * posix.texi (Networking Databases): Add docs for gethost, getnet,
- getserv, getproto. Expanded on miscellaneous docs.
-
-1997-11-18 Tim Pierce <twp@twp.tezcat.com>
-
- * posix.texi: New file; moved docs for POSIX interface here.
- * Makefile.am: Add posix.texi.
- * Makefile.in: Regenerated.
- * guile-ref.texi: Reorganize top-level menu. @include posix.texi.
- * scheme.texi: Moved many nodes around, some restructuring
- (e.g. new "Data Structures" node for records, structures, arrays,
- hash tables, and so on).
-
-1997-10-19 Mark Galassi <rosalia@cygnus.com>
-
- * gh.texi (Calling Scheme procedures from C): added many routines
- as I go through R4RS and try to complete the gh_ interface.
-
-Wed Oct 8 04:51:54 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * scheme.texi (Dynamic Roots): added batch mode procedures.
-
-1997-10-03 Mikael Djurfeldt <mdj@nada.kth.se>
-
- * scheme.texi (Vtables): Changed 0 --> @code{vtable-index-layout};
- Changed @code{struct-vtable-offset} --> @code{vtable-offset-user};
- Added short note about the print call-back initializer. (This
- section is in need of review. However, we shoudn't spend much
- time on it since the structs will be replaced by something
- equivalent, but with a different interface.}
-
-Sun Sep 28 00:02:35 1997 Mark Galassi <rosalia@nis.lanl.gov>
-
- * scheme.texi (Keywords): very small re-organization to take
- advantage of the fact that read-options is now documented in
- another chapter.
-
-Thu Sep 25 23:37:02 1997 Mark Galassi <rosalia@nis.lanl.gov>
-
- * scheme.texi (Guile options interface): renamed the symbol case
- section to "Guile options interface". "Reader options" is now a
- subsection of that. I've finally figured a lot of how options
- work, thanks to discovering Mikael's comments in options.c and an
- old note from Mikael to Jim describing it.
- (Guile options interface): reorganized the individual option
- groups. This section (on options) of the manual is now reasonably
- complete, unless I am completely missing something.
-
-Wed Sep 24 15:25:03 1997 Mark Galassi <rosalia@nis.lanl.gov>
-
- * scheme.texi (The Guile module system): Added a bit more to this
- chapter, mostly the more user-friendly (use-modules (ice-9
- module-name)) approach.
- (Symbol case): tried to write something about this, but it will
- need to be reviewed by someone who understands the big picture of
- read options. I also think the section name should be changed to
- something like "Read options".
-
-Sun Sep 21 18:45:57 1997 Mark Galassi <rosalia@nis.lanl.gov>
-
- * scheme.texi (SLIB): some little details, including splitting off
- what does in the installation chapter. Also added a section on
- Jacal, which has some open issues.
-
- * appendices.texi (Packages not shipped with Guile): added this
- section to describe getting resources on SCSH, SLIB and Jacal (and
- who knows what else in the future).
-
-Sat Aug 30 19:31:22 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * scheme.texi (Uniform Array): mention start and end arguments
- for uniform-array-read! and uniform-array-write.
-
-Sat Aug 23 19:05:08 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * guile-ref.texi (Top): corresponding changes.
- * scheme.texi (Exception Handling): add scm-error, strerror.
- (Exceptions): renamed from Exception Handling.
- (Exceptions): deleted empty section.
-
-Mon Aug 18 16:11:43 1997 Jim Blandy <jimb@totoro.red-bean.com>
-
- * texinfo.tex: Installed from texinfo release 3.11.
-
-Fri Aug 15 08:14:32 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * scheme.texi (file system): added truncate-file.
- chown, fcntl, fseek, ftell updated.
- (ports vs file descriptors): added fsync, open, open-fdes.
- (time): added times.
-
-Sun Aug 10 07:39:55 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * scheme.texi (processes): added execle.
-
-Tue Jul 29 02:01:21 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * setvbuf added. primitive-dup[2] removed.
-
-Sat Jul 26 04:25:40 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * various close and dup procedures added, plus setenv.
-
-Sat Jul 19 04:04:50 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * scheme.texi (signals): new section.
- (processes): primitive-exit.
- (ports vs. file descriptors): force-output, flush-all-ports.
- fcntl from NEWS.
-
-Fri Jul 18 07:58:52 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * scheme.texi (SLIB): update initialization details.
- (expect): likewise.
- (The Scheme shell (scsh)): likewise.
-
-Fri Jun 27 00:31:25 1997 Tim Pierce <twp@twp.tezcat.com>
-
- * scheme.texi (Regexp Functions): Add docs for make-regexp flags
- regexp/icase, regexp/newline, regexp/basic, regexp/extended.
-
-Mon Jun 23 12:35:57 1997 Tim Pierce <twpierce@bio-5.bsd.uchicago.edu>
-
- * appendices.texi (debugger user interface): new text.
- (Single-Step, Trace, Backtrace): new nodes.
-
- * scheme.texi: Many revised nodes, some new ones.
-
- (Binary Numeric Operations, Input/Output Ports, File Ports, Soft
- Ports, String Ports): Imported documentation from SCM and SLIB manuals.
-
- (Association Lists and Hash Tables, Dictionary Types, Association
- Lists, Hash Tables): New nodes.
- (Dictionaries in general): Removed.
-
- (Regular Expressions): Replaced.
- (Rx Interface): New node, renamed from old `Regular Expressions'.
- (Regexp Functions, Match Functions, Backslash Escapes): new nodes.
-
- (Property Lists): new node with documentation for both object and
- procedure properties.
- (Object Properties): removed.
- * guile-ref.texi: change `Object Properties' to `Property Lists'.
-
diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am
deleted file mode 100644
index 584bd8229..000000000
--- a/doc/ref/Makefile.am
+++ /dev/null
@@ -1,62 +0,0 @@
-## Process this file with Automake to create Makefile.in
-##
-## Copyright (C) 1998 Free Software Foundation, Inc.
-##
-## This file is part of GUILE.
-##
-## GUILE 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 2, or
-## (at your option) any later version.
-##
-## GUILE 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 GUILE; see the file COPYING. If not, write
-## to the Free Software Foundation, Inc., 59 Temple Place, Suite
-## 330, Boston, MA 02111-1307 USA
-
-AUTOMAKE_OPTIONS = gnu
-
-info_TEXINFOS = guile.texi
-
-guile_TEXINFOS = preface.texi intro.texi program.texi scheme-intro.texi \
- scheme-ideas.texi scheme-data.texi scheme-procedures.texi \
- scheme-utility.texi scheme-binding.texi scheme-control.texi \
- scheme-io.texi scheme-evaluation.texi scheme-memory.texi \
- scheme-modules.texi scheme-scheduling.texi scheme-options.texi \
- scheme-translation.texi scheme-debug.texi deprecated.texi \
- scheme-reading.texi scheme-indices.texi slib.texi posix.texi \
- expect.texi scsh.texi tcltk.texi scripts.texi gh.texi scm.texi \
- debugging.texi indices.texi script-getopt.texi data-rep.texi \
- extend.texi repl-modules.texi srfi-modules.texi misc-modules.texi \
- scheme-compound.texi autoconf.texi autoconf-macros.texi tools.texi
-
-ETAGS_ARGS = $(info_TEXINFOS) $(guile_TEXINFOS)
-
-include $(top_srcdir)/am/pre-inst-guile
-
-# Automated snarfing
-
-autoconf.texi: autoconf-macros.texi
-autoconf-macros.texi: $(top_srcdir)/guile-config/guile.m4
- $(preinstguiletool)/snarf-guile-m4-docs $< > $(srcdir)/$@
-
-# Optionally support building an HTML version of the reference manual.
-
-if HTMLDOC
-
-htmldir = $(prefix)/html/guile-$(VERSION)
-
-html_DATA = guile_toc.html $(shell ls guile_*.html 2>/dev/null)
-
-guile_toc.html: guile.texi $(guile_TEXINFOS)
- $(TEXI2HTML) -split_chapter $(srcdir)/guile.texi
-
-endif
-
-CLEANFILES = autoconf-macros.texi \
- guile.cps guile.fns guile.rns guile.tps guile.vrs guile.tmp
diff --git a/doc/ref/api.txt b/doc/ref/api.txt
deleted file mode 100644
index cc26b839f..000000000
--- a/doc/ref/api.txt
+++ /dev/null
@@ -1,185 +0,0 @@
-Scheme objects
-==============
-
-There are two basic C data types to represent objects in guile:
-
-- SCM: SCM is the user level abstract C type that is used to represent all of
-guile's scheme objects, no matter what the scheme object type is. No C
-operation except assignment is guaranteed to work with variables of type SCM.
-Only use macros and functions to work with SCM values. Values are converted
-between C data types and the SCM type with utility functions and macros.
-
-- scm_bits_t: An integral data type that is guaranteed to be large enough to
-hold all information that is required to represent any scheme object. While
-this data type is used to implement guile internals, the use of this type is
-also necessary to write certain kinds of extensions to guile.
-
-
-Relationship between SCM and scm_bits_t
-=======================================
-
-A variable of type SCM is guaranteed to hold a valid scheme object. A
-variable of type scm_bits_t, however, may either hold a representation of a
-SCM value as a C integral type, but may also hold any C value, even if it does
-not correspond to a valid scheme object.
-
-For a variable x of type SCM, the scheme object's type information is stored
-in a form that is not directly usable. To be able to work on the type
-encoding of the scheme value, the SCM variable has to be transformed into the
-corresponding representation as a scm_bits_t variable y by using the
-SCM_UNPACK macro. After this has been done, the type of the scheme object x
-can be derived from the content of the bits of the scm_bits_t value y, as is
-described in -->data-rep. A valid bit encoding of a scheme value as a
-scm_bits_t variable can be transformed into the corresponding SCM value by
-using the SCM_PACK macro.
-
-- scm_bits_t SCM_UNPACK (SCM x): Transforms the SCM value x into it's
-representation as an integral type. Only after applying SCM_UNPACK it is
-possible to access the bits and contents of the SCM value.
-
-- SCM SCM_PACK (scm_bits_t x): Takes a valid integral representation of a
-scheme object and transforms it into its representation as a SCM value.
-
-
-Immediate objects
-=================
-
-A scheme object may either be an immediate, i. e. carrying all necessary
-information by itself, or it may contain a reference to a 'cell' with
-additional information on the heap. While the fact, whether an object is an
-immediate or not should be irrelevant for user code, within guile's own code
-the distinction is sometimes of importance. Thus, the following low level
-macro is provided:
-
-- int SCM_IMP (SCM x): A scheme object is an immediate if it fullfills the
-SCM_IMP predicate, otherwise it holds an encoded reference to a heap cell.
-The result of the predicate is delivered as a C style boolean value. User
-code and code that extends guile should normally not be required to use this
-macro.
-
-Summary:
-* For a scheme object x of unknown type, check first with SCM_IMP (x) if it is
-an immediate object. If so, all of the type and value information can be
-determined from the scm_bits_t value that is delivered by SCM_UNPACK (x).
-
-
-Non immediate objects
-=====================
-
-- (scm_t_cell *) SCM2PTR (SCM x) (FIXME:: this name should be changed)
-- SCM PTR2SCM (scm_t_cell * x) (FIXME:: this name should be changed)
-
-A scheme object of type SCM that does not fullfill the SCM_IMP predicate holds
-an encoded reference to a heap cell. This reference can be decoded to a C
-pointer to a heap cell using the SCM2PTR macro. The encoding of a pointer to
-a heap cell into a SCM value is done using the PTR2SCM macro.
-
-Note that it is also possible to transform a non immediate SCM value by using
-SCM_UNPACK into a scm_bits_t variable. Hower, the result of SCM_UNPACK may
-not be used as a pointer to a scm_t_cell: Only SCM2PTR is guaranteed to
-transform a SCM object into a valid pointer to a heap cell. Also, it is not
-allowed to apply PTR2SCM to anything that is not a valid pointer to a heap
-cell.
-
-Summary:
-* Only use SCM2PTR for SCM values for which SCM_IMP is false!
-* Don't use '(scm_t_cell*) SCM_UNPACK (x)'! Use 'SCM2PTR (x)' instead!
-* Don't use PTR2SCM for anything but a cell pointer!
-
-
-Heap Cell Type Information
-==========================
-
-Heap cells contain a number of entries, each of which is either a scheme
-object of type SCM or a raw C value of type scm_bits_t. Which of the cell
-entries contain scheme objects and which contain raw C values is determined by
-the first entry of the cell, which holds the cell type information.
-
-- scm_bits_t SCM_CELL_TYPE (SCM x): For a non immediate scheme object x,
-deliver the content of the first entry of the heap cell referenced by x. This
-value holds the information about the cell type as described in -->data-rep.
-
-- void SCM_SET_CELL_TYPE (SCM x, scm_bits_t t): For a non immediate scheme
-object x, write the value t into the first entry of the heap cell referenced
-by x. The value t must hold a valid cell type as described in -->data-rep.
-
-
-Accessing Cell Entries
-======================
-
-For a non immediate scheme object x, the object type can be determined by
-reading the cell type entry using the SCM_CELL_TYPE macro. For the different
-types of cells it is known which cell entry holds scheme objects and which cell
-entry holds raw C data. To access the different cell entries appropriately,
-the following macros are provided:
-
-- scm_bits_t SCM_CELL_WORD (SCM x, unsigned int n): Deliver the cell entry n
-of the heap cell referenced by the non immediate scheme object x as raw data.
-It is illegal, to access cell entries that hold scheme objects by using these
-macros. For convenience, the following macros are also provided:
- SCM_CELL_WORD_0 (x) --> SCM_CELL_WORD (x, 0)
- SCM_CELL_WORD_1 (x) --> SCM_CELL_WORD (x, 1)
- ...
- SCM_CELL_WORD_n (x) --> SCM_CELL_WORD (x, n)
-
-- SCM SCM_CELL_OBJECT (SCM x, unsigned int n): Deliver the cell entry n of
-the heap cell referenced by the non immediate scheme object x as a scheme
-object. It is illegal, to access cell entries that do not hold scheme objects
-by using these macros. For convenience, the following macros are also
-provided:
- SCM_CELL_OBJECT_0 (x) --> SCM_CELL_OBJECT (x, 0)
- SCM_CELL_OBJECT_1 (x) --> SCM_CELL_OBJECT (x, 1)
- ...
- SCM_CELL_OBJECT_n (x) --> SCM_CELL_OBJECT (x, n)
-
-- void SCM_SET_CELL_WORD (SCM x, unsigned int n, scm_bits_t w): Write the raw
-C value w into entry number n of the heap cell referenced by the non immediate
-scheme value x. Values that are written into cells this way may only be read
-from the cells using the SCM_CELL_WORD macros or, in case cell entry 0 is
-written, using the SCM_CELL_TYPE macro. For the special case of cell entry 0
-it has to be made sure that w contains a cell type information (see
--->data-rep) which does not describe a scheme object. For convenience, the
-following macros are also provided:
- SCM_SET_CELL_WORD_0 (x, w) --> SCM_SET_CELL_WORD (x, 0, w)
- SCM_SET_CELL_WORD_1 (x, w) --> SCM_SET_CELL_WORD (x, 1, w)
- ...
- SCM_SET_CELL_WORD_n (x, w) --> SCM_SET_CELL_WORD (x, n, w)
-
-- void SCM_SET_CELL_OBJECT (SCM x, unsigned int n, SCM o): Write the scheme
-object o into entry number n of the heap cell referenced by the non immediate
-scheme value x. Values that are written into cells this way may only be read
-from the cells using the SCM_CELL_OBJECT macros or, in case cell entry 0 is
-written, using the SCM_CELL_TYPE macro. For the special case of cell entry 0
-the writing of a scheme object into this cell is only allowed, if the cell
-forms a scheme pair. For convenience, the following macros are also provided:
- SCM_SET_CELL_OBJECT_0 (x, o) --> SCM_SET_CELL_OBJECT (x, 0, o)
- SCM_SET_CELL_OBJECT_1 (x, o) --> SCM_SET_CELL_OBJECT (x, 1, o)
- ...
- SCM_SET_CELL_OBJECT_n (x, o) --> SCM_SET_CELL_OBJECT (x, n, o)
-
-Summary:
-* For a non immediate scheme object x of unknown type, get the type
- information by using SCM_CELL_TYPE (x).
-* As soon as the cell type information is available, only use the appropriate
- access methods to read and write data to the different cell entries.
-
-
-Basic Rules for Accessing Cell Entries
-======================================
-
-For each cell type it is generally up to the implementation of that type which
-of the corresponding cell entries hold scheme objects and which hold raw C
-values. However, there is one basic rules that has to be followed: Scheme
-pairs consist of exactly two cell entries, which both contain scheme objects.
-Further, a cell which contains a scheme object in it first entry has to be a
-scheme pair. In other words, it is not allowed to store a scheme object in
-the first cell entry and a non scheme object in the second cell entry.
-
-Fixme:shouldn't this rather be SCM_PAIRP / SCM_PAIR_P ?
-- int SCM_CONSP (SCM x): Determine, whether the scheme object x is a scheme
-pair, i. e. whether x references a heap cell consisting of exactly two
-entries, where both entries contain a scheme object. In this case, both
-entries will have to be accessed using the SCM_CELL_OBJECT macros. On the
-contrary, if the SCM_CONSP predicate is not fulfilled, the first entry of the
-scheme cell is guaranteed not to be a scheme value and thus the first cell
-entry must be accessed using the SCM_CELL_WORD_0 macro.
diff --git a/doc/ref/autoconf.texi b/doc/ref/autoconf.texi
deleted file mode 100644
index 8d05b2ecc..000000000
--- a/doc/ref/autoconf.texi
+++ /dev/null
@@ -1,234 +0,0 @@
-@page
-@node Autoconf Support
-@chapter Autoconf Support
-
-When Guile is installed, a set of autoconf macros is also installed as
-PREFIX/share/aclocal/guile.m4. This chapter documents the macros provided in
-that file, as well as the high-level guile-tool Autofrisk. @xref{Top,The GNU
-Autoconf Manual,,autoconf}, for more info.
-
-@menu
-* Autoconf Background:: Why use autoconf?
-* Autoconf Macros:: The GUILE_* macros.
-* Using Autoconf Macros:: How to use them, plus examples.
-* Autofrisk:: AUTOFRISK_CHECKS and AUTOFRISK_SUMMARY.
-* Using Autofrisk:: Example modules.af files.
-@end menu
-
-
-@node Autoconf Background
-@section Autoconf Background
-
-As explained elsewhere (@pxref{Top,The GNU Autoconf Manual,,autoconf}), any
-package needs configuration at build-time. If your package uses Guile (or
-uses a package that in turn uses Guile), you probably need to know what
-specific Guile features are available and details about them.
-
-The way to do this is to write feature tests and arrange for their execution
-by the @file{configure} script, typically by adding the tests to
-@file{configure.ac}, and running @code{autoconf} to create @file{configure}.
-Users of your package then run @file{configure} in the normal way.
-
-Macros are a way to make common feature tests easy to express. Autoconf
-provides a wide range of macros (@pxref{Existing Tests,,,autoconf}), and
-Guile installation provides Guile-specific tests in the areas of:
-program detection, compilation flags reporting, and Scheme module
-checks.
-
-
-@node Autoconf Macros
-@section Autoconf Macros
-
-The macro names all begin with "GUILE_".
-
-@c see Makefile.am
-@include autoconf-macros.texi
-
-
-@node Using Autoconf Macros
-@section Using Autoconf Macros
-
-Using the autoconf macros is straightforward: Add the macro "calls" (actually
-instantiations) to @file{configure.ac}, run @code{aclocal}, and finally,
-run @code{autoconf}. If your system doesn't have guile.m4 installed, place
-the desired macro definitions (@code{AC_DEFUN} forms) in @file{acinclude.m4},
-and @code{aclocal} will do the right thing.
-
-Some of the macros can be used inside normal shell constructs: @code{if foo ;
-then GUILE_BAZ ; fi}, but this is not guaranteed. It's probably a good idea
-to instantiate macros at top-level.
-
-We now include two examples, one simple and one complicated.
-
-The first example is for a package that uses libguile, and thus needs to know
-how to compile and link against it. So we use @code{GUILE_FLAGS} to set the
-vars @code{GUILE_CFLAGS} and @code{GUILE_LDFLAGS}, which are automatically
-substituted in the Makefile.
-
-@example
-In configure.ac:
-
- GUILE_FLAGS
-
-In Makefile.in:
-
- GUILE_CFLAGS = @@GUILE_CFLAGS@@
- GUILE_LDFLAGS = @@GUILE_LDFLAGS@@
-
- myprog.o: myprog.c
- $(CC) -o $@ $(GUILE_CFLAGS) $<
- myprog: myprog.o
- $(CC) -o $@ $< $(GUILE_LDFLAGS)
-@end example
-
-The second example is for a package of Guile Scheme modules that uses an
-external program and other Guile Scheme modules (some might call this a "pure
-scheme" package). So we use the @code{GUILE_SITE_DIR} macro, a regular
-@code{AC_PATH_PROG} macro, and the @code{GUILE_MODULE_AVAILABLE} macro.
-
-@example
-In configure.ac:
-
- GUILE_SITE_DIR
-
- probably_wont_work=""
-
- # pgtype pgtable
- GUILE_MODULE_AVAILABLE(have_guile_pg, (database postgres))
- test $have_guile_pg = no &&
- probably_wont_work="(my pgtype) (my pgtable) $probably_wont_work"
-
- # gpgutils
- AC_PATH_PROG(GNUPG,gpg)
- test x"$GNUPG" = x &&
- probably_wont_work="(my gpgutils) $probably_wont_work"
-
- if test ! "$probably_wont_work" = "" ; then
- p=" ***"
- echo
- echo "$p"
- echo "$p NOTE:"
- echo "$p The following modules probably won't work:"
- echo "$p $probably_wont_work"
- echo "$p They can be installed anyway, and will work if their"
- echo "$p dependencies are installed later. Please see README."
- echo "$p"
- echo
- fi
-
-In Makefile.in:
-
- instdir = @@GUILE_SITE@@/my
-
- install:
- $(INSTALL) my/*.scm $(instdir)
-@end example
-
-
-@node Autofrisk
-@section Autofrisk
-
-The @dfn{guile-tools autofrisk} command looks for the file @file{modules.af}
-in the current directory and writes out @file{modules.af.m4} containing
-autoconf definitions for @code{AUTOFRISK_CHECKS} and @code{AUTOFRISK_SUMMARY}.
-@xref{Autoconf Background}, and @xref{Using Autoconf Macros}, for more info.
-
-The modules.af file consists of a series of configuration forms (Scheme
-lists), which have one of the following formats:
-
-@example
- (files-glob PATTERN ...) ;; required
- (non-critical-external MODULE ...) ;; optional
- (non-critical-internal MODULE ...) ;; optional
- (programs (MODULE PROG ...) ...) ;; optional
- (pww-varname VARNAME) ;; optional
-@end example
-
-@var{pattern} is a string that may contain "*" and "?" characters to be
-expanded into filenames. @var{module} is a list of symbols naming a module,
-such as `(srfi srfi-1)'. @var{varname} is a shell-safe name to use instead of
-@code{probably_wont_work}, the default. This var is passed to `AC_SUBST'.
-@var{prog} is a string that names a program, such as "gpg".
-
-Autofrisk expands the @code{files-glob} pattern(s) into a list of files, scans
-each file's module definition form(s), and constructs a module dependency
-graph wherein modules defined by @code{define-module} are considered
-@dfn{internal} and the remaining, @dfn{external}. For each external module
-that has an internal dependency, Autofrisk emits a
-@code{GUILE_MODULE_REQUIRED} check (@pxref{Autoconf Macros}), which altogether
-form the body of @code{AUTOFRISK_CHECKS}.
-
-@code{GUILE_MODULE_REQUIRED} causes the @file{configure} script to exit with
-an error message if the specified module is not available; it enforces a
-strong dependency. You can temper dependency strength by using the
-@code{non-critical-external} and @code{non-critical-internal} configuration
-forms in modules.af. For graph edges that touch such non-critical modules,
-Autofrisk uses @code{GUILE_MODULE_AVAILABLE}, and arranges for
-@code{AUTOFRISK_SUMMARY} to display a warning if they are not found.
-
-The shell code resulting from the expansion of @code{AUTOFRISK_CHECKS} and
-@code{AUTOFRISK_SUMMARY} uses the shell variable @code{probably_wont_work} to
-collect the names of unfound non-critical modules. If this bothers you, use
-configuration form @code{(pww-name foo)} in modules.af.
-
-Although Autofrisk does not detect when a module uses a program (for example,
-in a @code{system} call), it can generate @code{AC_PATH_PROG} forms anyway if
-you use the @code{programs} configuration form in modules.af. These are
-collected into @code{AUTOCONF_CHECKS}.
-
-@xref{Using Autofrisk}, for some modules.af examples.
-
-
-@node Using Autofrisk
-@section Using Autofrisk
-
-Using Autofrisk (@pxref{Autofrisk}) involves writing @file{modules.af} and
-adding two macro calls to @file{configure.in}. Here is an example of the
-latter:
-
-@example
-AUTOFRISK_CHECKS
-AUTOFRISK_SUMMARY
-@end example
-
-Here is an adaptation of the second "GUILE_*" example (@pxref{Using Autoconf
-Macros}) that does basically the same thing.
-
-@example
-(files-glob "my/*.scm")
-(non-critical-external (database postgres))
-(programs ((my gpgutils) "gpg")) ;; (my gpgutils) uses "gpg"
-@end example
-
-If the SRFI modules (@pxref{SRFI Support}) were a separate package, we could
-use @code{guile-tools frisk} to find out its dependencies:
-
-@example
-$ guile-tools frisk srfi/*.scm
-13 files, 18 modules (13 internal, 5 external), 9 edges
-
-x (ice-9 and-let-star)
- regular (srfi srfi-2)
-x (ice-9 syncase)
- regular (srfi srfi-11)
-x (ice-9 rdelim)
- regular (srfi srfi-10)
-x (ice-9 receive)
- regular (srfi srfi-8)
- regular (srfi srfi-1)
-x (ice-9 session)
- regular (srfi srfi-1)
-@end example
-
-Then, we could use the following modules.af to help configure it:
-
-@example
-(files-glob "srfi/*.scm")
-(non-critical-external ;; relatively recent
- (ice-9 rdelim)
- (ice-9 receive)
- (ice-9 and-let-star))
-(pww-varname not_fully_supported)
-@end example
-
-@c autoconf.texi ends here
diff --git a/doc/ref/data-rep.texi b/doc/ref/data-rep.texi
deleted file mode 100644
index 30fcee6c6..000000000
--- a/doc/ref/data-rep.texi
+++ /dev/null
@@ -1,2047 +0,0 @@
-@c essay \input texinfo
-@c essay @c -*-texinfo-*-
-@c essay @c %**start of header
-@c essay @setfilename data-rep.info
-@c essay @settitle Data Representation in Guile
-@c essay @c %**end of header
-
-@c essay @include version.texi
-
-@c essay @dircategory The Algorithmic Language Scheme
-@c essay @direntry
-@c essay * data-rep: (data-rep). Data Representation in Guile --- how to use
-@c essay Guile objects in your C code.
-@c essay @end direntry
-
-@c essay @setchapternewpage off
-
-@c essay @ifinfo
-@c essay Data Representation in Guile
-
-@c essay Copyright (C) 1998, 1999, 2000 Free Software Foundation
-
-@c essay Permission is granted to make and distribute verbatim copies of
-@c essay this manual provided the copyright notice and this permission notice
-@c essay are preserved on all copies.
-
-@c essay @ignore
-@c essay Permission is granted to process this file through TeX and print the
-@c essay results, provided the printed document carries copying permission
-@c essay notice identical to this one except for the removal of this paragraph
-@c essay (this paragraph not being relevant to the printed manual).
-@c essay @end ignore
-
-@c essay Permission is granted to copy and distribute modified versions of this
-@c essay manual under the conditions for verbatim copying, provided that the entire
-@c essay resulting derived work is distributed under the terms of a permission
-@c essay notice identical to this one.
-
-@c essay Permission is granted to copy and distribute translations of this manual
-@c essay into another language, under the above conditions for modified versions,
-@c essay except that this permission notice may be stated in a translation approved
-@c essay by the Free Software Foundation.
-@c essay @end ifinfo
-
-@c essay @titlepage
-@c essay @sp 10
-@c essay @comment The title is printed in a large font.
-@c essay @title Data Representation in Guile
-@c essay @subtitle $Id: data-rep.texi,v 1.7 2002-03-29 20:25:23 ossau Exp $
-@c essay @subtitle For use with Guile @value{VERSION}
-@c essay @author Jim Blandy
-@c essay @author Free Software Foundation
-@c essay @author @email{jimb@@red-bean.com}
-@c essay @c The following two commands start the copyright page.
-@c essay @page
-@c essay @vskip 0pt plus 1filll
-@c essay @vskip 0pt plus 1filll
-@c essay Copyright @copyright{} 1998 Free Software Foundation
-
-@c essay Permission is granted to make and distribute verbatim copies of
-@c essay this manual provided the copyright notice and this permission notice
-@c essay are preserved on all copies.
-
-@c essay Permission is granted to copy and distribute modified versions of this
-@c essay manual under the conditions for verbatim copying, provided that the entire
-@c essay resulting derived work is distributed under the terms of a permission
-@c essay notice identical to this one.
-
-@c essay Permission is granted to copy and distribute translations of this manual
-@c essay into another language, under the above conditions for modified versions,
-@c essay except that this permission notice may be stated in a translation approved
-@c essay by Free Software Foundation.
-@c essay @end titlepage
-
-@c essay @c @smallbook
-@c essay @c @finalout
-@c essay @headings double
-
-
-@c essay @node Top, Data Representation in Scheme, (dir), (dir)
-@c essay @top Data Representation in Guile
-
-@c essay @ifinfo
-@c essay This essay is meant to provide the background necessary to read and
-@c essay write C code that manipulates Scheme values in a way that conforms to
-@c essay libguile's interface. If you would like to write or maintain a
-@c essay Guile-based application in C or C++, this is the first information you
-@c essay need.
-
-@c essay In order to make sense of Guile's @code{SCM_} functions, or read
-@c essay libguile's source code, it's essential to have a good grasp of how Guile
-@c essay actually represents Scheme values. Otherwise, a lot of the code, and
-@c essay the conventions it follows, won't make very much sense.
-
-@c essay We assume you know both C and Scheme, but we do not assume you are
-@c essay familiar with Guile's C interface.
-@c essay @end ifinfo
-
-
-@page
-@node Data Representation
-@chapter Data Representation in Guile
-
-@strong{by Jim Blandy}
-
-[Due to the rather non-orthogonal and performance-oriented nature of the
-SCM interface, you need to understand SCM internals *before* you can use
-the SCM API. That's why this chapter comes first.]
-
-[NOTE: this is Jim Blandy's essay almost entirely unmodified. It has to
-be adapted to fit this manual smoothly.]
-
-In order to make sense of Guile's SCM_ functions, or read libguile's
-source code, it's essential to have a good grasp of how Guile actually
-represents Scheme values. Otherwise, a lot of the code, and the
-conventions it follows, won't make very much sense. This essay is meant
-to provide the background necessary to read and write C code that
-manipulates Scheme values in a way that is compatible with libguile.
-
-We assume you know both C and Scheme, but we do not assume you are
-familiar with Guile's implementation.
-
-@menu
-* Data Representation in Scheme:: Why things aren't just totally
- straightforward, in general terms.
-* How Guile does it:: How to write C code that manipulates
- Guile values, with an explanation
- of Guile's garbage collector.
-* Defining New Types (Smobs):: How to extend Guile with your own
- application-specific datatypes.
-@end menu
-
-@node Data Representation in Scheme
-@section Data Representation in Scheme
-
-Scheme is a latently-typed language; this means that the system cannot,
-in general, determine the type of a given expression at compile time.
-Types only become apparent at run time. Variables do not have fixed
-types; a variable may hold a pair at one point, an integer at the next,
-and a thousand-element vector later. Instead, values, not variables,
-have fixed types.
-
-In order to implement standard Scheme functions like @code{pair?} and
-@code{string?} and provide garbage collection, the representation of
-every value must contain enough information to accurately determine its
-type at run time. Often, Scheme systems also use this information to
-determine whether a program has attempted to apply an operation to an
-inappropriately typed value (such as taking the @code{car} of a string).
-
-Because variables, pairs, and vectors may hold values of any type,
-Scheme implementations use a uniform representation for values --- a
-single type large enough to hold either a complete value or a pointer
-to a complete value, along with the necessary typing information.
-
-The following sections will present a simple typing system, and then
-make some refinements to correct its major weaknesses. However, this is
-not a description of the system Guile actually uses. It is only an
-illustration of the issues Guile's system must address. We provide all
-the information one needs to work with Guile's data in @ref{How Guile
-does it}.
-
-
-@menu
-* A Simple Representation::
-* Faster Integers::
-* Cheaper Pairs::
-* Guile Is Hairier::
-@end menu
-
-@node A Simple Representation
-@subsection A Simple Representation
-
-The simplest way to meet the above requirements in C would be to
-represent each value as a pointer to a structure containing a type
-indicator, followed by a union carrying the real value. Assuming that
-@code{SCM} is the name of our universal type, we can write:
-
-@example
-enum type @{ integer, pair, string, vector, ... @};
-
-typedef struct value *SCM;
-
-struct value @{
- enum type type;
- union @{
- int integer;
- struct @{ SCM car, cdr; @} pair;
- struct @{ int length; char *elts; @} string;
- struct @{ int length; SCM *elts; @} vector;
- ...
- @} value;
-@};
-@end example
-with the ellipses replaced with code for the remaining Scheme types.
-
-This representation is sufficient to implement all of Scheme's
-semantics. If @var{x} is an @code{SCM} value:
-@itemize @bullet
-@item
- To test if @var{x} is an integer, we can write @code{@var{x}->type == integer}.
-@item
- To find its value, we can write @code{@var{x}->value.integer}.
-@item
- To test if @var{x} is a vector, we can write @code{@var{x}->type == vector}.
-@item
- If we know @var{x} is a vector, we can write
- @code{@var{x}->value.vector.elts[0]} to refer to its first element.
-@item
- If we know @var{x} is a pair, we can write
- @code{@var{x}->value.pair.car} to extract its car.
-@end itemize
-
-
-@node Faster Integers
-@subsection Faster Integers
-
-Unfortunately, the above representation has a serious disadvantage. In
-order to return an integer, an expression must allocate a @code{struct
-value}, initialize it to represent that integer, and return a pointer to
-it. Furthermore, fetching an integer's value requires a memory
-reference, which is much slower than a register reference on most
-processors. Since integers are extremely common, this representation is
-too costly, in both time and space. Integers should be very cheap to
-create and manipulate.
-
-One possible solution comes from the observation that, on many
-architectures, structures must be aligned on a four-byte boundary.
-(Whether or not the machine actually requires it, we can write our own
-allocator for @code{struct value} objects that assures this is true.)
-In this case, the lower two bits of the structure's address are known to
-be zero.
-
-This gives us the room we need to provide an improved representation
-for integers. We make the following rules:
-@itemize @bullet
-@item
-If the lower two bits of an @code{SCM} value are zero, then the SCM
-value is a pointer to a @code{struct value}, and everything proceeds as
-before.
-@item
-Otherwise, the @code{SCM} value represents an integer, whose value
-appears in its upper bits.
-@end itemize
-
-Here is C code implementing this convention:
-@example
-enum type @{ pair, string, vector, ... @};
-
-typedef struct value *SCM;
-
-struct value @{
- enum type type;
- union @{
- struct @{ SCM car, cdr; @} pair;
- struct @{ int length; char *elts; @} string;
- struct @{ int length; SCM *elts; @} vector;
- ...
- @} value;
-@};
-
-#define POINTER_P(x) (((int) (x) & 3) == 0)
-#define INTEGER_P(x) (! POINTER_P (x))
-
-#define GET_INTEGER(x) ((int) (x) >> 2)
-#define MAKE_INTEGER(x) ((SCM) (((x) << 2) | 1))
-@end example
-
-Notice that @code{integer} no longer appears as an element of @code{enum
-type}, and the union has lost its @code{integer} member. Instead, we
-use the @code{POINTER_P} and @code{INTEGER_P} macros to make a coarse
-classification of values into integers and non-integers, and do further
-type testing as before.
-
-Here's how we would answer the questions posed above (again, assume
-@var{x} is an @code{SCM} value):
-@itemize @bullet
-@item
- To test if @var{x} is an integer, we can write @code{INTEGER_P (@var{x})}.
-@item
- To find its value, we can write @code{GET_INTEGER (@var{x})}.
-@item
- To test if @var{x} is a vector, we can write:
-@example
- @code{POINTER_P (@var{x}) && @var{x}->type == vector}
-@end example
- Given the new representation, we must make sure @var{x} is truly a
- pointer before we dereference it to determine its complete type.
-@item
- If we know @var{x} is a vector, we can write
- @code{@var{x}->value.vector.elts[0]} to refer to its first element, as
- before.
-@item
- If we know @var{x} is a pair, we can write
- @code{@var{x}->value.pair.car} to extract its car, just as before.
-@end itemize
-
-This representation allows us to operate more efficiently on integers
-than the first. For example, if @var{x} and @var{y} are known to be
-integers, we can compute their sum as follows:
-@example
-MAKE_INTEGER (GET_INTEGER (@var{x}) + GET_INTEGER (@var{y}))
-@end example
-Now, integer math requires no allocation or memory references. Most
-real Scheme systems actually use an even more efficient representation,
-but this essay isn't about bit-twiddling. (Hint: what if pointers had
-@code{01} in their least significant bits, and integers had @code{00}?)
-
-
-@node Cheaper Pairs
-@subsection Cheaper Pairs
-
-However, there is yet another issue to confront. Most Scheme heaps
-contain more pairs than any other type of object; Jonathan Rees says
-that pairs occupy 45% of the heap in his Scheme implementation, Scheme
-48. However, our representation above spends three @code{SCM}-sized
-words per pair --- one for the type, and two for the @sc{car} and
-@sc{cdr}. Is there any way to represent pairs using only two words?
-
-Let us refine the convention we established earlier. Let us assert
-that:
-@itemize @bullet
-@item
- If the bottom two bits of an @code{SCM} value are @code{#b00}, then
- it is a pointer, as before.
-@item
- If the bottom two bits are @code{#b01}, then the upper bits are an
- integer. This is a bit more restrictive than before.
-@item
- If the bottom two bits are @code{#b10}, then the value, with the bottom
- two bits masked out, is the address of a pair.
-@end itemize
-
-Here is the new C code:
-@example
-enum type @{ string, vector, ... @};
-
-typedef struct value *SCM;
-
-struct value @{
- enum type type;
- union @{
- struct @{ int length; char *elts; @} string;
- struct @{ int length; SCM *elts; @} vector;
- ...
- @} value;
-@};
-
-struct pair @{
- SCM car, cdr;
-@};
-
-#define POINTER_P(x) (((int) (x) & 3) == 0)
-
-#define INTEGER_P(x) (((int) (x) & 3) == 1)
-#define GET_INTEGER(x) ((int) (x) >> 2)
-#define MAKE_INTEGER(x) ((SCM) (((x) << 2) | 1))
-
-#define PAIR_P(x) (((int) (x) & 3) == 2)
-#define GET_PAIR(x) ((struct pair *) ((int) (x) & ~3))
-@end example
-
-Notice that @code{enum type} and @code{struct value} now only contain
-provisions for vectors and strings; both integers and pairs have become
-special cases. The code above also assumes that an @code{int} is large
-enough to hold a pointer, which isn't generally true.
-
-
-Our list of examples is now as follows:
-@itemize @bullet
-@item
- To test if @var{x} is an integer, we can write @code{INTEGER_P
- (@var{x})}; this is as before.
-@item
- To find its value, we can write @code{GET_INTEGER (@var{x})}, as
- before.
-@item
- To test if @var{x} is a vector, we can write:
-@example
- @code{POINTER_P (@var{x}) && @var{x}->type == vector}
-@end example
- We must still make sure that @var{x} is a pointer to a @code{struct
- value} before dereferencing it to find its type.
-@item
- If we know @var{x} is a vector, we can write
- @code{@var{x}->value.vector.elts[0]} to refer to its first element, as
- before.
-@item
- We can write @code{PAIR_P (@var{x})} to determine if @var{x} is a
- pair, and then write @code{GET_PAIR (@var{x})->car} to refer to its
- car.
-@end itemize
-
-This change in representation reduces our heap size by 15%. It also
-makes it cheaper to decide if a value is a pair, because no memory
-references are necessary; it suffices to check the bottom two bits of
-the @code{SCM} value. This may be significant when traversing lists, a
-common activity in a Scheme system.
-
-Again, most real Scheme systems use a slightly different implementation;
-for example, if GET_PAIR subtracts off the low bits of @code{x}, instead
-of masking them off, the optimizer will often be able to combine that
-subtraction with the addition of the offset of the structure member we
-are referencing, making a modified pointer as fast to use as an
-unmodified pointer.
-
-
-@node Guile Is Hairier
-@subsection Guile Is Hairier
-
-We originally started with a very simple typing system --- each object
-has a field that indicates its type. Then, for the sake of efficiency
-in both time and space, we moved some of the typing information directly
-into the @code{SCM} value, and left the rest in the @code{struct value}.
-Guile itself employs a more complex hierarchy, storing finer and finer
-gradations of type information in different places, depending on the
-object's coarser type.
-
-In the author's opinion, Guile could be simplified greatly without
-significant loss of efficiency, but the simplified system would still be
-more complex than what we've presented above.
-
-
-@node How Guile does it
-@section How Guile does it
-
-Here we present the specifics of how Guile represents its data. We
-don't go into complete detail; an exhaustive description of Guile's
-system would be boring, and we do not wish to encourage people to write
-code which depends on its details anyway. We do, however, present
-everything one need know to use Guile's data.
-
-
-@menu
-* General Rules::
-* Conservative GC::
-* Immediates vs Non-immediates::
-* Immediate Datatypes::
-* Non-immediate Datatypes::
-* Signalling Type Errors::
-* Unpacking the SCM type::
-@end menu
-
-@node General Rules
-@subsection General Rules
-
-Any code which operates on Guile datatypes must @code{#include} the
-header file @code{<libguile.h>}. This file contains a definition for
-the @code{SCM} typedef (Guile's universal type, as in the examples
-above), and definitions and declarations for a host of macros and
-functions that operate on @code{SCM} values.
-
-All identifiers declared by @code{<libguile.h>} begin with @code{scm_}
-or @code{SCM_}.
-
-@c [[I wish this were true, but I don't think it is at the moment. -JimB]]
-@c Macros do not evaluate their arguments more than once, unless documented
-@c to do so.
-
-The functions described here generally check the types of their
-@code{SCM} arguments, and signal an error if their arguments are of an
-inappropriate type. Macros generally do not, unless that is their
-specified purpose. You must verify their argument types beforehand, as
-necessary.
-
-Macros and functions that return a boolean value have names ending in
-@code{P} or @code{_p} (for ``predicate''). Those that return a negated
-boolean value have names starting with @code{SCM_N}. For example,
-@code{SCM_IMP (@var{x})} is a predicate which returns non-zero iff
-@var{x} is an immediate value (an @code{IM}). @code{SCM_NCONSP
-(@var{x})} is a predicate which returns non-zero iff @var{x} is
-@emph{not} a pair object (a @code{CONS}).
-
-
-@node Conservative GC
-@subsection Conservative Garbage Collection
-
-Aside from the latent typing, the major source of constraints on a
-Scheme implementation's data representation is the garbage collector.
-The collector must be able to traverse every live object in the heap, to
-determine which objects are not live.
-
-There are many ways to implement this, but Guile uses an algorithm
-called @dfn{mark and sweep}. The collector scans the system's global
-variables and the local variables on the stack to determine which
-objects are immediately accessible by the C code. It then scans those
-objects to find the objects they point to, @i{et cetera}. The collector
-sets a @dfn{mark bit} on each object it finds, so each object is
-traversed only once. This process is called @dfn{tracing}.
-
-When the collector can find no unmarked objects pointed to by marked
-objects, it assumes that any objects that are still unmarked will never
-be used by the program (since there is no path of dereferences from any
-global or local variable that reaches them) and deallocates them.
-
-In the above paragraphs, we did not specify how the garbage collector
-finds the global and local variables; as usual, there are many different
-approaches. Frequently, the programmer must maintain a list of pointers
-to all global variables that refer to the heap, and another list
-(adjusted upon entry to and exit from each function) of local variables,
-for the collector's benefit.
-
-The list of global variables is usually not too difficult to maintain,
-since global variables are relatively rare. However, an explicitly
-maintained list of local variables (in the author's personal experience)
-is a nightmare to maintain. Thus, Guile uses a technique called
-@dfn{conservative garbage collection}, to make the local variable list
-unnecessary.
-
-The trick to conservative collection is to treat the stack as an
-ordinary range of memory, and assume that @emph{every} word on the stack
-is a pointer into the heap. Thus, the collector marks all objects whose
-addresses appear anywhere in the stack, without knowing for sure how
-that word is meant to be interpreted.
-
-Obviously, such a system will occasionally retain objects that are
-actually garbage, and should be freed. In practice, this is not a
-problem. The alternative, an explicitly maintained list of local
-variable addresses, is effectively much less reliable, due to programmer
-error.
-
-To accommodate this technique, data must be represented so that the
-collector can accurately determine whether a given stack word is a
-pointer or not. Guile does this as follows:
-
-@itemize @bullet
-@item
-Every heap object has a two-word header, called a @dfn{cell}. Some
-objects, like pairs, fit entirely in a cell's two words; others may
-store pointers to additional memory in either of the words. For
-example, strings and vectors store their length in the first word, and a
-pointer to their elements in the second.
-
-@item
-Guile allocates whole arrays of cells at a time, called @dfn{heap
-segments}. These segments are always allocated so that the cells they
-contain fall on eight-byte boundaries, or whatever is appropriate for
-the machine's word size. Guile keeps all cells in a heap segment
-initialized, whether or not they are currently in use.
-
-@item
-Guile maintains a sorted table of heap segments.
-@end itemize
-
-Thus, given any random word @var{w} fetched from the stack, Guile's
-garbage collector can consult the table to see if @var{w} falls within a
-known heap segment, and check @var{w}'s alignment. If both tests pass,
-the collector knows that @var{w} is a valid pointer to a cell,
-intentional or not, and proceeds to trace the cell.
-
-Note that heap segments do not contain all the data Guile uses; cells
-for objects like vectors and strings contain pointers to other memory
-areas. However, since those pointers are internal, and not shared among
-many pieces of code, it is enough for the collector to find the cell,
-and then use the cell's type to find more pointers to trace.
-
-
-@node Immediates vs Non-immediates
-@subsection Immediates vs Non-immediates
-
-Guile classifies Scheme objects into two kinds: those that fit entirely
-within an @code{SCM}, and those that require heap storage.
-
-The former class are called @dfn{immediates}. The class of immediates
-includes small integers, characters, boolean values, the empty list, the
-mysterious end-of-file object, and some others.
-
-The remaining types are called, not surprisingly, @dfn{non-immediates}.
-They include pairs, procedures, strings, vectors, and all other data
-types in Guile.
-
-@deftypefn Macro int SCM_IMP (SCM @var{x})
-Return non-zero iff @var{x} is an immediate object.
-@end deftypefn
-
-@deftypefn Macro int SCM_NIMP (SCM @var{x})
-Return non-zero iff @var{x} is a non-immediate object. This is the
-exact complement of @code{SCM_IMP}, above.
-@end deftypefn
-
-Note that for versions of Guile prior to 1.4 it was necessary to use the
-@code{SCM_NIMP} macro before calling a finer-grained predicate to
-determine @var{x}'s type, such as @code{SCM_CONSP} or
-@code{SCM_VECTORP}. This is no longer required: the definitions of all
-Guile type predicates now include a call to @code{SCM_NIMP} where
-necessary.
-
-
-@node Immediate Datatypes
-@subsection Immediate Datatypes
-
-The following datatypes are immediate values; that is, they fit entirely
-within an @code{SCM} value. The @code{SCM_IMP} and @code{SCM_NIMP}
-macros will distinguish these from non-immediates; see @ref{Immediates
-vs Non-immediates} for an explanation of the distinction.
-
-Note that the type predicates for immediate values work correctly on any
-@code{SCM} value; you do not need to call @code{SCM_IMP} first, to
-establish that a value is immediate.
-
-@menu
-* Integer Data::
-* Character Data::
-* Boolean Data::
-* Unique Values::
-@end menu
-
-@node Integer Data
-@subsubsection Integers
-
-Here are functions for operating on small integers, that fit within an
-@code{SCM}. Such integers are called @dfn{immediate numbers}, or
-@dfn{INUMs}. In general, INUMs occupy all but two bits of an
-@code{SCM}.
-
-Bignums and floating-point numbers are non-immediate objects, and have
-their own, separate accessors. The functions here will not work on
-them. This is not as much of a problem as you might think, however,
-because the system never constructs bignums that could fit in an INUM,
-and never uses floating point values for exact integers.
-
-@deftypefn Macro int SCM_INUMP (SCM @var{x})
-Return non-zero iff @var{x} is a small integer value.
-@end deftypefn
-
-@deftypefn Macro int SCM_NINUMP (SCM @var{x})
-The complement of SCM_INUMP.
-@end deftypefn
-
-@deftypefn Macro int SCM_INUM (SCM @var{x})
-Return the value of @var{x} as an ordinary, C integer. If @var{x}
-is not an INUM, the result is undefined.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_MAKINUM (int @var{i})
-Given a C integer @var{i}, return its representation as an @code{SCM}.
-This function does not check for overflow.
-@end deftypefn
-
-
-@node Character Data
-@subsubsection Characters
-
-Here are functions for operating on characters.
-
-@deftypefn Macro int SCM_CHARP (SCM @var{x})
-Return non-zero iff @var{x} is a character value.
-@end deftypefn
-
-@deftypefn Macro {unsigned int} SCM_CHAR (SCM @var{x})
-Return the value of @code{x} as a C character. If @var{x} is not a
-Scheme character, the result is undefined.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_MAKE_CHAR (int @var{c})
-Given a C character @var{c}, return its representation as a Scheme
-character value.
-@end deftypefn
-
-
-@node Boolean Data
-@subsubsection Booleans
-
-Here are functions and macros for operating on booleans.
-
-@deftypefn Macro SCM SCM_BOOL_T
-@deftypefnx Macro SCM SCM_BOOL_F
-The Scheme true and false values.
-@end deftypefn
-
-@deftypefn Macro int SCM_NFALSEP (@var{x})
-Convert the Scheme boolean value to a C boolean. Since every object in
-Scheme except @code{#f} is true, this amounts to comparing @var{x} to
-@code{#f}; hence the name.
-@c Noel feels a chill here.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_BOOL_NOT (@var{x})
-Return the boolean inverse of @var{x}. If @var{x} is not a
-Scheme boolean, the result is undefined.
-@end deftypefn
-
-
-@node Unique Values
-@subsubsection Unique Values
-
-The immediate values that are neither small integers, characters, nor
-booleans are all unique values --- that is, datatypes with only one
-instance.
-
-@deftypefn Macro SCM SCM_EOL
-The Scheme empty list object, or ``End Of List'' object, usually written
-in Scheme as @code{'()}.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_EOF_VAL
-The Scheme end-of-file value. It has no standard written
-representation, for obvious reasons.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_UNSPECIFIED
-The value returned by expressions which the Scheme standard says return
-an ``unspecified'' value.
-
-This is sort of a weirdly literal way to take things, but the standard
-read-eval-print loop prints nothing when the expression returns this
-value, so it's not a bad idea to return this when you can't think of
-anything else helpful.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_UNDEFINED
-The ``undefined'' value. Its most important property is that is not
-equal to any valid Scheme value. This is put to various internal uses
-by C code interacting with Guile.
-
-For example, when you write a C function that is callable from Scheme
-and which takes optional arguments, the interpreter passes
-@code{SCM_UNDEFINED} for any arguments you did not receive.
-
-We also use this to mark unbound variables.
-@end deftypefn
-
-@deftypefn Macro int SCM_UNBNDP (SCM @var{x})
-Return true if @var{x} is @code{SCM_UNDEFINED}. Apply this to a
-symbol's value to see if it has a binding as a global variable.
-@end deftypefn
-
-
-@node Non-immediate Datatypes
-@subsection Non-immediate Datatypes
-
-A non-immediate datatype is one which lives in the heap, either because
-it cannot fit entirely within a @code{SCM} word, or because it denotes a
-specific storage location (in the nomenclature of the Revised^5 Report
-on Scheme).
-
-The @code{SCM_IMP} and @code{SCM_NIMP} macros will distinguish these
-from immediates; see @ref{Immediates vs Non-immediates}.
-
-Given a cell, Guile distinguishes between pairs and other non-immediate
-types by storing special @dfn{tag} values in a non-pair cell's car, that
-cannot appear in normal pairs. A cell with a non-tag value in its car
-is an ordinary pair. The type of a cell with a tag in its car depends
-on the tag; the non-immediate type predicates test this value. If a tag
-value appears elsewhere (in a vector, for example), the heap may become
-corrupted.
-
-Note how the type information for a non-immediate object is split
-between the @code{SCM} word and the cell that the @code{SCM} word points
-to. The @code{SCM} word itself only indicates that the object is
-non-immediate --- in other words stored in a heap cell. The tag stored
-in the first word of the heap cell indicates more precisely the type of
-that object.
-
-The type predicates for non-immediate values work correctly on any
-@code{SCM} value; you do not need to call @code{SCM_NIMP} first, to
-establish that a value is non-immediate.
-
-@menu
-* Pair Data::
-* Vector Data::
-* Procedures::
-* Closures::
-* Subrs::
-* Port Data::
-@end menu
-
-
-@node Pair Data
-@subsubsection Pairs
-
-Pairs are the essential building block of list structure in Scheme. A
-pair object has two fields, called the @dfn{car} and the @dfn{cdr}.
-
-It is conventional for a pair's @sc{car} to contain an element of a
-list, and the @sc{cdr} to point to the next pair in the list, or to
-contain @code{SCM_EOL}, indicating the end of the list. Thus, a set of
-pairs chained through their @sc{cdr}s constitutes a singly-linked list.
-Scheme and libguile define many functions which operate on lists
-constructed in this fashion, so although lists chained through the
-@sc{car}s of pairs will work fine too, they may be less convenient to
-manipulate, and receive less support from the community.
-
-Guile implements pairs by mapping the @sc{car} and @sc{cdr} of a pair
-directly into the two words of the cell.
-
-
-@deftypefn Macro int SCM_CONSP (SCM @var{x})
-Return non-zero iff @var{x} is a Scheme pair object.
-@end deftypefn
-
-@deftypefn Macro int SCM_NCONSP (SCM @var{x})
-The complement of SCM_CONSP.
-@end deftypefn
-
-@deftypefun SCM scm_cons (SCM @var{car}, SCM @var{cdr})
-Allocate (``CONStruct'') a new pair, with @var{car} and @var{cdr} as its
-contents.
-@end deftypefun
-
-The macros below perform no type checking. The results are undefined if
-@var{cell} is an immediate. However, since all non-immediate Guile
-objects are constructed from cells, and these macros simply return the
-first element of a cell, they actually can be useful on datatypes other
-than pairs. (Of course, it is not very modular to use them outside of
-the code which implements that datatype.)
-
-@deftypefn Macro SCM SCM_CAR (SCM @var{cell})
-Return the @sc{car}, or first field, of @var{cell}.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_CDR (SCM @var{cell})
-Return the @sc{cdr}, or second field, of @var{cell}.
-@end deftypefn
-
-@deftypefn Macro void SCM_SETCAR (SCM @var{cell}, SCM @var{x})
-Set the @sc{car} of @var{cell} to @var{x}.
-@end deftypefn
-
-@deftypefn Macro void SCM_SETCDR (SCM @var{cell}, SCM @var{x})
-Set the @sc{cdr} of @var{cell} to @var{x}.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_CAAR (SCM @var{cell})
-@deftypefnx Macro SCM SCM_CADR (SCM @var{cell})
-@deftypefnx Macro SCM SCM_CDAR (SCM @var{cell}) @dots{}
-@deftypefnx Macro SCM SCM_CDDDDR (SCM @var{cell})
-Return the @sc{car} of the @sc{car} of @var{cell}, the @sc{car} of the
-@sc{cdr} of @var{cell}, @i{et cetera}.
-@end deftypefn
-
-
-@node Vector Data
-@subsubsection Vectors, Strings, and Symbols
-
-Vectors, strings, and symbols have some properties in common. They all
-have a length, and they all have an array of elements. In the case of a
-vector, the elements are @code{SCM} values; in the case of a string or
-symbol, the elements are characters.
-
-All these types store their length (along with some tagging bits) in the
-@sc{car} of their header cell, and store a pointer to the elements in
-their @sc{cdr}. Thus, the @code{SCM_CAR} and @code{SCM_CDR} macros
-are (somewhat) meaningful when applied to these datatypes.
-
-@deftypefn Macro int SCM_VECTORP (SCM @var{x})
-Return non-zero iff @var{x} is a vector.
-@end deftypefn
-
-@deftypefn Macro int SCM_STRINGP (SCM @var{x})
-Return non-zero iff @var{x} is a string.
-@end deftypefn
-
-@deftypefn Macro int SCM_SYMBOLP (SCM @var{x})
-Return non-zero iff @var{x} is a symbol.
-@end deftypefn
-
-@deftypefn Macro int SCM_VECTOR_LENGTH (SCM @var{x})
-@deftypefnx Macro int SCM_STRING_LENGTH (SCM @var{x})
-@deftypefnx Macro int SCM_SYMBOL_LENGTH (SCM @var{x})
-Return the length of the object @var{x}. The result is undefined if
-@var{x} is not a vector, string, or symbol, respectively.
-@end deftypefn
-
-@deftypefn Macro {SCM *} SCM_VECTOR_BASE (SCM @var{x})
-Return a pointer to the array of elements of the vector @var{x}.
-The result is undefined if @var{x} is not a vector.
-@end deftypefn
-
-@deftypefn Macro {char *} SCM_STRING_CHARS (SCM @var{x})
-@deftypefnx Macro {char *} SCM_SYMBOL_CHARS (SCM @var{x})
-Return a pointer to the characters of @var{x}. The result is undefined
-if @var{x} is not a symbol or string, respectively.
-@end deftypefn
-
-There are also a few magic values stuffed into memory before a symbol's
-characters, but you don't want to know about those. What cruft!
-
-
-@node Procedures
-@subsubsection Procedures
-
-Guile provides two kinds of procedures: @dfn{closures}, which are the
-result of evaluating a @code{lambda} expression, and @dfn{subrs}, which
-are C functions packaged up as Scheme objects, to make them available to
-Scheme programmers.
-
-(There are actually other sorts of procedures: compiled closures, and
-continuations; see the source code for details about them.)
-
-@deftypefun SCM scm_procedure_p (SCM @var{x})
-Return @code{SCM_BOOL_T} iff @var{x} is a Scheme procedure object, of
-any sort. Otherwise, return @code{SCM_BOOL_F}.
-@end deftypefun
-
-
-@node Closures
-@subsubsection Closures
-
-[FIXME: this needs to be further subbed, but texinfo has no subsubsub]
-
-A closure is a procedure object, generated as the value of a
-@code{lambda} expression in Scheme. The representation of a closure is
-straightforward --- it contains a pointer to the code of the lambda
-expression from which it was created, and a pointer to the environment
-it closes over.
-
-In Guile, each closure also has a property list, allowing the system to
-store information about the closure. I'm not sure what this is used for
-at the moment --- the debugger, maybe?
-
-@deftypefn Macro int SCM_CLOSUREP (SCM @var{x})
-Return non-zero iff @var{x} is a closure.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_PROCPROPS (SCM @var{x})
-Return the property list of the closure @var{x}. The results are
-undefined if @var{x} is not a closure.
-@end deftypefn
-
-@deftypefn Macro void SCM_SETPROCPROPS (SCM @var{x}, SCM @var{p})
-Set the property list of the closure @var{x} to @var{p}. The results
-are undefined if @var{x} is not a closure.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_CODE (SCM @var{x})
-Return the code of the closure @var{x}. The result is undefined if
-@var{x} is not a closure.
-
-This function should probably only be used internally by the
-interpreter, since the representation of the code is intimately
-connected with the interpreter's implementation.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_ENV (SCM @var{x})
-Return the environment enclosed by @var{x}.
-The result is undefined if @var{x} is not a closure.
-
-This function should probably only be used internally by the
-interpreter, since the representation of the environment is intimately
-connected with the interpreter's implementation.
-@end deftypefn
-
-
-@node Subrs
-@subsubsection Subrs
-
-[FIXME: this needs to be further subbed, but texinfo has no subsubsub]
-
-A subr is a pointer to a C function, packaged up as a Scheme object to
-make it callable by Scheme code. In addition to the function pointer,
-the subr also contains a pointer to the name of the function, and
-information about the number of arguments accepted by the C function, for
-the sake of error checking.
-
-There is no single type predicate macro that recognizes subrs, as
-distinct from other kinds of procedures. The closest thing is
-@code{scm_procedure_p}; see @ref{Procedures}.
-
-@deftypefn Macro {char *} SCM_SNAME (@var{x})
-Return the name of the subr @var{x}. The result is undefined if
-@var{x} is not a subr.
-@end deftypefn
-
-@deftypefun SCM scm_make_gsubr (char *@var{name}, int @var{req}, int @var{opt}, int @var{rest}, SCM (*@var{function})())
-Create a new subr object named @var{name}, based on the C function
-@var{function}, make it visible to Scheme the value of as a global
-variable named @var{name}, and return the subr object.
-
-The subr object accepts @var{req} required arguments, @var{opt} optional
-arguments, and a @var{rest} argument iff @var{rest} is non-zero. The C
-function @var{function} should accept @code{@var{req} + @var{opt}}
-arguments, or @code{@var{req} + @var{opt} + 1} arguments if @code{rest}
-is non-zero.
-
-When a subr object is applied, it must be applied to at least @var{req}
-arguments, or else Guile signals an error. @var{function} receives the
-subr's first @var{req} arguments as its first @var{req} arguments. If
-there are fewer than @var{opt} arguments remaining, then @var{function}
-receives the value @code{SCM_UNDEFINED} for any missing optional
-arguments. If @var{rst} is non-zero, then any arguments after the first
-@code{@var{req} + @var{opt}} are packaged up as a list as passed as
-@var{function}'s last argument.
-
-Note that subrs can actually only accept a predefined set of
-combinations of required, optional, and rest arguments. For example, a
-subr can take one required argument, or one required and one optional
-argument, but a subr can't take one required and two optional arguments.
-It's bizarre, but that's the way the interpreter was written. If the
-arguments to @code{scm_make_gsubr} do not fit one of the predefined
-patterns, then @code{scm_make_gsubr} will return a compiled closure
-object instead of a subr object.
-@end deftypefun
-
-
-@node Port Data
-@subsubsection Ports
-
-Haven't written this yet, 'cos I don't understand ports yet.
-
-
-@node Signalling Type Errors
-@subsection Signalling Type Errors
-
-Every function visible at the Scheme level should aggressively check the
-types of its arguments, to avoid misinterpreting a value, and perhaps
-causing a segmentation fault. Guile provides some macros to make this
-easier.
-
-@deftypefn Macro void SCM_ASSERT (int @var{test}, SCM @var{obj}, unsigned int @var{position}, const char *@var{subr})
-If @var{test} is zero, signal a ``wrong type argument'' error,
-attributed to the subroutine named @var{subr}, operating on the value
-@var{obj}, which is the @var{position}'th argument of @var{subr}.
-@end deftypefn
-
-@deftypefn Macro int SCM_ARG1
-@deftypefnx Macro int SCM_ARG2
-@deftypefnx Macro int SCM_ARG3
-@deftypefnx Macro int SCM_ARG4
-@deftypefnx Macro int SCM_ARG5
-@deftypefnx Macro int SCM_ARG6
-@deftypefnx Macro int SCM_ARG7
-One of the above values can be used for @var{position} to indicate the
-number of the argument of @var{subr} which is being checked.
-Alternatively, a positive integer number can be used, which allows to
-check arguments after the seventh. However, for parameter numbers up to
-seven it is preferable to use @code{SCM_ARGN} instead of the
-corresponding raw number, since it will make the code easier to
-understand.
-@end deftypefn
-
-@deftypefn Macro int SCM_ARGn
-Passing a value of zero or @code{SCM_ARGn} for @var{position} allows to
-leave it unspecified which argument's type is incorrect. Again,
-@code{SCM_ARGn} should be preferred over a raw zero constant.
-@end deftypefn
-
-
-@node Unpacking the SCM type
-@subsection Unpacking the SCM Type
-
-The previous sections have explained how @code{SCM} values can refer to
-immediate and non-immediate Scheme objects. For immediate objects, the
-complete object value is stored in the @code{SCM} word itself, while for
-non-immediates, the @code{SCM} word contains a pointer to a heap cell,
-and further information about the object in question is stored in that
-cell. This section describes how the @code{SCM} type is actually
-represented and used at the C level.
-
-In fact, there are two basic C data types to represent objects in Guile:
-
-@itemize @bullet
-@item
-@code{SCM} is the user level abstract C type that is used to represent
-all of Guile's Scheme objects, no matter what the Scheme object type is.
-No C operation except assignment is guaranteed to work with variables of
-type @code{SCM}, so you should only use macros and functions to work
-with @code{SCM} values. Values are converted between C data types and
-the @code{SCM} type with utility functions and macros.
-
-@item
-@code{scm_t_bits} is an integral data type that is guaranteed to be
-large enough to hold all information that is required to represent any
-Scheme object. While this data type is mostly used to implement Guile's
-internals, the use of this type is also necessary to write certain kinds
-of extensions to Guile.
-@end itemize
-
-@menu
-* Relationship between SCM and scm_t_bits::
-* Immediate objects::
-* Non-immediate objects::
-* Allocating Cells::
-* Heap Cell Type Information::
-* Accessing Cell Entries::
-* Basic Rules for Accessing Cell Entries::
-@end menu
-
-
-@node Relationship between SCM and scm_t_bits
-@subsubsection Relationship between @code{SCM} and @code{scm_t_bits}
-
-A variable of type @code{SCM} is guaranteed to hold a valid Scheme
-object. A variable of type @code{scm_t_bits}, on the other hand, may
-hold a representation of a @code{SCM} value as a C integral type, but
-may also hold any C value, even if it does not correspond to a valid
-Scheme object.
-
-For a variable @var{x} of type @code{SCM}, the Scheme object's type
-information is stored in a form that is not directly usable. To be able
-to work on the type encoding of the scheme value, the @code{SCM}
-variable has to be transformed into the corresponding representation as
-a @code{scm_t_bits} variable @var{y} by using the @code{SCM_UNPACK}
-macro. Once this has been done, the type of the scheme object @var{x}
-can be derived from the content of the bits of the @code{scm_t_bits}
-value @var{y}, in the way illustrated by the example earlier in this
-chapter (@pxref{Cheaper Pairs}). Conversely, a valid bit encoding of a
-Scheme value as a @code{scm_t_bits} variable can be transformed into the
-corresponding @code{SCM} value using the @code{SCM_PACK} macro.
-
-@deftypefn Macro scm_t_bits SCM_UNPACK (SCM @var{x})
-Transforms the @code{SCM} value @var{x} into its representation as an
-integral type. Only after applying @code{SCM_UNPACK} it is possible to
-access the bits and contents of the @code{SCM} value.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_PACK (scm_t_bits @var{x})
-Takes a valid integral representation of a Scheme object and transforms
-it into its representation as a @code{SCM} value.
-@end deftypefn
-
-
-@node Immediate objects
-@subsubsection Immediate objects
-
-A Scheme object may either be an immediate, i.e. carrying all necessary
-information by itself, or it may contain a reference to a @dfn{cell}
-with additional information on the heap. Although in general it should
-be irrelevant for user code whether an object is an immediate or not,
-within Guile's own code the distinction is sometimes of importance.
-Thus, the following low level macro is provided:
-
-@deftypefn Macro int SCM_IMP (SCM @var{x})
-A Scheme object is an immediate if it fulfills the @code{SCM_IMP}
-predicate, otherwise it holds an encoded reference to a heap cell. The
-result of the predicate is delivered as a C style boolean value. User
-code and code that extends Guile should normally not be required to use
-this macro.
-@end deftypefn
-
-@noindent
-Summary:
-@itemize @bullet
-@item
-Given a Scheme object @var{x} of unknown type, check first
-with @code{SCM_IMP (@var{x})} if it is an immediate object.
-@item
-If so, all of the type and value information can be determined from the
-@code{scm_t_bits} value that is delivered by @code{SCM_UNPACK
-(@var{x})}.
-@end itemize
-
-
-@node Non-immediate objects
-@subsubsection Non-immediate objects
-
-A Scheme object of type @code{SCM} that does not fulfill the
-@code{SCM_IMP} predicate holds an encoded reference to a heap cell.
-This reference can be decoded to a C pointer to a heap cell using the
-@code{SCM2PTR} macro. The encoding of a pointer to a heap cell into a
-@code{SCM} value is done using the @code{PTR2SCM} macro.
-
-@c (FIXME:: this name should be changed)
-@deftypefn Macro (scm_t_cell *) SCM2PTR (SCM @var{x})
-Extract and return the heap cell pointer from a non-immediate @code{SCM}
-object @var{x}.
-@end deftypefn
-
-@c (FIXME:: this name should be changed)
-@deftypefn Macro SCM PTR2SCM (scm_t_cell * @var{x})
-Return a @code{SCM} value that encodes a reference to the heap cell
-pointer @var{x}.
-@end deftypefn
-
-Note that it is also possible to transform a non-immediate @code{SCM}
-value by using @code{SCM_UNPACK} into a @code{scm_t_bits} variable.
-However, the result of @code{SCM_UNPACK} may not be used as a pointer to
-a @code{scm_t_cell}: only @code{SCM2PTR} is guaranteed to transform a
-@code{SCM} object into a valid pointer to a heap cell. Also, it is not
-allowed to apply @code{PTR2SCM} to anything that is not a valid pointer
-to a heap cell.
-
-@noindent
-Summary:
-@itemize @bullet
-@item
-Only use @code{SCM2PTR} on @code{SCM} values for which @code{SCM_IMP} is
-false!
-@item
-Don't use @code{(scm_t_cell *) SCM_UNPACK (@var{x})}! Use @code{SCM2PTR
-(@var{x})} instead!
-@item
-Don't use @code{PTR2SCM} for anything but a cell pointer!
-@end itemize
-
-@node Allocating Cells
-@subsubsection Allocating Cells
-
-Guile provides both ordinary cells with two slots, and double cells
-with four slots. The following two function are the most primitive
-way to allocate such cells.
-
-If the caller intends to use it as a header for some other type, she
-must pass an appropriate magic value in @var{word_0}, to mark it as a
-member of that type, and pass whatever value as @var{word_1}, etc that
-the type expects. You should generally not need these functions,
-unless you are implementing a new datatype, and thoroughly understand
-the code in @code{<libguile/tags.h>}.
-
-If you just want to allocate pairs, use @code{scm_cons}.
-
-@deftypefn Function SCM scm_cell (scm_t_bits word_0, scm_t_bits word_1)
-Allocate a new cell, initialize the two slots with @var{word_0} and
-@var{word_1}, and return it.
-
-Note that @var{word_0} and @var{word_1} are of type @code{scm_t_bits}.
-If you want to pass a @code{SCM} object, you need to use
-@code{SCM_UNPACK}.
-@end deftypefn
-
-@deftypefn Function SCM scm_double_cell (scm_t_bits word_0, scm_t_bits word_1, scm_t_bits word_2, scm_t_bits word_3)
-Like @code{scm_cell}, but allocates a double cell with four
-slots.
-@end deftypefn
-
-@node Heap Cell Type Information
-@subsubsection Heap Cell Type Information
-
-Heap cells contain a number of entries, each of which is either a scheme
-object of type @code{SCM} or a raw C value of type @code{scm_t_bits}.
-Which of the cell entries contain Scheme objects and which contain raw C
-values is determined by the first entry of the cell, which holds the
-cell type information.
-
-@deftypefn Macro scm_t_bits SCM_CELL_TYPE (SCM @var{x})
-For a non-immediate Scheme object @var{x}, deliver the content of the
-first entry of the heap cell referenced by @var{x}. This value holds
-the information about the cell type.
-@end deftypefn
-
-@deftypefn Macro void SCM_SET_CELL_TYPE (SCM @var{x}, scm_t_bits @var{t})
-For a non-immediate Scheme object @var{x}, write the value @var{t} into
-the first entry of the heap cell referenced by @var{x}. The value
-@var{t} must hold a valid cell type.
-@end deftypefn
-
-
-@node Accessing Cell Entries
-@subsubsection Accessing Cell Entries
-
-For a non-immediate Scheme object @var{x}, the object type can be
-determined by reading the cell type entry using the @code{SCM_CELL_TYPE}
-macro. For each different type of cell it is known which cell entries
-hold Scheme objects and which cell entries hold raw C data. To access
-the different cell entries appropriately, the following macros are
-provided.
-
-@deftypefn Macro scm_t_bits SCM_CELL_WORD (SCM @var{x}, unsigned int @var{n})
-Deliver the cell entry @var{n} of the heap cell referenced by the
-non-immediate Scheme object @var{x} as raw data. It is illegal, to
-access cell entries that hold Scheme objects by using these macros. For
-convenience, the following macros are also provided.
-@itemize @bullet
-@item
-SCM_CELL_WORD_0 (@var{x}) @result{} SCM_CELL_WORD (@var{x}, 0)
-@item
-SCM_CELL_WORD_1 (@var{x}) @result{} SCM_CELL_WORD (@var{x}, 1)
-@item
-@dots{}
-@item
-SCM_CELL_WORD_@var{n} (@var{x}) @result{} SCM_CELL_WORD (@var{x}, @var{n})
-@end itemize
-@end deftypefn
-
-@deftypefn Macro SCM SCM_CELL_OBJECT (SCM @var{x}, unsigned int @var{n})
-Deliver the cell entry @var{n} of the heap cell referenced by the
-non-immediate Scheme object @var{x} as a Scheme object. It is illegal,
-to access cell entries that do not hold Scheme objects by using these
-macros. For convenience, the following macros are also provided.
-@itemize @bullet
-@item
-SCM_CELL_OBJECT_0 (@var{x}) @result{} SCM_CELL_OBJECT (@var{x}, 0)
-@item
-SCM_CELL_OBJECT_1 (@var{x}) @result{} SCM_CELL_OBJECT (@var{x}, 1)
-@item
-@dots{}
-@item
-SCM_CELL_OBJECT_@var{n} (@var{x}) @result{} SCM_CELL_OBJECT (@var{x},
-@var{n})
-@end itemize
-@end deftypefn
-
-@deftypefn Macro void SCM_SET_CELL_WORD (SCM @var{x}, unsigned int @var{n}, scm_t_bits @var{w})
-Write the raw C value @var{w} into entry number @var{n} of the heap cell
-referenced by the non-immediate Scheme value @var{x}. Values that are
-written into cells this way may only be read from the cells using the
-@code{SCM_CELL_WORD} macros or, in case cell entry 0 is written, using
-the @code{SCM_CELL_TYPE} macro. For the special case of cell entry 0 it
-has to be made sure that @var{w} contains a cell type information which
-does not describe a Scheme object. For convenience, the following
-macros are also provided.
-@itemize @bullet
-@item
-SCM_SET_CELL_WORD_0 (@var{x}, @var{w}) @result{} SCM_SET_CELL_WORD
-(@var{x}, 0, @var{w})
-@item
-SCM_SET_CELL_WORD_1 (@var{x}, @var{w}) @result{} SCM_SET_CELL_WORD
-(@var{x}, 1, @var{w})
-@item
-@dots{}
-@item
-SCM_SET_CELL_WORD_@var{n} (@var{x}, @var{w}) @result{} SCM_SET_CELL_WORD
-(@var{x}, @var{n}, @var{w})
-@end itemize
-@end deftypefn
-
-@deftypefn Macro void SCM_SET_CELL_OBJECT (SCM @var{x}, unsigned int @var{n}, SCM @var{o})
-Write the Scheme object @var{o} into entry number @var{n} of the heap
-cell referenced by the non-immediate Scheme value @var{x}. Values that
-are written into cells this way may only be read from the cells using
-the @code{SCM_CELL_OBJECT} macros or, in case cell entry 0 is written,
-using the @code{SCM_CELL_TYPE} macro. For the special case of cell
-entry 0 the writing of a Scheme object into this cell is only allowed
-if the cell forms a Scheme pair. For convenience, the following macros
-are also provided.
-@itemize @bullet
-@item
-SCM_SET_CELL_OBJECT_0 (@var{x}, @var{o}) @result{} SCM_SET_CELL_OBJECT
-(@var{x}, 0, @var{o})
-@item
-SCM_SET_CELL_OBJECT_1 (@var{x}, @var{o}) @result{} SCM_SET_CELL_OBJECT
-(@var{x}, 1, @var{o})
-@item
-@dots{}
-@item
-SCM_SET_CELL_OBJECT_@var{n} (@var{x}, @var{o}) @result{}
-SCM_SET_CELL_OBJECT (@var{x}, @var{n}, @var{o})
-@end itemize
-@end deftypefn
-
-@noindent
-Summary:
-@itemize @bullet
-@item
-For a non-immediate Scheme object @var{x} of unknown type, get the type
-information by using @code{SCM_CELL_TYPE (@var{x})}.
-@item
-As soon as the cell type information is available, only use the
-appropriate access methods to read and write data to the different cell
-entries.
-@end itemize
-
-
-@node Basic Rules for Accessing Cell Entries
-@subsubsection Basic Rules for Accessing Cell Entries
-
-For each cell type it is generally up to the implementation of that type
-which of the corresponding cell entries hold Scheme objects and which
-hold raw C values. However, there is one basic rule that has to be
-followed: Scheme pairs consist of exactly two cell entries, which both
-contain Scheme objects. Further, a cell which contains a Scheme object
-in it first entry has to be a Scheme pair. In other words, it is not
-allowed to store a Scheme object in the first cell entry and a non
-Scheme object in the second cell entry.
-
-@c Fixme:shouldn't this rather be SCM_PAIRP / SCM_PAIR_P ?
-@deftypefn Macro int SCM_CONSP (SCM @var{x})
-Determine, whether the Scheme object @var{x} is a Scheme pair,
-i.e. whether @var{x} references a heap cell consisting of exactly two
-entries, where both entries contain a Scheme object. In this case, both
-entries will have to be accessed using the @code{SCM_CELL_OBJECT}
-macros. On the contrary, if the @code{SCM_CONSP} predicate is not
-fulfilled, the first entry of the Scheme cell is guaranteed not to be a
-Scheme value and thus the first cell entry must be accessed using the
-@code{SCM_CELL_WORD_0} macro.
-@end deftypefn
-
-
-@node Defining New Types (Smobs)
-@section Defining New Types (Smobs)
-
-@dfn{Smobs} are Guile's mechanism for adding new non-immediate types to
-the system.@footnote{The term ``smob'' was coined by Aubrey Jaffer, who
-says it comes from ``small object'', referring to the fact that only the
-@sc{cdr} and part of the @sc{car} of a smob's cell are available for
-use.} To define a new smob type, the programmer provides Guile with
-some essential information about the type --- how to print it, how to
-garbage collect it, and so on --- and Guile returns a fresh type tag for
-use in the first word of new cells. The programmer can then use
-@code{scm_c_define_gsubr} to make a set of C functions that create and
-operate on these objects visible to Scheme code.
-
-(You can find a complete version of the example code used in this
-section in the Guile distribution, in @file{doc/example-smob}. That
-directory includes a makefile and a suitable @code{main} function, so
-you can build a complete interactive Guile shell, extended with the
-datatypes described here.)
-
-@menu
-* Describing a New Type::
-* Creating Instances::
-* Type checking::
-* Garbage Collecting Smobs::
-* A Common Mistake In Allocating Smobs::
-* Garbage Collecting Simple Smobs::
-* A Complete Example::
-@end menu
-
-@node Describing a New Type
-@subsection Describing a New Type
-
-To define a new type, the programmer must write four functions to
-manage instances of the type:
-
-@table @code
-@item mark
-Guile will apply this function to each instance of the new type it
-encounters during garbage collection. This function is responsible for
-telling the collector about any other non-immediate objects the object
-refers to. The default smob mark function is to not mark any data.
-@xref{Garbage Collecting Smobs}, for more details.
-
-@item free
-Guile will apply this function to each instance of the new type it could
-not find any live pointers to. The function should release all
-resources held by the object and return the number of bytes released.
-This is analogous to the Java finalization method-- it is invoked at
-an unspecified time (when garbage collection occurs) after the object
-is dead. The default free function frees the smob data (if the size
-of the struct passed to @code{scm_make_smob_type} is non-zero) using
-@code{scm_gc_free}. @xref{Garbage Collecting Smobs}, for more
-details.
-
-@item print
-@c GJB:FIXME:: @var{exp} and @var{port} need to refer to a prototype of
-@c the print function.... where is that, or where should it go?
-Guile will apply this function to each instance of the new type to print
-the value, as for @code{display} or @code{write}. The function should
-write a printed representation of @var{exp} on @var{port}, in accordance
-with the parameters in @var{pstate}. (For more information on print
-states, see @ref{Port Data}.) The default print function prints
-@code{#<NAME ADDRESS>} where @code{NAME} is the first argument passed to
-@code{scm_make_smob_type}.
-
-@item equalp
-If Scheme code asks the @code{equal?} function to compare two instances
-of the same smob type, Guile calls this function. It should return
-@code{SCM_BOOL_T} if @var{a} and @var{b} should be considered
-@code{equal?}, or @code{SCM_BOOL_F} otherwise. If @code{equalp} is
-@code{NULL}, @code{equal?} will assume that two instances of this type are
-never @code{equal?} unless they are @code{eq?}.
-
-@end table
-
-To actually register the new smob type, call @code{scm_make_smob_type}:
-
-@deftypefun scm_t_bits scm_make_smob_type (const char *name, size_t size)
-This function implements the standard way of adding a new smob type,
-named @var{name}, with instance size @var{size}, to the system. The
-return value is a tag that is used in creating instances of the type.
-If @var{size} is 0, then no memory will be allocated when instances of
-the smob are created, and nothing will be freed by the default free
-function. Default values are provided for mark, free, print, and,
-equalp, as described above. If you want to customize any of these
-functions, the call to @code{scm_make_smob_type} should be immediately
-followed by calls to one or several of @code{scm_set_smob_mark},
-@code{scm_set_smob_free}, @code{scm_set_smob_print}, and/or
-@code{scm_set_smob_equalp}.
-@end deftypefun
-
-Each of the below @code{scm_set_smob_XXX} functions registers a smob
-special function for a given type. Each function is intended to be used
-only zero or one time per type, and the call should be placed
-immediately following the call to @code{scm_make_smob_type}.
-
-@deftypefun void scm_set_smob_mark (scm_t_bits tc, SCM (*mark) (SCM))
-This function sets the smob marking procedure for the smob type specified by
-the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
-@end deftypefun
-
-@deftypefun void scm_set_smob_free (scm_t_bits tc, size_t (*free) (SCM))
-This function sets the smob freeing procedure for the smob type specified by
-the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
-@end deftypefun
-
-@deftypefun void scm_set_smob_print (scm_t_bits tc, int (*print) (SCM, SCM, scm_print_state*))
-This function sets the smob printing procedure for the smob type specified by
-the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
-@end deftypefun
-
-@deftypefun void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM, SCM))
-This function sets the smob equality-testing predicate for the smob type specified by
-the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
-@end deftypefun
-
-In versions 1.4 and earlier, there was another way of creating smob
-types, using @code{scm_make_smob_type_mfpe}. This function is now
-deprecated and will be removed in a future version of Guile. You should
-use the mechanism described above for new code, and change old code not
-to use deprecated features.
-
-Instead of using @code{scm_make_smob_type} and calling each of the
-individual @code{scm_set_smob_XXX} functions to register each special
-function independently, you could use @code{scm_make_smob_type_mfpe} to
-register all of the special functions at once as you create the smob
-type
-
-@deftypefun long scm_make_smob_type_mfpe(const char *name, size_t size, SCM (*mark) (SCM), size_t (*free) (SCM), int (*print) (SCM, SCM, scm_print_state*), SCM (*equalp) (SCM, SCM))
-This function invokes @code{scm_make_smob_type} on its first two arguments
-to add a new smob type named @var{name}, with instance size @var{size} to the system.
-It also registers the @var{mark}, @var{free}, @var{print}, @var{equalp} smob
-special functions for that new type. Any of these parameters can be @code{NULL}
-to have that special function use the default behavior for guile.
-The return value is a tag that is used in creating instances of the type. If @var{size}
-is 0, then no memory will be allocated when instances of the smob are created, and
-nothing will be freed by the default free function.
-@end deftypefun
-
-For example, here is how one might declare and register a new type
-representing eight-bit gray-scale images:
-
-@example
-#include <libguile.h>
-
-static scm_t_bits image_tag;
-
-void
-init_image_type (void)
-@{
- image_tag = scm_make_smob_type ("image", sizeof (struct image));
- scm_set_smob_mark (image_tag, mark_image);
- scm_set_smob_free (image_tag, free_image);
- scm_set_smob_print (image_tag, print_image);
-@}
-@end example
-
-
-@node Creating Instances
-@subsection Creating Instances
-
-Like other non-immediate types, smobs start with a cell whose first word
-contains typing information, and whose remaining words are free for any
-use.
-
-After the header word containing the type code, smobs can have either
-one, two or three additional words of data. These words store either a
-pointer to the internal C structure holding the smob-specific data, or
-the smob data itself. To create an instance of a smob type following
-these standards, you should use @code{SCM_NEWSMOB}, @code{SCM_NEWSMOB2}
-or @code{SCM_NEWSMOB3}:@footnote{The @code{SCM_NEWSMOB2} and
-@code{SCM_NEWSMOB3} variants will allocate double cells and thus use
-twice as much memory as smobs created by @code{SCM_NEWSMOB}.}
-
-@deftypefn Macro void SCM_NEWSMOB(SCM value, scm_t_bits tag, void *data)
-@deftypefnx Macro void SCM_NEWSMOB2(SCM value, scm_t_bits tag, void *data1, void *data2)
-@deftypefnx Macro void SCM_NEWSMOB3(SCM value, scm_t_bits tag, void *data1, void *data2, void *data3)
-Make @var{value} contain a smob instance of the type with tag @var{tag}
-and smob data @var{data} (or @var{data1}, @var{data2}, and @var{data3}).
-@var{value} must be previously declared as C type @code{SCM}.
-@end deftypefn
-
-Since it is often the case (e.g., in smob constructors) that you will
-create a smob instance and return it, there is also a slightly specialized
-macro for this situation:
-
-@deftypefn Macro fn_returns SCM_RETURN_NEWSMOB(scm_t_bits tag, void *data)
-@deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB2(scm_t_bits tag, void *data1, void *data2)
-@deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB3(scm_t_bits tag, void *data1, void *data2, void *data3)
-This macro expands to a block of code that creates a smob instance of
-the type with tag @var{tag} and smob data @var{data} (or @var{data1},
-@var{data2}, and @var{data3}), and causes the surrounding function to
-return that @code{SCM} value. It should be the last piece of code in
-a block.
-@end deftypefn
-
-Guile provides some functions for managing memory, which are often
-helpful when implementing smobs. @xref{Memory Blocks}.
-
-
-Continuing the above example, if the global variable @code{image_tag}
-contains a tag returned by @code{scm_make_smob_type}, here is how we
-could construct a smob whose @sc{cdr} contains a pointer to a freshly
-allocated @code{struct image}:
-
-@example
-struct image @{
- int width, height;
- char *pixels;
-
- /* The name of this image */
- SCM name;
-
- /* A function to call when this image is
- modified, e.g., to update the screen,
- or SCM_BOOL_F if no action necessary */
- SCM update_func;
-@};
-
-SCM
-make_image (SCM name, SCM s_width, SCM s_height)
-@{
- struct image *image;
- int width, height;
-
- SCM_ASSERT (SCM_STRINGP (name), name, SCM_ARG1, "make-image");
- SCM_ASSERT (SCM_INUMP (s_width), s_width, SCM_ARG2, "make-image");
- SCM_ASSERT (SCM_INUMP (s_height), s_height, SCM_ARG3, "make-image");
-
- width = SCM_INUM (s_width);
- height = SCM_INUM (s_height);
-
- image = (struct image *) scm_gc_malloc (sizeof (struct image), "image");
- image->width = width;
- image->height = height;
- image->pixels = scm_gc_malloc (width * height, "image pixels");
- image->name = name;
- image->update_func = SCM_BOOL_F;
-
- SCM_RETURN_NEWSMOB (image_tag, image);
-@}
-@end example
-
-
-@node Type checking
-@subsection Type checking
-
-Functions that operate on smobs should aggressively check the types of
-their arguments, to avoid misinterpreting some other datatype as a smob,
-and perhaps causing a segmentation fault. Fortunately, this is pretty
-simple to do. The function need only verify that its argument is a
-non-immediate, whose first word is the type tag returned by
-@code{scm_make_smob_type}.
-
-For example, here is a simple function that operates on an image smob,
-and checks the type of its argument. We also present an expanded
-version of the @code{init_image_type} function, to make
-@code{clear_image} and the image constructor function @code{make_image}
-visible to Scheme code.
-
-@example
-SCM
-clear_image (SCM image_smob)
-@{
- int area;
- struct image *image;
-
- SCM_ASSERT (SCM_SMOB_PREDICATE (image_tag, image_smob),
- image_smob, SCM_ARG1, "clear-image");
-
- image = (struct image *) SCM_SMOB_DATA (image_smob);
- area = image->width * image->height;
- memset (image->pixels, 0, area);
-
- /* Invoke the image's update function. */
- if (image->update_func != SCM_BOOL_F)
- scm_apply (image->update_func, SCM_EOL, SCM_EOL);
-
- return SCM_UNSPECIFIED;
-@}
-
-
-void
-init_image_type (void)
-@{
- image_tag = scm_make_smob_type ("image", sizeof (struct image));
- scm_set_smob_mark (image_tag, mark_image);
- scm_set_smob_free (image_tag, free_image);
- scm_set_smob_print (image_tag, print_image);
-
- scm_c_define_gsubr ("clear-image", 1, 0, 0, clear_image);
- scm_c_define_gsubr ("make-image", 3, 0, 0, make_image);
-@}
-@end example
-
-@c GJB:FIXME:: should talk about guile-snarf somewhere!
-
-
-@node Garbage Collecting Smobs
-@subsection Garbage Collecting Smobs
-
-Once a smob has been released to the tender mercies of the Scheme
-system, it must be prepared to survive garbage collection. Guile calls
-the @code{mark} and @code{free} functions of the @code{scm_smobfuns}
-structure to manage this.
-
-As described before (@pxref{Conservative GC}), every object in the
-Scheme system has a @dfn{mark bit}, which the garbage collector uses to
-tell live objects from dead ones. When collection starts, every
-object's mark bit is clear. The collector traces pointers through the
-heap, starting from objects known to be live, and sets the mark bit on
-each object it encounters. When it can find no more unmarked objects,
-the collector walks all objects, live and dead, frees those whose mark
-bits are still clear, and clears the mark bit on the others.
-
-The two main portions of the collection are called the @dfn{mark phase},
-during which the collector marks live objects, and the @dfn{sweep
-phase}, during which the collector frees all unmarked objects.
-
-The mark bit of a smob lives in a special memory region. When the
-collector encounters a smob, it sets the smob's mark bit, and uses the
-smob's type tag to find the appropriate @code{mark} function for that
-smob: the one listed in that smob's @code{scm_smobfuns} structure. It
-then calls the @code{mark} function, passing it the smob as its only
-argument.
-
-The @code{mark} function is responsible for marking any other Scheme
-objects the smob refers to. If it does not do so, the objects' mark
-bits will still be clear when the collector begins to sweep, and the
-collector will free them. If this occurs, it will probably break, or at
-least confuse, any code operating on the smob; the smob's @code{SCM}
-values will have become dangling references.
-
-To mark an arbitrary Scheme object, the @code{mark} function may call
-this function:
-
-@deftypefun void scm_gc_mark (SCM @var{x})
-Mark the object @var{x}, and recurse on any objects @var{x} refers to.
-If @var{x}'s mark bit is already set, return immediately.
-@end deftypefun
-
-Thus, here is how we might write the @code{mark} function for the image
-smob type discussed above:
-
-@example
-@group
-SCM
-mark_image (SCM image_smob)
-@{
- /* Mark the image's name and update function. */
- struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
-
- scm_gc_mark (image->name);
- scm_gc_mark (image->update_func);
-
- return SCM_BOOL_F;
-@}
-@end group
-@end example
-
-Note that, even though the image's @code{update_func} could be an
-arbitrarily complex structure (representing a procedure and any values
-enclosed in its environment), @code{scm_gc_mark} will recurse as
-necessary to mark all its components. Because @code{scm_gc_mark} sets
-an object's mark bit before it recurses, it is not confused by
-circular structures.
-
-As an optimization, the collector will mark whatever value is returned
-by the @code{mark} function; this helps limit depth of recursion during
-the mark phase. Thus, the code above could also be written as:
-@example
-@group
-SCM
-mark_image (SCM image_smob)
-@{
- /* Mark the image's name and update function. */
- struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
-
- scm_gc_mark (image->name);
- return image->update_func;
-@}
-@end group
-@end example
-
-
-Finally, when the collector encounters an unmarked smob during the sweep
-phase, it uses the smob's tag to find the appropriate @code{free}
-function for the smob. It then calls the function, passing it the smob
-as its only argument.
-
-The @code{free} function must release any resources used by the smob.
-However, it need not free objects managed by the collector; the
-collector will take care of them. For historical reasons, the return
-type of the @code{free} function should be @code{size_t}, an unsigned
-integral type; the @code{free} function should always return zero.
-
-Here is how we might write the @code{free} function for the image smob
-type:
-@example
-size_t
-free_image (SCM image_smob)
-@{
- struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
-
- scm_gc_free (image->pixels, image->width * image->height, "image pixels");
- scm_gc_free (image, sizeof (struct image), "image");
-
- return 0;
-@}
-@end example
-
-During the sweep phase, the garbage collector will clear the mark bits
-on all live objects. The code which implements a smob need not do this
-itself.
-
-There is no way for smob code to be notified when collection is
-complete.
-
-It is usually a good idea to minimize the amount of processing done
-during garbage collection; keep @code{mark} and @code{free} functions
-very simple. Since collections occur at unpredictable times, it is easy
-for any unusual activity to interfere with normal code.
-
-
-@node A Common Mistake In Allocating Smobs, Garbage Collecting Simple Smobs, Garbage Collecting Smobs, Defining New Types (Smobs)
-@subsection A Common Mistake In Allocating Smobs
-
-When constructing new objects, you must be careful that the garbage
-collector can always find any new objects you allocate. For example,
-suppose we wrote the @code{make_image} function this way:
-
-@example
-SCM
-make_image (SCM name, SCM s_width, SCM s_height)
-@{
- struct image *image;
- SCM image_smob;
- int width, height;
-
- SCM_ASSERT (SCM_STRINGP (name), name, SCM_ARG1, "make-image");
- SCM_ASSERT (SCM_INUMP (s_width), s_width, SCM_ARG2, "make-image");
- SCM_ASSERT (SCM_INUMP (s_height), s_height, SCM_ARG3, "make-image");
-
- width = SCM_INUM (s_width);
- height = SCM_INUM (s_height);
-
- image = (struct image *) scm_gc_malloc (sizeof (struct image), "image");
- image->width = width;
- image->height = height;
- image->pixels = scm_gc_malloc (width * height, "image pixels");
-
- /* THESE TWO LINES HAVE CHANGED: */
- image->name = scm_string_copy (name);
- image->update_func = scm_c_define_gsubr (@dots{});
-
- SCM_NEWCELL (image_smob);
- SCM_SET_CELL_WORD_1 (image_smob, image);
- SCM_SET_CELL_TYPE (image_smob, image_tag);
-
- return image_smob;
-@}
-@end example
-
-This code is incorrect. The calls to @code{scm_string_copy} and
-@code{scm_c_define_gsubr} allocate fresh objects. Allocating any new object
-may cause the garbage collector to run. If @code{scm_c_define_gsubr}
-invokes a collection, the garbage collector has no way to discover that
-@code{image->name} points to the new string object; the @code{image}
-structure is not yet part of any Scheme object, so the garbage collector
-will not traverse it. Since the garbage collector cannot find any
-references to the new string object, it will free it, leaving
-@code{image} pointing to a dead object.
-
-A correct implementation might say, instead:
-
-@example
- image->name = SCM_BOOL_F;
- image->update_func = SCM_BOOL_F;
-
- SCM_NEWCELL (image_smob);
- SCM_SET_CELL_WORD_1 (image_smob, image);
- SCM_SET_CELL_TYPE (image_smob, image_tag);
-
- image->name = scm_string_copy (name);
- image->update_func = scm_c_define_gsubr (@dots{});
-
- return image_smob;
-@end example
-
-Now, by the time we allocate the new string and function objects,
-@code{image_smob} points to @code{image}. If the garbage collector
-scans the stack, it will find a reference to @code{image_smob} and
-traverse @code{image}, so any objects @code{image} points to will be
-preserved.
-
-
-@node Garbage Collecting Simple Smobs, A Complete Example, A Common Mistake In Allocating Smobs, Defining New Types (Smobs)
-@subsection Garbage Collecting Simple Smobs
-
-It is often useful to define very simple smob types --- smobs which have
-no data to mark, other than the cell itself, or smobs whose first data
-word is simply an ordinary Scheme object, to be marked recursively.
-Guile provides some functions to handle these common cases; you can use
-this function as your smob type's @code{mark} function, if your smob's
-structure is simple enough.
-
-If the smob refers to no other Scheme objects, then no action is
-necessary; the garbage collector has already marked the smob cell
-itself. In that case, you can use zero as your mark function.
-
-@deftypefun SCM scm_markcdr (SCM @var{x})
-Mark the references in the smob @var{x}, assuming that @var{x}'s first
-data word contains an ordinary Scheme object, and @var{x} refers to no
-other objects. This function simply returns @var{x}'s first data word.
-
-This is only useful for simple smobs created by @code{SCM_NEWSMOB} or
-@code{SCM_RETURN_NEWSMOB}, not for smobs allocated as double cells.
-@end deftypefun
-
-@deftypefun size_t scm_free0 (SCM @var{x})
-Do nothing; return zero. This function is appropriate for smobs that
-use either zero or @code{scm_markcdr} as their marking functions, and
-refer to no heap storage, including memory managed by @code{malloc},
-other than the smob's header cell.
-
-This function should not be needed anymore, because simply passing
-@code{NULL} as the free function does the same.
-@end deftypefun
-
-
-@node A Complete Example
-@subsection A Complete Example
-
-Here is the complete text of the implementation of the image datatype,
-as presented in the sections above. We also provide a definition for
-the smob's @code{print} function, and make some objects and functions
-static, to clarify exactly what the surrounding code is using.
-
-As mentioned above, you can find this code in the Guile distribution, in
-@file{doc/example-smob}. That directory includes a makefile and a
-suitable @code{main} function, so you can build a complete interactive
-Guile shell, extended with the datatypes described here.)
-
-@example
-/* file "image-type.c" */
-
-#include <stdlib.h>
-#include <libguile.h>
-
-static scm_t_bits image_tag;
-
-struct image @{
- int width, height;
- char *pixels;
-
- /* The name of this image */
- SCM name;
-
- /* A function to call when this image is
- modified, e.g., to update the screen,
- or SCM_BOOL_F if no action necessary */
- SCM update_func;
-@};
-
-static SCM
-make_image (SCM name, SCM s_width, SCM s_height)
-@{
- struct image *image;
- int width, height;
-
- SCM_ASSERT (SCM_STRINGP (name), name, SCM_ARG1, "make-image");
- SCM_ASSERT (SCM_INUMP (s_width), s_width, SCM_ARG2, "make-image");
- SCM_ASSERT (SCM_INUMP (s_height), s_height, SCM_ARG3, "make-image");
-
- width = SCM_INUM (s_width);
- height = SCM_INUM (s_height);
-
- image = (struct image *) scm_gc_malloc (sizeof (struct image), "image");
- image->width = width;
- image->height = height;
- image->pixels = scm_gc_malloc (width * height, "image pixels");
- image->name = name;
- image->update_func = SCM_BOOL_F;
-
- SCM_RETURN_NEWSMOB (image_tag, image);
-@}
-
-static SCM
-clear_image (SCM image_smob)
-@{
- int area;
- struct image *image;
-
- SCM_ASSERT (SCM_SMOB_PREDICATE (image_tag, image_smob),
- image_smob, SCM_ARG1, "clear-image");
-
- image = (struct image *) SCM_SMOB_DATA (image_smob);
- area = image->width * image->height;
- memset (image->pixels, 0, area);
-
- /* Invoke the image's update function. */
- if (image->update_func != SCM_BOOL_F)
- scm_apply (image->update_func, SCM_EOL, SCM_EOL);
-
- return SCM_UNSPECIFIED;
-@}
-
-static SCM
-mark_image (SCM image_smob)
-@{
- /* Mark the image's name and update function. */
- struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
-
- scm_gc_mark (image->name);
- return image->update_func;
-@}
-
-static size_t
-free_image (SCM image_smob)
-@{
- struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
-
- scm_gc_free (image->pixels, image->width * image->height, "image pixels");
- scm_gc_free (image, sizeof (struct image), "image");
-
- return 0;
-@}
-
-static int
-print_image (SCM image_smob, SCM port, scm_print_state *pstate)
-@{
- struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
-
- scm_puts ("#<image ", port);
- scm_display (image->name, port);
- scm_puts (">", port);
-
- /* non-zero means success */
- return 1;
-@}
-
-void
-init_image_type (void)
-@{
- image_tag = scm_make_smob_type ("image", sizeof (struct image));
- scm_set_smob_mark (image_tag, mark_image);
- scm_set_smob_free (image_tag, free_image);
- scm_set_smob_print (image_tag, print_image);
-
- scm_c_define_gsubr ("clear-image", 1, 0, 0, clear_image);
- scm_c_define_gsubr ("make-image", 3, 0, 0, make_image);
-@}
-@end example
-
-Here is a sample build and interaction with the code from the
-@file{example-smob} directory, on the author's machine:
-
-@example
-zwingli:example-smob$ make CC=gcc
-gcc `guile-config compile` -c image-type.c -o image-type.o
-gcc `guile-config compile` -c myguile.c -o myguile.o
-gcc image-type.o myguile.o `guile-config link` -o myguile
-zwingli:example-smob$ ./myguile
-guile> make-image
-#<primitive-procedure make-image>
-guile> (define i (make-image "Whistler's Mother" 100 100))
-guile> i
-#<image Whistler's Mother>
-guile> (clear-image i)
-guile> (clear-image 4)
-ERROR: In procedure clear-image in expression (clear-image 4):
-ERROR: Wrong type argument in position 1: 4
-ABORT: (wrong-type-arg)
-
-Type "(backtrace)" to get more information.
-guile>
-@end example
-
-@c essay @bye
diff --git a/doc/ref/debugging.texi b/doc/ref/debugging.texi
deleted file mode 100644
index 06a61473d..000000000
--- a/doc/ref/debugging.texi
+++ /dev/null
@@ -1,115 +0,0 @@
-@page
-@node Debugging Features
-@chapter Debugging Features
-
-@c --- The title and introduction of this appendix need to
-@c distinguish this clearly from the chapter on the internal
-@c debugging interface.
-
-When debugging a program, programmers often find it helpful to examine
-the program's internal status while it runs: the values of internal
-variables, the choices made in @code{if} and @code{cond} statements, and
-so forth. Guile Scheme provides a debugging interface that programmers
-can use to single-step through Scheme functions and examine symbol
-bindings. This is different from the @ref{Debugging}, which permits
-programmers to debug the Guile interpreter itself. Most programmers
-will be more interested in debugging their own Scheme programs than the
-interpreter which evaluates them.
-
-[FIXME: should we include examples of traditional debuggers
-and explain why they can't be used to debug interpreted Scheme or Lisp?]
-
-@menu
-* Single-Step:: Execute a program or function one step at a time.
-* Trace:: Print a report each time a given function is called.
-* Backtrace:: See a list of the statements that caused an error.
-@end menu
-
-
-@node Single-Step
-@section Single-Step
-
-
-@node Trace
-@section Trace
-
-When a function is @dfn{traced}, it means that every call to that
-function is reported to the user during a program run. This can help a
-programmer determine whether a function is being called at the wrong
-time or with the wrong set of arguments.
-
-@defun trace function
-Enable debug tracing on @code{function}. While a program is being run, Guile
-will print a brief report at each call to a traced function,
-advising the user which function was called and the arguments that were
-passed to it.
-@end defun
-
-@defun untrace function
-Disable debug tracing for @code{function}.
-@end defun
-
-Example:
-
-@lisp
-(define (rev ls)
- (if (null? ls)
- '()
- (append (rev (cdr ls))
- (cons (car ls) '())))) @result{} rev
-
-(trace rev) @result{} (rev)
-
-(rev '(a b c d e))
-@result{} [rev (a b c d e)]
- | [rev (b c d e)]
- | | [rev (c d e)]
- | | | [rev (d e)]
- | | | | [rev (e)]
- | | | | | [rev ()]
- | | | | | ()
- | | | | (e)
- | | | (e d)
- | | (e d c)
- | (e d c b)
- (e d c b a)
- (e d c b a)
-@end lisp
-
-Note the way Guile indents the output, illustrating the depth of
-execution at each function call. This can be used to demonstrate, for
-example, that Guile implements self-tail-recursion properly:
-
-@lisp
-(define (rev ls sl)
- (if (null? ls)
- sl
- (rev (cdr ls)
- (cons (car ls) sl)))) @result{} rev
-
-(trace rev) @result{} (rev)
-
-(rev '(a b c d e) '())
-@result{} [rev (a b c d e) ()]
- [rev (b c d e) (a)]
- [rev (c d e) (b a)]
- [rev (d e) (c b a)]
- [rev (e) (d c b a)]
- [rev () (e d c b a)]
- (e d c b a)
- (e d c b a)
-@end lisp
-
-Since the tail call is effectively optimized to a @code{goto} statement,
-there is no need for Guile to create a new stack frame for each
-iteration. Using @code{trace} here helps us see why this is so.
-
-
-@node Backtrace
-@section Backtrace
-
-@deffn {Scheme Procedure} backtrace
-@deffnx {C Function} scm_backtrace ()
-Display a backtrace of the stack saved by the last error
-to the current output port.
-@end deffn
diff --git a/doc/ref/deprecated.texi b/doc/ref/deprecated.texi
deleted file mode 100644
index 8d335a936..000000000
--- a/doc/ref/deprecated.texi
+++ /dev/null
@@ -1,3 +0,0 @@
-@page
-@node Deprecated
-@chapter Deprecated
diff --git a/doc/ref/expect.texi b/doc/ref/expect.texi
deleted file mode 100644
index 7e169e428..000000000
--- a/doc/ref/expect.texi
+++ /dev/null
@@ -1,142 +0,0 @@
-@page
-@node Expect
-@chapter Expect
-
-The macros in this section are made available with:
-
-@smalllisp
-(use-modules (ice-9 expect))
-@end smalllisp
-
-@code{expect} is a macro for selecting actions based on the output from
-a port. The name comes from a tool of similar functionality by Don Libes.
-Actions can be taken when a particular string is matched, when a timeout
-occurs, or when end-of-file is seen on the port. The @code{expect} macro
-is described below; @code{expect-strings} is a front-end to @code{expect}
-based on regexec (see the regular expression documentation).
-
-@defmac expect-strings clause @dots{}
-By default, @code{expect-strings} will read from the current input port.
-The first term in each clause consists of an expression evaluating to
-a string pattern (regular expression). As characters
-are read one-by-one from the port, they are accumulated in a buffer string
-which is matched against each of the patterns. When a
-pattern matches, the remaining expression(s) in
-the clause are evaluated and the value of the last is returned. For example:
-
-@smalllisp
-(with-input-from-file "/etc/passwd"
- (lambda ()
- (expect-strings
- ("^nobody" (display "Got a nobody user.\n")
- (display "That's no problem.\n"))
- ("^daemon" (display "Got a daemon user.\n")))))
-@end smalllisp
-
-The regular expression is compiled with the @code{REG_NEWLINE} flag, so
-that the ^ and $ anchors will match at any newline, not just at the start
-and end of the string.
-
-There are two other ways to write a clause:
-
-The expression(s) to evaluate
-can be omitted, in which case the result of the regular expression match
-(converted to strings, as obtained from regexec with match-pick set to "")
-will be returned if the pattern matches.
-
-The symbol @code{=>} can be used to indicate that the expression is a
-procedure which will accept the result of a successful regular expression
-match. E.g.,
-
-@smalllisp
-("^daemon" => write)
-("^d\\(aemon\\)" => (lambda args (for-each write args)))
-("^da\\(em\\)on" => (lambda (all sub)
- (write all) (newline)
- (write sub) (newline)))
-@end smalllisp
-
-The order of the substrings corresponds to the order in which the
-opening brackets occur.
-
-A number of variables can be used to control the behaviour
-of @code{expect} (and @code{expect-strings}).
-Most have default top-level bindings to the value @code{#f},
-which produces the default behaviour.
-They can be redefined at the
-top level or locally bound in a form enclosing the expect expression.
-
-@table @code
-@item expect-port
-A port to read characters from, instead of the current input port.
-@item expect-timeout
-@code{expect} will terminate after this number of
-seconds, returning @code{#f} or the value returned by expect-timeout-proc.
-@item expect-timeout-proc
-A procedure called if timeout occurs. The procedure takes a single argument:
-the accumulated string.
-@item expect-eof-proc
-A procedure called if end-of-file is detected on the input port. The
-procedure takes a single argument: the accumulated string.
-@item expect-char-proc
-A procedure to be called every time a character is read from the
-port. The procedure takes a single argument: the character which was read.
-@item expect-strings-compile-flags
-Flags to be used when compiling a regular expression, which are passed
-to @code{make-regexp} @xref{Regexp Functions}. The default value
-is @code{regexp/newline}.
-@item expect-strings-exec-flags
-Flags to be used when executing a regular expression, which are
-passed to regexp-exec @xref{Regexp Functions}.
-The default value is @code{regexp/noteol}, which prevents @code{$}
-from matching the end of the string while it is still accumulating,
-but still allows it to match after a line break or at the end of file.
-@end table
-
-Here's an example using all of the variables:
-
-@smalllisp
-(let ((expect-port (open-input-file "/etc/passwd"))
- (expect-timeout 1)
- (expect-timeout-proc
- (lambda (s) (display "Times up!\n")))
- (expect-eof-proc
- (lambda (s) (display "Reached the end of the file!\n")))
- (expect-char-proc display)
- (expect-strings-compile-flags (logior regexp/newline regexp/icase))
- (expect-strings-exec-flags 0))
- (expect-strings
- ("^nobody" (display "Got a nobody user\n"))))
-@end smalllisp
-@end defmac
-
-@defmac expect clause @dots{}
-@code{expect} is used in the same way as @code{expect-strings},
-but tests are specified not as patterns, but as procedures. The
-procedures are called in turn after each character is read from the
-port, with two arguments: the value of the accumulated string and
-a flag to indicate whether end-of-file has been reached. The flag
-will usually be @code{#f}, but if end-of-file is reached, the procedures
-are called an additional time with the final accumulated string and
-@code{#t}.
-
-The test is successful if the procedure returns a non-false value.
-
-If the @code{=>} syntax is used, then if the test succeeds it must return
-a list containing the arguments to be provided to the corresponding
-expression.
-
-In the following example, a string will only be matched at the beginning
-of the file:
-
-@smalllisp
-(let ((expect-port (open-input-file "/etc/passwd")))
- (expect
- ((lambda (s eof?) (string=? s "fnord!"))
- (display "Got a nobody user!\n"))))
-@end smalllisp
-
-The control variables described for @code{expect-strings} also
-influence the behaviour of @code{expect}, with the exception of
-variables whose names begin with @code{expect-strings-}.
-@end defmac
diff --git a/doc/ref/extend.texi b/doc/ref/extend.texi
deleted file mode 100644
index 5c72bef33..000000000
--- a/doc/ref/extend.texi
+++ /dev/null
@@ -1,44 +0,0 @@
-@page
-@node Libguile Intro
-@chapter Using Guile as an Extension Language
-
-The chapters in this part of the manual explain how to use Guile as a
-powerful application extension language.
-
-An important change for the 1.6.x series of Guile releases is that the
-GH interface is now deprecated. For the reasoning behind this decision,
-see @xref{GH deprecation}. The GH interface will continue to be
-supported for the 1.6.x and 1.8.x release series, but will be dropped
-thereafter, so developers are encouraged to switch progressively to the
-scm interface. The last chapter in this part of the manual (@pxref{GH})
-documents both how to use GH and how to switch from GH to scm.
-
-The Guile developers believe that clarification of the GH vs. scm
-debate, and the consequent deprecation of the GH interface, are in the
-long term interests of the project. However it does create an
-unfortunate situation for developers who want to start a project using
-Guile and so read the manual to find out how to proceed. They will
-discover that the GH interface, although quite well documented, is
-deprecated, but that there is almost no adequate documentation for its
-theoretical replacement, the scm interface. Moreover, the scm interface
-still has the odd few rough edges which need smoothing down.
-
-Therefore, although deprecated, it is quite OK to continue to use the GH
-interface if you feel uncomfortable with the `scm_' interface as it
-stands today. By the time that support for GH is dropped, we plan to
-have thoroughly documented the `scm_' interface, and to have enhanced it
-such that conversion from GH to the `scm_' interface will be very
-straightforward, and probably mostly automated.
-
-As far as documentation of the scm interface is concerned, the current
-position is that it is a bit confused, but that the situation should
-improve rapidly once the 1.6.0 release is out. The plan is to refocus
-the bulk of Part II, currently ``Guile Scheme'', as the ``Guile API
-Reference'' so that it covers both Scheme and C interfaces. (This makes
-sense because almost all of Guile's primitive procedures on the Scheme
-level --- e.g. @code{memq} --- are also available as C level primitives
-in the scm interface --- e.g. @code{scm_memq}.) There will then remain
-a certain amount of Scheme-specific (such as the ``Basic Ideas''
-chapter) and C-specific documentation (such as SMOB usage and
-interaction with the garbage collector) to collect into corresponding
-chapters.
diff --git a/doc/ref/gh.texi b/doc/ref/gh.texi
deleted file mode 100644
index 1cadc168a..000000000
--- a/doc/ref/gh.texi
+++ /dev/null
@@ -1,1170 +0,0 @@
-@page
-@node GH
-@chapter GH: A Portable C to Scheme Interface
-@cindex libguile - gh
-@cindex gh
-@cindex gh - reference manual
-
-This chapter shows how to use the GH interface to call Guile from your
-application's C code, and to add new Scheme level procedures to Guile
-whose behaviour is specified by application specific code written in C.
-
-Note, however, that the GH interface is now deprecated, and developers
-are encouraged to switch to using the scm interface instead. Therefore,
-for each GH feature, this chapter should also document how to achieve
-the same result using the scm interface.
-
-@menu
-* GH deprecation:: Why the GH interface is now deprecated.
-* gh preliminaries::
-* Data types and constants defined by gh::
-* Starting and controlling the interpreter::
-* Error messages::
-* Executing Scheme code::
-* Defining new Scheme procedures in C::
-* Converting data between C and Scheme::
-* Type predicates::
-* Equality predicates::
-* Memory allocation and garbage collection::
-* Calling Scheme procedures from C::
-* Mixing gh and scm APIs::
-* scm transition summary::
-@end menu
-
-
-@node GH deprecation
-@section Why the GH Interface is Now Deprecated
-
-Historically, the GH interface was the product of a practical problem
-and a neat idea. The practical problem was that the interface of the
-@code{scm_} functions with which Guile itself was written (inherited
-from Aubrey Jaffer's SCM) was so closely tied to the (rather arcane)
-details of the internal data representation that it was extremely
-difficult to write a Guile extension using these functions. The neat
-idea was to define a high level language extension interface in such a
-way that other extension language projects, not just Guile, would be
-able to provide an implementation of that interface; then applications
-using this interface could be compiled with whichever of the various
-available implementations they chose. So the GH interface was created,
-and advertised both as the recommended interface for application
-developers wishing to use Guile, and as a portable high level interface
-that could theoretically be implemented by other extension language
-projects.
-
-Time passed, and various things changed. Crucially, an enormous number
-of improvements were made to the @code{scm_} interface that Guile itself
-uses in its implementation, with the result that it is now both easy and
-comfortable to write a Guile extension with this interface. At the same
-time, the contents of the GH interface were somewhat neglected by the
-core Guile developers, such that some key operations --- such as smob
-creation and management --- are simply not possible using GH alone.
-Finally, the idea of multiple implementations of the GH interface did
-not really crystallize (apart, I believe, from a short lived
-implementation by the MzScheme project).
-
-For all these reasons, the Guile developers have decided to deprecate
-the GH interface --- which means that support for GH will be completely
-removed after the next few releases --- and to focus only on the
-@code{scm_} interface, with additions to ensure that it is as easy to
-use in all respects as GH was.
-
-It remains an open question whether a deep kind of interface portability
-would be useful for extension language-based applications, and it may
-still be an interesting project to attempt to define a corresponding
-GH-like interface, but the Guile developers no longer plan to try to do
-this as part of the core Guile project.
-
-
-@node gh preliminaries
-@section gh preliminaries
-
-To use gh, you must have the following toward the beginning of your C
-source:
-@smallexample
-#include <guile/gh.h>
-@end smallexample
-@cindex gh - headers
-
-When you link, you will have to add at least @code{-lguile} to the list
-of libraries. If you are using more of Guile than the basic Scheme
-interpreter, you will have to add more libraries.
-@cindex gh - linking
-
-
-@node Data types and constants defined by gh
-@section Data types and constants defined by gh
-@cindex libguile - data types
-
-The following C constants and data types are defined in gh:
-
-@deftp {Data type} SCM
-This is a C data type used to store all Scheme data, no matter what the
-Scheme type. Values are converted between C data types and the SCM type
-with utility functions described below (@pxref{Converting data between C
-and Scheme}). [FIXME: put in references to Jim's essay and so forth.]
-@end deftp
-@cindex SCM data type
-
-@defvr Constant SCM_BOOL_T
-@defvrx Constant SCM_BOOL_F
-The @emph{Scheme} values returned by many boolean procedures in
-libguile.
-
-This can cause confusion because they are different from 0 and 1. In
-testing a boolean function in libguile programming, you must always make
-sure that you check the spec: @code{gh_} and @code{scm_} functions will
-usually return @code{SCM_BOOL_T} and @code{SCM_BOOL_F}, but other C
-functions usually can be tested against 0 and 1, so programmers' fingers
-tend to just type @code{if (boolean_function()) @{ ... @}}
-@end defvr
-
-@defvr Constant SCM_UNSPECIFIED
-This is a SCM value that is not the same as any legal Scheme value. It
-is the value that a Scheme function returns when its specification says
-that its return value is unspecified.
-@end defvr
-
-@defvr Constant SCM_UNDEFINED
-This is another SCM value that is not the same as any legal Scheme
-value. It is the value used to mark variables that do not yet have a
-value, and it is also used in C to terminate functions with variable
-numbers of arguments, such as @code{gh_list()}.
-@end defvr
-
-
-@node Starting and controlling the interpreter
-@section Starting and controlling the interpreter
-@cindex libguile - start interpreter
-
-In almost every case, your first @code{gh_} call will be:
-
-@deftypefun void gh_enter (int @var{argc}, char *@var{argv}[], void (*@var{main_prog})())
-Starts up a Scheme interpreter with all the builtin Scheme primitives.
-@code{gh_enter()} never exits, and the user's code should all be in the
-@code{@var{main_prog}()} function. @code{argc} and @code{argv} will be
-passed to @var{main_prog}.
-
-@deftypefun void main_prog (int @var{argc}, char *@var{argv}[])
-This is the user's main program. It will be invoked by
-@code{gh_enter()} after Guile has been started up.
-@end deftypefun
-
-Note that you can use @code{gh_repl} inside @code{gh_enter} (in other
-words, inside the code for @code{main-prog}) if you want the program to
-be controlled by a Scheme read-eval-print loop.
-@end deftypefun
-
-@cindex read eval print loop -- from the gh_ interface
-@cindex REPL -- from the gh_ interface
-A convenience routine which enters the Guile interpreter with the
-standard Guile read-eval-print loop (@dfn{REPL}) is:
-
-@deftypefun void gh_repl (int @var{argc}, char *@var{argv}[])
-Enters the Scheme interpreter giving control to the Scheme REPL.
-Arguments are processed as if the Guile program @file{guile} were being
-invoked.
-
-Note that @code{gh_repl} should be used @emph{inside} @code{gh_enter},
-since any Guile interpreter calls are meaningless unless they happen in
-the context of the interpreter.
-
-Also note that when you use @code{gh_repl}, your program will be
-controlled by Guile's REPL (which is written in Scheme and has many
-useful features). Use straight C code inside @code{gh_enter} if you
-want to maintain execution control in your C program.
-@end deftypefun
-
-You will typically use @code{gh_enter} and @code{gh_repl} when you
-want a Guile interpreter enhanced by your own libraries, but otherwise
-quite normal. For example, to build a Guile--derived program that
-includes some random number routines @dfn{GSL} (GNU Scientific Library),
-you would write a C program that looks like this:
-
-@smallexample
-#include <guile/gh.h>
-#include <gsl_ran.h>
-
-/* random number suite */
-SCM gw_ran_seed(SCM s)
-@{
- gsl_ran_seed(gh_scm2int(s));
- return SCM_UNSPECIFIED;
-@}
-
-SCM gw_ran_random()
-@{
- SCM x;
-
- x = gh_ulong2scm(gsl_ran_random());
- return x;
-@}
-
-SCM gw_ran_uniform()
-@{
- SCM x;
-
- x = gh_double2scm(gsl_ran_uniform());
- return x;
-@}
-SCM gw_ran_max()
-@{
- return gh_double2scm(gsl_ran_max());
-@}
-
-void
-init_gsl()
-@{
- /* random number suite */
- gh_new_procedure("gsl-ran-seed", gw_ran_seed, 1, 0, 0);
- gh_new_procedure("gsl-ran-random", gw_ran_random, 0, 0, 0);
- gh_new_procedure("gsl-ran-uniform", gw_ran_uniform, 0, 0, 0);
- gh_new_procedure("gsl-ran-max", gw_ran_max, 0, 0, 0);
-@}
-
-void
-main_prog (int argc, char *argv[])
-@{
- init_gsl();
-
- gh_repl(argc, argv);
-@}
-
-int
-main (int argc, char *argv[])
-@{
- gh_enter (argc, argv, main_prog);
-@}
-@end smallexample
-
-Then, supposing the C program is in @file{guile-gsl.c}, you could
-compile it with @kbd{gcc -o guile-gsl guile-gsl.c -lguile -lgsl}.
-
-The resulting program @file{guile-gsl} would have new primitive
-procedures @code{gsl-ran-random}, @code{gsl-ran-gaussian} and so forth.
-
-
-@node Error messages
-@section Error messages
-@cindex libguile - error messages
-@cindex error messages in libguile
-
-[FIXME: need to fill this based on Jim's new mechanism]
-
-
-@node Executing Scheme code
-@section Executing Scheme code
-@cindex libguile - executing Scheme
-@cindex executing Scheme
-
-Once you have an interpreter running, you can ask it to evaluate Scheme
-code. There are two calls that implement this:
-
-@deftypefun SCM gh_eval_str (char *@var{scheme_code})
-This asks the interpreter to evaluate a single string of Scheme code,
-and returns the result of the last expression evaluated.
-
-Note that the line of code in @var{scheme_code} must be a well formed
-Scheme expression. If you have many lines of code before you balance
-parentheses, you must either concatenate them into one string, or use
-@code{gh_eval_file()}.
-@end deftypefun
-
-@deftypefun SCM gh_eval_file (char *@var{fname})
-@deftypefunx SCM gh_load (char *@var{fname})
-@code{gh_eval_file} is completely analogous to @code{gh_eval_str()},
-except that a whole file is evaluated instead of a string.
-@code{gh_eval_file} returns @code{SCM_UNSPECIFIED}.
-
-@code{gh_load} is identical to @code{gh_eval_file} (it's a macro that
-calls @code{gh_eval_file} on its argument). It is provided to start
-making the @code{gh_} interface match the R5RS Scheme procedures
-closely.
-@end deftypefun
-
-
-@node Defining new Scheme procedures in C
-@section Defining new Scheme procedures in C
-@cindex libguile - new procedures
-@cindex new procedures
-@cindex procedures, new
-@cindex new primitives
-@cindex primitives, new
-
-The real interface between C and Scheme comes when you can write new
-Scheme procedures in C. This is done through the routine
-
-
-@deftypefn {Libguile high} SCM gh_new_procedure (char *@var{proc_name}, SCM (*@var{fn})(), int @var{n_required_args}, int @var{n_optional_args}, int @var{restp})
-@code{gh_new_procedure} defines a new Scheme procedure. Its Scheme name
-will be @var{proc_name}, it will be implemented by the C function
-(*@var{fn})(), it will take at least @var{n_required_args} arguments,
-and at most @var{n_optional_args} extra arguments.
-
-When the @var{restp} parameter is 1, the procedure takes a final
-argument: a list of remaining parameters.
-
-@code{gh_new_procedure} returns an SCM value representing the procedure.
-
-The C function @var{fn} should have the form
-@deftypefn {Libguile high} SCM fn (SCM @var{req1}, SCM @var{req2}, ..., SCM @var{opt1}, SCM @var{opt2}, ..., SCM @var{rest_args})
-The arguments are all passed as SCM values, so the user will have to use
-the conversion functions to convert to standard C types.
-
-Examples of C functions used as new Scheme primitives can be found in
-the sample programs @code{learn0} and @code{learn1}.
-@end deftypefn
-
-@end deftypefn
-
-@strong{Rationale:} this is the correct way to define new Scheme
-procedures in C. The ugly mess of arguments is required because of how
-C handles procedures with variable numbers of arguments.
-
-@strong{Note:} what about documentation strings?
-
-@cartouche
-There are several important considerations to be made when writing the C
-routine @code{(*fn)()}.
-
-First of all the C routine has to return type @code{SCM}.
-
-Second, all arguments passed to the C function will be of type
-@code{SCM}.
-
-Third: the C routine is now subject to Scheme flow control, which means
-that it could be interrupted at any point, and then reentered. This
-means that you have to be very careful with operations such as
-allocating memory, modifying static data @dots{}
-
-Fourth: to get around the latter issue, you can use
-@code{GH_DEFER_INTS} and @code{GH_ALLOW_INTS}.
-@end cartouche
-
-@defmac GH_DEFER_INTS
-@defmacx GH_ALLOW_INTS
-These macros disable and re-enable Scheme's flow control. They
-@end defmac
-
-
-@c [??? have to do this right; maybe using subsections, or maybe creating a
-@c section called Flow control issues...]
-
-@c [??? Go into exhaustive detail with examples of the various possible
-@c combinations of required and optional args...]
-
-
-@node Converting data between C and Scheme
-@section Converting data between C and Scheme
-@cindex libguile - converting data
-@cindex data conversion
-@cindex converting data
-
-Guile provides mechanisms to convert data between C and Scheme. This
-allows new builtin procedures to understand their arguments (which are
-of type @code{SCM}) and return values of type @code{SCM}.
-
-
-@menu
-* C to Scheme::
-* Scheme to C::
-@end menu
-
-@node C to Scheme
-@subsection C to Scheme
-
-@deftypefun SCM gh_bool2scm (int @var{x})
-Returns @code{#f} if @var{x} is zero, @code{#t} otherwise.
-@end deftypefun
-
-@deftypefun SCM gh_ulong2scm (unsigned long @var{x})
-@deftypefunx SCM gh_long2scm (long @var{x})
-@deftypefunx SCM gh_double2scm (double @var{x})
-@deftypefunx SCM gh_char2scm (char @var{x})
-Returns a Scheme object with the value of the C quantity @var{x}.
-@end deftypefun
-
-@deftypefun SCM gh_str2scm (char *@var{s}, int @var{len})
-Returns a new Scheme string with the (not necessarily null-terminated) C
-array @var{s} data.
-@end deftypefun
-
-@deftypefun SCM gh_str02scm (char *@var{s})
-Returns a new Scheme string with the null-terminated C string @var{s}
-data.
-@end deftypefun
-
-@deftypefun SCM gh_set_substr (char *@var{src}, SCM @var{dst}, int @var{start}, int @var{len})
-Copy @var{len} characters at @var{src} into the @emph{existing} Scheme
-string @var{dst}, starting at @var{start}. @var{start} is an index into
-@var{dst}; zero means the beginning of the string.
-
-If @var{start} + @var{len} is off the end of @var{dst}, signal an
-out-of-range error.
-@end deftypefun
-
-@deftypefun SCM gh_symbol2scm (char *@var{name})
-Given a null-terminated string @var{name}, return the symbol with that
-name.
-@end deftypefun
-
-@deftypefun SCM gh_ints2scm (int *@var{dptr}, int @var{n})
-@deftypefunx SCM gh_doubles2scm (double *@var{dptr}, int @var{n})
-Make a scheme vector containing the @var{n} ints or doubles at memory
-location @var{dptr}.
-@end deftypefun
-
-@deftypefun SCM gh_chars2byvect (char *@var{dptr}, int @var{n})
-@deftypefunx SCM gh_shorts2svect (short *@var{dptr}, int @var{n})
-@deftypefunx SCM gh_longs2ivect (long *@var{dptr}, int @var{n})
-@deftypefunx SCM gh_ulongs2uvect (ulong *@var{dptr}, int @var{n})
-@deftypefunx SCM gh_floats2fvect (float *@var{dptr}, int @var{n})
-@deftypefunx SCM gh_doubles2dvect (double *@var{dptr}, int @var{n})
-Make a scheme uniform vector containing the @var{n} chars, shorts,
-longs, unsigned longs, floats or doubles at memory location @var{dptr}.
-@end deftypefun
-
-
-
-@node Scheme to C
-@subsection Scheme to C
-
-@deftypefun int gh_scm2bool (SCM @var{obj})
-@deftypefunx {unsigned long} gh_scm2ulong (SCM @var{obj})
-@deftypefunx long gh_scm2long (SCM @var{obj})
-@deftypefunx double gh_scm2double (SCM @var{obj})
-@deftypefunx int gh_scm2char (SCM @var{obj})
-These routines convert the Scheme object to the given C type.
-@end deftypefun
-
-@deftypefun char *gh_scm2newstr (SCM @var{str}, int *@var{lenp})
-Given a Scheme string @var{str}, return a pointer to a new copy of its
-contents, followed by a null byte. If @var{lenp} is non-null, set
-@code{*@var{lenp}} to the string's length.
-
-This function uses malloc to obtain storage for the copy; the caller is
-responsible for freeing it.
-
-Note that Scheme strings may contain arbitrary data, including null
-characters. This means that null termination is not a reliable way to
-determine the length of the returned value. However, the function
-always copies the complete contents of @var{str}, and sets @var{*lenp}
-to the true length of the string (when @var{lenp} is non-null).
-@end deftypefun
-
-
-@deftypefun void gh_get_substr (SCM str, char *return_str, int *lenp)
-Copy @var{len} characters at @var{start} from the Scheme string
-@var{src} to memory at @var{dst}. @var{start} is an index into
-@var{src}; zero means the beginning of the string. @var{dst} has
-already been allocated by the caller.
-
-If @var{start} + @var{len} is off the end of @var{src}, signal an
-out-of-range error.
-@end deftypefun
-
-@deftypefun char *gh_symbol2newstr (SCM @var{sym}, int *@var{lenp})
-Takes a Scheme symbol and returns a string of the form
-@code{"'symbol-name"}. If @var{lenp} is non-null, the string's length
-is returned in @code{*@var{lenp}}.
-
-This function uses malloc to obtain storage for the returned string; the
-caller is responsible for freeing it.
-@end deftypefun
-
-@deftypefun char *gh_scm2chars (SCM @var{vector}, chars *@var{result})
-@deftypefunx short *gh_scm2shorts (SCM @var{vector}, short *@var{result})
-@deftypefunx long *gh_scm2longs (SCM @var{vector}, long *@var{result})
-@deftypefunx float *gh_scm2floats (SCM @var{vector}, float *@var{result})
-@deftypefunx double *gh_scm2doubles (SCM @var{vector}, double *@var{result})
-Copy the numbers in @var{vector} to the array pointed to by @var{result}
-and return it. If @var{result} is NULL, allocate a double array large
-enough.
-
-@var{vector} can be an ordinary vector, a weak vector, or a signed or
-unsigned uniform vector of the same type as the result array. For
-chars, @var{vector} can be a string or substring. For floats and
-doubles, @var{vector} can contain a mix of inexact and integer values.
-
-If @var{vector} is of unsigned type and contains values too large to fit
-in the signed destination array, those values will be wrapped around,
-that is, data will be copied as if the destination array was unsigned.
-@end deftypefun
-
-
-@node Type predicates
-@section Type predicates
-
-These C functions mirror Scheme's type predicate procedures with one
-important difference. The C routines return C boolean values (0 and 1)
-instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}.
-
-The Scheme notational convention of putting a @code{?} at the end of
-predicate procedure names is mirrored in C by placing @code{_p} at the
-end of the procedure. For example, @code{(pair? ...)} maps to
-@code{gh_pair_p(...)}.
-
-@deftypefun int gh_boolean_p (SCM @var{val})
-Returns 1 if @var{val} is a boolean, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_symbol_p (SCM @var{val})
-Returns 1 if @var{val} is a symbol, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_char_p (SCM @var{val})
-Returns 1 if @var{val} is a char, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_vector_p (SCM @var{val})
-Returns 1 if @var{val} is a vector, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_pair_p (SCM @var{val})
-Returns 1 if @var{val} is a pair, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_procedure_p (SCM @var{val})
-Returns 1 if @var{val} is a procedure, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_list_p (SCM @var{val})
-Returns 1 if @var{val} is a list, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_inexact_p (SCM @var{val})
-Returns 1 if @var{val} is an inexact number, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_exact_p (SCM @var{val})
-Returns 1 if @var{val} is an exact number, 0 otherwise.
-@end deftypefun
-
-
-@node Equality predicates
-@section Equality predicates
-
-These C functions mirror Scheme's equality predicate procedures with one
-important difference. The C routines return C boolean values (0 and 1)
-instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}.
-
-The Scheme notational convention of putting a @code{?} at the end of
-predicate procedure names is mirrored in C by placing @code{_p} at the
-end of the procedure. For example, @code{(equal? ...)} maps to
-@code{gh_equal_p(...)}.
-
-@deftypefun int gh_eq_p (SCM x, SCM y)
-Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
-@code{eq?} predicate, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_eqv_p (SCM x, SCM y)
-Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
-@code{eqv?} predicate, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_equal_p (SCM x, SCM y)
-Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
-@code{equal?} predicate, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_string_equal_p (SCM @var{s1}, SCM @var{s2})
-Returns 1 if the strings @var{s1} and @var{s2} are equal, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_null_p (SCM @var{l})
-Returns 1 if @var{l} is an empty list or pair; 0 otherwise.
-@end deftypefun
-
-
-@node Memory allocation and garbage collection
-@section Memory allocation and garbage collection
-
-@c [FIXME: flesh this out with some description of garbage collection in
-@c scm/guile]
-
-@c @deftypefun SCM gh_mkarray (int size)
-@c Allocate memory for a Scheme object in a garbage-collector-friendly
-@c manner.
-@c @end deftypefun
-
-
-@node Calling Scheme procedures from C
-@section Calling Scheme procedures from C
-
-Many of the Scheme primitives are available in the @code{gh_}
-interface; they take and return objects of type SCM, and one could
-basically use them to write C code that mimics Scheme code.
-
-I will list these routines here without much explanation, since what
-they do is the same as documented in @ref{Standard procedures, R5RS, ,
-r5rs, R5RS}. But I will point out that when a procedure takes a
-variable number of arguments (such as @code{gh_list}), you should pass
-the constant @var{SCM_UNDEFINED} from C to signify the end of the list.
-
-@deftypefun SCM gh_define (char *@var{name}, SCM @var{val})
-Corresponds to the Scheme @code{(define name val)}: it binds a value to
-the given name (which is a C string). Returns the new object.
-@end deftypefun
-
-@heading Pairs and lists
-
-@deftypefun SCM gh_cons (SCM @var{a}, SCM @var{b})
-@deftypefunx SCM gh_list (SCM l0, SCM l1, ... , SCM_UNDEFINED)
-These correspond to the Scheme @code{(cons a b)} and @code{(list l0 l1
-...)} procedures. Note that @code{gh_list()} is a C macro that invokes
-@code{scm_listify()}.
-@end deftypefun
-
-@deftypefun SCM gh_car (SCM @var{obj})
-@deftypefunx SCM gh_cdr (SCM @var{obj})
-@dots{}
-
-@deftypefunx SCM gh_c[ad][ad][ad][ad]r (SCM @var{obj})
-These correspond to the Scheme @code{(caadar ls)} procedures etc @dots{}
-@end deftypefun
-
-@deftypefun SCM gh_set_car_x(SCM @var{pair}, SCM @var{value})
-Modifies the CAR of @var{pair} to be @var{value}. This is equivalent to
-the Scheme procedure @code{(set-car! ...)}.
-@end deftypefun
-
-@deftypefun SCM gh_set_cdr_x(SCM @var{pair}, SCM @var{value})
-Modifies the CDR of @var{pair} to be @var{value}. This is equivalent to
-the Scheme procedure @code{(set-cdr! ...)}.
-@end deftypefun
-
-@deftypefun {unsigned long} gh_length (SCM @var{ls})
-Returns the length of the list.
-@end deftypefun
-
-@deftypefun SCM gh_append (SCM @var{args})
-@deftypefunx SCM gh_append2 (SCM @var{l1}, SCM @var{l2})
-@deftypefunx SCM gh_append3 (SCM @var{l1}, SCM @var{l2}, @var{l3})
-@deftypefunx SCM gh_append4 (SCM @var{l1}, SCM @var{l2}, @var{l3}, @var{l4})
-@code{gh_append()} takes @var{args}, which is a list of lists
-@code{(list1 list2 ...)}, and returns a list containing all the elements
-of the individual lists.
-
-A typical invocation of @code{gh_append()} to append 5 lists together
-would be
-@smallexample
- gh_append(gh_list(l1, l2, l3, l4, l5, SCM_UNDEFINED));
-@end smallexample
-
-The functions @code{gh_append2()}, @code{gh_append2()},
-@code{gh_append3()} and @code{gh_append4()} are convenience routines to
-make it easier for C programs to form the list of lists that goes as an
-argument to @code{gh_append()}.
-@end deftypefun
-
-@deftypefun SCM gh_reverse (SCM @var{ls})
-Returns a new list that has the same elements as @var{ls} but in the
-reverse order. Note that this is implemented as a macro which calls
-@code{scm_reverse()}.
-@end deftypefun
-
-@deftypefun SCM gh_list_tail (SCM @var{ls}, SCM @var{k})
-Returns the sublist of @var{ls} with the last @var{k} elements.
-@end deftypefun
-
-@deftypefun SCM gh_list_ref (SCM @var{ls}, SCM @var{k})
-Returns the @var{k}th element of the list @var{ls}.
-@end deftypefun
-
-@deftypefun SCM gh_memq (SCM @var{x}, SCM @var{ls})
-@deftypefunx SCM gh_memv (SCM @var{x}, SCM @var{ls})
-@deftypefunx SCM gh_member (SCM @var{x}, SCM @var{ls})
-These functions return the first sublist of @var{ls} whose CAR is
-@var{x}. They correspond to @code{(memq x ls)}, @code{(memv x ls)} and
-@code{(member x ls)}, and hence use (respectively) @code{eq?},
-@code{eqv?} and @code{equal?} to do comparisons.
-
-If @var{x} does not appear in @var{ls}, the value @code{SCM_BOOL_F} (not
-the empty list) is returned.
-
-Note that these functions are implemented as macros which call
-@code{scm_memq()}, @code{scm_memv()} and @code{scm_member()}
-respectively.
-@end deftypefun
-
-@deftypefun SCM gh_assq (SCM @var{x}, SCM @var{alist})
-@deftypefunx SCM gh_assv (SCM @var{x}, SCM @var{alist})
-@deftypefunx SCM gh_assoc (SCM @var{x}, SCM @var{alist})
-These functions search an @dfn{association list} (list of pairs)
-@var{alist} for the first pair whose CAR is @var{x}, and they return
-that pair.
-
-If no pair in @var{alist} has @var{x} as its CAR, the value
-@code{SCM_BOOL_F} (not the empty list) is returned.
-
-Note that these functions are implemented as macros which call
-@code{scm_assq()}, @code{scm_assv()} and @code{scm_assoc()}
-respectively.
-@end deftypefun
-
-
-@heading Symbols
-
-@c @deftypefun SCM gh_symbol (SCM str, SCM len)
-@c @deftypefunx SCM gh_tmp_symbol (SCM str, SCM len)
-@c Takes the given string @var{str} of length @var{len} and returns a
-@c symbol corresponding to that string.
-@c @end deftypefun
-
-
-@heading Vectors
-
-@deftypefun SCM gh_make_vector (SCM @var{n}, SCM @var{fill})
-@deftypefunx SCM gh_vector (SCM @var{ls})
-@deftypefunx SCM gh_vector_ref (SCM @var{v}, SCM @var{i})
-@deftypefunx SCM gh_vector_set (SCM @var{v}, SCM @var{i}, SCM @var{val})
-@deftypefunx {unsigned long} gh_vector_length (SCM @var{v})
-@deftypefunx SCM gh_list_to_vector (SCM @var{ls})
-These correspond to the Scheme @code{(make-vector n fill)},
-@code{(vector a b c ...)} @code{(vector-ref v i)} @code{(vector-set v i
-value)} @code{(vector-length v)} @code{(list->vector ls)} procedures.
-
-The correspondence is not perfect for @code{gh_vector}: this routine
-takes a list @var{ls} instead of the individual list elements, thus
-making it identical to @code{gh_list_to_vector}.
-
-There is also a difference in gh_vector_length: the value returned is a
-C @code{unsigned long} instead of an SCM object.
-@end deftypefun
-
-
-@heading Procedures
-
-@c @deftypefun SCM gh_make_subr (SCM (*@var{fn})(), int @var{req}, int @var{opt}, int @var{restp}, char *@var{sym})
-@c Make the C function @var{fn} available to Scheme programs. The function
-@c will be bound to the symbol @var{sym}. The arguments @var{req},
-@c @var{opt} and @var{restp} describe @var{fn}'s calling conventions. The
-@c function must take @var{req} required arguments and may take @var{opt}
-@c optional arguments. Any optional arguments which are not supplied by
-@c the caller will be bound to @var{SCM_UNSPECIFIED}. If @var{restp} is
-@c non-zero, it means that @var{fn} may be called with an arbitrary number
-@c of arguments, and that any extra arguments supplied by the caller will
-@c be passed to @var{fn} as a list. The @var{restp} argument is exactly
-@c like Scheme's @code{(lambda (arg1 arg2 . arglist))} calling convention.
-@c
-@c For example, the procedure @code{read-line}, which takes optional
-@c @var{port} and @var{handle-delim} arguments, would be declared like so:
-@c
-@c @example
-@c SCM scm_read_line (SCM port, SCM handle_delim);
-@c gh_make_subr (scm_read_line, 0, 2, 0, "read-line");
-@c @end example
-@c
-@c The @var{req} argument to @code{gh_make_subr} is 0 to indicate that
-@c there are no required arguments, so @code{read-line} may be called
-@c without any arguments at all. The @var{opt} argument is 2, to indicate
-@c that both the @var{port} and @var{handle_delim} arguments to
-@c @code{scm_read_line} are optional, and will be bound to
-@c @code{SCM_UNSPECIFIED} if the calling program does not supply them.
-@c Because the @var{restp} argument is 0, this function may not be called
-@c with more than two arguments.
-@c @end deftypefun
-
-@deftypefun SCM gh_apply (SCM proc, SCM args)
-Call the Scheme procedure @var{proc}, with the elements of @var{args} as
-arguments. @var{args} must be a proper list.
-@end deftypefun
-
-@deftypefun SCM gh_call0 (SCM proc)
-@deftypefunx SCM gh_call1 (SCM proc, SCM arg)
-@deftypefunx SCM gh_call2 (SCM proc, SCM arg1, SCM arg2)
-@deftypefunx SCM gh_call3 (SCM proc, SCM arg1, SCM arg2, SCM arg3)
-Call the Scheme procedure @var{proc} with no arguments
-(@code{gh_call0}), one argument (@code{gh_call1}), and so on. You can
-get the same effect by wrapping the arguments up into a list, and
-calling @code{gh_apply}; Guile provides these functions for convenience.
-@end deftypefun
-
-
-@deftypefun SCM gh_catch (SCM key, SCM thunk, SCM handler)
-@deftypefunx SCM gh_throw (SCM key, SCM args)
-Corresponds to the Scheme @code{catch} and @code{throw} procedures,
-which in Guile are provided as primitives.
-@end deftypefun
-
-@c [FIXME: must add the I/O section in gscm.h]
-
-@deftypefun SCM gh_is_eq (SCM a, SCM b)
-@deftypefunx SCM gh_is_eqv (SCM a, SCM b)
-@deftypefunx SCM gh_is_equal (SCM a, SCM b)
-These correspond to the Scheme @code{eq?}, @code{eqv?} and @code{equal?}
-predicates.
-@end deftypefun
-
-@deftypefun int gh_obj_length (SCM @var{obj})
-Returns the raw object length.
-@end deftypefun
-
-@heading Data lookup
-
-For now I just include Tim Pierce's comments from the @file{gh_data.c}
-file; it should be organized into a documentation of the two functions
-here.
-
-@smallexample
-/* Data lookups between C and Scheme
-
- Look up a symbol with a given name, and return the object to which
- it is bound. gh_lookup examines the Guile top level, and
- gh_module_lookup checks the module name space specified by the
- `vec' argument.
-
- The return value is the Scheme object to which SNAME is bound, or
- SCM_UNDEFINED if SNAME is not bound in the given context. [FIXME:
- should this be SCM_UNSPECIFIED? Can a symbol ever legitimately be
- bound to SCM_UNDEFINED or SCM_UNSPECIFIED? What is the difference?
- -twp] */
-@end smallexample
-
-
-@node Mixing gh and scm APIs
-@section Mixing gh and scm APIs
-
-
-@node scm transition summary
-@section Transitioning to the scm Interface
-
-The following table summarizes the available information on how to
-transition from the GH to the scm interface. Where transitioning is not
-completely straightforward, the table includes a reference to more
-detailed documentation in the preceding sections.
-
-@table @asis
-@item Header file
-Use @code{#include <libguile.h>} instead of @code{#include
-<guile/gh.h>}.
-
-@item Compiling and Linking
-Use @code{guile-config} to pick up the flags required to compile C or
-C++ code that uses @code{libguile}, like so
-
-@smallexample
-$(CC) -o prog.o -c prog.c `guile-config compile`
-@end smallexample
-
-If you are using libtool to link your executables, just use
-@code{-lguile} in your link command. Libtool will expand this into
-the needed linker options automatically. If you are not using
-libtool, use the @code{guile-config} program to query the needed
-options explicitly. A linker command like
-
-@smallexample
-$(CC) -o prog prog.o `guile-config link`
-@end smallexample
-
-should be all that is needed. To link shared libraries that will be
-used as Guile Extensions, use libtool to control both the compilation
-and the link stage.
-
-@item The @code{SCM} type
-No change: the scm interface also uses this type to represent an
-arbitrary Scheme value.
-
-@item @code{SCM_BOOL_F} and @code{SCM_BOOL_T}
-No change.
-
-@item @code{SCM_UNSPECIFIED} and @code{SCM_UNDEFINED}
-No change.
-
-@item @code{gh_enter}
-Use @code{scm_boot_guile} instead, but note that @code{scm_boot_guile}
-has a slightly different calling convention from @code{gh_enter}:
-@code{scm_boot_guile}, and the main program function that you specify
-for @code{scm_boot_guile} to call, both take an additional @var{closure}
-parameter. @ref{Guile Initialization Functions} for more details.
-
-@item @code{gh_repl}
-Use @code{scm_shell} instead.
-
-@item @code{gh_init}
-Use @code{scm_init_guile} instead.
-
-@item @code{gh_eval_str}
-Use @code{scm_c_eval_string} instead.
-
-@item @code{gh_eval_file} or @code{gh_load}
-Use @code{scm_c_primitive_load} instead.
-
-@item @code{gh_new_procedure}
-Use @code{scm_c_define_gsubr} instead, but note that the arguments are
-in a different order: for @code{scm_c_define_gsubr} the C function
-pointer is the last argument. @ref{A Sample Guile Extension} for an
-example.
-
-@item @code{gh_defer_ints} and @code{gh_allow_ints}
-Use @code{SCM_DEFER_INTS} and @code{SCM_ALLOW_INTS} instead. Note that
-these macros are used without parentheses, as in @code{SCM_DEFER_INTS;}.
-
-@item @code{gh_bool2scm}
-Use @code{SCM_BOOL} instead.
-
-@item @code{gh_ulong2scm}
-Use @code{scm_ulong2num} instead.
-
-@item @code{gh_long2scm}
-Use @code{scm_long2num} instead.
-
-@item @code{gh_double2scm}
-Use @code{scm_make_real} instead.
-
-@item @code{gh_char2scm}
-Use @code{SCM_MAKE_CHAR} instead.
-
-@item @code{gh_str2scm}
-Use @code{scm_mem2string} instead.
-
-@item @code{gh_str02scm}
-Use @code{scm_makfrom0str} instead.
-
-@item @code{gh_set_substr}
-No direct scm equivalent. [FIXME]
-
-@item @code{gh_symbol2scm}
-Use @code{scm_str2symbol} instead. [FIXME: inconsistent naming,
-should be @code{scm_str02symbol}.]
-
-@item @code{gh_ints2scm} and @code{gh_doubles2scm}
-Use @code{scm_c_ints2scm} and @code{scm_c_doubles2scm} instead.
-
-@item @code{gh_chars2byvect} and @code{gh_shorts2svect}
-Use @code{scm_c_chars2byvect} and @code{scm_c_shorts2svect} instead.
-
-@item @code{gh_longs2ivect} and @code{gh_ulongs2uvect}
-Use @code{scm_c_longs2ivect} and @code{scm_c_ulongs2uvect} instead.
-
-@item @code{gh_floats2fvect} and @code{gh_doubles2dvect}
-Use @code{scm_c_floats2fvect} and @code{scm_c_doubles2dvect} instead.
-
-@item @code{gh_scm2bool}
-Use @code{SCM_NFALSEP} instead.
-
-@item @code{gh_scm2int}
-Replace @code{gh_scm2int (@var{obj})} by
-@example
-scm_num2int (@var{obj}, SCM_ARG1, @var{str})
-@end example
-where @var{str} is a C string that describes the context of the call.
-
-@item @code{gh_scm2ulong}
-Replace @code{gh_scm2ulong (@var{obj})} by
-@example
-scm_num2ulong (@var{obj}, SCM_ARG1, @var{str})
-@end example
-where @var{str} is a C string that describes the context of the call.
-
-@item @code{gh_scm2long}
-Replace @code{gh_scm2long (@var{obj})} by
-@example
-scm_num2long (@var{obj}, SCM_ARG1, @var{str})
-@end example
-where @var{str} is a C string that describes the context of the call.
-
-@item @code{gh_scm2double}
-Replace @code{gh_scm2double (@var{obj})} by
-@example
-scm_num2dbl (@var{obj}, @var{str})
-@end example
-where @var{str} is a C string that describes the context of the call.
-
-@item @code{gh_scm2char}
-Use the @code{SCM_CHAR} macro instead, but note that @code{SCM_CHAR}
-does not check that its argument is actually a character. To check that
-a @code{SCM} value is a character before using @code{SCM_CHAR} to
-extract the character value, use the @code{SCM_VALIDATE_CHAR} macro.
-
-@item @code{gh_scm2newstr}
-Instead of @code{gh_scm2newstr (@var{obj}, @var{lenp})} use
-@code{scm_c_string2str (@var{obj}, @var{str}, @var{lenp})}. With the
-additional @var{str} argument the user can pass a pre-allocated memory
-chunk or leave it passing NULL.
-
-@item @code{gh_get_substr}
-Use the @code{scm_c_substring2str (@var{obj}, @var{str}, @var{start},
-@var{len})} function instead.
-
-@item @code{gh_symbol2newstr}
-Use the @code{scm_c_symbol2str (@var{obj}, @var{str}, @var{lenp})} function
-instead. With the additional @var{str} argument the user can pass a
-pre-allocated memory chunk or leave it passing NULL.
-
-@item @code{gh_scm2chars}
-Use @code{scm_c_scm2chars} instead.
-
-@item @code{gh_scm2shorts} and @code{gh_scm2longs}
-Use @code{scm_c_shorts2scm} and @code{scm_c_longs2scm} instead.
-
-@item @code{gh_scm2floats} and @code{gh_scm2doubles}
-Use @code{scm_c_floats2scm} and @code{scm_c_doubles2scm} instead.
-
-@item @code{gh_boolean_p}
-Use the @code{SCM_BOOLP} macro instead, or replace @code{gh_boolean_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_boolean_p (@var{obj}))
-@end example
-
-@item @code{gh_symbol_p}
-Use the @code{SCM_SYMBOLP} macro instead, or replace @code{gh_symbol_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_symbol_p (@var{obj}))
-@end example
-
-@item @code{gh_char_p}
-Use the @code{SCM_CHARP} macro instead, or replace @code{gh_char_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_char_p (@var{obj}))
-@end example
-
-@item @code{gh_vector_p}
-Use the @code{SCM_VECTORP} macro instead, or replace @code{gh_vector_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_vector_p (@var{obj}))
-@end example
-
-@item @code{gh_pair_p}
-Use the @code{SCM_CONSP} macro instead, or replace @code{gh_pair_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_pair_p (@var{obj}))
-@end example
-
-@item @code{gh_number_p}
-Use the @code{SCM_NUMBERP} macro instead, or replace @code{gh_number_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_number_p (@var{obj}))
-@end example
-
-@item @code{gh_string_p}
-Use the @code{SCM_STRINGP} macro instead, or replace @code{gh_string_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_string_p (@var{obj}))
-@end example
-
-@item @code{gh_procedure_p}
-Replace @code{gh_procedure_p (@var{obj})} by
-@example
-SCM_NFALSEP (scm_procedure_p (@var{obj}))
-@end example
-
-@item @code{gh_list_p}
-Replace @code{gh_list_p (@var{obj})} by
-@example
-SCM_NFALSEP (scm_list_p (@var{obj}))
-@end example
-
-@item @code{gh_inexact_p}
-Use the @code{SCM_INEXACTP} macro instead, or replace @code{gh_inexact_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_inexact_p (@var{obj}))
-@end example
-
-@item @code{gh_exact_p}
-Replace @code{gh_exact_p (@var{obj})} by
-@example
-SCM_NFALSEP (scm_exact_p (@var{obj}))
-@end example
-
-@item @code{gh_eq_p}
-Use the @code{SCM_EQ_P} macro instead, or replace @code{gh_eq_p
-(@var{x}, @var{y})} by
-@example
-SCM_NFALSEP (scm_eq_p (@var{x}, @var{y}))
-@end example
-
-@item @code{gh_eqv_p}
-Replace @code{gh_eqv_p (@var{x}, @var{y})} by
-@example
-SCM_NFALSEP (scm_eqv_p (@var{x}, @var{y}))
-@end example
-
-@item @code{gh_equal_p}
-Replace @code{gh_equal_p (@var{x}, @var{y})} by
-@example
-SCM_NFALSEP (scm_equal_p (@var{x}, @var{y}))
-@end example
-
-@item @code{gh_string_equal_p}
-Replace @code{gh_string_equal_p (@var{x}, @var{y})} by
-@example
-SCM_NFALSEP (scm_string_equal_p (@var{x}, @var{y}))
-@end example
-
-@item @code{gh_null_p}
-Use the @code{SCM_NULLP} macro instead, or replace @code{gh_null_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_null_p (@var{obj}))
-@end example
-
-@item @code{gh_cons}
-Use @code{scm_cons} instead.
-
-@item @code{gh_car} and @code{gh_cdr}
-Use the @code{SCM_CAR} and @code{SCM_CDR} macros instead.
-
-@item @code{gh_cxxr} and @code{gh_cxxxr}
-(Where each x is either @samp{a} or @samp{d}.) Use the corresponding
-@code{SCM_CXXR} or @code{SCM_CXXXR} macro instead.
-
-@item @code{gh_set_car_x} and @code{gh_set_cdr_x}
-Use @code{scm_set_car_x} and @code{scm_set_cdr_x} instead.
-
-@item @code{gh_list}
-Use @code{scm_listify} instead.
-
-@item @code{gh_length}
-Replace @code{gh_length (@var{lst})} by
-@example
-scm_num2ulong (scm_length (@var{lst}), SCM_ARG1, @var{str})
-@end example
-where @var{str} is a C string that describes the context of the call.
-
-@item @code{gh_append}
-Use @code{scm_append} instead.
-
-@item @code{gh_append2}, @code{gh_append3}, @code{gh_append4}
-Replace @code{gh_append@var{N} (@var{l1}, @dots{}, @var{lN})} by
-@example
-scm_append (scm_listify (@var{l1}, @dots{}, @var{lN}, SCM_UNDEFINED))
-@end example
-
-@item @code{gh_reverse}
-Use @code{scm_reverse} instead.
-
-@item @code{gh_list_tail} and @code{gh_list_ref}
-Use @code{scm_list_tail} and @code{scm_list_ref} instead.
-
-@item @code{gh_memq}, @code{gh_memv} and @code{gh_member}
-Use @code{scm_memq}, @code{scm_memv} and @code{scm_member} instead.
-
-@item @code{gh_assq}, @code{gh_assv} and @code{gh_assoc}
-Use @code{scm_assq}, @code{scm_assv} and @code{scm_assoc} instead.
-
-@item @code{gh_make_vector}
-Use @code{scm_make_vector} instead.
-
-@item @code{gh_vector} or @code{gh_list_to_vector}
-Use @code{scm_vector} instead.
-
-@item @code{gh_vector_ref} and @code{gh_vector_set_x}
-Use @code{scm_vector_ref} and @code{scm_vector_set_x} instead.
-
-@item @code{gh_vector_length}
-Use the @code{SCM_VECTOR_LENGTH} macro instead.
-
-@item @code{gh_apply}
-Use @code{scm_apply} instead, but note that @code{scm_apply} takes an
-additional third argument that you should set to @code{SCM_EOL}.
-
-@end table
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
deleted file mode 100644
index c819fb53d..000000000
--- a/doc/ref/guile.texi
+++ /dev/null
@@ -1,389 +0,0 @@
-\input texinfo
-@c -*-texinfo-*-
-@c %**start of header
-@setfilename guile.info
-@settitle Guile Reference Manual
-@set guile
-@set MANUAL_EDITION 1.1
-@c %**end of header
-
-@c Notes
-@c
-@c We no longer use the category "primitive" to distinguish C-defined
-@c Scheme procedures from those defined in Scheme. Instead, the
-@c reference manual now includes a C declaration as well as a Scheme
-@c declaration for each procedure that is available in both Scheme and
-@c C.
-@c
-@c When adding a new reference entry to the Guile manual, please
-@c document it with @deffn using one of the following categories:
-@c
-@c {Scheme Procedure}
-@c {Scheme Syntax}
-@c {C Function}
-@c {C Macro}
-@c
-@c If the entry is for a new primitive, it should have both a @deffn
-@c {Scheme Procedure} line and a @deffnx {C Function} line; see the
-@c manual source for plenty of existing examples of this.
-@c
-@c For {C Function} entries where the return type and all parameter
-@c types are SCM, we omit the SCMs. This is easier to read and also
-@c gets round the problem that Texinfo doesn't allow a @deftypefnx
-@c inside a @deffn.
-@c
-@c For a list of Guile primitives that are not yet incorporated into the
-@c reference manual, see the file `new-docstrings.texi', which holds all
-@c the docstrings snarfed from the libguile C sources for primitives
-@c that are not in the reference manual. If you have worked with some
-@c of these concepts, implemented them, or just happen to know what they
-@c do, please write up a little explanation -- it would be a big help.
-@c Alternatively, if you know of any reason why some of these should
-@c *not* go in the manual, please let the mailing list
-@c <guile-devel@gnu.org> know.
-
-@c Define indices that are used in the Guile Scheme part of the
-@c reference manual to group stuff according to whether it is R5RS or a
-@c Guile extension.
-@defcodeindex rn
-
-@include version.texi
-
-@c vnew - For (some) new items, indicates the Guile version in which
-@c item first appeared. In future, this could be made to expand to
-@c something like a "New in Guile 45!" banner.
-@macro vnew{VERSION}
-@end macro
-
-@c @iftex
-@c @cropmarks
-@c @end iftex
-
-@dircategory The Algorithmic Language Scheme
-@direntry
-* Guile Reference: (guile). The Guile reference manual.
-@end direntry
-
-@setchapternewpage off
-
-@ifinfo
-Guile Reference Manual
-Copyright (C) 1996 Free Software Foundation @*
-Copyright (C) 1997 Free Software Foundation @*
-Copyright (C) 2000 Free Software Foundation @*
-Copyright (C) 2001 Free Software Foundation @*
-Copyright (C) 2002 Free Software Foundation
-
-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.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-@end ignore
-
-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 Free Software Foundation.
-@end ifinfo
-
-@titlepage
-@sp 10
-@comment The title is printed in a large font.
-@title Guile Reference Manual
-@subtitle Edition @value{MANUAL_EDITION}, for use with Guile @value{VERSION}
-@subtitle $Id: guile.texi,v 1.18 2002-04-20 19:26:40 ossau Exp $
-
-@c AUTHORS
-
-@c The Guile reference and tutorial manuals were written and edited
-@c largely by Mark Galassi and Jim Blandy. In particular, Jim wrote the
-@c original tutorial on Guile's data representation and the C API for
-@c accessing Guile objects.
-
-@c Significant portions were contributed by Gary Houston (contributions
-@c to POSIX system calls and networking, expect, I/O internals and
-@c extensions, slib installation, error handling) and Tim Pierce
-@c (sections on script interpreter triggers, alists, function tracing).
-
-@c Tom Lord contributed a great deal of material with early Guile
-@c snapshots; although most of this text has been rewritten, all of it
-@c was important, and some of the structure remains.
-
-@c Aubrey Jaffer wrote the SCM Scheme implementation and manual upon
-@c which the Guile program and manual are based. Some portions of the
-@c SCM and SLIB manuals have been included here verbatim.
-
-@c Since Guile 1.4, Neil Jerram has been maintaining and improving the
-@c reference manual. Among other contributions, he wrote the Basic
-@c Ideas chapter, developed the tools for keeping the manual in sync
-@c with snarfed libguile docstrings, and reorganized the structure so as
-@c to accommodate docstrings for all Guile's primitives.
-
-@c Martin Grabmueller has made substantial contributions throughout the
-@c reference manual in preparation for the Guile 1.6 release, including
-@c filling out a lot of the documentation of Scheme data types, control
-@c mechanisms and procedures. In addition, he wrote the documentation
-@c for Guile's SRFI modules and modules associated with the Guile REPL.
-
-@author Mark Galassi
-@author Cygnus Solution and Los Alamos National Laboratory
-@author @email{rosalia@@cygnus.com}
-@author
-@author Jim Blandy
-@author Free Software Foundation and MIT AI Lab
-@author @email{jimb@@red-bean.com}
-@author
-@author Gary Houston
-@author @email{ghouston@@arglist.com}
-@author
-@author Tim Pierce
-@author @email{twp@@skepsis.com}
-@author
-@author Neil Jerram
-@author @email{neil@@ossau.uklinux.net}
-@author
-@author Martin Grabmueller
-@author @email{mgrabmue@@cs.tu-berlin.de}
-
-@c The following two commands start the copyright page.
-@page
-@vskip 0pt plus 1filll
-@vskip 0pt plus 1filll
-Copyright @copyright{} 1996 Free Software Foundation
-
-Copyright @copyright{} 1997 Free Software Foundation
-
-Copyright @copyright{} 2000 Free Software Foundation
-
-Copyright @copyright{} 2001 Free Software Foundation
-
-Copyright @copyright{} 2002 Free Software Foundation
-
-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 Free Software Foundation.
-@end titlepage
-
-@c @smallbook
-@finalout
-@headings double
-
-@c Where to find Guile examples.
-@set example-dir doc/examples
-
-@ifnottex
-@node Top, Guile License, (dir), (dir)
-@top The Guile Reference Manual
-
-This reference manual documents Guile, GNU's Ubiquitous Intelligent
-Language for Extensions. It describes how to use Guile in many useful
-and interesting ways.
-
-This Info file contains edition @value{MANUAL_EDITION} of the reference
-manual, corresponding to Guile version @value{VERSION}.
-@end ifnottex
-
-@menu
-Preface
-
-* Guile License:: Conditions for copying and using Guile.
-* Manual Layout:: How to read the rest of this manual.
-* Manual Conventions:: Conventional terminology.
-
-Part I: Introduction to Guile
-
-* What is Guile?:: And what does it do?
-* Whirlwind Tour:: An introductory whirlwind tour.
-* Obtaining and Installing Guile::
-* Reporting Bugs:: Reporting bugs in Guile or this manual.
-
-Part II: Writing and Running Guile Scheme
-
-* Running Intro:: Introduction to this part.
-* Guile Scheme:: Guile's implementation of Scheme.
-* Guile Scripting:: How to write Guile scripts.
-* Command Line Handling:: Command line options and arguments.
-* Debugging Features:: Features for debugging errors.
-* Autoconf Support:: Guile-specific configure.in macros.
-* Miscellaneous Tools:: Snarfing, linting, etc.
-* Basic Ideas:: Basic ideas in Scheme.
-* Further Reading:: Where to find out more about Scheme.
-
-Part III: Guile as an Extension Language
-
-* Programming Intro:: Introduction to this part.
-* Libguile Intro:: Using Guile as an extension language.
-* Programming Overview:: An overview of Guile programming.
-* Data Representation:: Data representation in Guile.
-* GH:: The deprecated GH interface.
-
-Part IV: Guile API Reference
-
-* Reference Intro:: Introduction to the Guile API reference.
-* API Overview:: Overview of the Guile API.
-* Simple Data Types:: Numbers, strings, booleans and so on.
-* Compound Data Types:: Data types for holding other data.
-* Procedures and Macros:: Procedures and macros.
-* Utility Functions:: General utility functions.
-* Binding Constructs:: Definitions and variable bindings.
-* Control Mechanisms:: Controlling the flow of program execution.
-* Input and Output:: Ports, reading and writing.
-* Read/Load/Eval:: Reading and evaluating Scheme code.
-* Memory Management:: Memory management and garbage collection.
-* Objects:: Low level object orientation support.
-* Modules:: Designing reusable code libraries.
-* Scheduling:: Threads, mutexes, asyncs and dynamic roots.
-* Options and Config:: Runtime options and configuration.
-* Translation:: Support for translating other languages.
-* Debugging:: Internal debugging interface.
-* Deprecated:: Features that are planned to disappear.
-
-Part V: Guile Modules
-
-* SLIB:: Using the SLIB Scheme library.
-* POSIX:: POSIX system calls and networking.
-* SRFI Support:: Support for various SRFIs.
-* Readline Support:: Module for using the readline library.
-* Value History:: Maintaining a value history in the REPL.
-* Pretty Printing:: Nicely formatting Scheme objects for output.
-* Formatted Output:: The @code{format} procedure.
-* Rx Regexps:: The Rx regular expression library.
-* Expect:: Controlling interactive programs with Guile.
-* The Scheme shell (scsh):: Using scsh interfaces in Guile.
-
-Indices
-
-* Concept Index::
-* Procedure Index::
-* Variable Index::
-* Type Index::
-* R5RS Index::
-
-@end menu
-
-@include preface.texi
-
-@iftex
-@page
-@unnumbered{Part I: Introduction to Guile}
-@end iftex
-
-@include intro.texi
-
-@page
-@node Running Intro
-@unnumbered Part II: Writing and Running Guile Scheme
-
-Guile's core language is Scheme, and an awful lot can be achieved simply
-by using Guile to write and run Scheme programs. In this part of the
-manual, we explain how to use Guile in this mode, and describe the tools
-that Guile provides to help you with script writing, debugging and
-packaging your programs for distribution.
-
-For readers who are not yet familiar with the Scheme language, this part
-includes a chapter that presents the basic concepts of the language, and
-gives references to freely available Scheme tutorial material on the
-web.
-
-For detailed reference information on the variables, functions etc. that
-make up Guile's application programming interface (API), please refer to
-Part IV (@pxref{Reference Intro,,Part IV --- Guile API Reference}).
-
-@include scheme-intro.texi
-@include scripts.texi
-@include script-getopt.texi
-@include debugging.texi
-@include autoconf.texi
-@include tools.texi
-@include scheme-ideas.texi
-@include scheme-reading.texi
-
-@page
-@node Programming Intro
-@unnumbered Part III: Guile as an Extension Language
-
-In this part of the manual, we aim to present a wide ranging picture of
-what it means to use Guile as an application extension language, to
-provide guidance, practical guidelines and tips for @emph{how} to
-program in Guile, and to document the tools that are available to help
-you with your programming. For detailed reference information on the
-variables, functions etc. that make up Guile's application programming
-interface (API), please refer to Part IV (@pxref{Reference Intro,,Part
-IV --- Guile API Reference}).
-
-@include extend.texi
-@include program.texi
-@include data-rep.texi
-@include gh.texi
-
-@page
-@node Reference Intro
-@unnumbered Part IV: Guile API Reference
-
-Guile provides an application programming interface (@dfn{API}) to
-developers in two core languages: Scheme and C. This part of the manual
-contains reference documentation for all of the functionality that is
-available through both Scheme and C interfaces.
-
-@include scm.texi
-@include scheme-data.texi
-@include scheme-compound.texi
-@include scheme-procedures.texi
-@include scheme-utility.texi
-@include scheme-binding.texi
-@include scheme-control.texi
-@include scheme-io.texi
-@include scheme-evaluation.texi
-@include scheme-memory.texi
-@include scheme-modules.texi
-@include scheme-scheduling.texi
-@c object orientation support here
-@include scheme-options.texi
-@include scheme-translation.texi
-@include scheme-debug.texi
-@include deprecated.texi
-
-@iftex
-@page
-@unnumbered{Part V: Guile Modules}
-@end iftex
-
-@include slib.texi
-@include posix.texi
-@include srfi-modules.texi
-@include repl-modules.texi
-@include misc-modules.texi
-@include expect.texi
-@include scsh.texi
-
-@iftex
-@page
-@unnumbered{Indices}
-@end iftex
-
-@include indices.texi
-@include scheme-indices.texi
-
-@contents
-
-@bye
diff --git a/doc/ref/indices.texi b/doc/ref/indices.texi
deleted file mode 100644
index 11ab7476b..000000000
--- a/doc/ref/indices.texi
+++ /dev/null
@@ -1,52 +0,0 @@
-@page
-@node Concept Index
-@unnumbered Concept Index
-
-This index contains concepts, keywords and non-Schemey names for several
-features, to make it easier to locate the desired sections.
-
-@printindex cp
-
-
-@page
-@node Procedure Index
-@unnumbered Procedure Index
-
-@c FIXME::martin: Review me!
-
-This is an alphabetical list of all the procedures and macros in Guile.
-
-When looking for a particular procedure, please look under its Scheme
-name as well as under its C name. The C name can be constructed from
-the Scheme names by a simple transformation described in the section
-@xref{Transforming Scheme name to C name}.
-
-@printindex fn
-
-
-@page
-@node Variable Index
-@unnumbered Variable Index
-
-@c FIXME::martin: Review me!
-
-This is an alphabetical list of all the important variables and
-constants in Guile.
-
-When looking for a particular variable or constant, please look under
-its Scheme name as well as under its C name. The C name can be
-constructed from the Scheme names by a simple transformation described
-in the section @xref{Transforming Scheme name to C name}.
-
-@printindex vr
-
-
-@page
-@node Type Index
-@unnumbered Type Index
-
-This is an alphabetical list of all the important data types defined in
-the Guile Programmers Manual.
-
-@printindex tp
-
diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi
deleted file mode 100644
index af1b48d0e..000000000
--- a/doc/ref/intro.texi
+++ /dev/null
@@ -1,1128 +0,0 @@
-@page
-@node What is Guile?
-@chapter What is Guile?
-
-Guile is an interpreter for the Scheme programming language, packaged
-for use in a wide variety of environments. Guile implements Scheme as
-described in the
-@tex
-Revised$^5$
-@end tex
-@ifnottex
-Revised^5
-@end ifnottex
-Report on the Algorithmic Language Scheme (usually known as R5RS),
-providing clean and general data and control structures. Guile goes
-beyond the rather austere language presented in R5RS, extending it with
-a module system, full access to POSIX system calls, networking support,
-multiple threads, dynamic linking, a foreign function call interface,
-powerful string processing, and many other features needed for
-programming in the real world.
-
-Like a shell, Guile can run interactively, reading expressions from the
-user, evaluating them, and displaying the results, or as a script
-interpreter, reading and executing Scheme code from a file. However,
-Guile is also packaged as an object library, allowing other applications
-to easily incorporate a complete Scheme interpreter. An application can
-use Guile as an extension language, a clean and powerful configuration
-language, or as multi-purpose ``glue'', connecting primitives provided
-by the application. It is easy to call Scheme code from C code and vice
-versa, giving the application designer full control of how and when to
-invoke the interpreter. Applications can add new functions, data types,
-control structures, and even syntax to Guile, creating a domain-specific
-language tailored to the task at hand, but based on a robust language
-design.
-
-Guile's module system allows one to break up a large program into
-manageable sections with well-defined interfaces between them. Modules
-may contain a mixture of interpreted and compiled code; Guile can use
-either static or dynamic linking to incorporate compiled code. Modules
-also encourage developers to package up useful collections of routines
-for general distribution; as of this writing, one can find Emacs
-interfaces, database access routines, compilers, GUI toolkit interfaces,
-and HTTP client functions, among others.
-
-In the future, we hope to expand Guile to support other languages like
-Tcl and Perl by translating them to Scheme code. This means that users
-can program applications which use Guile in the language of their
-choice, rather than having the tastes of the application's author
-imposed on them.
-
-
-@page
-@node Whirlwind Tour
-@chapter A Whirlwind Tour
-
-This chapter presents a quick tour of all the ways that Guile can be
-used.
-
-@menu
-* Running Guile Interactively::
-* Guile Scripts::
-* Linking Programs With Guile::
-* Writing Extensions for Guile::
-* Guile Modules::
-@end menu
-
-
-@node Running Guile Interactively
-@section Running Guile Interactively
-
-In its simplest form, Guile acts as an interactive interpreter for the
-Scheme programming language, reading and evaluating Scheme expressions
-the user enters from the terminal. Here is a sample interaction between
-Guile and a user; the user's input appears after the @code{$} and
-@code{guile>} prompts:
-
-@example
-$ guile
-guile> (+ 1 2 3) ; add some numbers
-6
-guile> (define (factorial n) ; define a function
- (if (zero? n) 1 (* n (factorial (- n 1)))))
-guile> (factorial 20)
-2432902008176640000
-guile> (getpwnam "jimb") ; find my entry in /etc/passwd
-#("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
- "/usr/local/bin/bash")
-guile> @kbd{C-d}
-$
-@end example
-
-@c [[When we get a fancier read-eval-print loop, with features for bouncing
-@c around among modules, referring to the value of the last expression,
-@c etc. then this section will get longer.]]
-
-
-@node Guile Scripts
-@section Guile Scripts
-
-Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
-script is simply a file of Scheme code with some extra information at
-the beginning which tells the operating system how to invoke Guile, and
-then tells Guile how to handle the Scheme code.
-
-Before we present the details, here is a trivial Guile script:
-
-@example
-#!/usr/local/bin/guile -s
-!#
-(display "Hello, world!")
-(newline)
-@end example
-
-@menu
-* The Top of a Script File:: How to start a Guile script.
-* Scripting Examples:: Simple Guile scripts, explained.
-@end menu
-
-
-@node The Top of a Script File
-@subsection The Top of a Script File
-
-The first line of a Guile script must tell the operating system to use
-Guile to evaluate the script, and then tell Guile how to go about doing
-that. Here is the simplest case:
-
-@itemize @bullet
-
-@item
-The first two characters of the file must be @samp{#!}.
-
-The operating system interprets this to mean that the rest of the line
-is the name of an executable that can interpret the script. Guile,
-however, interprets these characters as the beginning of a multi-line
-comment, terminated by the characters @samp{!#} on a line by themselves.
-(This is an extension to the syntax described in R5RS, added to support
-shell scripts.)
-
-@item
-Immediately after those two characters must come the full pathname to
-the Guile interpreter. On most systems, this would be
-@samp{/usr/local/bin/guile}.
-
-@item
-Then must come a space, followed by a command-line argument to pass to
-Guile; this should be @samp{-s}. This switch tells Guile to run a
-script, instead of soliciting the user for input from the terminal.
-There are more elaborate things one can do here; see @ref{The Meta
-Switch}.
-
-@item
-Follow this with a newline.
-
-@item
-The second line of the script should contain only the characters
-@samp{!#} --- just like the top of the file, but reversed. The
-operating system never reads this far, but Guile treats this as the end
-of the comment begun on the first line by the @samp{#!} characters.
-
-@item
-The rest of the file should be a Scheme program.
-
-@end itemize
-
-Guile reads the program, evaluating expressions in the order that they
-appear. Upon reaching the end of the file, Guile exits.
-
-The function @code{command-line} returns the name of the script file and
-any command-line arguments passed by the user, as a list of strings.
-
-For example, consider the following script file:
-@example
-#!/usr/local/bin/guile -s
-!#
-(write (command-line))
-(newline)
-@end example
-
-If you put that text in a file called @file{foo} in the current
-directory, then you could make it executable and try it out like this:
-@example
-$ chmod a+x foo
-$ ./foo
-("./foo")
-$ ./foo bar baz
-("./foo" "bar" "baz")
-$
-@end example
-
-As another example, here is a simple replacement for the POSIX
-@code{echo} command:
-@example
-#!/usr/local/bin/guile -s
-!#
-(for-each (lambda (s) (display s) (display " "))
- (cdr (command-line)))
-(newline)
-@end example
-
-@deffn {Scheme Procedure} command-line
-@deffnx {Scheme Procedure} program-arguments
-Return a list of the command-line arguments passed to the currently
-running program. If the program invoked Guile with the @samp{-s},
-@samp{-c} or @samp{--} switches, these procedures ignore everything up
-to and including those switches.
-@end deffn
-
-
-@node Scripting Examples
-@subsection Scripting Examples
-
-To start with, here are some examples of invoking Guile directly:
-
-@table @code
-
-@item guile -- a b c
-Run Guile interactively; @code{(command-line)} will return @*
-@code{("/usr/local/bin/guile" "a" "b" "c")}.
-
-@item guile -s /u/jimb/ex2 a b c
-Load the file @file{/u/jimb/ex2}; @code{(command-line)} will return @*
-@code{("/u/jimb/ex2" "a" "b" "c")}.
-
-@item guile -c '(write %load-path) (newline)'
-Write the value of the variable @code{%load-path}, print a newline,
-and exit.
-
-@item guile -e main -s /u/jimb/ex4 foo
-Load the file @file{/u/jimb/ex4}, and then call the function
-@code{main}, passing it the list @code{("/u/jimb/ex4" "foo")}.
-
-@item guile -l first -ds -l last -s script
-Load the files @file{first}, @file{script}, and @file{last}, in that
-order. The @code{-ds} switch says when to process the @code{-s}
-switch. For a more motivated example, see the scripts below.
-
-@end table
-
-
-Here is a very simple Guile script:
-@example
-#!/usr/local/bin/guile -s
-!#
-(display "Hello, world!")
-(newline)
-@end example
-The first line marks the file as a Guile script. When the user invokes
-it, the system runs @file{/usr/local/bin/guile} to interpret the script,
-passing @code{-s}, the script's filename, and any arguments given to the
-script as command-line arguments. When Guile sees @code{-s
-@var{script}}, it loads @var{script}. Thus, running this program
-produces the output:
-@example
-Hello, world!
-@end example
-
-Here is a script which prints the factorial of its argument:
-@example
-#!/usr/local/bin/guile -s
-!#
-(define (fact n)
- (if (zero? n) 1
- (* n (fact (- n 1)))))
-
-(display (fact (string->number (cadr (command-line)))))
-(newline)
-@end example
-In action:
-@example
-$ fact 5
-120
-$
-@end example
-
-However, suppose we want to use the definition of @code{fact} in this
-file from another script. We can't simply @code{load} the script file,
-and then use @code{fact}'s definition, because the script will try to
-compute and display a factorial when we load it. To avoid this problem,
-we might write the script this way:
-
-@example
-#!/usr/local/bin/guile \
--e main -s
-!#
-(define (fact n)
- (if (zero? n) 1
- (* n (fact (- n 1)))))
-
-(define (main args)
- (display (fact (string->number (cadr args))))
- (newline))
-@end example
-This version packages the actions the script should perform in a
-function, @code{main}. This allows us to load the file purely for its
-definitions, without any extraneous computation taking place. Then we
-used the meta switch @code{\} and the entry point switch @code{-e} to
-tell Guile to call @code{main} after loading the script.
-@example
-$ fact 50
-30414093201713378043612608166064768844377641568960512000000000000
-@end example
-
-Suppose that we now want to write a script which computes the
-@code{choose} function: given a set of @var{m} distinct objects,
-@code{(choose @var{n} @var{m})} is the number of distinct subsets
-containing @var{n} objects each. It's easy to write @code{choose} given
-@code{fact}, so we might write the script this way:
-@example
-#!/usr/local/bin/guile \
--l fact -e main -s
-!#
-(define (choose n m)
- (/ (fact m) (* (fact (- m n)) (fact n))))
-
-(define (main args)
- (let ((n (string->number (cadr args)))
- (m (string->number (caddr args))))
- (display (choose n m))
- (newline)))
-@end example
-
-The command-line arguments here tell Guile to first load the file
-@file{fact}, and then run the script, with @code{main} as the entry
-point. In other words, the @code{choose} script can use definitions
-made in the @code{fact} script. Here are some sample runs:
-@example
-$ choose 0 4
-1
-$ choose 1 4
-4
-$ choose 2 4
-6
-$ choose 3 4
-4
-$ choose 4 4
-1
-$ choose 50 100
-100891344545564193334812497256
-@end example
-
-
-@node Linking Programs With Guile
-@section Linking Programs With Guile
-
-The Guile interpreter is available as an object library, to be linked
-into applications using Scheme as a configuration or extension
-language. This chapter covers the mechanics of linking your program
-with Guile on a typical POSIX system.
-
-Parts III and IV of this manual describe the C functions Guile provides.
-Furthermore, any Scheme function described in this manual as a
-``Primitive'' is also callable from C; see @ref{Primitives}.
-
-The header file @code{<libguile.h>} provides declarations for all of
-Guile's functions and constants. You should @code{#include} it at the
-head of any C source file that uses identifiers described in this
-manual. Once you've compiled your source files, you need to link them
-against the Guile object code library, @code{libguile}.
-
-On most systems, you should not need to tell the compiler and linker
-explicitly where they can find @file{libguile.h} and @file{libguile}.
-When Guile has been installed in a peculiar way, or when you are on a
-peculiar system, things might not be so easy and you might need to pass
-additional @code{-I} or @code{-L} options to the compiler. Guile
-provides the utility program @code{guile-config} to help you find the
-right values for these options. You would typically run
-@code{guile-config} during the configuration phase of your program and
-use the obtained information in the Makefile.
-
-@menu
-* Guile Initialization Functions:: What to call first.
-* A Sample Guile Main Program:: Sources and makefiles.
-@end menu
-
-
-@node Guile Initialization Functions
-@subsection Guile Initialization Functions
-
-To initialize Guile, you can use one of two functions. The first,
-@code{scm_boot_guile}, is the most portable way to initialize Guile. It
-should be used whenever you have control over the main function of your
-program because it never returns. The second function,
-@code{scm_init_guile}, does return and can thus be used in more
-situations. However, @code{scm_init_guile} is not as widely available
-as @code{scm_boot_guile} because it needs to rely on non-portable code
-to find the stack bounds. When Guile does not know how to find these
-bounds on your system, it will not provide @code{scm_init_guile}.
-
-When you can tolerate the limits of @code{scm_boot_guile}, you should
-use it in favor of @code{scm_init_guile} since that will make your
-program more portable.
-
-@deftypefun void scm_boot_guile (int @var{argc}, char **@var{argv}, void (*@var{main_func}) (), void *@var{closure})
-Initialize the Guile Scheme interpreter. Then call @var{main_func},
-passing it @var{closure}, @var{argc}, and @var{argv}. @var{main_func}
-should do all the work of the program (initializing other packages,
-defining application-specific functions, reading user input, and so on)
-before returning. When @var{main_func} returns, call @code{exit (0)};
-@code{scm_boot_guile} never returns. If you want some other exit value,
-have @var{main_func} call exit itself.
-
-@code{scm_boot_guile} arranges for the Scheme @code{command-line}
-function to return the strings given by @var{argc} and @var{argv}. If
-@var{main_func} modifies @var{argc} or @var{argv}, it should call
-@code{scm_set_program_arguments} with the final list, so Scheme code
-will know which arguments have been processed.
-
-Why must the caller do all the real work from @var{main_func}? Guile's
-garbage collector scans the stack to find all local variables that
-reference Scheme objects. To do this, it needs to know the bounds of
-the stack that might contain such references. Because there is no
-portable way in C to find the base of the stack, @code{scm_boot_guile}
-assumes that all references are above its own stack frame. If you try
-to manipulate Scheme objects after this function returns, it's the luck
-of the draw whether Guile's storage manager will be able to find the
-objects you allocate. So, @code{scm_boot_guile} function exits, rather
-than returning, to discourage you from making that mistake.
-
-See @code{scm_init_guile}, below, for a function that can find the real
-base of the stack, but not in a portable way.
-@end deftypefun
-
-@deftypefun void scm_init_guile ()
-Initialize the Guile Scheme interpreter.
-
-In contrast to @code{scm_boot_guile}, this function knows how to find
-the true base of the stack and thus does not need to usurp the control
-flow of your program. However, since finding the stack base can not be
-done portably, this function might not be available in all installations
-of Guile. If you can, you should use @code{scm_boot_guile} instead.
-
-Note that @code{scm_init_guile} does not inform Guile about the command
-line arguments that should be returned by the Scheme function
-@code{command-line}. You can use @code{scm_set_program_arguments} to do
-this.
-@end deftypefun
-
-One common way to use Guile is to write a set of C functions which
-perform some useful task, make them callable from Scheme, and then link
-the program with Guile. This yields a Scheme interpreter just like
-@code{guile}, but augmented with extra functions for some specific
-application --- a special-purpose scripting language.
-
-In this situation, the application should probably process its
-command-line arguments in the same manner as the stock Guile
-interpreter. To make that straightforward, Guile provides this
-function:
-
-@deftypefun void scm_shell (int @var{argc}, char **@var{argv})
-Process command-line arguments in the manner of the @code{guile}
-executable. This includes loading the normal Guile initialization
-files, interacting with the user or running any scripts or expressions
-specified by @code{-s} or @code{-e} options, and then exiting.
-@xref{Invoking Guile}, for more details.
-
-Since this function does not return, you must do all
-application-specific initialization before calling this function.
-@end deftypefun
-
-
-@node A Sample Guile Main Program
-@subsection A Sample Guile Main Program
-
-Here is @file{simple-guile.c}, source code for a @code{main} and an
-@code{inner_main} function that will produce a complete Guile
-interpreter.
-
-@example
-/* simple-guile.c --- how to start up the Guile
- interpreter from C code. */
-
-/* Get declarations for all the scm_ functions. */
-#include <libguile.h>
-
-static void
-inner_main (void *closure, int argc, char **argv)
-@{
- /* module initializations would go here */
- scm_shell (argc, argv);
-@}
-
-int
-main (int argc, char **argv)
-@{
- scm_boot_guile (argc, argv, inner_main, 0);
- return 0; /* never reached */
-@}
-@end example
-
-The @code{main} function calls @code{scm_boot_guile} to initialize
-Guile, passing it @code{inner_main}. Once @code{scm_boot_guile} is
-ready, it invokes @code{inner_main}, which calls @code{scm_shell} to
-process the command-line arguments in the usual way.
-
-Here is a Makefile which you can use to compile the above program. It
-uses @code{guile-config} to learn about the necessary compiler and
-linker flags.
-@example
-# Use GCC, if you have it installed.
-CC=gcc
-
-# Tell the C compiler where to find <libguile.h>
-CFLAGS=`guile-config compile`
-
-# Tell the linker what libraries to use and where to find them.
-LIBS=`guile-config link`
-
-simple-guile: simple-guile.o
- $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
-
-simple-guile.o: simple-guile.c
- $@{CC@} -c $@{CFLAGS@} simple-guile.c
-@end example
-
-If you are using the GNU Autoconf package to make your application more
-portable, Autoconf will settle many of the details in the Makefile above
-automatically, making it much simpler and more portable; we recommend
-using Autoconf with Guile. Guile also provides the @code{GUILE_FLAGS}
-macro for autoconf that performs all necessary checks. Here is a
-@file{configure.in} file for @code{simple-guile} that uses this macro.
-Autoconf can use as this file as template to generate a @code{configure}
-script. In order for Autoconf to find the @code{GUILE_FLAGS} macro, you
-will need to run @code{aclocal} first. This is not really Guile
-specific, so you should refer to the Autoconf documentation REFFIXME
-when in doubt.
-@example
-AC_INIT(simple-guile.c)
-
-# Find a C compiler.
-AC_PROG_CC
-
-# Check for Guile
-GUILE_FLAGS
-
-# Generate a Makefile, based on the results.
-AC_OUTPUT(Makefile)
-@end example
-
-Here is a @code{Makefile.in} template, from which the @code{configure}
-script produces a Makefile customized for the host system:
-@example
-# The configure script fills in these values.
-CC=@@CC@@
-CFLAGS=@@GUILE_CFLAGS@@
-LIBS=@@GUILE_LDFLAGS@@
-
-simple-guile: simple-guile.o
- $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
-simple-guile.o: simple-guile.c
- $@{CC@} -c $@{CFLAGS@} simple-guile.c
-@end example
-
-The developer should use Autoconf to generate the @file{configure}
-script from the @file{configure.in} template, and distribute
-@file{configure} with the application. Here's how a user might go about
-building the application:
-
-@example
-$ ls
-Makefile.in configure* configure.in simple-guile.c
-$ ./configure
-creating cache ./config.cache
-checking for gcc... (cached) gcc
-checking whether the C compiler (gcc ) works... yes
-checking whether the C compiler (gcc ) is a cross-compiler... no
-checking whether we are using GNU C... (cached) yes
-checking whether gcc accepts -g... (cached) yes
-checking for Guile... yes
-creating ./config.status
-creating Makefile
-$ make
-gcc -c -I/usr/local/include simple-guile.c
-gcc simple-guile.o -L/usr/local/lib -lguile -lqthreads -lpthread -lm -o simple-guile
-$ ./simple-guile
-guile> (+ 1 2 3)
-6
-guile> (getpwnam "jimb")
-#("jimb" "83Z7d75W2tyJQ" 4008 10 "Jim Blandy" "/u/jimb"
- "/usr/local/bin/bash")
-guile> (exit)
-$
-@end example
-
-
-@node Writing Extensions for Guile
-@section Writing Extensions for Guile
-
-The previous sections have briefly explained how to write programs that
-make use of an embedded Guile interpreter. But sometimes, all you want
-to do is make new primitive procedures and data types available to the
-Scheme programmer. Writing a new version of @code{guile} is
-inconvenient in this case and it would in fact make the life of the
-users of your new features needlessly hard.
-
-@c [[ the following is probably a bit long-winded ]]
-
-For example, suppose that there is a program @code{guile-db} that is a
-version of Guile with additional features for accessing a database.
-People who want to write Scheme programs that use these features would
-have to use @code{guile-db} instead of the usual @code{guile} program.
-Now suppose that there is also a program @code{guile-gtk} that extends
-Guile with access to the popular Gtk+ toolkit for graphical user
-interfaces. People who want to write GUIs in Scheme would have to use
-@code{guile-gtk}. Now, what happens when you want to write a Scheme
-application that uses a GUI to let the user access a database? You
-would have to write a @emph{third} program that incorporates both the
-database stuff and the GUI stuff. This might not be easy (because
-@code{guile-gtk} might be a quite obscure program, say) and taking this
-example further makes it easy to see that this approach can not work in
-practice.
-
-It would have been much better if both the database features and the GUI
-feature had been provided as libraries that can just be linked with
-@code{guile}. Guile makes it easy to do just this, and we encourage you
-to make your extensions to Guile available as libraries whenever
-possible.
-
-You write the new primitive procedures and data types in the normal
-fashion, and link them into a shared library instead of into a
-stand-alone program. The shared library can then be loaded dynamically
-by Guile.
-
-@menu
-* A Sample Guile Extension::
-@end menu
-
-
-@node A Sample Guile Extension
-@subsection A Sample Guile Extension
-
-This section explains how to make the Bessel functions of the C library
-available to Scheme. First we need to write the appropriate glue code
-to convert the arguments and return values of the functions from Scheme
-to C and back. Additionally, we need a function that will add them to
-the set of Guile primitives. Because this is just an example, we will
-only implement this for the @code{j0} function.
-
-Consider the following file @file{bessel.c}.
-
-@smallexample
-#include <math.h>
-#include <libguile.h>
-
-SCM
-j0_wrapper (SCM x)
-@{
- return scm_make_real (j0 (scm_num2dbl (x, "j0")));
-@}
-
-void
-init_bessel ()
-@{
- scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
-@}
-@end smallexample
-
-This C source file needs to be compiled into a shared library. Here is
-how to do it on GNU/Linux:
-
-@smallexample
-gcc -shared -o libguile-bessel.so -fPIC bessel.c
-@end smallexample
-
-For creating shared libraries portably, we recommend the use of
-@code{GNU Libtool}.
-
-A shared library can be loaded into a running Guile process with the
-function @code{load-extension}. In addition to the name of the
-library to load, this function also expects the name of function from
-that library that will be called to initialize it. For our example,
-we are going to call the function @code{init_bessel} which will make
-@code{j0_wrapper} available to Scheme programs with the name
-@code{j0}. Note that we do not specify a filename extension such as
-@file{.so} when invoking @code{load-extension}. The right extension for
-the host platform will be provided automatically.
-
-@smalllisp
-(load-extension "libguile-bessel" "init_bessel")
-(j0 2)
-@result{} 0.223890779141236
-@end smalllisp
-
-For this to work, @code{load-extension} must be able to find
-@file{libguile-bessel}, of course. It will look in the places that
-are usual for your operating system, and it will additionally look
-into the directories listed in the @code{LTDL_LIBRARY_PATH}
-environment variable.
-
-To see how these Guile extensions via shared libraries relate to the
-module system, see below @xref{Intro to Modules and Extensions}.
-
-
-@node Guile Modules
-@section Guile Modules
-
-Guile has support for dividing a program into @dfn{modules}. By using
-modules, you can group related code together and manage the
-composition of complete programs from largely independent parts.
-
-(Although the module system implementation is in flux, feel free to use it
-anyway. Guile will provide reasonable backwards compatibility.)
-
-Details on the module system beyond this introductory material can be found in
-@xref{Modules}.
-
-@menu
-* Intro to Using Guile Modules::
-* Intro to Writing New Modules::
-* Intro to Modules and Extensions::
-@end menu
-
-
-@node Intro to Using Guile Modules
-@subsection Intro to Using Existing Modules
-
-Guile comes with a lot of useful modules, for example for string
-processing or command line parsing. Additionally, there exist many
-Guile modules written by other Guile hackers, but which have to be
-installed manually.
-
-Existing modules have to be placed in places where Guile looks for them
-by default or in colon-separated directories in the environment variable
-@code{GUILE_LOAD_PATH}. When this variable is set, those directories
-are searched first, then the the default. The following command
-shows the complete list of directories searched:
-
-@smallexample
-guile -c '(write %load-path) (newline)'
-@end smallexample
-
-Suppose you want to use the procedures and variables exported by the
-module @code{(ice-9 popen)}, which provides the means for communicating
-with other processes over pipes. Add the following line to your
-currently running Guile REPL or the top of your script file.
-
-@lisp
-(use-modules (ice-9 popen))
-@end lisp
-
-This will load the module and make the procedures exported by
-@code{(ice-9 popen)} automatically available. The next step could be to
-open a pipe to @file{ls} and read the contents of the current directory,
-one line at a time.
-
-@lisp
-(define p (open-input-pipe "ls -l"))
-(read-line p)
-@result{}
-"total 30"
-(read-line p)
-@result{}
-"drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
-@end lisp
-
-
-@node Intro to Writing New Modules
-@subsection Intro to Writing New Modules
-
-Of course it is possible to write modules yourself. Using modules for
-structuring your programs makes them more readable and lets you
-distribute them more easily. Also, explicitly defining the procedures
-and variables which are exported from a module adds documentation to the
-source and specifies the interface a module provides.
-
-In Guile, you can create new modules and switch to existing modules in
-order to add bindings to them using the syntactic form
-@code{define-module}.
-
-@lisp
-(define-module (foo bar))
-
-(define (frob x) x)
-@end lisp
-
-Will create the module @code{(foo bar)}.@footnote{It is only convention
-that the module names in this section have two elements. One or more
-than two elements are perfectly fine, such as @code{(foo)} or @code{(foo
-bar braz)}} All definitions following this statement will add bindings
-to the module @code{(foo bar)}, and these bindings will not be visible
-outside of the module. To make the bindings accessible to other
-modules, you have to export them explicitly using one of the following
-means:
-
-@itemize @bullet
-@item
-Export them with the @code{export} form:
-@lisp
-(export frob)
-@end lisp
-
-@item
-Include them into the @code{define-module} form with the keyword
-@code{export}:
-@lisp
-(define-module (foo bar)
- #:export (frob))
-@end lisp
-
-@item
-Change the definition of @code{frob} to use @code{define-public}, which
-is a combination of @code{define} and @code{export}.
-@lisp
-(define-public (frob x) x)
-@end lisp
-@end itemize
-
-After exporting, other modules can access the exported items simply by
-using @code{use-modules} to load the module @code{(foo bar)}.
-
-
-@node Intro to Modules and Extensions
-@subsection Intro to Modules and Extensions
-
-In addition to Scheme code you can also put things that are defined in
-C into a module.
-
-You do this by writing a small Scheme file that defines the module.
-That Scheme file in turn invokes @code{load-extension} to make the
-features defined in C available. This works since all definitions
-made by @code{scm_c_define_gsubr} etc. go into the @emph{current
-module} and @code{define-module} causes the newly defined module to be
-current while the code that follows it is executed.
-
-Suppose we want to put the Bessel function @code{j0} from the example
-extension into a module called @code{(math bessel)}. We would have to
-write a Scheme file with this contents
-
-@smallexample
-(define-module (math bessel))
-
-(export j0)
-
-(load-extension "libguile-bessel" "init_bessel")
-@end smallexample
-
-This file should of course be saved in the right place for
-autoloading, for example as
-@file{/usr/local/share/guile/math/bessel.scm}.
-
-When @code{init_bessel} is called, the new @code{(math bessel)} module
-is the current one. Thus, the call to @code{scm_c_define_gsubr} will
-put the new definition for @code{j0} into it, just as we want it.
-
-The definitions made in the C code are not automatically exported from
-a module. You need to explicitly list the ones you want to export in
-@code{export} statements or with the @code{:export} option of
-@code{define-module}.
-
-There is also a way to manipulate the module system from C but only
-Scheme files can be autoloaded. Thus, we recommend that you define
-your modules in Scheme.
-
-
-@page
-@node Obtaining and Installing Guile
-@chapter Obtaining and Installing Guile
-
-Here is the information you will need to get and install Guile and extra
-packages and documentation you might need or find interesting.
-
-@menu
-* The Basic Guile Package::
-* Packages not shipped with Guile::
-@end menu
-
-
-@node The Basic Guile Package
-@section The Basic Guile Package
-
-Guile can be obtained from the main GNU archive site
-@url{ftp://prep.ai.mit.edu/pub/gnu} or any of its mirrors. The file
-will be named guile-version.tar.gz. The current version is
-@value{VERSION}, so the file you should grab is:
-
-@url{ftp://prep.ai.mit.edu/pub/gnu/guile-@value{VERSION}.tar.gz}
-
-To unbundle Guile use the instruction
-@example
-zcat guile-@value{VERSION}.tar.gz | tar xvf -
-@end example
-which will create a directory called @file{guile-@value{VERSION}} with
-all the sources. You can look at the file @file{INSTALL} for detailed
-instructions on how to build and install Guile, but you should be able
-to just do
-@example
-cd guile-@value{VERSION}
-./configure
-make install
-@end example
-
-This will install the Guile executable @file{guile}, the Guile library
-@file{libguile.a} and various associated header files and support
-libraries. It will also install the Guile tutorial and reference manual.
-
-@c [[include instructions for getting R5RS]]
-
-Since this manual frequently refers to the Scheme ``standard'', also
-known as R5RS, or the
-@iftex
-``Revised$^5$ Report on the Algorithmic Language Scheme'',
-@end iftex
-@ifnottex
-``Revised^5 Report on the Algorithmic Language Scheme'',
-@end ifnottex
-we have included the report in the Guile distribution;
-@xref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
-Language Scheme}.
-This will also be installed in your info directory.
-
-
-@node Packages not shipped with Guile
-@section Packages not shipped with Guile
-
-We ship the Guile tutorial and reference manual with the Guile
-distribution. Since the Scheme standard (R5RS) is a stable document, we
-ship that too.
-
-Here are references (usually World Wide Web URLs) to some other freely
-redistributable documents and packages which you might find useful if
-you are using Guile.
-
-@table @strong
-@item SCSH
-the Scheme Shell. Gary Houston has ported SCSH to Guile. The relevant
-chapter (@pxref{The Scheme shell (scsh)}) has references to the SCSH web
-page with all its documentation.
-
-@item SLIB
-a portable Scheme library maintained by Aubrey Jaffer. SLIB can be
-obtained by ftp from @url{ftp://prep.ai.mit.edu/pub/gnu/jacal/}.
-
-The SLIB package should be unpacked somewhere in Guile's load path. It
-will typically be unpacked in @file{/usr/local/share/guile/site}, so
-that it will be @file{/usr/local/share/guile/site/slib}.
-
-Guile might have been installed with a different prefix, in which case
-the load path can be checked from inside the interpreter with:
-
-@smalllisp
-guile> %load-path
-("/usr/local/share/guile/site" "/usr/local/share/guile/1.3a" "/usr/local/share/guile" ".")
-@end smalllisp
-
-The relevant chapter (@pxref{SLIB}) has details on how to use SLIB with
-Guile.
-
-@item JACAL
-a symbolic math package by Aubrey Jaffer. The latest version of Jacal
-can be obtained from @url{ftp://prep.ai.mit.edu/pub/gnu/jacal/}, and
-should be unpacked in @file{/usr/local/share/guile/site/slib} so that
-it will be in @file{/usr/local/share/guile/site/slib/jacal}.
-
-The relevant section (@pxref{JACAL}) has details on how to use Jacal.
-@end table
-
-
-@page
-@node Reporting Bugs
-@chapter Reporting Bugs
-
-Any problems with the installation should be reported to
-@email{bug-guile@@gnu.org}.
-
-Whenever you have found a bug in Guile you are encouraged to report it
-to the Guile developers, so they can fix it. They may also be able to
-suggest workarounds when it is not possible for you to apply the bug-fix
-or install a new version of Guile yourself.
-
-Before sending in bug reports, please check with the following list that
-you really have found a bug.
-
-@itemize @bullet
-@item
-Whenever documentation and actual behavior differ, you have certainly
-found a bug, either in the documentation or in the program.
-
-@item
-When Guile crashes, it is a bug.
-
-@item
-When Guile hangs or takes forever to complete a task, it is a bug.
-
-@item
-When calculations produce wrong results, it is a bug.
-
-@item
-When Guile signals an error for valid Scheme programs, it is a bug.
-
-@item
-When Guile does not signal an error for invalid Scheme programs, it may
-be a bug, unless this is explicitly documented.
-
-@item
-When some part of the documentation is not clear and does not make sense
-to you even after re-reading the section, it is a bug.
-@end itemize
-
-When you write a bug report, please make sure to include as much of the
-information described below in the report. If you can't figure out some
-of the items, it is not a problem, but the more information we get, the
-more likely we can diagnose and fix the bug.
-
-@itemize @bullet
-@item
-The version number of Guile. Without this, we won't know whether there
-is any point in looking for the bug in the current version of Guile.
-
-You can get the version number by invoking the command
-
-@example
-$ guile --version
-Guile 1.4.1
-Copyright (c) 1995, 1996, 1997, 2000 Free Software Foundation
-Guile may be distributed under the terms of the GNU General Public License;
-certain other uses are permitted as well. For details, see the file
-`COPYING', which is included in the Guile distribution.
-There is no warranty, to the extent permitted by law.
-@end example
-
-@item
-The type of machine you are using, and the operating system name and
-version number. On GNU systems, you can get it with @file{uname}.
-
-@example
-$ uname -a
-Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown
-@end example
-
-@item
-The operands given to the @file{configure} command when Guile was
-installed. It's often useful to augment this with the output of the
-command @code{guile-config info}.
-
-@item
-A complete list of any modifications you have made to the Guile source.
-(We may not have time to investigate the bug unless it happens in an
-unmodified Guile. But if you've made modifications and you don't tell
-us, you are sending us on a wild goose chase.)
-
-Be precise about these changes. A description in English is not
-enough---send a context diff for them.
-
-Adding files of your own, or porting to another machine, is a
-modification of the source.
-
-@item
-Details of any other deviations from the standard procedure for
-installing Guile.
-
-@item
-The complete text of any source files needed to reproduce the bug.
-
-If you can tell us a way to cause the problem without loading any source
-files, please do so. This makes it much easier to debug. If you do
-need files, make sure you arrange for us to see their exact contents.
-
-@item
-The precise Guile invocation command line we need to type to reproduce
-the bug.
-
-@item
-A description of what behavior you observe that you believe is
-incorrect. For example, "The Guile process gets a fatal signal," or,
-"The resulting output is as follows, which I think is wrong."
-
-Of course, if the bug is that Guile gets a fatal signal, then one can't
-miss it. But if the bug is incorrect results, the maintainer might fail
-to notice what is wrong. Why leave it to chance?
-
-If the manifestation of the bug is a Guile error message, it is
-important to report the precise text of the error message, and a
-backtrace showing how the Scheme program arrived at the error.
-
-This can be done using the procedure @code{backtrace} in the REPL.
-
-@item
-Check whether any programs you have loaded into Guile, including your
-@file{.guile} file, set any variables that may affect the functioning of
-Guile. Also, see whether the problem happens in a freshly started Guile
-without loading your @file{.guile} file (start Guile with the @code{-q}
-switch to prevent loading the init file). If the problem does
-@emph{not} occur then, you must report the precise contents of any
-programs that you must load into Guile in order to cause the problem to
-occur.
-
-@item
-If the problem does depend on an init file or other Scheme programs that
-are not part of the standard Guile distribution, then you should make
-sure it is not a bug in those programs by complaining to their
-maintainers first. After they verify that they are using Guile in a way
-that is supposed to work, they should report the bug.
-
-@item
-If you wish to mention something in the Guile source, show the line of
-code with a few lines of context. Don't just give a line number.
-
-The line numbers in the development sources might not match those in your
-sources. It would take extra work for the maintainers to determine what
-code is in your version at a given line number, and we could not be
-certain.
-
-@item
-Additional information from a C debugger such as GDB might enable
-someone to find a problem on a machine which he does not have available.
-If you don't know how to use GDB, please read the GDB manual---it is not
-very long, and using GDB is easy. You can find the GDB distribution,
-including the GDB manual in online form, in most of the same places you
-can find the Guile distribution. To run Guile under GDB, you should
-switch to the @file{libguile} subdirectory in which Guile was compiled, then
-do @code{gdb guile} or @code{gdb .libs/guile} (if using GNU Libtool).
-
-However, you need to think when you collect the additional information
-if you want it to show what causes the bug.
-
-For example, many people send just a backtrace, but that is not very
-useful by itself. A simple backtrace with arguments often conveys
-little about what is happening inside Guile, because most of the
-arguments listed in the backtrace are pointers to Scheme objects. The
-numeric values of these pointers have no significance whatever; all that
-matters is the contents of the objects they point to (and most of the
-contents are themselves pointers).
-@end itemize
-
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/misc-modules.texi b/doc/ref/misc-modules.texi
deleted file mode 100644
index 6f262701e..000000000
--- a/doc/ref/misc-modules.texi
+++ /dev/null
@@ -1,426 +0,0 @@
-@page
-@node Pretty Printing
-@chapter Pretty Printing
-
-@c FIXME::martin: Review me!
-
-@cindex pretty printing
-The module @code{(ice-9 pretty-print)} provides the procedure
-@code{pretty-print}, which provides nicely formatted output of Scheme
-objects. This is especially useful for deeply nested or complex data
-structures, such as lists and vectors.
-
-The module is loaded by simply saying.
-
-@lisp
-(use-modules (ice-9 pretty-print))
-@end lisp
-
-This makes the procedure @code{pretty-print} available. As an example
-how @code{pretty-print} will format the output, see the following:
-
-@lisp
-(pretty-print '(define (foo) (lambda (x)
-(cond ((zero? x) #t) ((negative? x) -x) (else (if (= x 1) 2 (* x x x)))))))
-@print{}
-(define (foo)
- (lambda (x)
- (cond ((zero? x) #t)
- ((negative? x) -x)
- (else (if (= x 1) 2 (* x x x))))))
-@end lisp
-
-@deffn {Scheme Procedure} pretty-print obj [port]
-Print the textual representation of the Scheme object @var{obj} to
-@var{port}. @var{port} defaults to the current output port, if not
-given.
-@end deffn
-
-Beware: Since @code{pretty-print} uses it's own write procedure, it's
-output will not be the same as for example the output of @code{write}.
-Consider the following example.
-
-@lisp
-(write (lambda (x) x))
-@print{}
-#<procedure #f (x)>
-
-(pretty-print (lambda (x) x))
-@print{}
-#[procedure]
-@end lisp
-
-The reason is that @code{pretty-print} does not know as much about
-Guile's object types as the builtin procedures. This is particularly
-important for smobs, for which a write procedure can be defined and be
-used by @code{write}, but not by @code{pretty-print}.
-
-
-@page
-@node Formatted Output
-@chapter Formatted Output
-
-@c FIXME::martin: Review me!
-
-@cindex format
-@cindex formatted output
-Outputting messages or other texts which are composed of literal
-strings, variable contents, newlines and other formatting can be
-cumbersome, when only the standard procedures like @code{display},
-@code{write} and @code{newline} are available. Additionally, one
-often wants to collect the output in strings. With the standard
-routines, the user is required to set up a string port, add this port
-as a parameter to the output procedure calls and then retrieve the
-resulting string from the string port.
-
-The @code{format} procedure, to be found in module @code{(ice-9
-format)}, can do all this, and even more. If you are a C programmer,
-you can think of this procedure as Guile's @code{fprintf}.
-
-@deffn {Scheme Procedure} format destination format-string args @dots{}
-The first parameter is the @var{destination}, it determines where the
-output of @code{format} will go.
-
-@table @asis
-@item @code{#t}
-Send the formatted output to the current output port and return
-@code{#t}.
-
-@item @code{#f}
-Return the formatted output as a string.
-
-@item Any number value
-Send the formatted output to the current error port and return
-@code{#t}.
-
-@item A valid output port
-Send the formatted output to the port @var{destination} and return
-@code{#t}.
-@end table
-
-The second parameter is the format string. It has a similar function
-to the format string in calls to @code{printf} or @code{fprintf} in C.
-It is output to the specified destination, but all escape sequences
-are replaced by the results of formatting the corresponding sequence.
-
-Note that escape sequences are marked with the character @code{~}
-(tilde), and not with a @code{%} (percent sign), as in C.
-
-The escape sequences in the following table are supported. When there
-appears ``corresponding @var{arg}', that means any of the additional
-arguments, after dropping all arguments which have been used up by
-escape sequences which have been processed earlier. Some of the
-format characters (the characters following the tilde) can be prefixed
-by @code{:}, @code{@@}, or @code{:@@}, to modify the behaviour of the
-format character. How the modified behaviour differs from the default
-behaviour is described for every character in the table where
-appropriate.
-
-@table @code
-@item ~~
-Output a single @code{~} (tilde) character.
-
-@item ~%
-Output a newline character, thus advancing to the next output line.
-
-@item ~&
-Start a new line, that is, output a newline character if not already
-at the start of a line.
-
-@item ~_
-Output a single space character.
-
-@item ~/
-Output a single tabulator character.
-
-@item ~|
-Output a page separator (formfeed) character.
-
-@item ~t
-Advance to the next tabulator position.
-
-@item ~y
-Pretty-print the corresponding @var{arg}.
-
-@item ~a
-Output the corresponding @var{arg} like @code{display}.
-
-@item ~s
-Output the corresponding @var{arg} like @code{write}.
-
-@item ~d
-Output the corresponding @var{arg} as a decimal number.
-
-@item ~x
-Output the corresponding @var{arg} as a hexadecimal number.
-
-@item ~o
-Output the corresponding @var{arg} as an octal number.
-
-@item ~b
-Output the corresponding @var{arg} as a binary number.
-
-@item ~r
-Output the corresponding @var{arg} as a number word, e.g. 10 prints as
-@code{ten}. If prefixed with @code{:}, @code{tenth} is printed, if
-prefixed with @code{:@@}, Roman numbers are printed.
-
-@item ~f
-Output the corresponding @var{arg} as a fixed format floating point
-number, such as @code{1.34}.
-
-@item ~e
-Output the corresponding @var{arg} in exponential notation, such as
-@code{1.34E+0}.
-
-@item ~g
-This works either like @code{~f} or like @code{~e}, whichever produces
-less characters to be written.
-
-@item ~$
-Like @code{~f}, but only with two digits after the decimal point.
-
-@item ~i
-Output the corresponding @var{arg} as a complex number.
-
-@item ~c
-Output the corresponding @var{arg} as a character. If prefixed with
-@code{@@}, it is printed like with @code{write}. If prefixed with
-@code{:}, control characters are treated specially, for example
-@code{#\newline} will be printed as @code{^J}.
-
-@item ~p
-``Plural''. If the corresponding @var{arg} is 1, nothing is printed
-(or @code{y} if prefixed with @code{@@} or @code{:@@}), otherwise
-@code{s} is printed (or @code{ies} if prefixed with @code{@@} or
-@code{:@@}).
-
-@item ~?, ~k
-Take the corresponding argument as a format string, and the following
-argument as a list of values. Then format the values with respect to
-the format string.
-
-@item ~!
-Flush the output to the output port.
-
-@item ~#\newline (tilde-newline)
-@c FIXME::martin: I don't understand this from the source.
-Continuation lines.
-
-@item ~*
-Argument jumping. Navigate in the argument list as specified by the
-corresponding argument. If prefixed with @code{:}, jump backwards in
-the argument list, if prefixed by @code{:@@}, jump to the parameter
-with the absolute index, otherwise jump forward in the argument list.
-
-@item ~(
-Case conversion begin. If prefixed by @code{:}, the following output
-string will be capitalized, if prefixed by @code{@@}, the first
-character will be capitalized, if prefixed by @code{:@@} it will be
-upcased and otherwise it will be downcased. Conversion stops when the
-``Case conversion end'' @code{~)}sequence is encountered.
-
-@item ~)
-Case conversion end. Stop any case conversion currently in effect.
-
-@item ~[
-@c FIXME::martin: I don't understand this from the source.
-Conditional begin.
-
-@item ~;
-@c FIXME::martin: I don't understand this from the source.
-Conditional separator.
-
-@item ~]
-@c FIXME::martin: I don't understand this from the source.
-Conditional end.
-
-@item ~@{
-@c FIXME::martin: I don't understand this from the source.
-Iteration begin.
-
-@item ~@}
-@c FIXME::martin: I don't understand this from the source.
-Iteration end.
-
-@item ~^
-@c FIXME::martin: I don't understand this from the source.
-Up and out.
-
-@item ~'
-@c FIXME::martin: I don't understand this from the source.
-Character parameter.
-
-@item ~0 @dots{} ~9, ~-, ~+
-@c FIXME::martin: I don't understand this from the source.
-Numeric parameter.
-
-@item ~v
-@c FIXME::martin: I don't understand this from the source.
-Variable parameter from next argument.
-
-@item ~#
-Parameter is number of remaining args. The number of the remaining
-arguments is prepended to the list of unprocessed arguments.
-
-@item ~,
-@c FIXME::martin: I don't understand this from the source.
-Parameter separators.
-
-@item ~q
-Inquiry message. Insert a copyright message into the output.
-@end table
-
-If any type conversions should fail (for example when using an escape
-sequence for number output, but the argument is a string), an error
-will be signalled.
-@end deffn
-
-You may have noticed that Guile contains a @code{format} procedure
-even when the module @code{(ice-9 format)} is not loaded. The default
-@code{format} procedure does not support all escape sequences
-documented in this chapter, and will signal an error if you try to use
-one of them. The reason for providing two versions of @code{format}
-is that the full-featured module is fairly large and requires some
-time to get loaded. So the Guile maintainers decided not to load the
-large version of @code{format} by default, so that the start-up time
-of the interpreter is not unnecessarily increased.
-
-
-@page
-@node Rx Regexps
-@chapter The Rx Regular Expression Library
-
-[FIXME: this is taken from Gary and Mark's quick summaries and should be
-reviewed and expanded. Rx is pretty stable, so could already be done!]
-
-@cindex rx
-@cindex finite automaton
-
-The @file{guile-lang-allover} package provides an interface to Tom
-Lord's Rx library (currently only to POSIX regular expressions). Use of
-the library requires a two step process: compile a regular expression
-into an efficient structure, then use the structure in any number of
-string comparisons.
-
-For example, given the regular expression @samp{abc.} (which matches any
-string containing @samp{abc} followed by any single character):
-
-@smalllisp
-guile> @kbd{(define r (regcomp "abc."))}
-guile> @kbd{r}
-#<rgx abc.>
-guile> @kbd{(regexec r "abc")}
-#f
-guile> @kbd{(regexec r "abcd")}
-#((0 . 4))
-guile>
-@end smalllisp
-
-The definitions of @code{regcomp} and @code{regexec} are as follows:
-
-@deffn {Scheme Procedure} regcomp pattern [flags]
-Compile the regular expression pattern using POSIX rules. Flags is
-optional and should be specified using symbolic names:
-@defvar REG_EXTENDED
-use extended POSIX syntax
-@end defvar
-@defvar REG_ICASE
-use case-insensitive matching
-@end defvar
-@defvar REG_NEWLINE
-allow anchors to match after newline characters in the
-string and prevents @code{.} or @code{[^...]} from matching newlines.
-@end defvar
-
-The @code{logior} procedure can be used to combine multiple flags.
-The default is to use
-POSIX basic syntax, which makes @code{+} and @code{?} literals and @code{\+}
-and @code{\?}
-operators. Backslashes in @var{pattern} must be escaped if specified in a
-literal string e.g., @code{"\\(a\\)\\?"}.
-@end deffn
-
-@deffn {Scheme Procedure} regexec regex string [match-pick] [flags]
-Match @var{string} against the compiled POSIX regular expression
-@var{regex}.
-@var{match-pick} and @var{flags} are optional. Possible flags (which can be
-combined using the logior procedure) are:
-
-@defvar REG_NOTBOL
-The beginning of line operator won't match the beginning of
-@var{string} (presumably because it's not the beginning of a line)
-@end defvar
-
-@defvar REG_NOTEOL
-Similar to REG_NOTBOL, but prevents the end of line operator
-from matching the end of @var{string}.
-@end defvar
-
-If no match is possible, regexec returns #f. Otherwise @var{match-pick}
-determines the return value:
-
-@code{#t} or unspecified: a newly-allocated vector is returned,
-containing pairs with the indices of the matched part of @var{string} and any
-substrings.
-
-@code{""}: a list is returned: the first element contains a nested list
-with the matched part of @var{string} surrounded by the the unmatched parts.
-Remaining elements are matched substrings (if any). All returned
-substrings share memory with @var{string}.
-
-@code{#f}: regexec returns #t if a match is made, otherwise #f.
-
-vector: the supplied vector is returned, with the first element replaced
-by a pair containing the indices of the matched portion of @var{string} and
-further elements replaced by pairs containing the indices of matched
-substrings (if any).
-
-list: a list will be returned, with each member of the list
-specified by a code in the corresponding position of the supplied list:
-
-a number: the numbered matching substring (0 for the entire match).
-
-@code{#\<}: the beginning of @var{string} to the beginning of the part matched
-by regex.
-
-@code{#\>}: the end of the matched part of @var{string} to the end of
-@var{string}.
-
-@code{#\c}: the "final tag", which seems to be associated with the "cut
-operator", which doesn't seem to be available through the posix
-interface.
-
-e.g., @code{(list #\< 0 1 #\>)}. The returned substrings share memory with
-@var{string}.
-@end deffn
-
-Here are some other procedures that might be used when using regular
-expressions:
-
-@deffn {Scheme Procedure} compiled-regexp? obj
-Test whether obj is a compiled regular expression.
-@end deffn
-
-@deffn {Scheme Procedure} regexp->dfa regex [flags]
-@end deffn
-
-@deffn {Scheme Procedure} dfa-fork dfa
-@end deffn
-
-@deffn {Scheme Procedure} reset-dfa! dfa
-@end deffn
-
-@deffn {Scheme Procedure} dfa-final-tag dfa
-@end deffn
-
-@deffn {Scheme Procedure} dfa-continuable? dfa
-@end deffn
-
-@deffn {Scheme Procedure} advance-dfa! dfa string
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/new-docstrings.texi b/doc/ref/new-docstrings.texi
deleted file mode 100644
index 17aa45680..000000000
--- a/doc/ref/new-docstrings.texi
+++ /dev/null
@@ -1,701 +0,0 @@
-
-@c module (guile)
-
-@deffn {Scheme Procedure} environment? obj
-@deffnx {C Function} scm_environment_p (obj)
-Return @code{#t} if @var{obj} is an environment, or @code{#f}
-otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} environment-bound? env sym
-@deffnx {C Function} scm_environment_bound_p (env, sym)
-Return @code{#t} if @var{sym} is bound in @var{env}, or
-@code{#f} otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} environment-ref env sym
-@deffnx {C Function} scm_environment_ref (env, sym)
-Return the value of the location bound to @var{sym} in
-@var{env}. If @var{sym} is unbound in @var{env}, signal an
-@code{environment:unbound} error.
-@end deffn
-
-@deffn {Scheme Procedure} environment-fold env proc init
-@deffnx {C Function} scm_environment_fold (env, proc, init)
-Iterate over all the bindings in @var{env}, accumulating some
-value.
-For each binding in @var{env}, apply @var{proc} to the symbol
-bound, its value, and the result from the previous application
-of @var{proc}.
-Use @var{init} as @var{proc}'s third argument the first time
-@var{proc} is applied.
-If @var{env} contains no bindings, this function simply returns
-@var{init}.
-If @var{env} binds the symbol sym1 to the value val1, sym2 to
-val2, and so on, then this procedure computes:
-@lisp
- (proc sym1 val1
- (proc sym2 val2
- ...
- (proc symn valn
- init)))
-@end lisp
-Each binding in @var{env} will be processed exactly once.
-@code{environment-fold} makes no guarantees about the order in
-which the bindings are processed.
-Here is a function which, given an environment, constructs an
-association list representing that environment's bindings,
-using environment-fold:
-@lisp
- (define (environment->alist env)
- (environment-fold env
- (lambda (sym val tail)
- (cons (cons sym val) tail))
- '()))
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} environment-define env sym val
-@deffnx {C Function} scm_environment_define (env, sym, val)
-Bind @var{sym} to a new location containing @var{val} in
-@var{env}. If @var{sym} is already bound to another location
-in @var{env} and the binding is mutable, that binding is
-replaced. The new binding and location are both mutable. The
-return value is unspecified.
-If @var{sym} is already bound in @var{env}, and the binding is
-immutable, signal an @code{environment:immutable-binding} error.
-@end deffn
-
-@deffn {Scheme Procedure} environment-undefine env sym
-@deffnx {C Function} scm_environment_undefine (env, sym)
-Remove any binding for @var{sym} from @var{env}. If @var{sym}
-is unbound in @var{env}, do nothing. The return value is
-unspecified.
-If @var{sym} is already bound in @var{env}, and the binding is
-immutable, signal an @code{environment:immutable-binding} error.
-@end deffn
-
-@deffn {Scheme Procedure} environment-set! env sym val
-@deffnx {C Function} scm_environment_set_x (env, sym, val)
-If @var{env} binds @var{sym} to some location, change that
-location's value to @var{val}. The return value is
-unspecified.
-If @var{sym} is not bound in @var{env}, signal an
-@code{environment:unbound} error. If @var{env} binds @var{sym}
-to an immutable location, signal an
-@code{environment:immutable-location} error.
-@end deffn
-
-@deffn {Scheme Procedure} environment-cell env sym for_write
-@deffnx {C Function} scm_environment_cell (env, sym, for_write)
-Return the value cell which @var{env} binds to @var{sym}, or
-@code{#f} if the binding does not live in a value cell.
-The argument @var{for-write} indicates whether the caller
-intends to modify the variable's value by mutating the value
-cell. If the variable is immutable, then
-@code{environment-cell} signals an
-@code{environment:immutable-location} error.
-If @var{sym} is unbound in @var{env}, signal an
-@code{environment:unbound} error.
-If you use this function, you should consider using
-@code{environment-observe}, to be notified when @var{sym} gets
-re-bound to a new value cell, or becomes undefined.
-@end deffn
-
-@deffn {Scheme Procedure} environment-observe env proc
-@deffnx {C Function} scm_environment_observe (env, proc)
-Whenever @var{env}'s bindings change, apply @var{proc} to
-@var{env}.
-This function returns an object, token, which you can pass to
-@code{environment-unobserve} to remove @var{proc} from the set
-of procedures observing @var{env}. The type and value of
-token is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} environment-observe-weak env proc
-@deffnx {C Function} scm_environment_observe_weak (env, proc)
-This function is the same as environment-observe, except that
-the reference @var{env} retains to @var{proc} is a weak
-reference. This means that, if there are no other live,
-non-weak references to @var{proc}, it will be
-garbage-collected, and dropped from @var{env}'s
-list of observing procedures.
-@end deffn
-
-@deffn {Scheme Procedure} environment-unobserve token
-@deffnx {C Function} scm_environment_unobserve (token)
-Cancel the observation request which returned the value
-@var{token}. The return value is unspecified.
-If a call @code{(environment-observe env proc)} returns
-@var{token}, then the call @code{(environment-unobserve token)}
-will cause @var{proc} to no longer be called when @var{env}'s
-bindings change.
-@end deffn
-
-@deffn {Scheme Procedure} make-leaf-environment
-@deffnx {C Function} scm_make_leaf_environment ()
-Create a new leaf environment, containing no bindings.
-All bindings and locations created in the new environment
-will be mutable.
-@end deffn
-
-@deffn {Scheme Procedure} leaf-environment? object
-@deffnx {C Function} scm_leaf_environment_p (object)
-Return @code{#t} if object is a leaf environment, or @code{#f}
-otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} make-eval-environment local imported
-@deffnx {C Function} scm_make_eval_environment (local, imported)
-Return a new environment object eval whose bindings are the
-union of the bindings in the environments @var{local} and
-@var{imported}, with bindings from @var{local} taking
-precedence. Definitions made in eval are placed in @var{local}.
-Applying @code{environment-define} or
-@code{environment-undefine} to eval has the same effect as
-applying the procedure to @var{local}.
-Note that eval incorporates @var{local} and @var{imported} by
-reference:
-If, after creating eval, the program changes the bindings of
-@var{local} or @var{imported}, those changes will be visible
-in eval.
-Since most Scheme evaluation takes place in eval environments,
-they transparently cache the bindings received from @var{local}
-and @var{imported}. Thus, the first time the program looks up
-a symbol in eval, eval may make calls to @var{local} or
-@var{imported} to find their bindings, but subsequent
-references to that symbol will be as fast as references to
-bindings in finite environments.
-In typical use, @var{local} will be a finite environment, and
-@var{imported} will be an import environment
-@end deffn
-
-@deffn {Scheme Procedure} eval-environment? object
-@deffnx {C Function} scm_eval_environment_p (object)
-Return @code{#t} if object is an eval environment, or @code{#f}
-otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} eval-environment-local env
-@deffnx {C Function} scm_eval_environment_local (env)
-Return the local environment of eval environment @var{env}.
-@end deffn
-
-@deffn {Scheme Procedure} eval-environment-set-local! env local
-@deffnx {C Function} scm_eval_environment_set_local_x (env, local)
-Change @var{env}'s local environment to @var{local}.
-@end deffn
-
-@deffn {Scheme Procedure} eval-environment-imported env
-@deffnx {C Function} scm_eval_environment_imported (env)
-Return the imported environment of eval environment @var{env}.
-@end deffn
-
-@deffn {Scheme Procedure} eval-environment-set-imported! env imported
-@deffnx {C Function} scm_eval_environment_set_imported_x (env, imported)
-Change @var{env}'s imported environment to @var{imported}.
-@end deffn
-
-@deffn {Scheme Procedure} make-import-environment imports conflict_proc
-@deffnx {C Function} scm_make_import_environment (imports, conflict_proc)
-Return a new environment @var{imp} whose bindings are the union
-of the bindings from the environments in @var{imports};
-@var{imports} must be a list of environments. That is,
-@var{imp} binds a symbol to a location when some element of
-@var{imports} does.
-If two different elements of @var{imports} have a binding for
-the same symbol, the @var{conflict-proc} is called with the
-following parameters: the import environment, the symbol and
-the list of the imported environments that bind the symbol.
-If the @var{conflict-proc} returns an environment @var{env},
-the conflict is considered as resolved and the binding from
-@var{env} is used. If the @var{conflict-proc} returns some
-non-environment object, the conflict is considered unresolved
-and the symbol is treated as unspecified in the import
-environment.
-The checking for conflicts may be performed lazily, i. e. at
-the moment when a value or binding for a certain symbol is
-requested instead of the moment when the environment is
-created or the bindings of the imports change.
-All bindings in @var{imp} are immutable. If you apply
-@code{environment-define} or @code{environment-undefine} to
-@var{imp}, Guile will signal an
- @code{environment:immutable-binding} error. However,
-notice that the set of bindings in @var{imp} may still change,
-if one of its imported environments changes.
-@end deffn
-
-@deffn {Scheme Procedure} import-environment? object
-@deffnx {C Function} scm_import_environment_p (object)
-Return @code{#t} if object is an import environment, or
-@code{#f} otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} import-environment-imports env
-@deffnx {C Function} scm_import_environment_imports (env)
-Return the list of environments imported by the import
-environment @var{env}.
-@end deffn
-
-@deffn {Scheme Procedure} import-environment-set-imports! env imports
-@deffnx {C Function} scm_import_environment_set_imports_x (env, imports)
-Change @var{env}'s list of imported environments to
-@var{imports}, and check for conflicts.
-@end deffn
-
-@deffn {Scheme Procedure} make-export-environment private signature
-@deffnx {C Function} scm_make_export_environment (private, signature)
-Return a new environment @var{exp} containing only those
-bindings in private whose symbols are present in
-@var{signature}. The @var{private} argument must be an
-environment.
-
-The environment @var{exp} binds symbol to location when
-@var{env} does, and symbol is exported by @var{signature}.
-
-@var{signature} is a list specifying which of the bindings in
-@var{private} should be visible in @var{exp}. Each element of
-@var{signature} should be a list of the form:
- (symbol attribute ...)
-where each attribute is one of the following:
-@table @asis
-@item the symbol @code{mutable-location}
- @var{exp} should treat the
- location bound to symbol as mutable. That is, @var{exp}
- will pass calls to @code{environment-set!} or
- @code{environment-cell} directly through to private.
-@item the symbol @code{immutable-location}
- @var{exp} should treat
- the location bound to symbol as immutable. If the program
- applies @code{environment-set!} to @var{exp} and symbol, or
- calls @code{environment-cell} to obtain a writable value
- cell, @code{environment-set!} will signal an
- @code{environment:immutable-location} error. Note that, even
- if an export environment treats a location as immutable, the
- underlying environment may treat it as mutable, so its
- value may change.
-@end table
-It is an error for an element of signature to specify both
-@code{mutable-location} and @code{immutable-location}. If
-neither is specified, @code{immutable-location} is assumed.
-
-As a special case, if an element of signature is a lone
-symbol @var{sym}, it is equivalent to an element of the form
-@code{(sym)}.
-
-All bindings in @var{exp} are immutable. If you apply
-@code{environment-define} or @code{environment-undefine} to
-@var{exp}, Guile will signal an
-@code{environment:immutable-binding} error. However,
-notice that the set of bindings in @var{exp} may still change,
-if the bindings in private change.
-@end deffn
-
-@deffn {Scheme Procedure} export-environment? object
-@deffnx {C Function} scm_export_environment_p (object)
-Return @code{#t} if object is an export environment, or
-@code{#f} otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} export-environment-private env
-@deffnx {C Function} scm_export_environment_private (env)
-Return the private environment of export environment @var{env}.
-@end deffn
-
-@deffn {Scheme Procedure} export-environment-set-private! env private
-@deffnx {C Function} scm_export_environment_set_private_x (env, private)
-Change the private environment of export environment @var{env}.
-@end deffn
-
-@deffn {Scheme Procedure} export-environment-signature env
-@deffnx {C Function} scm_export_environment_signature (env)
-Return the signature of export environment @var{env}.
-@end deffn
-
-@deffn {Scheme Procedure} export-environment-set-signature! env signature
-@deffnx {C Function} scm_export_environment_set_signature_x (env, signature)
-Change the signature of export environment @var{env}.
-@end deffn
-
-@deffn {Scheme Procedure} %compute-slots class
-@deffnx {C Function} scm_sys_compute_slots (class)
-Return a list consisting of the names of all slots belonging to
-class @var{class}, i. e. the slots of @var{class} and of all of
-its superclasses.
-@end deffn
-
-@deffn {Scheme Procedure} get-keyword key l default_value
-@deffnx {C Function} scm_get_keyword (key, l, default_value)
-Determine an associated value for the keyword @var{key} from
-the list @var{l}. The list @var{l} has to consist of an even
-number of elements, where, starting with the first, every
-second element is a keyword, followed by its associated value.
-If @var{l} does not hold a value for @var{key}, the value
-@var{default_value} is returned.
-@end deffn
-
-@deffn {Scheme Procedure} slot-ref-using-class class obj slot_name
-@deffnx {C Function} scm_slot_ref_using_class (class, obj, slot_name)
-
-@end deffn
-
-@deffn {Scheme Procedure} slot-set-using-class! class obj slot_name value
-@deffnx {C Function} scm_slot_set_using_class_x (class, obj, slot_name, value)
-
-@end deffn
-
-@deffn {Scheme Procedure} class-of x
-@deffnx {C Function} scm_class_of (x)
-Return the class of @var{x}.
-@end deffn
-
-@deffn {Scheme Procedure} %goops-loaded
-@deffnx {C Function} scm_sys_goops_loaded ()
-Announce that GOOPS is loaded and perform initialization
-on the C level which depends on the loaded GOOPS modules.
-@end deffn
-
-@deffn {Scheme Procedure} %method-more-specific? m1 m2 targs
-@deffnx {C Function} scm_sys_method_more_specific_p (m1, m2, targs)
-
-@end deffn
-
-@deffn {Scheme Procedure} find-method . l
-@deffnx {C Function} scm_find_method (l)
-
-@end deffn
-
-@deffn {Scheme Procedure} primitive-generic-generic subr
-@deffnx {C Function} scm_primitive_generic_generic (subr)
-
-@end deffn
-
-@deffn {Scheme Procedure} enable-primitive-generic! . subrs
-@deffnx {C Function} scm_enable_primitive_generic_x (subrs)
-
-@end deffn
-
-@deffn {Scheme Procedure} generic-capability? proc
-@deffnx {C Function} scm_generic_capability_p (proc)
-
-@end deffn
-
-@deffn {Scheme Procedure} %invalidate-method-cache! gf
-@deffnx {C Function} scm_sys_invalidate_method_cache_x (gf)
-
-@end deffn
-
-@deffn {Scheme Procedure} %invalidate-class class
-@deffnx {C Function} scm_sys_invalidate_class (class)
-
-@end deffn
-
-@deffn {Scheme Procedure} %modify-class old new
-@deffnx {C Function} scm_sys_modify_class (old, new)
-
-@end deffn
-
-@deffn {Scheme Procedure} %modify-instance old new
-@deffnx {C Function} scm_sys_modify_instance (old, new)
-
-@end deffn
-
-@deffn {Scheme Procedure} %set-object-setter! obj setter
-@deffnx {C Function} scm_sys_set_object_setter_x (obj, setter)
-
-@end deffn
-
-@deffn {Scheme Procedure} %allocate-instance class initargs
-@deffnx {C Function} scm_sys_allocate_instance (class, initargs)
-Create a new instance of class @var{class} and initialize it
-from the arguments @var{initargs}.
-@end deffn
-
-@deffn {Scheme Procedure} slot-exists? obj slot_name
-@deffnx {C Function} scm_slot_exists_p (obj, slot_name)
-Return @code{#t} if @var{obj} has a slot named @var{slot_name}.
-@end deffn
-
-@deffn {Scheme Procedure} slot-bound? obj slot_name
-@deffnx {C Function} scm_slot_bound_p (obj, slot_name)
-Return @code{#t} if the slot named @var{slot_name} of @var{obj}
-is bound.
-@end deffn
-
-@deffn {Scheme Procedure} slot-set! obj slot_name value
-@deffnx {C Function} scm_slot_set_x (obj, slot_name, value)
-Set the slot named @var{slot_name} of @var{obj} to @var{value}.
-@end deffn
-
-@deffn {Scheme Procedure} slot-exists-using-class? class obj slot_name
-@deffnx {C Function} scm_slot_exists_using_class_p (class, obj, slot_name)
-
-@end deffn
-
-@deffn {Scheme Procedure} slot-bound-using-class? class obj slot_name
-@deffnx {C Function} scm_slot_bound_using_class_p (class, obj, slot_name)
-
-@end deffn
-
-@deffn {Scheme Procedure} %fast-slot-set! obj index value
-@deffnx {C Function} scm_sys_fast_slot_set_x (obj, index, value)
-Set the slot with index @var{index} in @var{obj} to
-@var{value}.
-@end deffn
-
-@deffn {Scheme Procedure} %fast-slot-ref obj index
-@deffnx {C Function} scm_sys_fast_slot_ref (obj, index)
-Return the slot value with index @var{index} from @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} @@assert-bound-ref obj index
-@deffnx {C Function} scm_at_assert_bound_ref (obj, index)
-Like @code{assert-bound}, but use @var{index} for accessing
-the value from @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} assert-bound value obj
-@deffnx {C Function} scm_assert_bound (value, obj)
-Return @var{value} if it is bound, and invoke the
-@var{slot-unbound} method of @var{obj} if it is not.
-@end deffn
-
-@deffn {Scheme Procedure} unbound? obj
-@deffnx {C Function} scm_unbound_p (obj)
-Return @code{#t} if @var{obj} is unbound.
-@end deffn
-
-@deffn {Scheme Procedure} make-unbound
-@deffnx {C Function} scm_make_unbound ()
-Return the unbound value.
-@end deffn
-
-@deffn {Scheme Procedure} accessor-method-slot-definition obj
-@deffnx {C Function} scm_accessor_method_slot_definition (obj)
-Return the slot definition of the accessor @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} method-procedure obj
-@deffnx {C Function} scm_method_procedure (obj)
-Return the procedure of the method @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} method-specializers obj
-@deffnx {C Function} scm_method_specializers (obj)
-Return specializers of the method @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} method-generic-function obj
-@deffnx {C Function} scm_method_generic_function (obj)
-Return the generic function for the method @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} generic-function-methods obj
-@deffnx {C Function} scm_generic_function_methods (obj)
-Return the methods of the generic function @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} generic-function-name obj
-@deffnx {C Function} scm_generic_function_name (obj)
-Return the name of the generic function @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} class-environment obj
-@deffnx {C Function} scm_class_environment (obj)
-Return the environment of the class @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} class-slots obj
-@deffnx {C Function} scm_class_slots (obj)
-Return the slot list of the class @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} class-precedence-list obj
-@deffnx {C Function} scm_class_precedence_list (obj)
-Return the class precedence list of the class @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} class-direct-methods obj
-@deffnx {C Function} scm_class_direct_methods (obj)
-Return the direct methods of the class @var{obj}
-@end deffn
-
-@deffn {Scheme Procedure} class-direct-subclasses obj
-@deffnx {C Function} scm_class_direct_subclasses (obj)
-Return the direct subclasses of the class @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} class-direct-slots obj
-@deffnx {C Function} scm_class_direct_slots (obj)
-Return the direct slots of the class @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} class-direct-supers obj
-@deffnx {C Function} scm_class_direct_supers (obj)
-Return the direct superclasses of the class @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} class-name obj
-@deffnx {C Function} scm_class_name (obj)
-Return the class name of @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} instance? obj
-@deffnx {C Function} scm_instance_p (obj)
-Return @code{#t} if @var{obj} is an instance.
-@end deffn
-
-@deffn {Scheme Procedure} %inherit-magic! class dsupers
-@deffnx {C Function} scm_sys_inherit_magic_x (class, dsupers)
-
-@end deffn
-
-@deffn {Scheme Procedure} %prep-layout! class
-@deffnx {C Function} scm_sys_prep_layout_x (class)
-
-@end deffn
-
-@deffn {Scheme Procedure} %initialize-object obj initargs
-@deffnx {C Function} scm_sys_initialize_object (obj, initargs)
-Initialize the object @var{obj} with the given arguments
-@var{initargs}.
-@end deffn
-
-@deffn {Scheme Procedure} make . args
-@deffnx {C Function} scm_make (args)
-Make a new object. @var{args} must contain the class and
-all necessary initialization information.
-@end deffn
-
-@deffn {Scheme Procedure} slot-ref obj slot_name
-@deffnx {C Function} scm_slot_ref (obj, slot_name)
-Return the value from @var{obj}'s slot with the name
-@var{slot_name}.
-@end deffn
-
-@deffn {Scheme Procedure} %tag-body body
-@deffnx {C Function} scm_sys_tag_body (body)
-Internal GOOPS magic---don't use this function!
-@end deffn
-
-@deffn {Scheme Procedure} list*
-implemented by the C function "scm_cons_star"
-@end deffn
-
-@deffn {Scheme Procedure} set-current-module module
-@deffnx {C Function} scm_set_current_module (module)
-Set the current module to @var{module} and return
-the previous current module.
-@end deffn
-
-@deffn {Scheme Procedure} current-module
-@deffnx {C Function} scm_current_module ()
-Return the current module.
-@end deffn
-
-@deffn {Scheme Procedure} c-clear-registered-modules
-Destroy the list of modules registered with the current Guile process.
-The return value is unspecified. @strong{Warning:} this function does
-not actually unlink or deallocate these modules, but only destroys the
-records of which modules have been loaded. It should therefore be used
-only by module bookkeeping operations.
-@end deffn
-
-@deffn {Scheme Procedure} c-registered-modules
-Return a list of the object code modules that have been imported into
-the current Guile process. Each element of the list is a pair whose
-car is the name of the module, and whose cdr is the function handle
-for that module's initializer function. The name is the string that
-has been passed to scm_register_module_xxx.
-@end deffn
-
-@deffn {Scheme Procedure} include-deprecated-features
-Return @code{#t} iff deprecated features should be included
-in public interfaces.
-@end deffn
-
-@deffn {Scheme Procedure} issue-deprecation-warning . msgs
-Output @var{msgs} to @code{(current-error-port)} when this
-is the first call to @code{issue-deprecation-warning} with
-this specific @var{msg}. Do nothing otherwise.
-The argument @var{msgs} should be a list of strings;
-they are printed in turn, each one followed by a newline.
-@end deffn
-
-@deffn {Scheme Procedure} valid-object-procedure? proc
-@deffnx {C Function} scm_valid_object_procedure_p (proc)
-Return @code{#t} iff @var{proc} is a procedure that can be used with @code{set-object-procedure}. It is always valid to use a closure constructed by @code{lambda}.
-@end deffn
-
-@deffn {Scheme Procedure} %get-pre-modules-obarray
-@deffnx {C Function} scm_get_pre_modules_obarray ()
-Return the obarray that is used for all new bindings before the module system is booted. The first call to @code{set-current-module} will boot the module system.
-@end deffn
-
-@deffn {Scheme Procedure} standard-interface-eval-closure module
-@deffnx {C Function} scm_standard_interface_eval_closure (module)
-Return a interface eval closure for the module @var{module}. Such a closure does not allow new bindings to be added.
-@end deffn
-
-@deffn {Scheme Procedure} env-module env
-@deffnx {C Function} scm_env_module (env)
-Return the module of @var{ENV}, a lexical environment.
-@end deffn
-
-@deffn {Scheme Procedure} load-extension lib init
-@deffnx {C Function} scm_load_extension (lib, init)
-Load and initialize the extension designated by LIB and INIT.
-When there is no pre-registered function for LIB/INIT, this is
-equivalent to
-
-@lisp
-(dynamic-call INIT (dynamic-link LIB))
-@end lisp
-
-When there is a pre-registered function, that function is called
-instead.
-
-Normally, there is no pre-registered function. This option exists
-only for situations where dynamic linking is unavailable or unwanted.
-In that case, you would statically link your program with the desired
-library, and register its init function right after Guile has been
-initialized.
-
-LIB should be a string denoting a shared library without any file type
-suffix such as ".so". The suffix is provided automatically. It
-should also not contain any directory components. Libraries that
-implement Guile Extensions should be put into the normal locations for
-shared libraries. We recommend to use the naming convention
-libguile-bla-blum for a extension related to a module `(bla blum)'.
-
-The normal way for a extension to be used is to write a small Scheme
-file that defines a module, and to load the extension into this
-module. When the module is auto-loaded, the extension is loaded as
-well. For example,
-
-@lisp
-(define-module (bla blum))
-
-(load-extension "libguile-bla-blum" "bla_init_blum")
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} single-active-thread?
-implemented by the C function "scm_single_thread_p"
-@end deffn
-
-@deffn {Scheme Procedure} object-address obj
-@deffnx {C Function} scm_object_address (obj)
-Return an integer that for the lifetime of @var{obj} is uniquely
-returned by this function for @var{obj}
-@end deffn
-
-@deffn {Scheme Procedure} nan
-@deffnx {C Function} scm_nan ()
-Return NaN.
-@end deffn
-
-@deffn {Scheme Procedure} inf
-@deffnx {C Function} scm_inf ()
-Return Inf.
-@end deffn
diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi
deleted file mode 100644
index 8a9fc280e..000000000
--- a/doc/ref/posix.texi
+++ /dev/null
@@ -1,2490 +0,0 @@
-@node POSIX
-@chapter POSIX System Calls and Networking
-
-@menu
-* Conventions:: Conventions employed by the POSIX interface.
-* Ports and File Descriptors:: Scheme ``ports'' and Unix file descriptors
- have different representations.
-* File System:: stat, chown, chmod, etc.
-* User Information:: Retrieving a user's GECOS (/etc/passwd) entry.
-* Time:: gettimeofday, localtime, strftime, etc.
-* Runtime Environment:: Accessing and modifying Guile's environment.
-* Processes:: getuid, getpid, etc.
-* Signals:: sigaction, kill, pause, alarm, setitimer, etc.
-* Terminals and Ptys:: ttyname, tcsetpgrp, etc.
-* Pipes:: Communicating data between processes.
-* Networking:: gethostbyaddr, getnetent, socket, bind, listen.
-* System Identification:: Obtaining information about the system.
-* Locales:: setlocale, etc.
-* Encryption::
-@end menu
-
-@node Conventions
-@section POSIX Interface Conventions
-
-These interfaces provide access to operating system facilities.
-They provide a simple wrapping around the underlying C interfaces
-to make usage from Scheme more convenient. They are also used
-to implement the Guile port of @ref{The Scheme shell (scsh)}.
-
-Generally there is a single procedure for each corresponding Unix
-facility. There are some exceptions, such as procedures implemented for
-speed and convenience in Scheme with no primitive Unix equivalent,
-e.g., @code{copy-file}.
-
-The interfaces are intended as far as possible to be portable across
-different versions of Unix. In some cases procedures which can't be
-implemented on particular systems may become no-ops, or perform limited
-actions. In other cases they may throw errors.
-
-General naming conventions are as follows:
-
-@itemize @bullet
-@item
-The Scheme name is often identical to the name of the underlying Unix
-facility.
-@item
-Underscores in Unix procedure names are converted to hyphens.
-@item
-Procedures which destructively modify Scheme data have exclamation
-marks appended, e.g., @code{recv!}.
-@item
-Predicates (returning only @code{#t} or @code{#f}) have question marks
-appended, e.g., @code{access?}.
-@item
-Some names are changed to avoid conflict with dissimilar interfaces
-defined by scsh, e.g., @code{primitive-fork}.
-@item
-Unix preprocessor names such as @code{EPERM} or @code{R_OK} are converted
-to Scheme variables of the same name (underscores are not replaced
-with hyphens).
-@end itemize
-
-Unexpected conditions are generally handled by raising exceptions.
-There are a few procedures which return a special value if they don't
-succeed, e.g., @code{getenv} returns @code{#f} if it the requested
-string is not found in the environment. These cases are noted in
-the documentation.
-
-For ways to deal with exceptions, @ref{Exceptions}.
-
-Errors which the C-library would report by returning a NULL pointer or
-through some other means are reported by raising a @code{system-error}
-exception. The value of the Unix @code{errno} variable is available
-in the data passed by the exception.
-
-It can be extracted with the function @code{system-error-errno}:
-
-@example
-(catch
- 'system-error
- (lambda ()
- (mkdir "/this-ought-to-fail-if-I'm-not-root"))
- (lambda stuff
- (let ((errno (system-error-errno stuff)))
- (cond
- ((= errno EACCES)
- (display "You're not allowed to do that."))
- ((= errno EEXIST)
- (display "Already exists."))
- (#t
- (display (strerror errno))))
- (newline))))
-@end example
-
-@node Ports and File Descriptors
-@section Ports and File Descriptors
-
-Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}.
-
-File ports are implemented using low-level operating system I/O
-facilities, with optional buffering to improve efficiency
-@pxref{File Ports}
-
-Note that some procedures (e.g., @code{recv!}) will accept ports as
-arguments, but will actually operate directly on the file descriptor
-underlying the port. Any port buffering is ignored, including the
-buffer which implements @code{peek-char} and @code{unread-char}.
-
-The @code{force-output} and @code{drain-input} procedures can be used
-to clear the buffers.
-
-Each open file port has an associated operating system file descriptor.
-File descriptors are generally not useful in Scheme programs; however
-they may be needed when interfacing with foreign code and the Unix
-environment.
-
-A file descriptor can be extracted from a port and a new port can be
-created from a file descriptor. However a file descriptor is just an
-integer and the garbage collector doesn't recognize it as a reference
-to the port. If all other references to the port were dropped, then
-it's likely that the garbage collector would free the port, with the
-side-effect of closing the file descriptor prematurely.
-
-To assist the programmer in avoiding this problem, each port has an
-associated "revealed count" which can be used to keep track of how many
-times the underlying file descriptor has been stored in other places.
-If a port's revealed count is greater than zero, the file descriptor
-will not be closed when the port is garbage collected. A programmer
-can therefore ensure that the revealed count will be greater than
-zero if the file descriptor is needed elsewhere.
-
-For the simple case where a file descriptor is "imported" once to become
-a port, it does not matter if the file descriptor is closed when the
-port is garbage collected. There is no need to maintain a revealed
-count. Likewise when "exporting" a file descriptor to the external
-environment, setting the revealed count is not required provided the
-port is kept open (i.e., is pointed to by a live Scheme binding) while
-the file descriptor is in use.
-
-To correspond with traditional Unix behaviour, the three file
-descriptors (0, 1 and 2) are automatically imported when a program
-starts up and assigned to the initial values of the current input,
-output and error ports. The revealed count for each is initially set to
-one, so that dropping references to one of these ports will not result
-in its garbage collection: it could be retrieved with fdopen or
-fdes->ports.
-
-@deffn {Scheme Procedure} port-revealed port
-@deffnx {C Function} scm_port_revealed (port)
-Return the revealed count for @var{port}.
-@end deffn
-
-@deffn {Scheme Procedure} set-port-revealed! port rcount
-@deffnx {C Function} scm_set_port_revealed_x (port, rcount)
-Sets the revealed count for a port to a given value.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} fileno port
-@deffnx {C Function} scm_fileno (port)
-Return the integer file descriptor underlying @var{port}. Does
-not change its revealed count.
-@end deffn
-
-@deffn {Scheme Procedure} port->fdes port
-Returns the integer file descriptor underlying @var{port}. As a
-side effect the revealed count of @var{port} is incremented.
-@end deffn
-
-@deffn {Scheme Procedure} fdopen fdes modes
-@deffnx {C Function} scm_fdopen (fdes, modes)
-Return a new port based on the file descriptor @var{fdes}.
-Modes are given by the string @var{modes}. The revealed count
-of the port is initialized to zero. The modes string is the
-same as that accepted by @ref{File Ports, open-file}.
-@end deffn
-
-@deffn {Scheme Procedure} fdes->ports fd
-@deffnx {C Function} scm_fdes_to_ports (fd)
-Return a list of existing ports which have @var{fdes} as an
-underlying file descriptor, without changing their revealed
-counts.
-@end deffn
-
-@deffn {Scheme Procedure} fdes->inport fdes
-Returns an existing input port which has @var{fdes} as its underlying file
-descriptor, if one exists, and increments its revealed count.
-Otherwise, returns a new input port with a revealed count of 1.
-@end deffn
-
-@deffn {Scheme Procedure} fdes->outport fdes
-Returns an existing output port which has @var{fdes} as its underlying file
-descriptor, if one exists, and increments its revealed count.
-Otherwise, returns a new output port with a revealed count of 1.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-move->fdes port fd
-@deffnx {C Function} scm_primitive_move_to_fdes (port, fd)
-Moves the underlying file descriptor for @var{port} to the integer
-value @var{fdes} without changing the revealed count of @var{port}.
-Any other ports already using this descriptor will be automatically
-shifted to new descriptors and their revealed counts reset to zero.
-The return value is @code{#f} if the file descriptor already had the
-required value or @code{#t} if it was moved.
-@end deffn
-
-@deffn {Scheme Procedure} move->fdes port fdes
-Moves the underlying file descriptor for @var{port} to the integer
-value @var{fdes} and sets its revealed count to one. Any other ports
-already using this descriptor will be automatically
-shifted to new descriptors and their revealed counts reset to zero.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} release-port-handle port
-Decrements the revealed count for a port.
-@end deffn
-
-@deffn {Scheme Procedure} fsync object
-@deffnx {C Function} scm_fsync (object)
-Copies any unwritten data for the specified output file descriptor to disk.
-If @var{port/fd} is a port, its buffer is flushed before the underlying
-file descriptor is fsync'd.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} open path flags [mode]
-@deffnx {C Function} scm_open (path, flags, mode)
-Open the file named by @var{path} for reading and/or writing.
-@var{flags} is an integer specifying how the file should be opened.
-@var{mode} is an integer specifying the permission bits of the file, if
-it needs to be created, before the umask is applied. The default is 666
-(Unix itself has no default).
-
-@var{flags} can be constructed by combining variables using @code{logior}.
-Basic flags are:
-
-@defvar O_RDONLY
-Open the file read-only.
-@end defvar
-@defvar O_WRONLY
-Open the file write-only.
-@end defvar
-@defvar O_RDWR
-Open the file read/write.
-@end defvar
-@defvar O_APPEND
-Append to the file instead of truncating.
-@end defvar
-@defvar O_CREAT
-Create the file if it does not already exist.
-@end defvar
-
-See the Unix documentation of the @code{open} system call
-for additional flags.
-@end deffn
-
-@deffn {Scheme Procedure} open-fdes path flags [mode]
-@deffnx {C Function} scm_open_fdes (path, flags, mode)
-Similar to @code{open} but return a file descriptor instead of
-a port.
-@end deffn
-
-@deffn {Scheme Procedure} close fd_or_port
-@deffnx {C Function} scm_close (fd_or_port)
-Similar to close-port (@pxref{Closing, close-port}),
-but also works on file descriptors. A side
-effect of closing a file descriptor is that any ports using that file
-descriptor are moved to a different file descriptor and have
-their revealed counts set to zero.
-@end deffn
-
-@deffn {Scheme Procedure} close-fdes fd
-@deffnx {C Function} scm_close_fdes (fd)
-A simple wrapper for the @code{close} system call.
-Close file descriptor @var{fd}, which must be an integer.
-Unlike close (@pxref{Ports and File Descriptors, close}),
-the file descriptor will be closed even if a port is using it.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} unread-char char [port]
-@deffnx {C Function} scm_unread_char (char, port)
-Place @var{char} in @var{port} so that it will be read by the
-next read operation. If called multiple times, the unread characters
-will be read again in last-in first-out order. If @var{port} is
-not supplied, the current input port is used.
-@end deffn
-
-@deffn {Scheme Procedure} unread-string str port
-Place the string @var{str} in @var{port} so that its characters will be
-read in subsequent read operations. If called multiple times, the
-unread characters will be read again in last-in first-out order. If
-@var{port} is not supplied, the current-input-port is used.
-@end deffn
-
-@deffn {Scheme Procedure} pipe
-@deffnx {C Function} scm_pipe ()
-Return a newly created pipe: a pair of ports which are linked
-together on the local machine. The @emph{car} is the input
-port and the @emph{cdr} is the output port. Data written (and
-flushed) to the output port can be read from the input port.
-Pipes are commonly used for communication with a newly forked
-child process. The need to flush the output port can be
-avoided by making it unbuffered using @code{setvbuf}.
-
-Writes occur atomically provided the size of the data in bytes
-is not greater than the value of @code{PIPE_BUF}. Note that
-the output port is likely to block if too much data (typically
-equal to @code{PIPE_BUF}) has been written but not yet read
-from the input port.
-@end deffn
-
-The next group of procedures perform a @code{dup2}
-system call, if @var{newfd} (an
-integer) is supplied, otherwise a @code{dup}. The file descriptor to be
-duplicated can be supplied as an integer or contained in a port. The
-type of value returned varies depending on which procedure is used.
-
-All procedures also have the side effect when performing @code{dup2} that any
-ports using @var{newfd} are moved to a different file descriptor and have
-their revealed counts set to zero.
-
-@deffn {Scheme Procedure} dup->fdes fd_or_port [fd]
-@deffnx {C Function} scm_dup_to_fdes (fd_or_port, fd)
-Return a new integer file descriptor referring to the open file
-designated by @var{fd_or_port}, which must be either an open
-file port or a file descriptor.
-@end deffn
-
-@deffn {Scheme Procedure} dup->inport port/fd [newfd]
-Returns a new input port using the new file descriptor.
-@end deffn
-
-@deffn {Scheme Procedure} dup->outport port/fd [newfd]
-Returns a new output port using the new file descriptor.
-@end deffn
-
-@deffn {Scheme Procedure} dup port/fd [newfd]
-Returns a new port if @var{port/fd} is a port, with the same mode as the
-supplied port, otherwise returns an integer file descriptor.
-@end deffn
-
-@deffn {Scheme Procedure} dup->port port/fd mode [newfd]
-Returns a new port using the new file descriptor. @var{mode} supplies a
-mode string for the port (@pxref{File Ports, open-file}).
-@end deffn
-
-@deffn {Scheme Procedure} duplicate-port port modes
-Returns a new port which is opened on a duplicate of the file
-descriptor underlying @var{port}, with mode string @var{modes}
-as for @ref{File Ports, open-file}. The two ports
-will share a file position and file status flags.
-
-Unexpected behaviour can result if both ports are subsequently used
-and the original and/or duplicate ports are buffered.
-The mode string can include @code{0} to obtain an unbuffered duplicate
-port.
-
-This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}.
-@end deffn
-
-@deffn {Scheme Procedure} redirect-port old new
-@deffnx {C Function} scm_redirect_port (old, new)
-This procedure takes two ports and duplicates the underlying file
-descriptor from @var{old-port} into @var{new-port}. The
-current file descriptor in @var{new-port} will be closed.
-After the redirection the two ports will share a file position
-and file status flags.
-
-The return value is unspecified.
-
-Unexpected behaviour can result if both ports are subsequently used
-and the original and/or duplicate ports are buffered.
-
-This procedure does not have any side effects on other ports or
-revealed counts.
-@end deffn
-
-@deffn {Scheme Procedure} dup2 oldfd newfd
-@deffnx {C Function} scm_dup2 (oldfd, newfd)
-A simple wrapper for the @code{dup2} system call.
-Copies the file descriptor @var{oldfd} to descriptor
-number @var{newfd}, replacing the previous meaning
-of @var{newfd}. Both @var{oldfd} and @var{newfd} must
-be integers.
-Unlike for dup->fdes or primitive-move->fdes, no attempt
-is made to move away ports which are using @var{newfd}.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} port-mode port
-Return the port modes associated with the open port @var{port}.
-These will not necessarily be identical to the modes used when
-the port was opened, since modes such as "append" which are
-used only during port creation are not retained.
-@end deffn
-
-@deffn {Scheme Procedure} port-for-each proc
-@deffnx {C Function} scm_port_for_each (proc)
-Apply @var{proc} to each port in the Guile port table
-in turn. The return value is unspecified. More specifically,
-@var{proc} is applied exactly once to every port that exists
-in the system at the time @var{port-for-each} is invoked.
-Changes to the port table while @var{port-for-each} is running
-have no effect as far as @var{port-for-each} is concerned.
-@end deffn
-
-@deffn {Scheme Procedure} setvbuf port mode [size]
-@deffnx {C Function} scm_setvbuf (port, mode, size)
-Set the buffering mode for @var{port}. @var{mode} can be:
-@table @code
-@item _IONBF
-non-buffered
-@item _IOLBF
-line buffered
-@item _IOFBF
-block buffered, using a newly allocated buffer of @var{size} bytes.
-If @var{size} is omitted, a default size will be used.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} fcntl object cmd [value]
-@deffnx {C Function} scm_fcntl (object, cmd, value)
-Apply @var{command} to the specified file descriptor or the underlying
-file descriptor of the specified port. @var{value} is an optional
-integer argument.
-
-Values for @var{command} are:
-
-@table @code
-@item F_DUPFD
-Duplicate a file descriptor
-@item F_GETFD
-Get flags associated with the file descriptor.
-@item F_SETFD
-Set flags associated with the file descriptor to @var{value}.
-@item F_GETFL
-Get flags associated with the open file.
-@item F_SETFL
-Set flags associated with the open file to @var{value}
-@item F_GETOWN
-Get the process ID of a socket's owner, for @code{SIGIO} signals.
-@item F_SETOWN
-Set the process that owns a socket to @var{value}, for @code{SIGIO} signals.
-@item FD_CLOEXEC
-The value used to indicate the "close on exec" flag with @code{F_GETFL} or
-@code{F_SETFL}.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} flock file operation
-@deffnx {C Function} scm_flock (file, operation)
-Apply or remove an advisory lock on an open file.
-@var{operation} specifies the action to be done:
-@table @code
-@item LOCK_SH
-Shared lock. More than one process may hold a shared lock
-for a given file at a given time.
-@item LOCK_EX
-Exclusive lock. Only one process may hold an exclusive lock
-for a given file at a given time.
-@item LOCK_UN
-Unlock the file.
-@item LOCK_NB
-Don't block when locking. May be specified by bitwise OR'ing
-it to one of the other operations.
-@end table
-The return value is not specified. @var{file} may be an open
-file descriptor or an open file descriptor port.
-@end deffn
-
-@deffn {Scheme Procedure} select reads writes excepts [secs [usecs]]
-@deffnx {C Function} scm_select (reads, writes, excepts, secs, usecs)
-This procedure has a variety of uses: waiting for the ability
-to provide input, accept output, or the existence of
-exceptional conditions on a collection of ports or file
-descriptors, or waiting for a timeout to occur.
-It also returns if interrupted by a signal.
-
-@var{reads}, @var{writes} and @var{excepts} can be lists or
-vectors, with each member a port or a file descriptor.
-The value returned is a list of three corresponding
-lists or vectors containing only the members which meet the
-specified requirement. The ability of port buffers to
-provide input or accept output is taken into account.
-Ordering of the input lists or vectors is not preserved.
-
-The optional arguments @var{secs} and @var{usecs} specify the
-timeout. Either @var{secs} can be specified alone, as
-either an integer or a real number, or both @var{secs} and
-@var{usecs} can be specified as integers, in which case
-@var{usecs} is an additional timeout expressed in
-microseconds. If @var{secs} is omitted or is @code{#f} then
-select will wait for as long as it takes for one of the other
-conditions to be satisfied.
-
-The scsh version of @code{select} differs as follows:
-Only vectors are accepted for the first three arguments.
-The @var{usecs} argument is not supported.
-Multiple values are returned instead of a list.
-Duplicates in the input vectors appear only once in output.
-An additional @code{select!} interface is provided.
-@end deffn
-
-@node File System
-@section File System
-
-These procedures allow querying and setting file system attributes
-(such as owner,
-permissions, sizes and types of files); deleting, copying, renaming and
-linking files; creating and removing directories and querying their
-contents; syncing the file system and creating special files.
-
-@deffn {Scheme Procedure} access? path how
-@deffnx {C Function} scm_access (path, how)
-Return @code{#t} if @var{path} corresponds to an existing file
-and the current process has the type of access specified by
-@var{how}, otherwise @code{#f}. @var{how} should be specified
-using the values of the variables listed below. Multiple
-values can be combined using a bitwise or, in which case
-@code{#t} will only be returned if all accesses are granted.
-
-Permissions are checked using the real id of the current
-process, not the effective id, although it's the effective id
-which determines whether the access would actually be granted.
-
-@defvar R_OK
-test for read permission.
-@end defvar
-@defvar W_OK
-test for write permission.
-@end defvar
-@defvar X_OK
-test for execute permission.
-@end defvar
-@defvar F_OK
-test for existence of the file.
-@end defvar
-@end deffn
-
-@findex fstat
-@deffn {Scheme Procedure} stat object
-@deffnx {C Function} scm_stat (object)
-Return an object containing various information about the file
-determined by @var{obj}. @var{obj} can be a string containing
-a file name or a port or integer file descriptor which is open
-on a file (in which case @code{fstat} is used as the underlying
-system call).
-
-The object returned by @code{stat} can be passed as a single
-parameter to the following procedures, all of which return
-integers:
-
-@table @code
-@item stat:dev
-The device containing the file.
-@item stat:ino
-The file serial number, which distinguishes this file from all
-other files on the same device.
-@item stat:mode
-The mode of the file. This includes file type information and
-the file permission bits. See @code{stat:type} and
-@code{stat:perms} below.
-@item stat:nlink
-The number of hard links to the file.
-@item stat:uid
-The user ID of the file's owner.
-@item stat:gid
-The group ID of the file.
-@item stat:rdev
-Device ID; this entry is defined only for character or block
-special files.
-@item stat:size
-The size of a regular file in bytes.
-@item stat:atime
-The last access time for the file.
-@item stat:mtime
-The last modification time for the file.
-@item stat:ctime
-The last modification time for the attributes of the file.
-@item stat:blksize
-The optimal block size for reading or writing the file, in
-bytes.
-@item stat:blocks
-The amount of disk space that the file occupies measured in
-units of 512 byte blocks.
-@end table
-
-In addition, the following procedures return the information
-from stat:mode in a more convenient form:
-
-@table @code
-@item stat:type
-A symbol representing the type of file. Possible values are
-regular, directory, symlink, block-special, char-special, fifo,
-socket and unknown
-@item stat:perms
-An integer representing the access permission bits.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} lstat str
-@deffnx {C Function} scm_lstat (str)
-Similar to @code{stat}, but does not follow symbolic links, i.e.,
-it will return information about a symbolic link itself, not the
-file it points to. @var{path} must be a string.
-@end deffn
-
-@deffn {Scheme Procedure} readlink path
-@deffnx {C Function} scm_readlink (path)
-Return the value of the symbolic link named by @var{path} (a
-string), i.e., the file that the link points to.
-@end deffn
-
-@findex fchown
-@findex lchown
-@deffn {Scheme Procedure} chown object owner group
-@deffnx {C Function} scm_chown (object, owner, group)
-Change the ownership and group of the file referred to by @var{object} to
-the integer values @var{owner} and @var{group}. @var{object} can be
-a string containing a file name or, if the platform
-supports fchown, a port or integer file descriptor
-which is open on the file. The return value
-is unspecified.
-
-If @var{object} is a symbolic link, either the
-ownership of the link or the ownership of the referenced file will be
-changed depending on the operating system (lchown is
-unsupported at present). If @var{owner} or @var{group} is specified
-as @code{-1}, then that ID is not changed.
-@end deffn
-
-@findex fchmod
-@deffn {Scheme Procedure} chmod object mode
-@deffnx {C Function} scm_chmod (object, mode)
-Changes the permissions of the file referred to by @var{obj}.
-@var{obj} can be a string containing a file name or a port or integer file
-descriptor which is open on a file (in which case @code{fchmod} is used
-as the underlying system call).
-@var{mode} specifies
-the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} utime pathname [actime [modtime]]
-@deffnx {C Function} scm_utime (pathname, actime, modtime)
-@code{utime} sets the access and modification times for the
-file named by @var{path}. If @var{actime} or @var{modtime} is
-not supplied, then the current time is used. @var{actime} and
-@var{modtime} must be integer time values as returned by the
-@code{current-time} procedure.
-@lisp
-(utime "foo" (- (current-time) 3600))
-@end lisp
-will set the access time to one hour in the past and the
-modification time to the current time.
-@end deffn
-
-@findex unlink
-@deffn {Scheme Procedure} delete-file str
-@deffnx {C Function} scm_delete_file (str)
-Deletes (or "unlinks") the file specified by @var{path}.
-@end deffn
-
-@deffn {Scheme Procedure} copy-file oldfile newfile
-@deffnx {C Function} scm_copy_file (oldfile, newfile)
-Copy the file specified by @var{path-from} to @var{path-to}.
-The return value is unspecified.
-@end deffn
-
-@findex rename
-@deffn {Scheme Procedure} rename-file oldname newname
-@deffnx {C Function} scm_rename (oldname, newname)
-Renames the file specified by @var{oldname} to @var{newname}.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} link oldpath newpath
-@deffnx {C Function} scm_link (oldpath, newpath)
-Creates a new name @var{newpath} in the file system for the
-file named by @var{oldpath}. If @var{oldpath} is a symbolic
-link, the link may or may not be followed depending on the
-system.
-@end deffn
-
-@deffn {Scheme Procedure} symlink oldpath newpath
-@deffnx {C Function} scm_symlink (oldpath, newpath)
-Create a symbolic link named @var{path-to} with the value (i.e., pointing to)
-@var{path-from}. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} mkdir path [mode]
-@deffnx {C Function} scm_mkdir (path, mode)
-Create a new directory named by @var{path}. If @var{mode} is omitted
-then the permissions of the directory file are set using the current
-umask. Otherwise they are set to the decimal value specified with
-@var{mode}. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} rmdir path
-@deffnx {C Function} scm_rmdir (path)
-Remove the existing directory named by @var{path}. The directory must
-be empty for this to succeed. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} opendir dirname
-@deffnx {C Function} scm_opendir (dirname)
-Open the directory specified by @var{path} and return a directory
-stream.
-@end deffn
-
-@deffn {Scheme Procedure} directory-stream? obj
-@deffnx {C Function} scm_directory_stream_p (obj)
-Return a boolean indicating whether @var{object} is a directory
-stream as returned by @code{opendir}.
-@end deffn
-
-@deffn {Scheme Procedure} readdir port
-@deffnx {C Function} scm_readdir (port)
-Return (as a string) the next directory entry from the directory stream
-@var{stream}. If there is no remaining entry to be read then the
-end of file object is returned.
-@end deffn
-
-@deffn {Scheme Procedure} rewinddir port
-@deffnx {C Function} scm_rewinddir (port)
-Reset the directory port @var{stream} so that the next call to
-@code{readdir} will return the first directory entry.
-@end deffn
-
-@deffn {Scheme Procedure} closedir port
-@deffnx {C Function} scm_closedir (port)
-Close the directory stream @var{stream}.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} sync
-@deffnx {C Function} scm_sync ()
-Flush the operating system disk buffers.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} mknod path type perms dev
-@deffnx {C Function} scm_mknod (path, type, perms, dev)
-Creates a new special file, such as a file corresponding to a device.
-@var{path} specifies the name of the file. @var{type} should
-be one of the following symbols:
-regular, directory, symlink, block-special, char-special,
-fifo, or socket. @var{perms} (an integer) specifies the file permissions.
-@var{dev} (an integer) specifies which device the special file refers
-to. Its exact interpretation depends on the kind of special file
-being created.
-
-E.g.,
-@lisp
-(mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
-@end lisp
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} tmpnam
-@deffnx {C Function} scm_tmpnam ()
-Return a name in the file system that does not match any
-existing file. However there is no guarantee that another
-process will not create the file after @code{tmpnam} is called.
-Care should be taken if opening the file, e.g., use the
-@code{O_EXCL} open flag or use @code{mkstemp!} instead.
-@end deffn
-
-@deffn {Scheme Procedure} mkstemp! tmpl
-@deffnx {C Function} scm_mkstemp (tmpl)
-Create a new unique file in the file system and returns a new
-buffered port open for reading and writing to the file.
-@var{tmpl} is a string specifying where the file should be
-created: it must end with @code{XXXXXX} and will be changed in
-place to return the name of the temporary file.
-@end deffn
-
-@deffn {Scheme Procedure} dirname filename
-@deffnx {C Function} scm_dirname (filename)
-Return the directory name component of the file name
-@var{filename}. If @var{filename} does not contain a directory
-component, @code{.} is returned.
-@end deffn
-
-@deffn {Scheme Procedure} basename filename [suffix]
-@deffnx {C Function} scm_basename (filename, suffix)
-Return the base name of the file name @var{filename}. The
-base name is the file name without any directory components.
-If @var{suffix} is provided, and is equal to the end of
-@var{basename}, it is removed also.
-@end deffn
-
-
-@node User Information
-@section User Information
-
-The facilities in this section provide an interface to the user and
-group database.
-They should be used with care since they are not reentrant.
-
-The following functions accept an object representing user information
-and return a selected component:
-
-@table @code
-@item passwd:name
-The name of the userid.
-@item passwd:passwd
-The encrypted passwd.
-@item passwd:uid
-The user id number.
-@item passwd:gid
-The group id number.
-@item passwd:gecos
-The full name.
-@item passwd:dir
-The home directory.
-@item passwd:shell
-The login shell.
-@end table
-
-@deffn {Scheme Procedure} getpwuid uid
-Look up an integer userid in the user database.
-@end deffn
-
-@deffn {Scheme Procedure} getpwnam name
-Look up a user name string in the user database.
-@end deffn
-
-@deffn {Scheme Procedure} setpwent
-Initializes a stream used by @code{getpwent} to read from the user database.
-The next use of @code{getpwent} will return the first entry. The
-return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} getpwent
-Return the next entry in the user database, using the stream set by
-@code{setpwent}.
-@end deffn
-
-@deffn {Scheme Procedure} endpwent
-Closes the stream used by @code{getpwent}. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setpw [arg]
-@deffnx {C Function} scm_setpwent (arg)
-If called with a true argument, initialize or reset the password data
-stream. Otherwise, close the stream. The @code{setpwent} and
-@code{endpwent} procedures are implemented on top of this.
-@end deffn
-
-@deffn {Scheme Procedure} getpw [user]
-@deffnx {C Function} scm_getpwuid (user)
-Look up an entry in the user database. @var{obj} can be an integer,
-a string, or omitted, giving the behaviour of getpwuid, getpwnam
-or getpwent respectively.
-@end deffn
-
-The following functions accept an object representing group information
-and return a selected component:
-
-@table @code
-@item group:name
-The group name.
-@item group:passwd
-The encrypted group password.
-@item group:gid
-The group id number.
-@item group:mem
-A list of userids which have this group as a supplementary group.
-@end table
-
-@deffn {Scheme Procedure} getgrgid gid
-Look up an integer group id in the group database.
-@end deffn
-
-@deffn {Scheme Procedure} getgrnam name
-Look up a group name in the group database.
-@end deffn
-
-@deffn {Scheme Procedure} setgrent
-Initializes a stream used by @code{getgrent} to read from the group database.
-The next use of @code{getgrent} will return the first entry.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} getgrent
-Return the next entry in the group database, using the stream set by
-@code{setgrent}.
-@end deffn
-
-@deffn {Scheme Procedure} endgrent
-Closes the stream used by @code{getgrent}.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setgr [arg]
-@deffnx {C Function} scm_setgrent (arg)
-If called with a true argument, initialize or reset the group data
-stream. Otherwise, close the stream. The @code{setgrent} and
-@code{endgrent} procedures are implemented on top of this.
-@end deffn
-
-@deffn {Scheme Procedure} getgr [name]
-@deffnx {C Function} scm_getgrgid (name)
-Look up an entry in the group database. @var{obj} can be an integer,
-a string, or omitted, giving the behaviour of getgrgid, getgrnam
-or getgrent respectively.
-@end deffn
-
-In addition to the accessor procedures for the user database, the
-following shortcut procedures are also available.
-
-@deffn {Scheme Procedure} cuserid
-@deffnx {C Function} scm_cuserid ()
-Return a string containing a user name associated with the
-effective user id of the process. Return @code{#f} if this
-information cannot be obtained.
-@end deffn
-
-@deffn {Scheme Procedure} getlogin
-@deffnx {C Function} scm_getlogin ()
-Return a string containing the name of the user logged in on
-the controlling terminal of the process, or @code{#f} if this
-information cannot be obtained.
-@end deffn
-
-
-@node Time
-@section Time
-
-@deffn {Scheme Procedure} current-time
-@deffnx {C Function} scm_current_time ()
-Return the number of seconds since 1970-01-01 00:00:00 UTC,
-excluding leap seconds.
-@end deffn
-
-@deffn {Scheme Procedure} gettimeofday
-@deffnx {C Function} scm_gettimeofday ()
-Return a pair containing the number of seconds and microseconds
-since 1970-01-01 00:00:00 UTC, excluding leap seconds. Note:
-whether true microsecond resolution is available depends on the
-operating system.
-@end deffn
-
-The following procedures either accept an object representing a broken down
-time and return a selected component, or accept an object representing
-a broken down time and a value and set the component to the value.
-The numbers in parentheses give the usual range.
-
-@table @code
-@item tm:sec, set-tm:sec
-Seconds (0-59).
-@item tm:min, set-tm:min
-Minutes (0-59).
-@item tm:hour, set-tm:hour
-Hours (0-23).
-@item tm:mday, set-tm:mday
-Day of the month (1-31).
-@item tm:mon, set-tm:mon
-Month (0-11).
-@item tm:year, set-tm:year
-Year (70-), the year minus 1900.
-@item tm:wday, set-tm:wday
-Day of the week (0-6) with Sunday represented as 0.
-@item tm:yday, set-tm:yday
-Day of the year (0-364, 365 in leap years).
-@item tm:isdst, set-tm:isdst
-Daylight saving indicator (0 for "no", greater than 0 for "yes", less than
-0 for "unknown").
-@item tm:gmtoff, set-tm:gmtoff
-Time zone offset in seconds west of UTC (-46800 to 43200).
-@item tm:zone, set-tm:zone
-Time zone label (a string), not necessarily unique.
-@end table
-
-@deffn {Scheme Procedure} localtime time [zone]
-@deffnx {C Function} scm_localtime (time, zone)
-Return an object representing the broken down components of
-@var{time}, an integer like the one returned by
-@code{current-time}. The time zone for the calculation is
-optionally specified by @var{zone} (a string), otherwise the
-@code{TZ} environment variable or the system default is used.
-@end deffn
-
-@deffn {Scheme Procedure} gmtime time
-@deffnx {C Function} scm_gmtime (time)
-Return an object representing the broken down components of
-@var{time}, an integer like the one returned by
-@code{current-time}. The values are calculated for UTC.
-@end deffn
-
-@deffn {Scheme Procedure} mktime sbd_time [zone]
-@deffnx {C Function} scm_mktime (sbd_time, zone)
-@var{bd-time} is an object representing broken down time and @code{zone}
-is an optional time zone specifier (otherwise the TZ environment variable
-or the system default is used).
-
-Returns a pair: the car is a corresponding
-integer time value like that returned
-by @code{current-time}; the cdr is a broken down time object, similar to
-as @var{bd-time} but with normalized values.
-@end deffn
-
-@deffn {Scheme Procedure} tzset
-@deffnx {C Function} scm_tzset ()
-Initialize the timezone from the TZ environment variable
-or the system default. It's not usually necessary to call this procedure
-since it's done automatically by other procedures that depend on the
-timezone.
-@end deffn
-
-@deffn {Scheme Procedure} strftime format stime
-@deffnx {C Function} scm_strftime (format, stime)
-Formats a time specification @var{time} using @var{template}. @var{time}
-is an object with time components in the form returned by @code{localtime}
-or @code{gmtime}. @var{template} is a string which can include formatting
-specifications introduced by a @code{%} character. The formatting of
-month and day names is dependent on the current locale. The value returned
-is the formatted string.
-@xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.)
-@end deffn
-
-@deffn {Scheme Procedure} strptime format string
-@deffnx {C Function} scm_strptime (format, string)
-Performs the reverse action to @code{strftime}, parsing
-@var{string} according to the specification supplied in
-@var{template}. The interpretation of month and day names is
-dependent on the current locale. The value returned is a pair.
-The car has an object with time components
-in the form returned by @code{localtime} or @code{gmtime},
-but the time zone components
-are not usefully set.
-The cdr reports the number of characters from @var{string}
-which were used for the conversion.
-@end deffn
-
-@defvar internal-time-units-per-second
-The value of this variable is the number of time units per second
-reported by the following procedures.
-@end defvar
-
-@deffn {Scheme Procedure} times
-@deffnx {C Function} scm_times ()
-Return an object with information about real and processor
-time. The following procedures accept such an object as an
-argument and return a selected component:
-
-@table @code
-@item tms:clock
-The current real time, expressed as time units relative to an
-arbitrary base.
-@item tms:utime
-The CPU time units used by the calling process.
-@item tms:stime
-The CPU time units used by the system on behalf of the calling
-process.
-@item tms:cutime
-The CPU time units used by terminated child processes of the
-calling process, whose status has been collected (e.g., using
-@code{waitpid}).
-@item tms:cstime
-Similarly, the CPU times units used by the system on behalf of
-terminated child processes.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} get-internal-real-time
-@deffnx {C Function} scm_get_internal_real_time ()
-Return the number of time units since the interpreter was
-started.
-@end deffn
-
-@deffn {Scheme Procedure} get-internal-run-time
-@deffnx {C Function} scm_get_internal_run_time ()
-Return the number of time units of processor time used by the
-interpreter. Both @emph{system} and @emph{user} time are
-included but subprocesses are not.
-@end deffn
-
-@node Runtime Environment
-@section Runtime Environment
-
-@deffn {Scheme Procedure} program-arguments
-@deffnx {Scheme Procedure} command-line
-@deffnx {C Function} scm_program_arguments ()
-Return the list of command line arguments passed to Guile, as a list of
-strings. The list includes the invoked program name, which is usually
-@code{"guile"}, but excludes switches and parameters for command line
-options like @code{-e} and @code{-l}.
-@end deffn
-
-@deffn {Scheme Procedure} getenv nam
-@deffnx {C Function} scm_getenv (nam)
-Looks up the string @var{name} in the current environment. The return
-value is @code{#f} unless a string of the form @code{NAME=VALUE} is
-found, in which case the string @code{VALUE} is returned.
-@end deffn
-
-@c begin (scm-doc-string "boot-9.scm" "setenv")
-@deffn {Scheme Procedure} setenv name value
-Modifies the environment of the current process, which is
-also the default environment inherited by child processes.
-
-If @var{value} is @code{#f}, then @var{name} is removed from the
-environment. Otherwise, the string @var{name}=@var{value} is added
-to the environment, replacing any existing string with name matching
-@var{name}.
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} environ [env]
-@deffnx {C Function} scm_environ (env)
-If @var{env} is omitted, return the current environment (in the
-Unix sense) as a list of strings. Otherwise set the current
-environment, which is also the default environment for child
-processes, to the supplied list of strings. Each member of
-@var{env} should be of the form @code{NAME=VALUE} and values of
-@code{NAME} should not be duplicated. If @var{env} is supplied
-then the return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} putenv str
-@deffnx {C Function} scm_putenv (str)
-Modifies the environment of the current process, which is
-also the default environment inherited by child processes.
-
-If @var{string} is of the form @code{NAME=VALUE} then it will be written
-directly into the environment, replacing any existing environment string
-with
-name matching @code{NAME}. If @var{string} does not contain an equal
-sign, then any existing string with name matching @var{string} will
-be removed.
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setenv name value
-Give the environment variable @var{name} the value @var{value}. The
-name can not contain a @samp{=} character.
-@end deffn
-
-@deffn {Scheme Procedure} unsetenv name
-Remove variable @var{name} from the environment. The
-name can not contain a @samp{=} character.
-@end deffn
-
-@node Processes
-@section Processes
-
-@findex cd
-@deffn {Scheme Procedure} chdir str
-@deffnx {C Function} scm_chdir (str)
-Change the current working directory to @var{path}.
-The return value is unspecified.
-@end deffn
-
-@findex pwd
-@deffn {Scheme Procedure} getcwd
-@deffnx {C Function} scm_getcwd ()
-Return the name of the current working directory.
-@end deffn
-
-@deffn {Scheme Procedure} umask [mode]
-@deffnx {C Function} scm_umask (mode)
-If @var{mode} is omitted, returns a decimal number representing the current
-file creation mask. Otherwise the file creation mask is set to
-@var{mode} and the previous value is returned.
-
-E.g., @code{(umask #o022)} sets the mask to octal 22, decimal 18.
-@end deffn
-
-@deffn {Scheme Procedure} chroot path
-@deffnx {C Function} scm_chroot (path)
-Change the root directory to that specified in @var{path}.
-This directory will be used for path names beginning with
-@file{/}. The root directory is inherited by all children
-of the current process. Only the superuser may change the
-root directory.
-@end deffn
-
-@deffn {Scheme Procedure} getpid
-@deffnx {C Function} scm_getpid ()
-Return an integer representing the current process ID.
-@end deffn
-
-@deffn {Scheme Procedure} getgroups
-@deffnx {C Function} scm_getgroups ()
-Return a vector of integers representing the current
-supplementary group IDs.
-@end deffn
-
-@deffn {Scheme Procedure} getppid
-@deffnx {C Function} scm_getppid ()
-Return an integer representing the process ID of the parent
-process.
-@end deffn
-
-@deffn {Scheme Procedure} getuid
-@deffnx {C Function} scm_getuid ()
-Return an integer representing the current real user ID.
-@end deffn
-
-@deffn {Scheme Procedure} getgid
-@deffnx {C Function} scm_getgid ()
-Return an integer representing the current real group ID.
-@end deffn
-
-@deffn {Scheme Procedure} geteuid
-@deffnx {C Function} scm_geteuid ()
-Return an integer representing the current effective user ID.
-If the system does not support effective IDs, then the real ID
-is returned. @code{(feature? 'EIDs)} reports whether the
-system supports effective IDs.
-@end deffn
-
-@deffn {Scheme Procedure} getegid
-@deffnx {C Function} scm_getegid ()
-Return an integer representing the current effective group ID.
-If the system does not support effective IDs, then the real ID
-is returned. @code{(feature? 'EIDs)} reports whether the
-system supports effective IDs.
-@end deffn
-
-@deffn {Scheme Procedure} setuid id
-@deffnx {C Function} scm_setuid (id)
-Sets both the real and effective user IDs to the integer @var{id}, provided
-the process has appropriate privileges.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setgid id
-@deffnx {C Function} scm_setgid (id)
-Sets both the real and effective group IDs to the integer @var{id}, provided
-the process has appropriate privileges.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} seteuid id
-@deffnx {C Function} scm_seteuid (id)
-Sets the effective user ID to the integer @var{id}, provided the process
-has appropriate privileges. If effective IDs are not supported, the
-real ID is set instead -- @code{(feature? 'EIDs)} reports whether the
-system supports effective IDs.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setegid id
-@deffnx {C Function} scm_setegid (id)
-Sets the effective group ID to the integer @var{id}, provided the process
-has appropriate privileges. If effective IDs are not supported, the
-real ID is set instead -- @code{(feature? 'EIDs)} reports whether the
-system supports effective IDs.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} getpgrp
-@deffnx {C Function} scm_getpgrp ()
-Return an integer representing the current process group ID.
-This is the POSIX definition, not BSD.
-@end deffn
-
-@deffn {Scheme Procedure} setpgid pid pgid
-@deffnx {C Function} scm_setpgid (pid, pgid)
-Move the process @var{pid} into the process group @var{pgid}. @var{pid} or
-@var{pgid} must be integers: they can be zero to indicate the ID of the
-current process.
-Fails on systems that do not support job control.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setsid
-@deffnx {C Function} scm_setsid ()
-Creates a new session. The current process becomes the session leader
-and is put in a new process group. The process will be detached
-from its controlling terminal if it has one.
-The return value is an integer representing the new process group ID.
-@end deffn
-
-@deffn {Scheme Procedure} waitpid pid [options]
-@deffnx {C Function} scm_waitpid (pid, options)
-This procedure collects status information from a child process which
-has terminated or (optionally) stopped. Normally it will
-suspend the calling process until this can be done. If more than one
-child process is eligible then one will be chosen by the operating system.
-
-The value of @var{pid} determines the behaviour:
-
-@table @r
-@item @var{pid} greater than 0
-Request status information from the specified child process.
-@item @var{pid} equal to -1 or WAIT_ANY
-Request status information for any child process.
-@item @var{pid} equal to 0 or WAIT_MYPGRP
-Request status information for any child process in the current process
-group.
-@item @var{pid} less than -1
-Request status information for any child process whose process group ID
-is -@var{PID}.
-@end table
-
-The @var{options} argument, if supplied, should be the bitwise OR of the
-values of zero or more of the following variables:
-
-@defvar WNOHANG
-Return immediately even if there are no child processes to be collected.
-@end defvar
-
-@defvar WUNTRACED
-Report status information for stopped processes as well as terminated
-processes.
-@end defvar
-
-The return value is a pair containing:
-
-@enumerate
-@item
-The process ID of the child process, or 0 if @code{WNOHANG} was
-specified and no process was collected.
-@item
-The integer status value.
-@end enumerate
-@end deffn
-
-The following three
-functions can be used to decode the process status code returned
-by @code{waitpid}.
-
-@deffn {Scheme Procedure} status:exit-val status
-@deffnx {C Function} scm_status_exit_val (status)
-Return the exit status value, as would be set if a process
-ended normally through a call to @code{exit} or @code{_exit},
-if any, otherwise @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} status:term-sig status
-@deffnx {C Function} scm_status_term_sig (status)
-Return the signal number which terminated the process, if any,
-otherwise @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} status:stop-sig status
-@deffnx {C Function} scm_status_stop_sig (status)
-Return the signal number which stopped the process, if any,
-otherwise @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} system [cmd]
-@deffnx {C Function} scm_system (cmd)
-Execute @var{cmd} using the operating system's "command
-processor". Under Unix this is usually the default shell
-@code{sh}. The value returned is @var{cmd}'s exit status as
-returned by @code{waitpid}, which can be interpreted using the
-functions above.
-
-If @code{system} is called without arguments, return a boolean
-indicating whether the command processor is available.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-exit [status]
-@deffnx {C Function} scm_primitive_exit (status)
-Terminate the current process without unwinding the Scheme stack.
-This is would typically be useful after a fork. The exit status
-is @var{status} if supplied, otherwise zero.
-@end deffn
-
-@deffn {Scheme Procedure} execl filename . args
-@deffnx {C Function} scm_execl (filename, args)
-Executes the file named by @var{path} as a new process image.
-The remaining arguments are supplied to the process; from a C program
-they are accessible as the @code{argv} argument to @code{main}.
-Conventionally the first @var{arg} is the same as @var{path}.
-All arguments must be strings.
-
-If @var{arg} is missing, @var{path} is executed with a null
-argument list, which may have system-dependent side-effects.
-
-This procedure is currently implemented using the @code{execv} system
-call, but we call it @code{execl} because of its Scheme calling interface.
-@end deffn
-
-@deffn {Scheme Procedure} execlp filename . args
-@deffnx {C Function} scm_execlp (filename, args)
-Similar to @code{execl}, however if
-@var{filename} does not contain a slash
-then the file to execute will be located by searching the
-directories listed in the @code{PATH} environment variable.
-
-This procedure is currently implemented using the @code{execvp} system
-call, but we call it @code{execlp} because of its Scheme calling interface.
-@end deffn
-
-@deffn {Scheme Procedure} execle filename env . args
-@deffnx {C Function} scm_execle (filename, env, args)
-Similar to @code{execl}, but the environment of the new process is
-specified by @var{env}, which must be a list of strings as returned by the
-@code{environ} procedure.
-
-This procedure is currently implemented using the @code{execve} system
-call, but we call it @code{execle} because of its Scheme calling interface.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-fork
-@deffnx {C Function} scm_fork ()
-Creates a new "child" process by duplicating the current "parent" process.
-In the child the return value is 0. In the parent the return value is
-the integer process ID of the child.
-
-This procedure has been renamed from @code{fork} to avoid a naming conflict
-with the scsh fork.
-@end deffn
-
-@deffn {Scheme Procedure} nice incr
-@deffnx {C Function} scm_nice (incr)
-Increment the priority of the current process by @var{incr}. A higher
-priority value means that the process runs less often.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setpriority which who prio
-@deffnx {C Function} scm_setpriority (which, who, prio)
-Set the scheduling priority of the process, process group
-or user, as indicated by @var{which} and @var{who}. @var{which}
-is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
-or @code{PRIO_USER}, and @var{who} is interpreted relative to
-@var{which} (a process identifier for @code{PRIO_PROCESS},
-process group identifier for @code{PRIO_PGRP}, and a user
-identifier for @code{PRIO_USER}. A zero value of @var{who}
-denotes the current process, process group, or user.
-@var{prio} is a value in the range -20 and 20, the default
-priority is 0; lower priorities cause more favorable
-scheduling. Sets the priority of all of the specified
-processes. Only the super-user may lower priorities.
-The return value is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} getpriority which who
-@deffnx {C Function} scm_getpriority (which, who)
-Return the scheduling priority of the process, process group
-or user, as indicated by @var{which} and @var{who}. @var{which}
-is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
-or @code{PRIO_USER}, and @var{who} is interpreted relative to
-@var{which} (a process identifier for @code{PRIO_PROCESS},
-process group identifier for @code{PRIO_PGRP}, and a user
-identifier for @code{PRIO_USER}. A zero value of @var{who}
-denotes the current process, process group, or user. Return
-the highest priority (lowest numerical value) of any of the
-specified processes.
-@end deffn
-
-
-@node Signals
-@section Signals
-
-Procedures to raise, handle and wait for signals.
-
-@deffn {Scheme Procedure} kill pid sig
-@deffnx {C Function} scm_kill (pid, sig)
-Sends a signal to the specified process or group of processes.
-
-@var{pid} specifies the processes to which the signal is sent:
-
-@table @r
-@item @var{pid} greater than 0
-The process whose identifier is @var{pid}.
-@item @var{pid} equal to 0
-All processes in the current process group.
-@item @var{pid} less than -1
-The process group whose identifier is -@var{pid}
-@item @var{pid} equal to -1
-If the process is privileged, all processes except for some special
-system processes. Otherwise, all processes with the current effective
-user ID.
-@end table
-
-@var{sig} should be specified using a variable corresponding to
-the Unix symbolic name, e.g.,
-
-@defvar SIGHUP
-Hang-up signal.
-@end defvar
-
-@defvar SIGINT
-Interrupt signal.
-@end defvar
-@end deffn
-
-@deffn {Scheme Procedure} raise sig
-@deffnx {C Function} scm_raise (sig)
-Sends a specified signal @var{sig} to the current process, where
-@var{sig} is as described for the kill procedure.
-@end deffn
-
-@deffn {Scheme Procedure} sigaction signum [handler [flags]]
-@deffnx {C Function} scm_sigaction (signum, handler, flags)
-Install or report the signal handler for a specified signal.
-
-@var{signum} is the signal number, which can be specified using the value
-of variables such as @code{SIGINT}.
-
-If @var{action} is omitted, @code{sigaction} returns a pair: the
-CAR is the current
-signal hander, which will be either an integer with the value @code{SIG_DFL}
-(default action) or @code{SIG_IGN} (ignore), or the Scheme procedure which
-handles the signal, or @code{#f} if a non-Scheme procedure handles the
-signal. The CDR contains the current @code{sigaction} flags for the handler.
-
-If @var{action} is provided, it is installed as the new handler for
-@var{signum}. @var{action} can be a Scheme procedure taking one
-argument, or the value of @code{SIG_DFL} (default action) or
-@code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
-was installed before @code{sigaction} was first used. Flags can
-optionally be specified for the new handler (@code{SA_RESTART} will
-always be added if it's available and the system is using restartable
-system calls.) The return value is a pair with information about the
-old handler as described above.
-
-This interface does not provide access to the "signal blocking"
-facility. Maybe this is not needed, since the thread support may
-provide solutions to the problem of consistent access to data
-structures.
-@end deffn
-
-@deffn {Scheme Procedure} restore-signals
-@deffnx {C Function} scm_restore_signals ()
-Return all signal handlers to the values they had before any call to
-@code{sigaction} was made. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} alarm i
-@deffnx {C Function} scm_alarm (i)
-Set a timer to raise a @code{SIGALRM} signal after the specified
-number of seconds (an integer). It's advisable to install a signal
-handler for
-@code{SIGALRM} beforehand, since the default action is to terminate
-the process.
-
-The return value indicates the time remaining for the previous alarm,
-if any. The new value replaces the previous alarm. If there was
-no previous alarm, the return value is zero.
-@end deffn
-
-@deffn {Scheme Procedure} pause
-@deffnx {C Function} scm_pause ()
-Pause the current process (thread?) until a signal arrives whose
-action is to either terminate the current process or invoke a
-handler procedure. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} sleep i
-@deffnx {C Function} scm_sleep (i)
-Wait for the given number of seconds (an integer) or until a signal
-arrives. The return value is zero if the time elapses or the number
-of seconds remaining otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} usleep i
-@deffnx {C Function} scm_usleep (i)
-Sleep for I microseconds. @code{usleep} is not available on
-all platforms.
-@end deffn
-
-@deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
-@deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds)
-Set the timer specified by @var{which_timer} according to the given
-@var{interval_seconds}, @var{interval_microseconds},
-@var{value_seconds}, and @var{value_microseconds} values.
-
-Return information about the timer's previous setting.
-Errors are handled as described in the guile info pages under ``POSIX
-Interface Conventions''.
-
-The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
-and @code{ITIMER_PROF}.
-
-The return value will be a list of two cons pairs representing the
-current state of the given timer. The first pair is the seconds and
-microseconds of the timer @code{it_interval}, and the second pair is
-the seconds and microseconds of the timer @code{it_value}.
-@end deffn
-
-@deffn {Scheme Procedure} getitimer which_timer
-@deffnx {C Function} scm_getitimer (which_timer)
-Return information about the timer specified by @var{which_timer}
-Errors are handled as described in the guile info pages under ``POSIX
-Interface Conventions''.
-
-The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
-and @code{ITIMER_PROF}.
-
-The return value will be a list of two cons pairs representing the
-current state of the given timer. The first pair is the seconds and
-microseconds of the timer @code{it_interval}, and the second pair is
-the seconds and microseconds of the timer @code{it_value}.
-@end deffn
-
-
-@node Terminals and Ptys
-@section Terminals and Ptys
-
-@deffn {Scheme Procedure} isatty? port
-@deffnx {C Function} scm_isatty_p (port)
-Return @code{#t} if @var{port} is using a serial non--file
-device, otherwise @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} ttyname port
-@deffnx {C Function} scm_ttyname (port)
-Return a string with the name of the serial terminal device
-underlying @var{port}.
-@end deffn
-
-@deffn {Scheme Procedure} ctermid
-@deffnx {C Function} scm_ctermid ()
-Return a string containing the file name of the controlling
-terminal for the current process.
-@end deffn
-
-@deffn {Scheme Procedure} tcgetpgrp port
-@deffnx {C Function} scm_tcgetpgrp (port)
-Return the process group ID of the foreground process group
-associated with the terminal open on the file descriptor
-underlying @var{port}.
-
-If there is no foreground process group, the return value is a
-number greater than 1 that does not match the process group ID
-of any existing process group. This can happen if all of the
-processes in the job that was formerly the foreground job have
-terminated, and no other job has yet been moved into the
-foreground.
-@end deffn
-
-@deffn {Scheme Procedure} tcsetpgrp port pgid
-@deffnx {C Function} scm_tcsetpgrp (port, pgid)
-Set the foreground process group ID for the terminal used by the file
-descriptor underlying @var{port} to the integer @var{pgid}.
-The calling process
-must be a member of the same session as @var{pgid} and must have the same
-controlling terminal. The return value is unspecified.
-@end deffn
-
-@node Pipes
-@section Pipes
-
-The following procedures provide an interface to the @code{popen} and
-@code{pclose} system routines. The code is in a separate "popen"
-module:
-
-@smalllisp
-(use-modules (ice-9 popen))
-@end smalllisp
-
-@findex popen
-@deffn {Scheme Procedure} open-pipe command modes
-Executes the shell command @var{command} (a string) in a subprocess.
-A pipe to the process is created and returned. @var{modes} specifies
-whether an input or output pipe to the process is created: it should
-be the value of @code{OPEN_READ} or @code{OPEN_WRITE}.
-@end deffn
-
-@deffn {Scheme Procedure} open-input-pipe command
-Equivalent to @code{open-pipe} with mode @code{OPEN_READ}.
-@end deffn
-
-@deffn {Scheme Procedure} open-output-pipe command
-Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}.
-@end deffn
-
-@findex pclose
-@deffn {Scheme Procedure} close-pipe port
-Closes the pipe created by @code{open-pipe}, then waits for the process
-to terminate and returns its status value, @xref{Processes, waitpid}, for
-information on how to interpret this value.
-
-@code{close-port} (@pxref{Closing, close-port}) can also be used to
-close a pipe, but doesn't return the status.
-@end deffn
-
-@node Networking
-@section Networking
-
-@menu
-* Network Address Conversion::
-* Network Databases::
-* Network Sockets and Communication::
-@end menu
-
-@node Network Address Conversion
-@subsection Network Address Conversion
-
-This section describes procedures which convert internet addresses
-between numeric and string formats.
-
-@subsubsection IPv4 Address Conversion
-
-@deffn {Scheme Procedure} inet-aton address
-@deffnx {C Function} scm_inet_aton (address)
-Convert an IPv4 Internet address from printable string
-(dotted decimal notation) to an integer. E.g.,
-
-@lisp
-(inet-aton "127.0.0.1") @result{} 2130706433
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} inet-ntoa inetid
-@deffnx {C Function} scm_inet_ntoa (inetid)
-Convert an IPv4 Internet address to a printable
-(dotted decimal notation) string. E.g.,
-
-@lisp
-(inet-ntoa 2130706433) @result{} "127.0.0.1"
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} inet-netof address
-@deffnx {C Function} scm_inet_netof (address)
-Return the network number part of the given IPv4
-Internet address. E.g.,
-
-@lisp
-(inet-netof 2130706433) @result{} 127
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} inet-lnaof address
-@deffnx {C Function} scm_lnaof (address)
-Return the local-address-with-network part of the given
-IPv4 Internet address, using the obsolete class A/B/C system.
-E.g.,
-
-@lisp
-(inet-lnaof 2130706433) @result{} 1
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} inet-makeaddr net lna
-@deffnx {C Function} scm_inet_makeaddr (net, lna)
-Make an IPv4 Internet address by combining the network number
-@var{net} with the local-address-within-network number
-@var{lna}. E.g.,
-
-@lisp
-(inet-makeaddr 127 1) @result{} 2130706433
-@end lisp
-@end deffn
-
-@subsubsection IPv6 Address Conversion
-
-@deffn {Scheme Procedure} inet-ntop family address
-@deffnx {C Function} scm_inet_ntop (family, address)
-Convert a network address into a printable string.
-Note that unlike the C version of this function,
-the input is an integer with normal host byte ordering.
-@var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
-
-@lisp
-(inet-ntop AF_INET 2130706433) @result{} "127.0.0.1"
-(inet-ntop AF_INET6 (- (expt 2 128) 1)) @result{}
-ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} inet-pton family address
-@deffnx {C Function} scm_inet_pton (family, address)
-Convert a string containing a printable network address to
-an integer address. Note that unlike the C version of this
-function,
-the result is an integer with normal host byte ordering.
-@var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
-
-@lisp
-(inet-pton AF_INET "127.0.0.1") @result{} 2130706433
-(inet-pton AF_INET6 "::1") @result{} 1
-@end lisp
-@end deffn
-
-
-@node Network Databases
-@subsection Network Databases
-
-This section describes procedures which query various network databases.
-Care should be taken when using the database routines since they are not
-reentrant.
-
-@subsubsection The Host Database
-
-A @dfn{host object} is a structure that represents what is known about a
-network host, and is the usual way of representing a system's network
-identity inside software.
-
-The following functions accept a host object and return a selected
-component:
-
-@deffn {Scheme Procedure} hostent:name host
-The "official" hostname for @var{host}.
-@end deffn
-@deffn {Scheme Procedure} hostent:aliases host
-A list of aliases for @var{host}.
-@end deffn
-@deffn {Scheme Procedure} hostent:addrtype host
-The host address type. For hosts with Internet addresses, this will
-return @code{AF_INET}.
-@end deffn
-@deffn {Scheme Procedure} hostent:length host
-The length of each address for @var{host}, in bytes.
-@end deffn
-@deffn {Scheme Procedure} hostent:addr-list host
-The list of network addresses associated with @var{host}.
-@end deffn
-
-The following procedures are used to search the host database:
-
-@deffn {Scheme Procedure} gethost [host]
-@deffnx {Scheme Procedure} gethostbyname hostname
-@deffnx {Scheme Procedure} gethostbyaddr address
-@deffnx {C Function} scm_gethost (host)
-Look up a host by name or address, returning a host object. The
-@code{gethost} procedure will accept either a string name or an integer
-address; if given no arguments, it behaves like @code{gethostent} (see
-below). If a name or address is supplied but the address can not be
-found, an error will be thrown to one of the keys:
-@code{host-not-found}, @code{try-again}, @code{no-recovery} or
-@code{no-data}, corresponding to the equivalent @code{h_error} values.
-Unusual conditions may result in errors thrown to the
-@code{system-error} or @code{misc_error} keys.
-@end deffn
-
-The following procedures may be used to step through the host
-database from beginning to end.
-
-@deffn {Scheme Procedure} sethostent [stayopen]
-Initialize an internal stream from which host objects may be read. This
-procedure must be called before any calls to @code{gethostent}, and may
-also be called afterward to reset the host entry stream. If
-@var{stayopen} is supplied and is not @code{#f}, the database is not
-closed by subsequent @code{gethostbyname} or @code{gethostbyaddr} calls,
-possibly giving an efficiency gain.
-@end deffn
-
-@deffn {Scheme Procedure} gethostent
-Return the next host object from the host database, or @code{#f} if
-there are no more hosts to be found (or an error has been encountered).
-This procedure may not be used before @code{sethostent} has been called.
-@end deffn
-
-@deffn {Scheme Procedure} endhostent
-Close the stream used by @code{gethostent}. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} sethost [stayopen]
-@deffnx {C Function} scm_sethost (stayopen)
-If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
-Otherwise it is equivalent to @code{sethostent stayopen}.
-@end deffn
-@subsubsection The Network Database
-
-The following functions accept an object representing a network
-and return a selected component:
-
-@deffn {Scheme Procedure} netent:name net
-The "official" network name.
-@end deffn
-@deffn {Scheme Procedure} netent:aliases net
-A list of aliases for the network.
-@end deffn
-@deffn {Scheme Procedure} netent:addrtype net
-The type of the network number. Currently, this returns only
-@code{AF_INET}.
-@end deffn
-@deffn {Scheme Procedure} netent:net net
-The network number.
-@end deffn
-
-The following procedures are used to search the network database:
-
-@deffn {Scheme Procedure} getnet [net]
-@deffnx {Scheme Procedure} getnetbyname net-name
-@deffnx {Scheme Procedure} getnetbyaddr net-number
-@deffnx {C Function} scm_getnet (net)
-Look up a network by name or net number in the network database. The
-@var{net-name} argument must be a string, and the @var{net-number}
-argument must be an integer. @code{getnet} will accept either type of
-argument, behaving like @code{getnetent} (see below) if no arguments are
-given.
-@end deffn
-
-The following procedures may be used to step through the network
-database from beginning to end.
-
-@deffn {Scheme Procedure} setnetent [stayopen]
-Initialize an internal stream from which network objects may be read. This
-procedure must be called before any calls to @code{getnetent}, and may
-also be called afterward to reset the net entry stream. If
-@var{stayopen} is supplied and is not @code{#f}, the database is not
-closed by subsequent @code{getnetbyname} or @code{getnetbyaddr} calls,
-possibly giving an efficiency gain.
-@end deffn
-
-@deffn {Scheme Procedure} getnetent
-Return the next entry from the network database.
-@end deffn
-
-@deffn {Scheme Procedure} endnetent
-Close the stream used by @code{getnetent}. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setnet [stayopen]
-@deffnx {C Function} scm_setnet (stayopen)
-If @var{stayopen} is omitted, this is equivalent to @code{endnetent}.
-Otherwise it is equivalent to @code{setnetent stayopen}.
-@end deffn
-
-@subsubsection The Protocol Database
-
-The following functions accept an object representing a protocol
-and return a selected component:
-
-@deffn {Scheme Procedure} protoent:name protocol
-The "official" protocol name.
-@end deffn
-@deffn {Scheme Procedure} protoent:aliases protocol
-A list of aliases for the protocol.
-@end deffn
-@deffn {Scheme Procedure} protoent:proto protocol
-The protocol number.
-@end deffn
-
-The following procedures are used to search the protocol database:
-
-@deffn {Scheme Procedure} getproto [protocol]
-@deffnx {Scheme Procedure} getprotobyname name
-@deffnx {Scheme Procedure} getprotobynumber number
-@deffnx {C Function} scm_getproto (protocol)
-Look up a network protocol by name or by number. @code{getprotobyname}
-takes a string argument, and @code{getprotobynumber} takes an integer
-argument. @code{getproto} will accept either type, behaving like
-@code{getprotoent} (see below) if no arguments are supplied.
-@end deffn
-
-The following procedures may be used to step through the protocol
-database from beginning to end.
-
-@deffn {Scheme Procedure} setprotoent [stayopen]
-Initialize an internal stream from which protocol objects may be read. This
-procedure must be called before any calls to @code{getprotoent}, and may
-also be called afterward to reset the protocol entry stream. If
-@var{stayopen} is supplied and is not @code{#f}, the database is not
-closed by subsequent @code{getprotobyname} or @code{getprotobynumber} calls,
-possibly giving an efficiency gain.
-@end deffn
-
-@deffn {Scheme Procedure} getprotoent
-Return the next entry from the protocol database.
-@end deffn
-
-@deffn {Scheme Procedure} endprotoent
-Close the stream used by @code{getprotoent}. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setproto [stayopen]
-@deffnx {C Function} scm_setproto (stayopen)
-If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}.
-Otherwise it is equivalent to @code{setprotoent stayopen}.
-@end deffn
-
-@subsubsection The Service Database
-
-The following functions accept an object representing a service
-and return a selected component:
-
-@deffn {Scheme Procedure} servent:name serv
-The "official" name of the network service.
-@end deffn
-@deffn {Scheme Procedure} servent:aliases serv
-A list of aliases for the network service.
-@end deffn
-@deffn {Scheme Procedure} servent:port serv
-The Internet port used by the service.
-@end deffn
-@deffn {Scheme Procedure} servent:proto serv
-The protocol used by the service. A service may be listed many times
-in the database under different protocol names.
-@end deffn
-
-The following procedures are used to search the service database:
-
-@deffn {Scheme Procedure} getserv [name [protocol]]
-@deffnx {Scheme Procedure} getservbyname name protocol
-@deffnx {Scheme Procedure} getservbyport port protocol
-@deffnx {C Function} scm_getserv (name, protocol)
-Look up a network service by name or by service number, and return a
-network service object. The @var{protocol} argument specifies the name
-of the desired protocol; if the protocol found in the network service
-database does not match this name, a system error is signalled.
-
-The @code{getserv} procedure will take either a service name or number
-as its first argument; if given no arguments, it behaves like
-@code{getservent} (see below).
-@end deffn
-
-The following procedures may be used to step through the service
-database from beginning to end.
-
-@deffn {Scheme Procedure} setservent [stayopen]
-Initialize an internal stream from which service objects may be read. This
-procedure must be called before any calls to @code{getservent}, and may
-also be called afterward to reset the service entry stream. If
-@var{stayopen} is supplied and is not @code{#f}, the database is not
-closed by subsequent @code{getservbyname} or @code{getservbyport} calls,
-possibly giving an efficiency gain.
-@end deffn
-
-@deffn {Scheme Procedure} getservent
-Return the next entry from the services database.
-@end deffn
-
-@deffn {Scheme Procedure} endservent
-Close the stream used by @code{getservent}. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setserv [stayopen]
-@deffnx {C Function} scm_setserv (stayopen)
-If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
-Otherwise it is equivalent to @code{setservent stayopen}.
-@end deffn
-
-@node Network Sockets and Communication
-@subsection Network Sockets and Communication
-
-Socket ports can be created using @code{socket} and @code{socketpair}.
-The ports are initially unbuffered, to make reading and writing to the
-same port more reliable. A buffer can be added to the port using
-@code{setvbuf}, @xref{Ports and File Descriptors}.
-
-The convention used for "host" vs "network" addresses is that addresses
-are always held in host order at the Scheme level. The procedures in
-this section automatically convert between host and network order when
-required. The arguments and return values are thus in host order.
-
-@deffn {Scheme Procedure} socket family style proto
-@deffnx {C Function} scm_socket (family, style, proto)
-Return a new socket port of the type specified by @var{family},
-@var{style} and @var{proto}. All three parameters are
-integers. Supported values for @var{family} are
-@code{AF_UNIX}, @code{AF_INET} and @code{AF_INET6}.
-Typical values for @var{style} are @code{SOCK_STREAM},
-@code{SOCK_DGRAM} and @code{SOCK_RAW}.
-
-@var{proto} can be obtained from a protocol name using
-@code{getprotobyname}. A value of zero specifies the default
-protocol, which is usually right.
-
-A single socket port cannot by used for communication until it
-has been connected to another socket.
-@end deffn
-
-@deffn {Scheme Procedure} socketpair family style proto
-@deffnx {C Function} scm_socketpair (family, style, proto)
-Return a pair of connected (but unnamed) socket ports of the
-type specified by @var{family}, @var{style} and @var{proto}.
-Many systems support only socket pairs of the @code{AF_UNIX}
-family. Zero is likely to be the only meaningful value for
-@var{proto}.
-@end deffn
-
-@deffn {Scheme Procedure} getsockopt sock level optname
-@deffnx {C Function} scm_getsockopt (sock, level, optname)
-Return the value of a particular socket option for the socket
-port @var{sock}. @var{level} is an integer code for type of
-option being requested, e.g., @code{SOL_SOCKET} for
-socket-level options. @var{optname} is an integer code for the
-option required and should be specified using one of the
-symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
-
-The returned value is typically an integer but @code{SO_LINGER}
-returns a pair of integers.
-@end deffn
-
-@deffn {Scheme Procedure} setsockopt sock level optname value
-@deffnx {C Function} scm_setsockopt (sock, level, optname, value)
-Set the value of a particular socket option for the socket
-port @var{sock}. @var{level} is an integer code for type of option
-being set, e.g., @code{SOL_SOCKET} for socket-level options.
-@var{optname} is an
-integer code for the option to set and should be specified using one of
-the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
-@var{value} is the value to which the option should be set. For
-most options this must be an integer, but for @code{SO_LINGER} it must
-be a pair.
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} shutdown sock how
-@deffnx {C Function} scm_shutdown (sock, how)
-Sockets can be closed simply by using @code{close-port}. The
-@code{shutdown} procedure allows reception or transmission on a
-connection to be shut down individually, according to the parameter
-@var{how}:
-
-@table @asis
-@item 0
-Stop receiving data for this socket. If further data arrives, reject it.
-@item 1
-Stop trying to transmit data from this socket. Discard any
-data waiting to be sent. Stop looking for acknowledgement of
-data already sent; don't retransmit it if it is lost.
-@item 2
-Stop both reception and transmission.
-@end table
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} connect sock fam address . args
-@deffnx {C Function} scm_connect (sock, fam, address, args)
-Initiate a connection from a socket using a specified address
-family to the address
-specified by @var{address} and possibly @var{args}.
-The format required for @var{address}
-and @var{args} depends on the family of the socket.
-
-For a socket of family @code{AF_UNIX},
-only @var{address} is specified and must be a string with the
-filename where the socket is to be created.
-
-For a socket of family @code{AF_INET},
-@var{address} must be an integer IPv4 host address and
-@var{args} must be a single integer port number.
-
-For a socket of family @code{AF_INET6},
-@var{address} must be an integer IPv6 host address and
-@var{args} may be up to three integers:
-port [flowinfo] [scope_id],
-where flowinfo and scope_id default to zero.
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} bind sock fam address . args
-@deffnx {C Function} scm_bind (sock, fam, address, args)
-Assign an address to the socket port @var{sock}.
-Generally this only needs to be done for server sockets,
-so they know where to look for incoming connections. A socket
-without an address will be assigned one automatically when it
-starts communicating.
-
-The format of @var{address} and @var{args} depends
-on the family of the socket.
-
-For a socket of family @code{AF_UNIX}, only @var{address}
-is specified and must be a string with the filename where
-the socket is to be created.
-
-For a socket of family @code{AF_INET}, @var{address}
-must be an integer IPv4 address and @var{args}
-must be a single integer port number.
-
-The values of the following variables can also be used for
-@var{address}:
-
-@defvar INADDR_ANY
-Allow connections from any address.
-@end defvar
-
-@defvar INADDR_LOOPBACK
-The address of the local host using the loopback device.
-@end defvar
-
-@defvar INADDR_BROADCAST
-The broadcast address on the local network.
-@end defvar
-
-@defvar INADDR_NONE
-No address.
-@end defvar
-
-For a socket of family @code{AF_INET6}, @var{address}
-must be an integer IPv6 address and @var{args}
-may be up to three integers:
-port [flowinfo] [scope_id],
-where flowinfo and scope_id default to zero.
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} listen sock backlog
-@deffnx {C Function} scm_listen (sock, backlog)
-Enable @var{sock} to accept connection
-requests. @var{backlog} is an integer specifying
-the maximum length of the queue for pending connections.
-If the queue fills, new clients will fail to connect until
-the server calls @code{accept} to accept a connection from
-the queue.
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} accept sock
-@deffnx {C Function} scm_accept (sock)
-Accept a connection on a bound, listening socket.
-If there
-are no pending connections in the queue, wait until
-one is available unless the non-blocking option has been
-set on the socket.
-
-The return value is a
-pair in which the @emph{car} is a new socket port for the
-connection and
-the @emph{cdr} is an object with address information about the
-client which initiated the connection.
-
-@var{sock} does not become part of the
-connection and will continue to accept new requests.
-@end deffn
-
-The following functions take a socket address object, as returned
-by @code{accept} and other procedures, and return a selected component.
-
-@table @code
-@item sockaddr:fam
-The socket family, typically equal to the value of @code{AF_UNIX} or
-@code{AF_INET}.
-@item sockaddr:path
-If the socket family is @code{AF_UNIX}, returns the path of the
-filename the socket is based on.
-@item sockaddr:addr
-If the socket family is @code{AF_INET}, returns the Internet host
-address.
-@item sockaddr:port
-If the socket family is @code{AF_INET}, returns the Internet port
-number.
-@end table
-
-@deffn {Scheme Procedure} getsockname sock
-@deffnx {C Function} scm_getsockname (sock)
-Return the address of @var{sock}, in the same form as the
-object returned by @code{accept}. On many systems the address
-of a socket in the @code{AF_FILE} namespace cannot be read.
-@end deffn
-
-@deffn {Scheme Procedure} getpeername sock
-@deffnx {C Function} scm_getpeername (sock)
-Return the address that @var{sock}
-is connected to, in the same form as the object returned by
-@code{accept}. On many systems the address of a socket in the
-@code{AF_FILE} namespace cannot be read.
-@end deffn
-
-@deffn {Scheme Procedure} recv! sock buf [flags]
-@deffnx {C Function} scm_recv (sock, buf, flags)
-Receive data from a socket port.
-@var{sock} must already
-be bound to the address from which data is to be received.
-@var{buf} is a string into which
-the data will be written. The size of @var{buf} limits
-the amount of
-data which can be received: in the case of packet
-protocols, if a packet larger than this limit is encountered
-then some data
-will be irrevocably lost.
-
-The optional @var{flags} argument is a value or
-bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
-
-The value returned is the number of bytes read from the
-socket.
-
-Note that the data is read directly from the socket file
-descriptor:
-any unread buffered port data is ignored.
-@end deffn
-
-@deffn {Scheme Procedure} send sock message [flags]
-@deffnx {C Function} scm_send (sock, message, flags)
-Transmit the string @var{message} on a socket port @var{sock}.
-@var{sock} must already be bound to a destination address. The
-value returned is the number of bytes transmitted --
-it's possible for
-this to be less than the length of @var{message}
-if the socket is
-set to be non-blocking. The optional @var{flags} argument
-is a value or
-bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
-
-Note that the data is written directly to the socket
-file descriptor:
-any unflushed buffered port data is ignored.
-@end deffn
-
-@deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]]
-@deffnx {C Function} scm_recvfrom (sock, str, flags, start, end)
-Return data from the socket port @var{sock} and also
-information about where the data was received from.
-@var{sock} must already be bound to the address from which
-data is to be received. @code{str}, is a string into which the
-data will be written. The size of @var{str} limits the amount
-of data which can be received: in the case of packet protocols,
-if a packet larger than this limit is encountered then some
-data will be irrevocably lost.
-
-The optional @var{flags} argument is a value or bitwise OR of
-@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
-
-The value returned is a pair: the @emph{car} is the number of
-bytes read from the socket and the @emph{cdr} an address object
-in the same form as returned by @code{accept}. The address
-will given as @code{#f} if not available, as is usually the
-case for stream sockets.
-
-The @var{start} and @var{end} arguments specify a substring of
-@var{str} to which the data should be written.
-
-Note that the data is read directly from the socket file
-descriptor: any unread buffered port data is ignored.
-@end deffn
-
-@deffn {Scheme Procedure} sendto sock message fam address . args_and_flags
-@deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags)
-Transmit the string @var{message} on the socket port
-@var{sock}. The
-destination address is specified using the @var{fam},
-@var{address} and
-@var{args_and_flags} arguments, in a similar way to the
-@code{connect} procedure. @var{args_and_flags} contains
-the usual connection arguments optionally followed by
-a flags argument, which is a value or
-bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
-
-The value returned is the number of bytes transmitted --
-it's possible for
-this to be less than the length of @var{message} if the
-socket is
-set to be non-blocking.
-Note that the data is written directly to the socket
-file descriptor:
-any unflushed buffered port data is ignored.
-@end deffn
-
-The following functions can be used to convert short and long integers
-between "host" and "network" order. Although the procedures above do
-this automatically for addresses, the conversion will still need to
-be done when sending or receiving encoded integer data from the network.
-
-@deffn {Scheme Procedure} htons value
-@deffnx {C Function} scm_htons (value)
-Convert a 16 bit quantity from host to network byte ordering.
-@var{value} is packed into 2 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
-@deffn {Scheme Procedure} ntohs value
-@deffnx {C Function} scm_ntohs (value)
-Convert a 16 bit quantity from network to host byte ordering.
-@var{value} is packed into 2 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
-@deffn {Scheme Procedure} htonl value
-@deffnx {C Function} scm_htonl (value)
-Convert a 32 bit quantity from host to network byte ordering.
-@var{value} is packed into 4 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
-@deffn {Scheme Procedure} ntohl value
-@deffnx {C Function} scm_ntohl (value)
-Convert a 32 bit quantity from network to host byte ordering.
-@var{value} is packed into 4 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
-These procedures are inconvenient to use at present, but consider:
-
-@example
-(define write-network-long
- (lambda (value port)
- (let ((v (make-uniform-vector 1 1 0)))
- (uniform-vector-set! v 0 (htonl value))
- (uniform-vector-write v port))))
-
-(define read-network-long
- (lambda (port)
- (let ((v (make-uniform-vector 1 1 0)))
- (uniform-vector-read! v port)
- (ntohl (uniform-vector-ref v 0)))))
-@end example
-
-@node System Identification
-@section System Identification
-
-This section lists the various procedures Guile provides for accessing
-information about the system it runs on.
-
-@deffn {Scheme Procedure} uname
-@deffnx {C Function} scm_uname ()
-Return an object with some information about the computer
-system the program is running on.
-@end deffn
-
-The following procedures accept an object as returned by @code{uname}
-and return a selected component.
-
-@table @code
-@item utsname:sysname
-The name of the operating system.
-@item utsname:nodename
-The network name of the computer.
-@item utsname:release
-The current release level of the operating system implementation.
-@item utsname:version
-The current version level within the release of the operating system.
-@item utsname:machine
-A description of the hardware.
-@end table
-
-@deffn {Scheme Procedure} gethostname
-@deffnx {C Function} scm_gethostname ()
-Return the host name of the current processor.
-@end deffn
-
-@deffn {Scheme Procedure} sethostname name
-@deffnx {C Function} scm_sethostname (name)
-Set the host name of the current processor to @var{name}. May
-only be used by the superuser. The return value is not
-specified.
-@end deffn
-
-@c FIXME::martin: Not in libguile!
-@deffn {Scheme Procedure} software-type
-Return a symbol describing the current platform's operating system.
-This may be one of AIX, VMS, UNIX, COHERENT, WINDOWS, MS-DOS, OS/2,
-THINKC, AMIGA, ATARIST, MACH, or ACORN.
-
-Note that most varieties of Unix are considered to be simply "UNIX".
-That is because when a program depends on features that are not present
-on every operating system, it is usually better to test for the presence
-or absence of that specific feature. The return value of
-@code{software-type} should only be used for this purpose when there is
-no other easy or unambiguous way of detecting such features.
-@end deffn
-
-@node Locales
-@section Locales
-
-@deffn {Scheme Procedure} setlocale category [locale]
-@deffnx {C Function} scm_setlocale (category, locale)
-If @var{locale} is omitted, return the current value of the
-specified locale category as a system-dependent string.
-@var{category} should be specified using the values
-@code{LC_COLLATE}, @code{LC_ALL} etc.
-
-Otherwise the specified locale category is set to the string
-@var{locale} and the new value is returned as a
-system-dependent string. If @var{locale} is an empty string,
-the locale will be set using environment variables.
-@end deffn
-
-@node Encryption
-@section Encryption
-
-Please note that the procedures in this section are not suited for
-strong encryption, they are only interfaces to the well-known and
-common system library functions of the same name. They are just as good
-(or bad) as the underlying functions, so you should refer to your system
-documentation before using them.
-
-@deffn {Scheme Procedure} crypt key salt
-@deffnx {C Function} scm_crypt (key, salt)
-Encrypt @var{key} using @var{salt} as the salt value to the
-crypt(3) library call.
-@end deffn
-
-Although @code{getpass} is not an encryption procedure per se, it
-appears here because it is often used in combination with @code{crypt}:
-
-@deffn {Scheme Procedure} getpass prompt
-@deffnx {C Function} scm_getpass (prompt)
-Display @var{prompt} to the standard error output and read
-a password from @file{/dev/tty}. If this file is not
-accessible, it reads from standard input. The password may be
-up to 127 characters in length. Additional characters and the
-terminating newline character are discarded. While reading
-the password, echoing and the generation of signals by special
-characters is disabled.
-@end deffn
diff --git a/doc/ref/preface.texi b/doc/ref/preface.texi
deleted file mode 100644
index bcabb411a..000000000
--- a/doc/ref/preface.texi
+++ /dev/null
@@ -1,200 +0,0 @@
-@iftex
-@page
-@unnumbered Preface
-
-This reference manual documents Guile, GNU's Ubiquitous Intelligent
-Language for Extensions. It describes how to use Guile in many useful
-and interesting ways.
-
-This is edition @value{MANUAL_EDITION} of the reference manual, and
-corresponds to Guile version @value{VERSION}.
-@end iftex
-
-
-@iftex
-@section The Guile License
-@end iftex
-
-@ifnottex
-@node Guile License
-@chapter The Guile License
-@end ifnottex
-
-The license of Guile consists of the GNU GPL plus a special statement
-giving blanket permission to link with non-free software. This is the
-license statement as found in any individual file that it applies to:
-
-@quotation
-This program 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 2, or (at your option) any
-later version.
-
-This program 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 this software; see the file COPYING. If not, write to the Free
-Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
-02111-1307 USA
-
-As a special exception, the Free Software Foundation gives permission
-for additional uses of the text contained in its release of GUILE.
-
-The exception is that, if you link the GUILE library with other files to
-produce an executable, this does not by itself cause the resulting
-executable to be covered by the GNU General Public License. Your use of
-that executable is in no way restricted on account of linking the GUILE
-library code into it.
-
-This exception does not however invalidate any other reasons why the
-executable file might be covered by the GNU General Public License.
-
-This exception applies only to the code released by the Free Software
-Foundation under the name GUILE. If you copy code from other Free
-Software Foundation releases into a copy of GUILE, as the General Public
-License permits, the exception does not apply to the code that you add
-in this way. To avoid misleading anyone as to the status of such
-modified files, you must delete this exception notice from them.
-
-If you write modifications of your own for GUILE, it is your choice
-whether to permit this exception to apply to your modifications. If you
-do not wish that, delete this exception notice.
-@end quotation
-
-
-@iftex
-@section Layout of this Manual
-@end iftex
-
-@ifnottex
-@node Manual Layout
-@chapter Layout of this Manual
-@end ifnottex
-
-The manual is divided into five parts.
-
-@strong{Part I: Introduction to Guile} provides an overview of what
-Guile is and how you can use it. A whirlwind tour shows how Guile can
-be used interactively and as a script interpreter, how to link Guile
-into your own applications, and how to write modules of interpreted and
-compiled code for use with Guile. Everything introduced here is
-documented again and in full by the later parts of the manual. This
-part also explains how to obtain and install new versions of Guile, and
-how to report bugs effectively.
-
-@strong{Part II: Writing and Running Guile Scheme} and @strong{Part III:
-Programming with Guile} document all aspects of practical programming
-using Guile. This covers both the Scheme level --- where we provide an
-introduction to the key ideas of the Scheme language --- and use of
-Guile's @code{scm} interface to write new primitives and objects in C,
-and to incorporate Guile into a C application. It also covers the use
-of Guile as a POSIX compliant script interpreter, and how to use the
-Guile debugger.
-
-@c @strong{Part V: Extending Applications Using Guile} explains the options
-@c available for using Guile as a application extension language. At the
-@c simpler end of the scale, an application might use Guile to define some
-@c application-specific primitives in C and then load an application Scheme
-@c file. In this case most of the application code is written on the
-@c Scheme level, and uses the application-specific primitives as an
-@c extension to standard Scheme. At the other end of the scale, an
-@c application might be predominantly written in C --- with its main
-@c control loop implemented in C --- but make occasional forays into Scheme
-@c to, say, read configuration data or run user-defined customization code.
-@c This part of the manual covers the complete range of application
-@c extension options.
-
-@strong{Part IV: Guile API Reference} documents Guile's core API. Most
-of the variables and procedures in Guile's core programming interface
-are available in both Scheme and C, and are related systematically such
-that the C interface can be inferred from the Scheme interface and vice
-versa. Therefore this part of the manual documents the Guile API in
-functionality-based groups with the Scheme and C interfaces presented
-side by side. Where the Scheme and C interfaces for a particular
-functional area do differ --- which is sometimes inevitable, given the
-differences in the structure of the two languages --- this is pointed
-out and explained. In all cases the overriding principle is that all
-the reference documentation for a given functional area is grouped
-together.
-
-@c the core Scheme language and features that Guile implements. Although
-@c the basis for this is the Scheme language described in R5RS, this part
-@c of the manual does not assume any prior familiarity with R5RS in
-@c particular, or with Scheme in general. Basic Scheme concepts, standard
-@c aspects of the Scheme language and Guile extensions on top of R5RS are
-@c all documented from scratch, and organized by functionality rather than
-@c by the defining standards.
-
-@strong{Part V: Guile Modules} describes some important modules,
-distributed as part of the Guile distribution, that extend the
-functionality provided by the Guile Scheme core. Two important examples
-are:
-
-@itemize @bullet
-@item
-the POSIX module, which provides Scheme level procedures for system and
-network programming that conform to the POSIX standard
-
-@item
-the SLIB module, which makes Aubrey Jaffer's portable Scheme library
-available for use in Guile.
-@end itemize
-
-
-@iftex
-@section Manual Conventions
-@end iftex
-
-@ifnottex
-@node Manual Conventions
-@chapter Conventions used in this Manual
-@end ifnottex
-
-We use some conventions in this manual.
-
-@itemize @bullet
-
-@item
-For some procedures, notably type predicates, we use @dfn{iff} to
-mean `if and only if'. The construct is usually something like:
-`Return @var{val} iff @var{condition}', where @var{val} is usually
-`@code{#t}' or `non-@code{#f}'. This typically means that @var{val}
-is returned if @var{condition} holds, and that @samp{#f} is returned
-otherwise.
-@cindex iff
-
-@item
-In examples and procedure descriptions and all other places where the
-evaluation of Scheme expression is shown, we use some notation for
-denoting the output and evaluation results of expressions.
-
-The symbol @code{@result{}} is used to tell which value is returned by
-an evaluation:
-
-@lisp
-(+ 1 2)
-@result{}
-3
-@end lisp
-
-Some procedures produce some output besides returning a value. This
-is denoted by the symbol @code{@print{}}.
-
-@lisp
-(begin (display 1) (newline) 'hooray)
-@print{} 1
-@result{}
-hooray
-@end lisp
-
-@c Add other conventions here.
-
-@end itemize
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/program.texi b/doc/ref/program.texi
deleted file mode 100644
index eba3fdf83..000000000
--- a/doc/ref/program.texi
+++ /dev/null
@@ -1,776 +0,0 @@
-@page
-@node Programming Overview
-@chapter An Overview of Guile Programming
-
-Guile is designed as an extension language interpreter that is
-straightforward to integrate with applications written in C (and C++).
-The big win here for the application developer is that Guile
-integration, as the Guile web page says, ``lowers your project's
-hacktivation energy.'' Lowering the hacktivation energy means that you,
-as the application developer, @emph{and your users}, reap the benefits
-that flow from being able to extend the application in a high level
-extension language rather than in plain old C.
-
-In abstract terms, it's difficult to explain what this really means and
-what the integration process involves, so instead let's begin by jumping
-straight into an example of how you might integrate Guile into an
-existing program, and what you could expect to gain by so doing. With
-that example under our belts, we'll then return to a more general
-analysis of the arguments involved and the range of programming options
-available.
-
-@menu
-* Extending Dia:: How one might extend Dia using Guile.
-* Scheme vs C:: Why Scheme is more hackable than C.
-* Testbed Example:: Example: using Guile in a testbed.
-* Programming Options:: Options for Guile programming.
-* User Programming:: How about application users?
-@end menu
-
-
-@node Extending Dia
-@section How One Might Extend Dia Using Guile
-
-Dia is a free software program for drawing schematic diagrams like flow
-charts and floor plans (REFFIXME). This section conducts the thought
-experiment of adding Guile to Dia. In so doing, it aims to illustrate
-several of the steps and considerations involved in adding Guile to
-applications in general.
-
-@menu
-* Dia Objective:: Deciding why you want to add Guile.
-* Dia Steps:: Four steps required to add Guile.
-* Dia Smobs:: How to represent Dia data in Scheme.
-* Dia Primitives:: Writing Guile primitives for Dia.
-* Dia Hook:: Providing a hook for Scheme evaluation.
-* Dia Structure:: Overall structure for adding Guile.
-* Dia Advanced:: Going further with Dia and Guile.
-@end menu
-
-
-@node Dia Objective
-@subsection Deciding Why You Want to Add Guile
-
-First off, you should understand why you want to add Guile to Dia at
-all, and that means forming a picture of what Dia does and how it does
-it. So, what are the constituents of the Dia application?
-
-@itemize @bullet
-@item
-Most importantly, the @dfn{application domain objects} --- in other
-words, the concepts that differentiate Dia from another application such
-as a word processor or spreadsheet: shapes, templates, connectors,
-pages, plus the properties of all these things.
-
-@item
-The code that manages the graphical face of the application, including
-the layout and display of the objects above.
-
-@item
-The code that handles input events, which indicate that the application
-user is wanting to do something.
-@end itemize
-
-@noindent
-(In other words, a textbook example of the @dfn{model - view -
-controller} paradigm.)
-
-Next question: how will Dia benefit once the Guile integration is
-complete? Several (positive!) answers are possible here, and the choice
-is obviously up to the application developers. Still, one answer is
-that the main benefit will be the ability to manipulate Dia's
-application domain objects from Scheme.
-
-Suppose that Dia made a set of procedures available in Scheme,
-representing the most basic operations on objects such as shapes,
-connectors, and so on. Using Scheme, the application user could then
-write code that builds upon these basic operations to create more
-complex procedures. For example, given basic procedures to enumerate
-the objects on a page, to determine whether an object is a square, and
-to change the fill pattern of a single shape, the user can write a
-Scheme procedure to change the fill pattern of all squares on the
-current page:
-
-@lisp
-(define (change-squares'-fill-pattern new-pattern)
- (for-each-shape current-page
- (lambda (shape)
- (if (square? shape)
- (change-fill-pattern shape new-pattern)))))
-@end lisp
-
-
-@node Dia Steps
-@subsection Four Steps Required to Add Guile
-
-Assuming this objective, four steps are needed to achieve it.
-
-First, you need a way of representing your application-specific objects
---- such as @code{shape} in the previous example --- when they are
-passed into the Scheme world. Unless your objects are so simple that
-they map naturally into builtin Scheme data types like numbers and
-strings, you will probably want to use Guile's @dfn{SMOB} interface to
-create a new Scheme data type for your objects.
-
-Second, you need to write code for the basic operations like
-@code{for-each-shape} and @code{square?} such that they access and
-manipulate your existing data structures correctly, and then make these
-operations available as @dfn{primitives} on the Scheme level.
-
-Third, you need to provide some mechanism within the Dia application
-that a user can hook into to cause arbitrary Scheme code to be
-evaluated.
-
-Finally, you need to restructure your top-level application C code a
-little so that it initializes the Guile interpreter correctly and
-declares your @dfn{SMOBs} and @dfn{primitives} to the Scheme world.
-
-The following subsections expand on these four points in turn.
-
-
-@node Dia Smobs
-@subsection How to Represent Dia Data in Scheme
-
-For all but the most trivial applications, you will probably want to
-allow some representation of your domain objects to exist on the Scheme
-level. This is where the idea of SMOBs comes in, and with it issues of
-lifetime management and garbage collection.
-
-To get more concrete about this, let's look again at the example we gave
-earlier of how application users can use Guile to build higher-level
-functions from the primitives that Dia itself provides.
-
-@lisp
-(define (change-squares'-fill-pattern new-pattern)
- (for-each-shape current-page
- (lambda (shape)
- (if (square? shape)
- (change-fill-pattern shape new-pattern)))))
-@end lisp
-
-Consider what is stored here in the variable @code{shape}. For each
-shape on the current page, the @code{for-each-shape} primitive calls
-@code{(lambda (shape) @dots{})} with an argument representing that
-shape. Question is: how is that argument represented on the Scheme
-level? The issues are as follows.
-
-@itemize @bullet
-@item
-Whatever the representation, it has to be decodable again by the C code
-for the @code{square?} and @code{change-fill-pattern} primitives. In
-other words, a primitive like @code{square?} has somehow to be able to
-turn the value that it receives back into something that points to the
-underlying C structure describing a shape.
-
-@item
-The representation must also cope with Scheme code holding on to the
-value for later use. What happens if the Scheme code stores
-@code{shape} in a global variable, but then that shape is deleted (in a
-way that the Scheme code is not aware of), and later on some other
-Scheme code uses that global variable again in a call to, say,
-@code{square?}?
-
-@item
-The lifetime and memory allocation of objects that exist @emph{only} in
-the Scheme world is managed automatically by Guile's garbage collector
-using one simple rule: when there are no remaining references to an
-object, the object is considered dead and so its memory is freed. But
-for objects that exist in both C and Scheme, the picture is more
-complicated; in the case of Dia, where the @code{shape} argument passes
-transiently in and out of the Scheme world, it would be quite wrong the
-@strong{delete} the underlying C shape just because the Scheme code has
-finished evaluation. How do we avoid this happening?
-@end itemize
-
-One resolution of these issues is for the Scheme-level representation of
-a shape to be a new, Scheme-specific C structure wrapped up as a SMOB.
-The SMOB is what is passed into and out of Scheme code, and the
-Scheme-specific C structure inside the SMOB points to Dia's underlying C
-structure so that the code for primitives like @code{square?} can get at
-it.
-
-To cope with an underlying shape being deleted while Scheme code is
-still holding onto a Scheme shape value, the underlying C structure
-should have a new field that points to the Scheme-specific SMOB. When a
-shape is deleted, the relevant code chains through to the
-Scheme-specific structure and sets its pointer back to the underlying
-structure to NULL. Thus the SMOB value for the shape continues to
-exist, but any primitive code that tries to use it will detect that the
-underlying shape has been deleted because the underlying structure
-pointer is NULL.
-
-So, to summarize the steps involved in this resolution of the problem
-(and assuming that the underlying C structure for a shape is
-@code{struct dia_shape}):
-
-@itemize @bullet
-@item
-Define a new Scheme-specific structure that @emph{points} to the
-underlying C structure:
-
-@lisp
-struct dia_guile_shape
-@{
- struct dia_shape * c_shape; /* NULL => deleted */
-@}
-@end lisp
-
-@item
-Add a field to @code{struct dia_shape} that points to its @code{struct
-dia_guile_shape} if it has one ---
-
-@lisp
-struct dia_shape
-@{
- @dots{}
- struct dia_guile_shape * guile_shape;
-@}
-@end lisp
-
-@noindent
---- so that C code can set @code{guile_shape->c_shape} to NULL when the
-underlying shape is deleted.
-
-@item
-Wrap @code{struct dia_guile_shape} as a SMOB type.
-
-@item
-Whenever you need to represent a C shape onto the Scheme level, create a
-SMOB instance for it, and pass that.
-
-@item
-In primitive code that receives a shape SMOB instance, check the
-@code{c_shape} field when decoding it, to find out whether the
-underlying C shape is still there.
-@end itemize
-
-As far as memory management is concerned, the SMOB values and their
-Scheme-specific structures are under the control of the garbage
-collector, whereas the underlying C structures are explicitly managed in
-exactly the same way that Dia managed them before we thought of adding
-Guile.
-
-When the garbage collector decides to free a shape SMOB value, it calls
-the @dfn{SMOB free} function that was specified when defining the shape
-SMOB type. To maintain the correctness of the @code{guile_shape} field
-in the underlying C structure, this function should chain through to the
-underlying C structure (if it still exists) and set its
-@code{guile_shape} field to NULL.
-
-For full documentation on defining and using SMOB types, see
-@ref{Defining New Types (Smobs)}.
-
-
-@node Dia Primitives
-@subsection Writing Guile Primitives for Dia
-
-Once the details of object representation are decided, writing the
-primitive function code that you need is usually straightforward.
-
-A primitive is simply a C function whose arguments and return value are
-all of type @code{SCM}, and whose body does whatever you want it to do.
-As an example, here is a possible implementation of the @code{square?}
-primitive:
-
-@lisp
-#define FUNC_NAME "square?"
-static SCM square_p (SCM shape)
-@{
- struct dia_guile_shape * guile_shape;
-
- /* Check that arg is really a shape SMOB. */
- SCM_VALIDATE_SHAPE (SCM_ARG1, shape);
-
- /* Access Scheme-specific shape structure. */
- guile_shape = SCM_SMOB_DATA (shape);
-
- /* Find out if underlying shape exists and is a
- square; return answer as a Scheme boolean. */
- return SCM_BOOL (guile_shape->c_shape &&
- (guile_shape->c_shape->type == DIA_SQUARE));
-@}
-#undef FUNC_NAME
-@end lisp
-
-Notice how easy it is to chain through from the @code{SCM shape}
-parameter that @code{square_p} receives --- which is a SMOB --- to the
-Scheme-specific structure inside the SMOB, and thence to the underlying
-C structure for the shape.
-
-In this code, @code{SCM_SMOB_DATA} and @code{SCM_BOOL} are macros from
-the standard Guile API. @code{SCM_VALIDATE_SHAPE} is a macro that you
-should define as part of your SMOB definition: it checks that the passed
-parameter is of the expected type. This is needed to guard against
-Scheme code using the @code{square?} procedure incorrectly, as in
-@code{(square? "hello")}; Scheme's latent typing means that usage errors
-like this must be caught at run time.
-
-Having written the C code for your primitives, you need to make them
-available as Scheme procedures by calling the @code{scm_c_define_gsubr}
-function. @code{scm_c_define_gsubr} (REFFIXME) takes arguments that
-specify the Scheme-level name for the primitive and how many required,
-optional and rest arguments it can accept. The @code{square?} primitive
-always requires exactly one argument, so the call to make it available
-in Scheme reads like this:
-
-@lisp
-scm_c_define_gsubr ("square?", 1, 0, 0, square_p);
-@end lisp
-
-For where to put this call, see the subsection after next on the
-structure of Guile-enabled code (@pxref{Dia Structure}).
-
-
-@node Dia Hook
-@subsection Providing a Hook for the Evaluation of Scheme Code
-
-To make the Guile integration useful, you have to design some kind of
-hook into your application that application users can use to cause their
-Scheme code to be evaluated.
-
-Technically, this is straightforward; you just have to decide on a
-mechanism that is appropriate for your application. Think of Emacs, for
-example: when you type @kbd{@key{ESC} :}, you get a prompt where you can
-type in any Elisp code, which Emacs will then evaluate. Or, again like
-Emacs, you could provide a mechanism (such as an init file) to allow
-Scheme code to be associated with a particular key sequence, and
-evaluate the code when that key sequence is entered.
-
-In either case, once you have the Scheme code that you want to evaluate,
-as a null terminated string, you can tell Guile to evaluate it by
-calling the @code{scm_c_eval_string} function.
-
-
-@node Dia Structure
-@subsection Top-level Structure of Guile-enabled Dia
-
-Let's assume that the pre-Guile Dia code looks structurally like this:
-
-@itemize @bullet
-@item
-@code{main ()}
-
-@itemize @bullet
-@item
-do lots of initialization and setup stuff
-@item
-enter Gtk main loop
-@end itemize
-@end itemize
-
-When you add Guile to a program, one (rather technical) requirement is
-that Guile's garbage collector needs to know where the bottom of the C
-stack is. The easiest way to ensure this is to use
-@code{scm_boot_guile} like this:
-
-@itemize @bullet
-@item
-@code{main ()}
-
-@itemize @bullet
-@item
-do lots of initialization and setup stuff
-@item
-@code{scm_boot_guile (argc, argv, inner_main, NULL)}
-@end itemize
-
-@item
-@code{inner_main ()}
-
-@itemize @bullet
-@item
-define all SMOB types
-@item
-export primitives to Scheme using @code{scm_c_define_gsubr}
-@item
-enter Gtk main loop
-@end itemize
-@end itemize
-
-In other words, you move the guts of what was previously in your
-@code{main} function into a new function called @code{inner_main}, and
-then add a @code{scm_boot_guile} call, with @code{inner_main} as a
-parameter, to the end of @code{main}.
-
-Assuming that you are using SMOBs and have written primitive code as
-described in the preceding subsections, you also need to insert calls to
-declare your new SMOBs and export the primitives to Scheme. These
-declarations must happen @emph{inside} the dynamic scope of the
-@code{scm_boot_guile} call, but also @emph{before} any code is run that
-could possibly use them --- the beginning of @code{inner_main} is an
-ideal place for this.
-
-
-@node Dia Advanced
-@subsection Going Further with Dia and Guile
-
-The steps described so far implement an initial Guile integration that
-already gives a lot of additional power to Dia application users. But
-there are further steps that you could take, and it's interesting to
-consider a few of these.
-
-In general, you could progressively move more of Dia's source code from
-C into Scheme. This might make the code more maintainable and
-extensible, and it could open the door to new programming paradigms that
-are tricky to effect in C but straightforward in Scheme.
-
-A specific example of this is that you could use the guile-gtk package,
-which provides Scheme-level procedures for most of the Gtk+ library, to
-move the code that lays out and displays Dia objects from C to Scheme.
-
-As you follow this path, it naturally becomes less useful to maintain a
-distinction between Dia's original non-Guile-related source code, and
-its later code implementing SMOBs and primitives for the Scheme world.
-
-For example, suppose that the original source code had a
-@code{dia_change_fill_pattern} function:
-
-@lisp
-void dia_change_fill_pattern (struct dia_shape * shape,
- struct dia_pattern * pattern)
-@{
- /* real pattern change work */
-@}
-@end lisp
-
-During initial Guile integration, you add a @code{change_fill_pattern}
-primitive for Scheme purposes, which accesses the underlying structures
-from its SMOB values and uses @code{dia_change_fill_pattern} to do the
-real work:
-
-@lisp
-SCM change_fill_pattern (SCM shape, SCM pattern)
-@{
- struct dia_shape * d_shape;
- struct dia_pattern * d_pattern;
-
- @dots{}
-
- dia_change_fill_pattern (d_shape, d_pattern);
-
- return SCM_UNSPECIFIED;
-@}
-@end lisp
-
-At this point, it makes sense to keep @code{dia_change_fill_pattern} and
-@code{change_fill_pattern} separate, because
-@code{dia_change_fill_pattern} can also be called without going through
-Scheme at all, say because the user clicks a button which causes a
-C-registered Gtk+ callback to be called.
-
-But, if the code for creating buttons and registering their callbacks is
-moved into Scheme (using guile-gtk), it may become true that
-@code{dia_change_fill_pattern} can no longer be called other than
-through Scheme. In which case, it makes sense to abolish it and move
-its contents directly into @code{change_fill_pattern}, like this:
-
-@lisp
-SCM change_fill_pattern (SCM shape, SCM pattern)
-@{
- struct dia_shape * d_shape;
- struct dia_pattern * d_pattern;
-
- @dots{}
-
- /* real pattern change work */
-
- return SCM_UNSPECIFIED;
-@}
-@end lisp
-
-So further Guile integration progressively @emph{reduces} the amount of
-functional C code that you have to maintain over the long term.
-
-A similar argument applies to data representation. In the discussion of
-SMOBs earlier, issues arose because of the different memory management
-and lifetime models that normally apply to data structures in C and in
-Scheme. However, with further Guile integration, you can resolve this
-issue in a more radical way by allowing all your data structures to be
-under the control of the garbage collector, and kept alive by references
-from the Scheme world. Instead of maintaining an array or linked list
-of shapes in C, you would instead maintain a list in Scheme.
-
-Rather like the coalescing of @code{dia_change_fill_pattern} and
-@code{change_fill_pattern}, the practical upshot of such a change is
-that you would no longer have to keep the @code{dia_shape} and
-@code{dia_guile_shape} structures separate, and so wouldn't need to
-worry about the pointers between them. Instead, you could change the
-SMOB definition to wrap the @code{dia_shape} structure directly, and
-send @code{dia_guile_shape} off to the scrap yard. Cut out the middle
-man!
-
-Finally, we come to the holy grail of Guile's free software / extension
-language approach. Once you have a Scheme representation for
-interesting Dia data types like shapes, and a handy bunch of primitives
-for manipulating them, it suddenly becomes clear that you have a bundle
-of functionality that could have far-ranging use beyond Dia itself. In
-other words, the data types and primitives could now become a library,
-and Dia becomes just one of the many possible applications using that
-library --- albeit, at this early stage, a rather important one!
-
-In this model, Guile becomes just the glue that binds everything
-together. Imagine an application that usefully combined functionality
-from Dia, Gnumeric and GnuCash --- it's tricky right now, because no
-such application yet exists; but it'll happen some day @dots{}
-
-
-@node Scheme vs C
-@section Why Scheme is More Hackable Than C
-
-Underlying Guile's value proposition is the assumption that programming
-in a high level language, specifically Guile's implementation of Scheme,
-is necessarily better in some way than programming in C. What do we
-mean by this claim, and how can we be so sure?
-
-One class of advantages applies not only to Scheme, but more generally
-to any interpretable, high level, scripting language, such as Emacs
-Lisp, Python, Ruby, or @TeX{}'s macro language. Common features of all
-such languages, when compared to C, are that:
-
-@itemize @bullet
-@item
-They lend themselves to rapid and experimental development cycles,
-owing usually to a combination of their interpretability and the
-integrated development environment in which they are used.
-
-@item
-They free developers from some of the low level bookkeeping tasks
-associated with C programming, notably memory management.
-
-@item
-They provide high level features such as container objects and exception
-handling that make common programming tasks easier.
-@end itemize
-
-In the case of Scheme, particular features that make programming easier
---- and more fun! --- are its powerful mechanisms for abstracting parts
-of programs (closures --- @pxref{About Closure}) and for iteration
-(@pxref{while do}).
-
-The evidence in support of this argument is empirical: the huge amount
-of code that has been written in extension languages for applications
-that support this mechanism. Most notable are extensions written in
-Emacs Lisp for GNU Emacs, in @TeX{}'s macro language for @TeX{}, and in
-Script-Fu for the Gimp, but there is increasingly now a significant code
-eco-system for Guile-based applications as well, such as Lilypond and
-GnuCash. It is close to inconceivable that similar amounts of
-functionality could have been added to these applications just by
-writing new code in their base implementation languages.
-
-
-@node Testbed Example
-@section Example: Using Guile for an Application Testbed
-
-As an example of what this means in practice, imagine writing a testbed
-for an application that is tested by submitting various requests (via a
-C interface) and validating the output received. Suppose further that
-the application keeps an idea of its current state, and that the
-``correct'' output for a given request may depend on the current
-application state. A complete ``white box''@footnote{A @dfn{white box}
-test plan is one that incorporates knowledge of the internal design of
-the application under test.} test plan for this application would aim to
-submit all possible requests in each distinguishable state, and validate
-the output for all request/state combinations.
-
-To write all this test code in C would be very tedious. Suppose instead
-that the testbed code adds a single new C function, to submit an
-arbitrary request and return the response, and then uses Guile to export
-this function as a Scheme procedure. The rest of the testbed can then
-be written in Scheme, and so benefits from all the advantages of
-programming in Scheme that were described in the previous section.
-
-(In this particular example, there is an additional benefit of writing
-most of the testbed in Scheme. A common problem for white box testing
-is that mistakes and mistaken assumptions in the application under test
-can easily be reproduced in the testbed code. It is more difficult to
-copy mistakes like this when the testbed is written in a different
-language from the application.)
-
-
-@node Programming Options
-@section A Choice of Programming Options
-
-The preceding arguments and example point to a model of Guile
-programming that is applicable in many cases. According to this model,
-Guile programming involves a balance between C and Scheme programming,
-with the aim being to extract the greatest possible Scheme level benefit
-from the least amount of C level work.
-
-The C level work required in this model usually consists of packaging
-and exporting functions and application objects such that they can be
-seen and manipulated on the Scheme level. To help with this, Guile's C
-language interface includes utility features that aim to make this kind
-of integration very easy for the application developer. These features
-are documented later in this part of the manual: see REFFIXME.
-
-This model, though, is really just one of a range of possible
-programming options. If all of the functionality that you need is
-available from Scheme, you could choose instead to write your whole
-application in Scheme (or one of the other high level languages that
-Guile supports through translation), and simply use Guile as an
-interpreter for Scheme. (In the future, we hope that Guile will also be
-able to compile Scheme code, so lessening the performance gap between C
-and Scheme code.) Or, at the other end of the C--Scheme scale, you
-could write the majority of your application in C, and only call out to
-Guile occasionally for specific actions such as reading a configuration
-file or executing a user-specified extension. The choices boil down to
-two basic questions:
-
-@itemize @bullet
-@item
-Which parts of the application do you write in C, and which in Scheme
-(or another high level translated language)?
-
-@item
-How do you design the interface between the C and Scheme parts of your
-application?
-@end itemize
-
-These are of course design questions, and the right design for any given
-application will always depend upon the particular requirements that you
-are trying to meet. In the context of Guile, however, there are some
-generally applicable considerations that can help you when designing
-your answers.
-
-@menu
-* Available Functionality:: What functionality is already available?
-* Basic Constraints:: Functional and performance constraints.
-* Style Choices:: Your preferred programming style.
-* Program Control:: What controls program execution?
-@end menu
-
-
-@node Available Functionality
-@subsection What Functionality is Already Available?
-
-Suppose, for the sake of argument, that you would prefer to write your
-whole application in Scheme. Then the API available to you consists of:
-
-@itemize @bullet
-@item
-standard Scheme
-
-@item
-plus the extensions to standard Scheme provided by
-Guile in its core distribution
-
-@item
-plus any additional functionality that you or others have packaged so
-that it can be loaded as a Guile Scheme module.
-@end itemize
-
-A module in the last category can either be a pure Scheme module --- in
-other words a collection of utility procedures coded in Scheme --- or a
-module that provides a Scheme interface to an extension library coded in
-C --- in other words a nice package where someone else has done the work
-of wrapping up some useful C code for you. The set of available modules
-is growing quickly and already includes such useful examples as
-@code{(gtk gtk)}, which makes Gtk+ drawing functions available in
-Scheme, and @code{(database postgres)}, which provides SQL access to a
-Postgres database.
-
-Given the growing collection of pre-existing modules, it is quite
-feasible that your application could be implemented by combining a
-selection of these modules together with new application code written in
-Scheme.
-
-If this approach is not enough, because the functionality that your
-application needs is not already available in this form, and it is
-impossible to write the new functionality in Scheme, you will need to
-write some C code. If the required function is already available in C
-(e.g. in a library), all you need is a little glue to connect it to the
-world of Guile. If not, you need both to write the basic code and to
-plumb it into Guile.
-
-In either case, two general considerations are important. Firstly, what
-is the interface by which the functionality is presented to the Scheme
-world? Does the interface consist only of function calls (for example,
-a simple drawing interface), or does it need to include @dfn{objects} of
-some kind that can be passed between C and Scheme and manipulated by
-both worlds. Secondly, how does the lifetime and memory management of
-objects in the C code relate to the garbage collection governed approach
-of Scheme objects? In the case where the basic C code is not already
-written, most of the difficulties of memory management can be avoided by
-using Guile's C interface features from the start.
-
-For the full documentation on writing C code for Guile and connecting
-existing C code to the Guile world, see REFFIXME.
-
-
-@node Basic Constraints
-@subsection Functional and Performance Constraints
-
-
-@node Style Choices
-@subsection Your Preferred Programming Style
-
-
-@node Program Control
-@subsection What Controls Program Execution?
-
-
-@node User Programming
-@section How About Application Users?
-
-So far we have considered what Guile programming means for an
-application developer. But what if you are instead @emph{using} an
-existing Guile-based application, and want to know what your
-options are for programming and extending this application?
-
-The answer to this question varies from one application to another,
-because the options available depend inevitably on whether the
-application developer has provided any hooks for you to hang your own
-code on and, if there are such hooks, what they allow you to
-do.@footnote{Of course, in the world of free software, you always have
-the freedom to modify the application's source code to your own
-requirements. Here we are concerned with the extension options that the
-application has provided for without your needing to modify its source
-code.} For example@dots{}
-
-@itemize @bullet
-@item
-If the application permits you to load and execute any Guile code, the
-world is your oyster. You can extend the application in any way that
-you choose.
-
-@item
-A more cautious application might allow you to load and execute Guile
-code, but only in a @dfn{safe} environment, where the interface
-available is restricted by the application from the standard Guile API.
-
-@item
-Or a really fearful application might not provide a hook to really
-execute user code at all, but just use Scheme syntax as a convenient way
-for users to specify application data or configuration options.
-@end itemize
-
-In the last two cases, what you can do is, by definition, restricted by
-the application, and you should refer to the application's own manual to
-find out your options.
-
-The most well known example of the first case is Emacs, with its
-extension language Emacs Lisp: as well as being a text editor, Emacs
-supports the loading and execution of arbitrary Emacs Lisp code. The
-result of such openness has been dramatic: Emacs now benefits from
-user-contributed Emacs Lisp libraries that extend the basic editing
-function to do everything from reading news to psychoanalysis and
-playing adventure games. The only limitation is that extensions are
-restricted to the functionality provided by Emacs's built-in set of
-primitive operations. For example, you can interact and display data by
-manipulating the contents of an Emacs buffer, but you can't pop-up and
-draw a window with a layout that is totally different to the Emacs
-standard.
-
-This situation with a Guile application that supports the loading of
-arbitrary user code is similar, except perhaps even more so, because
-Guile also supports the loading of extension libraries written in C.
-This last point enables user code to add new primitive operations to
-Guile, and so to bypass the limitation present in Emacs Lisp.
-
-At this point, the distinction between an application developer and an
-application user becomes rather blurred. Instead of seeing yourself as
-a user extending an application, you could equally well say that you are
-developing a new application of your own using some of the primitive
-functionality provided by the original application. As such, all the
-discussions of the preceding sections of this chapter are relevant to
-how you can proceed with developing your extension.
diff --git a/doc/ref/repl-modules.texi b/doc/ref/repl-modules.texi
deleted file mode 100644
index b136bd865..000000000
--- a/doc/ref/repl-modules.texi
+++ /dev/null
@@ -1,131 +0,0 @@
-@page
-@node Readline Support
-@chapter Readline Support
-
-@c FIXME::martin: Review me!
-
-@cindex readline
-@cindex command line history
-Guile comes with an interface module to the readline library. This
-makes interactive use much more convenient, because of the command-line
-editing features of readline. Using @code{(ice-9 readline)}, you can
-navigate through the current input line with the cursor keys, retrieve
-older command lines from the input history and even search through the
-history entries.
-
-@menu
-* Loading Readline Support:: How to load readline support into Guile.
-* Readline Options:: How to modify readline's behaviour.
-@end menu
-
-
-@node Loading Readline Support
-@section Loading Readline Support
-
-The module is not loaded by default and so has to be loaded and
-activated explicitly. This is done with two simple lines of code:
-
-@lisp
-(use-modules (ice-9 readline))
-(activate-readline)
-@end lisp
-
-@c FIXME::martin: Review me!
-
-The first line will load the necessary code, and the second will
-activate readline's features for the REPL. If you plan to use this
-module often, you should save these to lines to your @file{.guile}
-personal startup file.
-
-You will notice that the REPL's behaviour changes a bit when you have
-loaded the readline module. For example, when you press Enter before
-typing in the closing parentheses of a list, you will see the
-@dfn{continuation} prompt, three dots: @code{...} This gives you a nice
-visual feedback when trying to match parentheses. To make this even
-easier, @dfn{bouncing parentheses} are implemented. That means that
-when you type in a closing parentheses, the cursor will jump to the
-corresponding opening parenthesis for a short time, making it trivial to make
-them match.
-
-Once the readline module is activated, all lines entered interactively
-will be stored in a history and can be recalled later using the
-cursor-up and -down keys. Readline also understands the Emacs keys for
-navigating through the command line and history.
-
-When you quit your Guile session by evaluating @code{(quit)} or pressing
-Ctrl-D, the history will be saved to the file @file{.guile_history} and
-read in when you start Guile for the next time. Thus you can start a
-new Guile session and still have the (probably long-winded) definition
-expressions available.
-
-
-@node Readline Options
-@section Readline Options
-
-@c FIXME::martin: Review me!
-
-@cindex readline options
-The readline interface module can be configured in several ways to
-better suit the user's needs. Configuration is done via the readline
-module's options interface, in a similar way to the evaluator and
-debugging options (@pxref{General option interface}.)
-
-Here is the list of readline options generated by typing
-@code{(readline-options 'full)} in Guile. You can also see the
-default values.
-
-@smalllisp
-bounce-parens 500 Time (ms) to show matching opening parenthesis (0 = off).
-history-length 200 History length.
-history-file yes Use history file.
-@end smalllisp
-
-The history length specifies how many input lines will be remembered.
-If the history contains that many lines and additional lines are
-entered, the oldest lines will be lost. You can switch on/off the
-usage of the history file using the following call.
-
-@lisp
-(readline-disable 'history)
-@end lisp
-
-The readline options interface can only be used @emph{after} loading
-the readline module, because it is defined in that module.
-
-
-@page
-@node Value History
-@chapter Value History
-
-@c FIXME::martin: Review me!
-
-@cindex value history
-Another module which makes command line usage more convenient is
-@code{(ice-9 history)}. This module will change the REPL so that each
-value which is evaluated and printed will be remembered under a name
-constructed from the dollar character (@code{$}) and the number of the
-evaluated expression.
-
-Consider an example session.
-
-@example
-guile> (use-modules (ice-9 history))
-guile> 1
-$1 = 1
-guile> (+ $1 $1)
-$2 = 2
-guile> (* $2 $2)
-$3 = 4
-@end example
-
-After loading the value history module @code{(ice-9 history)}, one
-(trivial) expression is evaluated. The result is stored into the
-variable @code{$1}. This fact is indicated by the output @code{$1 = },
-which is also caused by @code{(ice-9 history)}. In the next line, this
-variable is used two times, to produce the value @code{$2}, which in
-turn is used in the calculation for @code{$3}.
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-binding.texi b/doc/ref/scheme-binding.texi
deleted file mode 100644
index 23786b3bf..000000000
--- a/doc/ref/scheme-binding.texi
+++ /dev/null
@@ -1,279 +0,0 @@
-@page
-@node Binding Constructs
-@chapter Definitions and Variable Bindings
-
-@c FIXME::martin: Review me!
-
-Scheme supports the definition of variables in different contexts.
-Variables can be defined at the top level, so that they are visible in
-the entire program, and variables can be defined locally to procedures
-and expressions. This is important for modularity and data abstraction.
-
-@menu
-* Top Level:: Top level variable definitions.
-* Local Bindings:: Local variable bindings.
-* Internal Definitions:: Internal definitions.
-* Binding Reflection:: Querying variable bindings.
-@end menu
-
-
-@node Top Level
-@section Top Level Variable Definitions
-
-@cindex variable definition
-
-On the top level of a program (i.e. when not inside the body of a
-procedure definition or a @code{let}, @code{let*} or @code{letrec}
-expression), a definition of the form
-
-@lisp
-(define a @var{value})
-@end lisp
-
-@noindent
-defines a variable called @code{a} and sets it to the value @var{value}.
-
-If the variable already exists, because it has already been created by a
-previous @code{define} expression with the same name, its value is
-simply changed to the new @var{value}. In this case, then, the above
-form is completely equivalent to
-
-@lisp
-(set! a @var{value})
-@end lisp
-
-@noindent
-This equivalence means that @code{define} can be used interchangeably
-with @code{set!} to change the value of variables at the top level of
-the REPL or a Scheme source file. It is useful during interactive
-development when reloading a Scheme file that you have modified, because
-it allows the @code{define} expressions in that file to work as expected
-both the first time that the file is loaded and on subsequent occasions.
-
-Note, though, that @code{define} and @code{set!} are not always
-equivalent. For example, a @code{set!} is not allowed if the named
-variable does not already exist, and the two expressions can behave
-differently in the case where there are imported variables visible from
-another module.
-
-@deffn {Scheme Syntax} define name value
-Create a top level variable named @var{name} with value @var{value}.
-If the named variable already exists, just change its value. The return
-value of a @code{define} expression is unspecified.
-@end deffn
-
-The C API equivalents of @code{define} are @code{scm_define} and
-@code{scm_c_define}, which differ from each other in whether the
-variable name is specified as a @code{SCM} symbol or as a
-null-terminated C string.
-
-@deffn {C Function} scm_define (sym, value)
-@deffnx {C Function} scm_c_define (const char *name, value)
-C equivalents of @code{define}, with variable name specified either by
-@var{sym}, a symbol, or by @var{name}, a null-terminated C string. Both
-variants return the new or preexisting variable object.
-@end deffn
-
-@code{define} (when it occurs at top level), @code{scm_define} and
-@code{scm_c_define} all create or set the value of a variable in the top
-level environment of the current module. If there was not already a
-variable with the specified name belonging to the current module, but a
-similarly named variable from another module was visible through having
-been imported, the newly created variable in the current module will
-shadow the imported variable, such that the imported variable is no
-longer visible.
-
-Attention: Scheme definitions inside local binding constructs
-(@pxref{Local Bindings}) act differently (@pxref{Internal Definitions}).
-
-
-@node Local Bindings
-@section Local Variable Bindings
-
-@c FIXME::martin: Review me!
-
-@cindex local bindings
-@cindex local variables
-
-As opposed to definitions at the top level, which are visible in the
-whole program (or current module, when Guile modules are used), it is
-also possible to define variables which are only visible in a
-well-defined part of the program. Normally, this part of a program
-will be a procedure or a subexpression of a procedure.
-
-With the constructs for local binding (@code{let}, @code{let*} and
-@code{letrec}), the Scheme language has a block structure like most
-other programming languages since the days of @sc{Algol 60}. Readers
-familiar to languages like C or Java should already be used to this
-concept, but the family of @code{let} expressions has a few properties
-which are well worth knowing.
-
-The first local binding construct is @code{let}. The other constructs
-@code{let*} and @code{letrec} are specialized versions for usage where
-using plain @code{let} is a bit inconvenient.
-
-@deffn syntax let bindings body
-@var{bindings} has the form
-
-@lisp
-((@var{variable1} @var{init1}) @dots{})
-@end lisp
-
-that is zero or more two-element lists of a variable and an arbitrary
-expression each. All @var{variable} names must be distinct.
-
-A @code{let} expression is evaluated as follows.
-
-@itemize @bullet
-@item
-All @var{init} expressions are evaluated.
-
-@item
-New storage is allocated for the @var{variables}.
-
-@item
-The values of the @var{init} expressions are stored into the variables.
-
-@item
-The expressions in @var{body} are evaluated in order, and the value of
-the last expression is returned as the value of the @code{let}
-expression.
-
-@item
-The storage for the @var{variables} is freed.
-@end itemize
-
-The @var{init} expressions are not allowed to refer to any of the
-@var{variables}.
-@end deffn
-
-@deffn syntax let* bindings body
-Similar to @code{let}, but the variable bindings are performed
-sequentially, that means that all @var{init} expression are allowed to
-use the variables defined on their left in the binding list.
-
-A @code{let*} expression can always be expressed with nested @code{let}
-expressions.
-
-@lisp
-(let* ((a 1) (b a))
- b)
-@equiv{}
-(let ((a 1))
- (let ((b a))
- b))
-@end lisp
-@end deffn
-
-@deffn syntax letrec bindings body
-Similar to @code{let}, but it is possible to refer to the @var{variable}
-from lambda expression created in any of the @var{inits}. That is,
-procedures created in the @var{init} expression can recursively refer to
-the defined variables.
-
-@lisp
-(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
-@end lisp
-@end deffn
-
-There is also an alternative form of the @code{let} form, which is used
-for expressing iteration. Because of the use as a looping construct,
-this form (the @dfn{named let}) is documented in the section about
-iteration (@pxref{while do, Iteration})
-
-@node Internal Definitions
-@section Internal definitions
-
-@c FIXME::martin: Review me!
-
-A @code{define} form which appears inside the body of a @code{lambda},
-@code{let}, @code{let*}, @code{letrec} or equivalent expression is
-called an @dfn{internal definition}. An internal definition differs
-from a top level definition (@pxref{Top Level}), because the definition
-is only visible inside the complete body of the enclosing form. Let us
-examine the following example.
-
-@lisp
-(let ((frumble "froz"))
- (define banana (lambda () (apple 'peach)))
- (define apple (lambda (x) x))
- (banana))
-@result{}
-peach
-@end lisp
-
-Here the enclosing form is a @code{let}, so the @code{define}s in the
-@code{let}-body are internal definitions. Because the scope of the
-internal definitions is the @strong{complete} body of the
-@code{let}-expression, the @code{lambda}-expression which gets bound
-to the variable @code{banana} may refer to the variable @code{apple},
-even though it's definition appears lexically @emph{after} the definition
-of @code{banana}. This is because a sequence of internal definition
-acts as if it were a @code{letrec} expression.
-
-@lisp
-(let ()
- (define a 1)
- (define b 2)
- (+ a b))
-@end lisp
-
-@noindent
-is equivalent to
-
-@lisp
-(let ()
- (letrec ((a 1) (b 2))
- (+ a b)))
-@end lisp
-
-Another noteworthy difference to top level definitions is that within
-one group of internal definitions all variable names must be distinct.
-That means where on the top level a second define for a given variable
-acts like a @code{set!}, an exception is thrown for internal definitions
-with duplicate bindings.
-
-@c FIXME::martin: The following is required by R5RS, but Guile does not
-@c signal an error. Document it anyway, saying that Guile is sloppy?
-
-@c Internal definitions are only allowed at the beginning of the body of an
-@c enclosing expression. They may not be mixed with other expressions.
-
-@c @lisp
-@c (let ()
-@c (define a 1)
-@c a
-@c (define b 2)
-@c b)
-@c @end lisp
-
-@node Binding Reflection
-@section Querying variable bindings
-
-Guile provides a procedure for checking whether a symbol is bound in the
-top level environment. If you want to test whether a symbol is locally
-bound in expression, you can use the @code{bound?} macro from the module
-@code{(ice-9 optargs)}, documented in @ref{Optional Arguments}.
-
-@c NJFIXME explain [env]
-@deffn {Scheme Procedure} defined? sym [env]
-@deffnx {C Function} scm_definedp (sym, env)
-Return @code{#t} if @var{sym} is defined in the lexical environment @var{env}. When @var{env} is not specified, look in the top-level environment as defined by the current module.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-compound.texi b/doc/ref/scheme-compound.texi
deleted file mode 100644
index b39ea76ca..000000000
--- a/doc/ref/scheme-compound.texi
+++ /dev/null
@@ -1,2431 +0,0 @@
-@page
-@node Compound Data Types
-@chapter Compound Data Types
-
-This chapter describes Guile's compound data types. By @dfn{compound}
-we mean that the primary purpose of these data types is to act as
-containers for other kinds of data (including other compound objects).
-For instance, a (non-uniform) vector with length 5 is a container that
-can hold five arbitrary Scheme objects.
-
-The various kinds of container object differ from each other in how
-their memory is allocated, how they are indexed, and how particular
-values can be looked up within them.
-
-@menu
-* Pairs:: Scheme's basic building block.
-* Lists:: Special list functions supported by Guile.
-* Vectors:: One-dimensional arrays of Scheme objects.
-* Records::
-* Structures::
-* Arrays:: Arrays of values.
-* Association Lists and Hash Tables:: Dictionary data types.
-@end menu
-
-
-@node Pairs
-@section Pairs
-@tpindex Pairs
-
-Pairs are used to combine two Scheme objects into one compound object.
-Hence the name: A pair stores a pair of objects.
-
-The data type @dfn{pair} is extremely important in Scheme, just like in
-any other Lisp dialect. The reason is that pairs are not only used to
-make two values available as one object, but that pairs are used for
-constructing lists of values. Because lists are so important in Scheme,
-they are described in a section of their own (@pxref{Lists}).
-
-Pairs can literally get entered in source code or at the REPL, in the
-so-called @dfn{dotted list} syntax. This syntax consists of an opening
-parentheses, the first element of the pair, a dot, the second element
-and a closing parentheses. The following example shows how a pair
-consisting of the two numbers 1 and 2, and a pair containing the symbols
-@code{foo} and @code{bar} can be entered. It is very important to write
-the whitespace before and after the dot, because otherwise the Scheme
-parser would not be able to figure out where to split the tokens.
-
-@lisp
-(1 . 2)
-(foo . bar)
-@end lisp
-
-But beware, if you want to try out these examples, you have to
-@dfn{quote} the expressions. More information about quotation is
-available in the section (REFFIXME). The correct way to try these
-examples is as follows.
-
-@lisp
-'(1 . 2)
-@result{}
-(1 . 2)
-'(foo . bar)
-@result{}
-(foo . bar)
-@end lisp
-
-A new pair is made by calling the procedure @code{cons} with two
-arguments. Then the argument values are stored into a newly allocated
-pair, and the pair is returned. The name @code{cons} stands for
-"construct". Use the procedure @code{pair?} to test whether a
-given Scheme object is a pair or not.
-
-@rnindex cons
-@deffn {Scheme Procedure} cons x y
-@deffnx {C Function} scm_cons (x, y)
-Return a newly allocated pair whose car is @var{x} and whose
-cdr is @var{y}. The pair is guaranteed to be different (in the
-sense of @code{eq?}) from every previously existing object.
-@end deffn
-
-@rnindex pair?
-@deffn {Scheme Procedure} pair? x
-@deffnx {C Function} scm_pair_p (x)
-Return @code{#t} if @var{x} is a pair; otherwise return
-@code{#f}.
-@end deffn
-
-The two parts of a pair are traditionally called @dfn{car} and
-@dfn{cdr}. They can be retrieved with procedures of the same name
-(@code{car} and @code{cdr}), and can be modified with the procedures
-@code{set-car!} and @code{set-cdr!}. Since a very common operation in
-Scheme programs is to access the car of a pair, or the car of the cdr of
-a pair, etc., the procedures called @code{caar}, @code{cadr} and so on
-are also predefined.
-
-@rnindex car
-@rnindex cdr
-@deffn {Scheme Procedure} car pair
-@deffnx {Scheme Procedure} cdr pair
-Return the car or the cdr of @var{pair}, respectively.
-@end deffn
-
-@deffn {Scheme Procedure} caar pair
-@deffnx {Scheme Procedure} cadr pair @dots{}
-@deffnx {Scheme Procedure} cdddar pair
-@deffnx {Scheme Procedure} cddddr pair
-These procedures are compositions of @code{car} and @code{cdr}, where
-for example @code{caddr} could be defined by
-
-@lisp
-(define caddr (lambda (x) (car (cdr (cdr x)))))
-@end lisp
-@end deffn
-
-@rnindex set-car!
-@deffn {Scheme Procedure} set-car! pair value
-@deffnx {C Function} scm_set_car_x (pair, value)
-Stores @var{value} in the car field of @var{pair}. The value returned
-by @code{set-car!} is unspecified.
-@end deffn
-
-@rnindex set-cdr!
-@deffn {Scheme Procedure} set-cdr! pair value
-@deffnx {C Function} scm_set_cdr_x (pair, value)
-Stores @var{value} in the cdr field of @var{pair}. The value returned
-by @code{set-cdr!} is unspecified.
-@end deffn
-
-
-@node Lists
-@section Lists
-@tpindex Lists
-
-A very important data type in Scheme---as well as in all other Lisp
-dialects---is the data type @dfn{list}.@footnote{Strictly speaking,
-Scheme does not have a real datatype @dfn{list}. Lists are made up of
-@dfn{chained pairs}, and only exist by definition---a list is a chain
-of pairs which looks like a list.}
-
-This is the short definition of what a list is:
-
-@itemize @bullet
-@item
-Either the empty list @code{()},
-
-@item
-or a pair which has a list in its cdr.
-@end itemize
-
-@c FIXME::martin: Describe the pair chaining in more detail.
-
-@c FIXME::martin: What is a proper, what an improper list?
-@c What is a circular list?
-
-@c FIXME::martin: Maybe steal some graphics from the Elisp reference
-@c manual?
-
-@menu
-* List Syntax:: Writing literal lists.
-* List Predicates:: Testing lists.
-* List Constructors:: Creating new lists.
-* List Selection:: Selecting from lists, getting their length.
-* Append/Reverse:: Appending and reversing lists.
-* List Modification:: Modifying existing lists.
-* List Searching:: Searching for list elements
-* List Mapping:: Applying procedures to lists.
-@end menu
-
-@node List Syntax
-@subsection List Read Syntax
-
-The syntax for lists is an opening parentheses, then all the elements of
-the list (separated by whitespace) and finally a closing
-parentheses.@footnote{Note that there is no separation character between
-the list elements, like a comma or a semicolon.}.
-
-@lisp
-(1 2 3) ; @r{a list of the numbers 1, 2 and 3}
-("foo" bar 3.1415) ; @r{a string, a symbol and a real number}
-() ; @r{the empty list}
-@end lisp
-
-The last example needs a bit more explanation. A list with no elements,
-called the @dfn{empty list}, is special in some ways. It is used for
-terminating lists by storing it into the cdr of the last pair that makes
-up a list. An example will clear that up:
-
-@lisp
-(car '(1))
-@result{}
-1
-(cdr '(1))
-@result{}
-()
-@end lisp
-
-This example also shows that lists have to be quoted (REFFIXME) when
-written, because they would otherwise be mistakingly taken as procedure
-applications (@pxref{Simple Invocation}).
-
-
-@node List Predicates
-@subsection List Predicates
-
-Often it is useful to test whether a given Scheme object is a list or
-not. List-processing procedures could use this information to test
-whether their input is valid, or they could do different things
-depending on the datatype of their arguments.
-
-@rnindex list?
-@deffn {Scheme Procedure} list? x
-@deffnx {C Function} scm_list_p (x)
-Return @code{#t} iff @var{x} is a proper list, else @code{#f}.
-@end deffn
-
-The predicate @code{null?} is often used in list-processing code to
-tell whether a given list has run out of elements. That is, a loop
-somehow deals with the elements of a list until the list satisfies
-@code{null?}. Then, the algorithm terminates.
-
-@rnindex null?
-@deffn {Scheme Procedure} null? x
-@deffnx {C Function} scm_null_p (x)
-Return @code{#t} iff @var{x} is the empty list, else @code{#f}.
-@end deffn
-
-@node List Constructors
-@subsection List Constructors
-
-This section describes the procedures for constructing new lists.
-@code{list} simply returns a list where the elements are the arguments,
-@code{cons*} is similar, but the last argument is stored in the cdr of
-the last pair of the list.
-
-@rnindex list
-@deffn {Scheme Procedure} list . objs
-@deffnx {C Function} scm_list (objs)
-Return a list containing @var{objs}, the arguments to
-@code{list}.
-@end deffn
-
-@deffn {Scheme Procedure} cons* arg1 arg2 @dots{}
-@deffnx {C Function} scm_cons_star (arg1, rest)
-Like @code{list}, but the last arg provides the tail of the
-constructed list, returning @code{(cons @var{arg1} (cons
-@var{arg2} (cons @dots{} @var{argn})))}. Requires at least one
-argument. If given one argument, that argument is returned as
-result. This function is called @code{list*} in some other
-Schemes and in Common LISP.
-@end deffn
-
-@deffn {Scheme Procedure} list-copy lst
-@deffnx {C Function} scm_list_copy (lst)
-Return a (newly-created) copy of @var{lst}.
-@end deffn
-
-@deffn {Scheme Procedure} make-list n [init]
-Create a list containing of @var{n} elements, where each element is
-initialized to @var{init}. @var{init} defaults to the empty list
-@code{()} if not given.
-@end deffn
-
-Note that @code{list-copy} only makes a copy of the pairs which make up
-the spine of the lists. The list elements are not copied, which means
-that modifying the elements of the new list also modifies the elements
-of the old list. On the other hand, applying procedures like
-@code{set-cdr!} or @code{delv!} to the new list will not alter the old
-list. If you also need to copy the list elements (making a deep copy),
-use the procedure @code{copy-tree} (@pxref{Copying}).
-
-@node List Selection
-@subsection List Selection
-
-These procedures are used to get some information about a list, or to
-retrieve one or more elements of a list.
-
-@rnindex length
-@deffn {Scheme Procedure} length lst
-@deffnx {C Function} scm_length (lst)
-Return the number of elements in list @var{lst}.
-@end deffn
-
-@deffn {Scheme Procedure} last-pair lst
-@deffnx {C Function} scm_last_pair (lst)
-Return a pointer to the last pair in @var{lst}, signalling an error if
-@var{lst} is circular.
-@end deffn
-
-@rnindex list-ref
-@deffn {Scheme Procedure} list-ref list k
-@deffnx {C Function} scm_list_ref (list, k)
-Return the @var{k}th element from @var{list}.
-@end deffn
-
-@rnindex list-tail
-@deffn {Scheme Procedure} list-tail lst k
-@deffnx {Scheme Procedure} list-cdr-ref lst k
-@deffnx {C Function} scm_list_tail (lst, k)
-Return the "tail" of @var{lst} beginning with its @var{k}th element.
-The first element of the list is considered to be element 0.
-
-@code{list-tail} and @code{list-cdr-ref} are identical. It may help to
-think of @code{list-cdr-ref} as accessing the @var{k}th cdr of the list,
-or returning the results of cdring @var{k} times down @var{lst}.
-@end deffn
-
-@deffn {Scheme Procedure} list-head lst k
-@deffnx {C Function} scm_list_head (lst, k)
-Copy the first @var{k} elements from @var{lst} into a new list, and
-return it.
-@end deffn
-
-@node Append/Reverse
-@subsection Append and Reverse
-
-@code{append} and @code{append!} are used to concatenate two or more
-lists in order to form a new list. @code{reverse} and @code{reverse!}
-return lists with the same elements as their arguments, but in reverse
-order. The procedure variants with an @code{!} directly modify the
-pairs which form the list, whereas the other procedures create new
-pairs. This is why you should be careful when using the side-effecting
-variants.
-
-@rnindex append
-@deffn {Scheme Procedure} append . args
-@deffnx {C Function} scm_append (args)
-Return a list consisting of the elements the lists passed as
-arguments.
-@lisp
-(append '(x) '(y)) @result{} (x y)
-(append '(a) '(b c d)) @result{} (a b c d)
-(append '(a (b)) '((c))) @result{} (a (b) (c))
-@end lisp
-The resulting list is always newly allocated, except that it
-shares structure with the last list argument. The last
-argument may actually be any object; an improper list results
-if the last argument is not a proper list.
-@lisp
-(append '(a b) '(c . d)) @result{} (a b c . d)
-(append '() 'a) @result{} a
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} append! . lists
-@deffnx {C Function} scm_append_x (lists)
-A destructive version of @code{append} (@pxref{Pairs and
-lists,,,r5rs, The Revised^5 Report on Scheme}). The cdr field
-of each list's final pair is changed to point to the head of
-the next list, so no consing is performed. Return a pointer to
-the mutated list.
-@end deffn
-
-@rnindex reverse
-@deffn {Scheme Procedure} reverse lst
-@deffnx {C Function} scm_reverse (lst)
-Return a new list that contains the elements of @var{lst} but
-in reverse order.
-@end deffn
-
-@c NJFIXME explain new_tail
-@deffn {Scheme Procedure} reverse! lst [new_tail]
-@deffnx {C Function} scm_reverse_x (lst, new_tail)
-A destructive version of @code{reverse} (@pxref{Pairs and lists,,,r5rs,
-The Revised^5 Report on Scheme}). The cdr of each cell in @var{lst} is
-modified to point to the previous list element. Return a pointer to the
-head of the reversed list.
-
-Caveat: because the list is modified in place, the tail of the original
-list now becomes its head, and the head of the original list now becomes
-the tail. Therefore, the @var{lst} symbol to which the head of the
-original list was bound now points to the tail. To ensure that the head
-of the modified list is not lost, it is wise to save the return value of
-@code{reverse!}
-@end deffn
-
-@node List Modification
-@subsection List Modification
-
-The following procedures modify an existing list, either by changing
-elements of the list, or by changing the list structure itself.
-
-@deffn {Scheme Procedure} list-set! list k val
-@deffnx {C Function} scm_list_set_x (list, k, val)
-Set the @var{k}th element of @var{list} to @var{val}.
-@end deffn
-
-@deffn {Scheme Procedure} list-cdr-set! list k val
-@deffnx {C Function} scm_list_cdr_set_x (list, k, val)
-Set the @var{k}th cdr of @var{list} to @var{val}.
-@end deffn
-
-@deffn {Scheme Procedure} delq item lst
-@deffnx {C Function} scm_delq (item, lst)
-Return a newly-created copy of @var{lst} with elements
-@code{eq?} to @var{item} removed. This procedure mirrors
-@code{memq}: @code{delq} compares elements of @var{lst} against
-@var{item} with @code{eq?}.
-@end deffn
-
-@deffn {Scheme Procedure} delv item lst
-@deffnx {C Function} scm_delv (item, lst)
-Return a newly-created copy of @var{lst} with elements
-@code{eqv?} to @var{item} removed. This procedure mirrors
-@code{memv}: @code{delv} compares elements of @var{lst} against
-@var{item} with @code{eqv?}.
-@end deffn
-
-@deffn {Scheme Procedure} delete item lst
-@deffnx {C Function} scm_delete (item, lst)
-Return a newly-created copy of @var{lst} with elements
-@code{equal?} to @var{item} removed. This procedure mirrors
-@code{member}: @code{delete} compares elements of @var{lst}
-against @var{item} with @code{equal?}.
-@end deffn
-
-@deffn {Scheme Procedure} delq! item lst
-@deffnx {Scheme Procedure} delv! item lst
-@deffnx {Scheme Procedure} delete! item lst
-@deffnx {C Function} scm_delq_x (item, lst)
-@deffnx {C Function} scm_delv_x (item, lst)
-@deffnx {C Function} scm_delete_x (item, lst)
-These procedures are destructive versions of @code{delq}, @code{delv}
-and @code{delete}: they modify the pointers in the existing @var{lst}
-rather than creating a new list. Caveat evaluator: Like other
-destructive list functions, these functions cannot modify the binding of
-@var{lst}, and so cannot be used to delete the first element of
-@var{lst} destructively.
-@end deffn
-
-@deffn {Scheme Procedure} delq1! item lst
-@deffnx {C Function} scm_delq1_x (item, lst)
-Like @code{delq!}, but only deletes the first occurrence of
-@var{item} from @var{lst}. Tests for equality using
-@code{eq?}. See also @code{delv1!} and @code{delete1!}.
-@end deffn
-
-@deffn {Scheme Procedure} delv1! item lst
-@deffnx {C Function} scm_delv1_x (item, lst)
-Like @code{delv!}, but only deletes the first occurrence of
-@var{item} from @var{lst}. Tests for equality using
-@code{eqv?}. See also @code{delq1!} and @code{delete1!}.
-@end deffn
-
-@deffn {Scheme Procedure} delete1! item lst
-@deffnx {C Function} scm_delete1_x (item, lst)
-Like @code{delete!}, but only deletes the first occurrence of
-@var{item} from @var{lst}. Tests for equality using
-@code{equal?}. See also @code{delq1!} and @code{delv1!}.
-@end deffn
-
-@node List Searching
-@subsection List Searching
-
-The following procedures search lists for particular elements. They use
-different comparison predicates for comparing list elements with the
-object to be searched. When they fail, they return @code{#f}, otherwise
-they return the sublist whose car is equal to the search object, where
-equality depends on the equality predicate used.
-
-@rnindex memq
-@deffn {Scheme Procedure} memq x lst
-@deffnx {C Function} scm_memq (x, lst)
-Return the first sublist of @var{lst} whose car is @code{eq?}
-to @var{x} where the sublists of @var{lst} are the non-empty
-lists returned by @code{(list-tail @var{lst} @var{k})} for
-@var{k} less than the length of @var{lst}. If @var{x} does not
-occur in @var{lst}, then @code{#f} (not the empty list) is
-returned.
-@end deffn
-
-@rnindex memv
-@deffn {Scheme Procedure} memv x lst
-@deffnx {C Function} scm_memv (x, lst)
-Return the first sublist of @var{lst} whose car is @code{eqv?}
-to @var{x} where the sublists of @var{lst} are the non-empty
-lists returned by @code{(list-tail @var{lst} @var{k})} for
-@var{k} less than the length of @var{lst}. If @var{x} does not
-occur in @var{lst}, then @code{#f} (not the empty list) is
-returned.
-@end deffn
-
-@rnindex member
-@deffn {Scheme Procedure} member x lst
-@deffnx {C Function} scm_member (x, lst)
-Return the first sublist of @var{lst} whose car is
-@code{equal?} to @var{x} where the sublists of @var{lst} are
-the non-empty lists returned by @code{(list-tail @var{lst}
-@var{k})} for @var{k} less than the length of @var{lst}. If
-@var{x} does not occur in @var{lst}, then @code{#f} (not the
-empty list) is returned.
-@end deffn
-
-
-@node List Mapping
-@subsection List Mapping
-
-List processing is very convenient in Scheme because the process of
-iterating over the elements of a list can be highly abstracted. The
-procedures in this section are the most basic iterating procedures for
-lists. They take a procedure and one or more lists as arguments, and
-apply the procedure to each element of the list. They differ in their
-return value.
-
-@rnindex map
-@c begin (texi-doc-string "guile" "map")
-@deffn {Scheme Procedure} map proc arg1 arg2 @dots{}
-@deffnx {Scheme Procedure} map-in-order proc arg1 arg2 @dots{}
-@deffnx {C Function} scm_map (proc, arg1, args)
-Apply @var{proc} to each element of the list @var{arg1} (if only two
-arguments are given), or to the corresponding elements of the argument
-lists (if more than two arguments are given). The result(s) of the
-procedure applications are saved and returned in a list. For
-@code{map}, the order of procedure applications is not specified,
-@code{map-in-order} applies the procedure from left to right to the list
-elements.
-@end deffn
-
-@rnindex for-each
-@c begin (texi-doc-string "guile" "for-each")
-@deffn {Scheme Procedure} for-each proc arg1 arg2 @dots{}
-Like @code{map}, but the procedure is always applied from left to right,
-and the result(s) of the procedure applications are thrown away. The
-return value is not specified.
-@end deffn
-
-
-@node Vectors
-@section Vectors
-@tpindex Vectors
-
-Vectors are sequences of Scheme objects. Unlike lists, the length of a
-vector, once the vector is created, cannot be changed. The advantage of
-vectors over lists is that the time required to access one element of a vector
-given its @dfn{position} (synonymous with @dfn{index}), a zero-origin number,
-is constant, whereas lists have an access time linear to the position of the
-accessed element in the list.
-
-Vectors can contain any kind of Scheme object; it is even possible to have
-different types of objects in the same vector. For vectors containing
-vectors, you may wish to use arrays, instead. Note, too, that some array
-procedures operate happily on vectors (@pxref{Arrays}).
-
-@menu
-* Vector Syntax:: Read syntax for vectors.
-* Vector Creation:: Dynamic vector creation and validation.
-* Vector Accessors:: Accessing and modifying vector contents.
-@end menu
-
-
-@node Vector Syntax
-@subsection Read Syntax for Vectors
-
-Vectors can literally be entered in source code, just like strings,
-characters or some of the other data types. The read syntax for vectors
-is as follows: A sharp sign (@code{#}), followed by an opening
-parentheses, all elements of the vector in their respective read syntax,
-and finally a closing parentheses. The following are examples of the
-read syntax for vectors; where the first vector only contains numbers
-and the second three different object types: a string, a symbol and a
-number in hexadecimal notation.
-
-@lisp
-#(1 2 3)
-#("Hello" foo #xdeadbeef)
-@end lisp
-
-
-@node Vector Creation
-@subsection Dynamic Vector Creation and Validation
-
-Instead of creating a vector implicitly by using the read syntax just
-described, you can create a vector dynamically by calling one of the
-@code{vector} and @code{list->vector} primitives with the list of Scheme
-values that you want to place into a vector. The size of the vector
-thus created is determined implicitly by the number of arguments given.
-
-@rnindex vector
-@rnindex list->vector
-@deffn {Scheme Procedure} vector . l
-@deffnx {Scheme Procedure} list->vector l
-@deffnx {C Function} scm_vector (l)
-Return a newly allocated vector composed of the
-given arguments. Analogous to @code{list}.
-
-@lisp
-(vector 'a 'b 'c) @result{} #(a b c)
-@end lisp
-@end deffn
-
-(As an aside, an interesting implementation detail is that the Guile
-reader reads the @code{#(@dots{})} syntax by reading everything but the
-initial @code{#} as a @emph{list}, and then passing the list that
-results to @code{list->vector}. Notice how neatly this fits with the
-similarity between the read (and print) syntaxes for lists and vectors.)
-
-The inverse operation is @code{vector->list}:
-
-@rnindex vector->list
-@deffn {Scheme Procedure} vector->list v
-@deffnx {C Function} scm_vector_to_list (v)
-Return a newly allocated list composed of the elements of @var{v}.
-
-@lisp
-(vector->list '#(dah dah didah)) @result{} (dah dah didah)
-(list->vector '(dididit dah)) @result{} #(dididit dah)
-@end lisp
-@end deffn
-
-To allocate a vector with an explicitly specified size, use
-@code{make-vector}. With this primitive you can also specify an initial
-value for the vector elements (the same value for all elements, that
-is):
-
-@rnindex make-vector
-@deffn {Scheme Procedure} make-vector k [fill]
-@deffnx {C Function} scm_make_vector (k, fill)
-Return a newly allocated vector of @var{k} elements. If a
-second argument is given, then each position is initialized to
-@var{fill}. Otherwise the initial contents of each position is
-unspecified.
-@end deffn
-
-To check whether an arbitrary Scheme value @emph{is} a vector, use the
-@code{vector?} primitive:
-
-@rnindex vector?
-@deffn {Scheme Procedure} vector? obj
-@deffnx {C Function} scm_vector_p (obj)
-Return @code{#t} if @var{obj} is a vector, otherwise return
-@code{#f}.
-@end deffn
-
-
-@node Vector Accessors
-@subsection Accessing and Modifying Vector Contents
-
-@code{vector-length} and @code{vector-ref} return information about a
-given vector, respectively its size and the elements that are contained
-in the vector.
-
-@rnindex vector-length
-@deffn {Scheme Procedure} vector-length vector
-@deffnx {C Function} scm_vector_length vector
-Return the number of elements in @var{vector} as an exact integer.
-@end deffn
-
-@rnindex vector-ref
-@deffn {Scheme Procedure} vector-ref vector k
-@deffnx {C Function} scm_vector_ref vector k
-Return the contents of position @var{k} of @var{vector}.
-@var{k} must be a valid index of @var{vector}.
-@lisp
-(vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
-(vector-ref '#(1 1 2 3 5 8 13 21)
- (let ((i (round (* 2 (acos -1)))))
- (if (inexact? i)
- (inexact->exact i)
- i))) @result{} 13
-@end lisp
-@end deffn
-
-A vector created by one of the dynamic vector constructor procedures
-(@pxref{Vector Creation}) can be modified using the following
-procedures.
-
-@emph{NOTE:} According to R5RS, it is an error to use any of these
-procedures on a literally read vector, because such vectors should be
-considered as constants. Currently, however, Guile does not detect this
-error.
-
-@rnindex vector-set!
-@deffn {Scheme Procedure} vector-set! vector k obj
-@deffnx {C Function} scm_vector_set_x vector k obj
-Store @var{obj} in position @var{k} of @var{vector}.
-@var{k} must be a valid index of @var{vector}.
-The value returned by @samp{vector-set!} is unspecified.
-@lisp
-(let ((vec (vector 0 '(2 2 2 2) "Anna")))
- (vector-set! vec 1 '("Sue" "Sue"))
- vec) @result{} #(0 ("Sue" "Sue") "Anna")
-@end lisp
-@end deffn
-
-@rnindex vector-fill!
-@deffn {Scheme Procedure} vector-fill! v fill
-@deffnx {C Function} scm_vector_fill_x (v, fill)
-Store @var{fill} in every position of @var{vector}. The value
-returned by @code{vector-fill!} is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} vector-move-left! vec1 start1 end1 vec2 start2
-@deffnx {C Function} scm_vector_move_left_x (vec1, start1, end1, vec2, start2)
-Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
-to @var{vec2} starting at position @var{start2}. @var{start1} and
-@var{start2} are inclusive indices; @var{end1} is exclusive.
-
-@code{vector-move-left!} copies elements in leftmost order.
-Therefore, in the case where @var{vec1} and @var{vec2} refer to the
-same vector, @code{vector-move-left!} is usually appropriate when
-@var{start1} is greater than @var{start2}.
-@end deffn
-
-@deffn {Scheme Procedure} vector-move-right! vec1 start1 end1 vec2 start2
-@deffnx {C Function} scm_vector_move_right_x (vec1, start1, end1, vec2, start2)
-Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
-to @var{vec2} starting at position @var{start2}. @var{start1} and
-@var{start2} are inclusive indices; @var{end1} is exclusive.
-
-@code{vector-move-right!} copies elements in rightmost order.
-Therefore, in the case where @var{vec1} and @var{vec2} refer to the
-same vector, @code{vector-move-right!} is usually appropriate when
-@var{start1} is less than @var{start2}.
-@end deffn
-
-
-@node Records
-@section Records
-
-A @dfn{record type} is a first class object representing a user-defined
-data type. A @dfn{record} is an instance of a record type.
-
-@deffn {Scheme Procedure} record? obj
-Return @code{#t} if @var{obj} is a record of any type and @code{#f}
-otherwise.
-
-Note that @code{record?} may be true of any Scheme value; there is no
-promise that records are disjoint with other Scheme types.
-@end deffn
-
-@deffn {Scheme Procedure} make-record-type type-name field-names
-Return 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. It is
-unspecified how record-type descriptors are represented.
-@end deffn
-
-@deffn {Scheme Procedure} record-constructor rtd [field-names]
-Return 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
-@code{make-record-type} 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.
-@end deffn
-
-@deffn {Scheme Procedure} record-predicate rtd
-Return a procedure for testing membership in the type represented by
-@var{rtd}. 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.
-@end deffn
-
-@deffn {Scheme Procedure} record-accessor rtd field-name
-Return 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
-@var{field-name} 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}.
-@end deffn
-
-@deffn {Scheme Procedure} record-modifier rtd field-name
-Return 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
-@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}.
-@end deffn
-
-@deffn {Scheme Procedure} record-type-descriptor record
-Return a record-type descriptor representing the type of the given
-record. That is, for example, if the returned descriptor were passed to
-@code{record-predicate}, the resulting predicate would return a true
-value when passed the given record. Note that it is not necessarily the
-case that the returned descriptor is the one that was passed to
-@code{record-constructor} in the call that created the constructor
-procedure that created the given record.
-@end deffn
-
-@deffn {Scheme Procedure} record-type-name rtd
-Return 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
-@var{rtd}.
-@end deffn
-
-@deffn {Scheme Procedure} record-type-fields rtd
-Return 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 @var{rtd}.
-@end deffn
-
-
-@node Structures
-@section Structures
-@tpindex Structures
-
-[FIXME: this is pasted in from Tom Lord's original guile.texi and should
-be reviewed]
-
-A @dfn{structure type} is a first class user-defined data type. A
-@dfn{structure} is an instance of a structure type. A structure type is
-itself a structure.
-
-Structures are less abstract and more general than traditional records.
-In fact, in Guile Scheme, records are implemented using structures.
-
-@menu
-* Structure Concepts:: The structure of Structures
-* Structure Layout:: Defining the layout of structure types
-* Structure Basics:: make-, -ref and -set! procedures for structs
-* Vtables:: Accessing type-specific data
-@end menu
-
-@node Structure Concepts
-@subsection Structure Concepts
-
-A structure object consists of a handle, structure data, and a vtable.
-The handle is a Scheme value which points to both the vtable and the
-structure's data. Structure data is a dynamically allocated region of
-memory, private to the structure, divided up into typed fields. A
-vtable is another structure used to hold type-specific data. Multiple
-structures can share a common vtable.
-
-Three concepts are key to understanding structures.
-
-@itemize @bullet{}
-@item @dfn{layout specifications}
-
-Layout specifications determine how memory allocated to structures is
-divided up into fields. Programmers must write a layout specification
-whenever a new type of structure is defined.
-
-@item @dfn{structural accessors}
-
-Structure access is by field number. There is only one set of
-accessors common to all structure objects.
-
-@item @dfn{vtables}
-
-Vtables, themselves structures, are first class representations of
-disjoint sub-types of structures in general. In most cases, when a
-new structure is created, programmers must specify a vtable for the
-new structure. Each vtable has a field describing the layout of its
-instances. Vtables can have additional, user-defined fields as well.
-@end itemize
-
-
-
-@node Structure Layout
-@subsection Structure Layout
-
-When a structure is created, a region of memory is allocated to hold its
-state. The @dfn{layout} of the structure's type determines how that
-memory is divided into fields.
-
-Each field has a specified type. There are only three types allowed, each
-corresponding to a one letter code. The allowed types are:
-
-@itemize @bullet{}
-@item 'u' -- unprotected
-
-The field holds binary data that is not GC protected.
-
-@item 'p' -- protected
-
-The field holds a Scheme value and is GC protected.
-
-@item 's' -- self
-
-The field holds a Scheme value and is GC protected. When a structure is
-created with this type of field, the field is initialized to refer to
-the structure's own handle. This kind of field is mainly useful when
-mixing Scheme and C code in which the C code may need to compute a
-structure's handle given only the address of its malloc'd data.
-@end itemize
-
-
-Each field also has an associated access protection. There are only
-three kinds of protection, each corresponding to a one letter code.
-The allowed protections are:
-
-@itemize @bullet{}
-@item 'w' -- writable
-
-The field can be read and written.
-
-@item 'r' -- readable
-
-The field can be read, but not written.
-
-@item 'o' -- opaque
-
-The field can be neither read nor written. This kind
-of protection is for fields useful only to built-in routines.
-@end itemize
-
-A layout specification is described by stringing together pairs
-of letters: one to specify a field type and one to specify a field
-protection. For example, a traditional cons pair type object could
-be described as:
-
-@example
-; cons pairs have two writable fields of Scheme data
-"pwpw"
-@end example
-
-A pair object in which the first field is held constant could be:
-
-@example
-"prpw"
-@end example
-
-Binary fields, (fields of type "u"), hold one @dfn{word} each. The
-size of a word is a machine dependent value defined to be equal to the
-value of the C expression: @code{sizeof (long)}.
-
-The last field of a structure layout may specify a tail array.
-A tail array is indicated by capitalizing the field's protection
-code ('W', 'R' or 'O'). A tail-array field is replaced by
-a read-only binary data field containing an array size. The array
-size is determined at the time the structure is created. It is followed
-by a corresponding number of fields of the type specified for the
-tail array. For example, a conventional Scheme vector can be
-described as:
-
-@example
-; A vector is an arbitrary number of writable fields holding Scheme
-; values:
-"pW"
-@end example
-
-In the above example, field 0 contains the size of the vector and
-fields beginning at 1 contain the vector elements.
-
-A kind of tagged vector (a constant tag followed by conventional
-vector elements) might be:
-
-@example
-"prpW"
-@end example
-
-
-Structure layouts are represented by specially interned symbols whose
-name is a string of type and protection codes. To create a new
-structure layout, use this procedure:
-
-@deffn {Scheme Procedure} make-struct-layout fields
-@deffnx {C Function} scm_make_struct_layout (fields)
-Return a new structure layout object.
-
-@var{fields} must be a string made up of pairs of characters
-strung together. The first character of each pair describes a field
-type, the second a field protection. Allowed types are 'p' for
-GC-protected Scheme data, 'u' for unprotected binary data, and 's' for
-a field that points to the structure itself. Allowed protections
-are 'w' for mutable fields, 'r' for read-only fields, and 'o' for opaque
-fields. The last field protection specification may be capitalized to
-indicate that the field is a tail-array.
-@end deffn
-
-
-
-@node Structure Basics
-@subsection Structure Basics
-
-This section describes the basic procedures for creating and accessing
-structures.
-
-@deffn {Scheme Procedure} make-struct vtable tail_array_size . init
-@deffnx {C Function} scm_make_struct (vtable, tail_array_size, init)
-Create a new structure.
-
-@var{type} must be a vtable structure (@pxref{Vtables}).
-
-@var{tail-elts} must be a non-negative integer. If the layout
-specification indicated by @var{type} includes a tail-array,
-this is the number of elements allocated to that array.
-
-The @var{init1}, @dots{} are optional arguments describing how
-successive fields of the structure should be initialized. Only fields
-with protection 'r' or 'w' can be initialized, except for fields of
-type 's', which are automatically initialized to point to the new
-structure itself; fields with protection 'o' can not be initialized by
-Scheme programs.
-
-If fewer optional arguments than initializable fields are supplied,
-fields of type 'p' get default value #f while fields of type 'u' are
-initialized to 0.
-
-Structs are currently the basic representation for record-like data
-structures in Guile. The plan is to eventually replace them with a
-new representation which will at the same time be easier to use and
-more powerful.
-
-For more information, see the documentation for @code{make-vtable-vtable}.
-@end deffn
-
-@deffn {Scheme Procedure} struct? x
-@deffnx {C Function} scm_struct_p (x)
-Return @code{#t} iff @var{x} is a structure object, else
-@code{#f}.
-@end deffn
-
-
-@deffn {Scheme Procedure} struct-ref handle pos
-@deffnx {Scheme Procedure} struct-set! struct n value
-@deffnx {C Function} scm_struct_ref (handle, pos)
-@deffnx {C Function} scm_struct_set_x (struct, n, value)
-Access (or modify) the @var{n}th field of @var{struct}.
-
-If the field is of type 'p', then it can be set to an arbitrary value.
-
-If the field is of type 'u', then it can only be set to a non-negative
-integer value small enough to fit in one machine word.
-@end deffn
-
-
-
-@node Vtables
-@subsection Vtables
-
-Vtables are structures that are used to represent structure types. Each
-vtable contains a layout specification in field
-@code{vtable-index-layout} -- instances of the type are laid out
-according to that specification. Vtables contain additional fields
-which are used only internally to libguile. The variable
-@code{vtable-offset-user} is bound to a field number. Vtable fields
-at that position or greater are user definable.
-
-@deffn {Scheme Procedure} struct-vtable handle
-@deffnx {C Function} scm_struct_vtable (handle)
-Return the vtable structure that describes the type of @var{struct}.
-@end deffn
-
-@deffn {Scheme Procedure} struct-vtable? x
-@deffnx {C Function} scm_struct_vtable_p (x)
-Return @code{#t} iff @var{x} is a vtable structure.
-@end deffn
-
-If you have a vtable structure, @code{V}, you can create an instance of
-the type it describes by using @code{(make-struct V ...)}. But where
-does @code{V} itself come from? One possibility is that @code{V} is an
-instance of a user-defined vtable type, @code{V'}, so that @code{V} is
-created by using @code{(make-struct V' ...)}. Another possibility is
-that @code{V} is an instance of the type it itself describes. Vtable
-structures of the second sort are created by this procedure:
-
-@deffn {Scheme Procedure} make-vtable-vtable user_fields tail_array_size . init
-@deffnx {C Function} scm_make_vtable_vtable (user_fields, tail_array_size, init)
-Return a new, self-describing vtable structure.
-
-@var{user-fields} is a string describing user defined fields of the
-vtable beginning at index @code{vtable-offset-user}
-(see @code{make-struct-layout}).
-
-@var{tail-size} specifies the size of the tail-array (if any) of
-this vtable.
-
-@var{init1}, @dots{} are the optional initializers for the fields of
-the vtable.
-
-Vtables have one initializable system field---the struct printer.
-This field comes before the user fields in the initializers passed
-to @code{make-vtable-vtable} and @code{make-struct}, and thus works as
-a third optional argument to @code{make-vtable-vtable} and a fourth to
-@code{make-struct} when creating vtables:
-
-If the value is a procedure, it will be called instead of the standard
-printer whenever a struct described by this vtable is printed.
-The procedure will be called with arguments STRUCT and PORT.
-
-The structure of a struct is described by a vtable, so the vtable is
-in essence the type of the struct. The vtable is itself a struct with
-a vtable. This could go on forever if it weren't for the
-vtable-vtables which are self-describing vtables, and thus terminate
-the chain.
-
-There are several potential ways of using structs, but the standard
-one is to use three kinds of structs, together building up a type
-sub-system: one vtable-vtable working as the root and one or several
-"types", each with a set of "instances". (The vtable-vtable should be
-compared to the class <class> which is the class of itself.)
-
-@lisp
-(define ball-root (make-vtable-vtable "pr" 0))
-
-(define (make-ball-type ball-color)
- (make-struct ball-root 0
- (make-struct-layout "pw")
- (lambda (ball port)
- (format port "#<a ~A ball owned by ~A>"
- (color ball)
- (owner ball)))
- ball-color))
-(define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user))
-(define (owner ball) (struct-ref ball 0))
-
-(define red (make-ball-type 'red))
-(define green (make-ball-type 'green))
-
-(define (make-ball type owner) (make-struct type 0 owner))
-
-(define ball (make-ball green 'Nisse))
-ball @result{} #<a green ball owned by Nisse>
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} struct-vtable-name vtable
-@deffnx {C Function} scm_struct_vtable_name (vtable)
-Return the name of the vtable @var{vtable}.
-@end deffn
-
-@deffn {Scheme Procedure} set-struct-vtable-name! vtable name
-@deffnx {C Function} scm_set_struct_vtable_name_x (vtable, name)
-Set the name of the vtable @var{vtable} to @var{name}.
-@end deffn
-
-@deffn {Scheme Procedure} struct-vtable-tag handle
-@deffnx {C Function} scm_struct_vtable_tag (handle)
-Return the vtable tag of the structure @var{handle}.
-@end deffn
-
-
-@node Arrays
-@section Arrays
-@tpindex Arrays
-
-@menu
-* Conventional Arrays:: Arrays with arbitrary data.
-* Array Mapping:: Applying a procedure to the contents of an array.
-* Uniform Arrays:: Arrays with data of a single type.
-* Bit Vectors:: Vectors of bits.
-@end menu
-
-@node Conventional Arrays
-@subsection Conventional Arrays
-
-@dfn{Conventional arrays} are a collection of cells organized into an
-arbitrary number of dimensions. Each cell can hold any kind of Scheme
-value and can be accessed in constant time by supplying an index for
-each dimension. This contrasts with uniform arrays, which use memory
-more efficiently but can hold data of only a single type, and lists
-where inserting and deleting cells is more efficient, but more time
-is usually required to access a particular cell.
-
-A conventional array is displayed as @code{#} followed by the @dfn{rank}
-(number of dimensions) followed by the cells, organized into dimensions
-using parentheses. The nesting depth of the parentheses is equal to
-the rank.
-
-When an array is created, the number of dimensions and range of each
-dimension must be specified, e.g., to create a 2x3 array with a
-zero-based index:
-
-@example
-(make-array 'ho 2 3) @result{}
-#2((ho ho ho) (ho ho ho))
-@end example
-
-The range of each dimension can also be given explicitly, e.g., another
-way to create the same array:
-
-@example
-(make-array 'ho '(0 1) '(0 2)) @result{}
-#2((ho ho ho) (ho ho ho))
-@end example
-
-A conventional array with one dimension based at zero is identical to
-a vector:
-
-@example
-(make-array 'ho 3) @result{}
-#(ho ho ho)
-@end example
-
-The following procedures can be used with conventional arrays (or vectors).
-
-@deffn {Scheme Procedure} array? v [prot]
-@deffnx {C Function} scm_array_p (v, prot)
-Return @code{#t} if the @var{obj} is an array, and @code{#f} if
-not. The @var{prototype} argument is used with uniform arrays
-and is described elsewhere.
-@end deffn
-
-@deffn {Scheme Procedure} make-array initial-value bound1 bound2 @dots{}
-Create and return an array that has as many dimensions as there are
-@var{bound}s and fill it with @var{initial-value}. Each @var{bound}
-may be a positive non-zero integer @var{N}, in which case the index for
-that dimension can range from 0 through @var{N-1}; or an explicit index
-range specifier in the form @code{(LOWER UPPER)}, where both @var{lower}
-and @var{upper} are integers, possibly less than zero, and possibly the
-same number (however, @var{lower} cannot be greater than @var{upper}).
-@end deffn
-
-@c array-ref's type is `compiled-closure'. There's some weird stuff
-@c going on in array.c, too. Let's call it a primitive. -twp
-
-@deffn {Scheme Procedure} uniform-vector-ref v args
-@deffnx {Scheme Procedure} array-ref v . args
-@deffnx {C Function} scm_uniform_vector_ref (v, args)
-Return the element at the @code{(index1, index2)} element in
-@var{array}.
-@end deffn
-
-@deffn {Scheme Procedure} array-in-bounds? v . args
-@deffnx {C Function} scm_array_in_bounds_p (v, args)
-Return @code{#t} if its arguments would be acceptable to
-@code{array-ref}.
-@end deffn
-
-@c fixme: why do these sigs differ? -ttn 2001/07/19 01:14:12
-@deffn {Scheme Procedure} array-set! v obj . args
-@deffnx {Scheme Procedure} uniform-array-set1! v obj args
-@deffnx {C Function} scm_array_set_x (v, obj, args)
-Set the element at the @code{(index1, index2)} element in @var{array} to
-@var{new-value}. The value returned by array-set! is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} make-shared-array oldra mapfunc . dims
-@deffnx {C Function} scm_make_shared_array (oldra, mapfunc, dims)
-@code{make-shared-array} can be used to create shared subarrays of other
-arrays. The @var{mapper} is a function that translates coordinates in
-the new array into coordinates in the old array. A @var{mapper} must be
-linear, and its range must stay within the bounds of the old array, but
-it can be otherwise arbitrary. A simple example:
-@lisp
-(define fred (make-array #f 8 8))
-(define freds-diagonal
- (make-shared-array fred (lambda (i) (list i i)) 8))
-(array-set! freds-diagonal 'foo 3)
-(array-ref fred 3 3) @result{} foo
-(define freds-center
- (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
-(array-ref freds-center 0 0) @result{} foo
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} shared-array-increments ra
-@deffnx {C Function} scm_shared_array_increments (ra)
-For each dimension, return the distance between elements in the root vector.
-@end deffn
-
-@deffn {Scheme Procedure} shared-array-offset ra
-@deffnx {C Function} scm_shared_array_offset (ra)
-Return the root vector index of the first element in the array.
-@end deffn
-
-@deffn {Scheme Procedure} shared-array-root ra
-@deffnx {C Function} scm_shared_array_root (ra)
-Return the root vector of a shared array.
-@end deffn
-
-@deffn {Scheme Procedure} transpose-array ra . args
-@deffnx {C Function} scm_transpose_array (ra, args)
-Return an array sharing contents with @var{array}, but with
-dimensions arranged in a different order. There must be one
-@var{dim} argument for each dimension of @var{array}.
-@var{dim0}, @var{dim1}, @dots{} should be integers between 0
-and the rank of the array to be returned. Each integer in that
-range must appear at least once in the argument list.
-
-The values of @var{dim0}, @var{dim1}, @dots{} correspond to
-dimensions in the array to be returned, their positions in the
-argument list to dimensions of @var{array}. Several @var{dim}s
-may have the same value, in which case the returned array will
-have smaller rank than @var{array}.
-
-@lisp
-(transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))
-(transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)
-(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}
- #2((a 4) (b 5) (c 6))
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} enclose-array ra . axes
-@deffnx {C Function} scm_enclose_array (ra, axes)
-@var{dim0}, @var{dim1} @dots{} should be nonnegative integers less than
-the rank of @var{array}. @var{enclose-array} returns an array
-resembling an array of shared arrays. The dimensions of each shared
-array are the same as the @var{dim}th dimensions of the original array,
-the dimensions of the outer array are the same as those of the original
-array that did not match a @var{dim}.
-
-An enclosed array is not a general Scheme array. Its elements may not
-be set using @code{array-set!}. Two references to the same element of
-an enclosed array will be @code{equal?} but will not in general be
-@code{eq?}. The value returned by @var{array-prototype} when given an
-enclosed array is unspecified.
-
-examples:
-@lisp
-(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}
- #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
-
-(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}
- #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} array-shape array
-Return a list of inclusive bounds of integers.
-@example
-(array-shape (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) (0 4))
-@end example
-@end deffn
-
-@deffn {Scheme Procedure} array-dimensions ra
-@deffnx {C Function} scm_array_dimensions (ra)
-@code{Array-dimensions} is similar to @code{array-shape} but replaces
-elements with a @code{0} minimum with one greater than the maximum. So:
-@lisp
-(array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} array-rank ra
-@deffnx {C Function} scm_array_rank (ra)
-Return the number of dimensions of @var{obj}. If @var{obj} is
-not an array, @code{0} is returned.
-@end deffn
-
-@deffn {Scheme Procedure} array->list v
-@deffnx {C Function} scm_array_to_list (v)
-Return a list consisting of all the elements, in order, of
-@var{array}.
-@end deffn
-
-@deffn {Scheme Procedure} array-copy! src dst
-@deffnx {Scheme Procedure} array-copy-in-order! src dst
-@deffnx {C Function} scm_array_copy_x (src, dst)
-Copy every element from vector or array @var{source} to the
-corresponding element of @var{destination}. @var{destination} must have
-the same rank as @var{source}, and be at least as large in each
-dimension. The order is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} array-fill! ra fill
-@deffnx {C Function} scm_array_fill_x (ra, fill)
-Store @var{fill} in every element of @var{array}. The value returned
-is unspecified.
-@end deffn
-
-@c begin (texi-doc-string "guile" "array-equal?")
-@deffn {Scheme Procedure} array-equal? ra0 ra1
-Return @code{#t} iff all arguments are arrays with the same shape, the
-same type, and have corresponding elements which are either
-@code{equal?} or @code{array-equal?}. This function differs from
-@code{equal?} in that a one dimensional shared array may be
-@var{array-equal?} but not @var{equal?} to a vector or uniform vector.
-@end deffn
-
-@deffn {Scheme Procedure} array-contents array [strict]
-@deffnx {C Function} scm_array_contents (array, strict)
-If @var{array} may be @dfn{unrolled} into a one dimensional shared array
-without changing their order (last subscript changing fastest), then
-@code{array-contents} returns that shared array, otherwise it returns
-@code{#f}. All arrays made by @var{make-array} and
-@var{make-uniform-array} may be unrolled, some arrays made by
-@var{make-shared-array} may not be.
-
-If the optional argument @var{strict} is provided, a shared array will
-be returned only if its elements are stored internally contiguous in
-memory.
-@end deffn
-
-@node Array Mapping
-@subsection Array Mapping
-
-@deffn {Scheme Procedure} array-map! ra0 proc . lra
-@deffnx {Scheme Procedure} array-map-in-order! ra0 proc . lra
-@deffnx {C Function} scm_array_map_x (ra0, proc, lra)
-@var{array1}, @dots{} must have the same number of dimensions as
-@var{array0} and have a range for each index which includes the range
-for the corresponding index in @var{array0}. @var{proc} is applied to
-each tuple of elements of @var{array1} @dots{} and the result is stored
-as the corresponding element in @var{array0}. The value returned is
-unspecified. The order of application is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} array-for-each proc ra0 . lra
-@deffnx {C Function} scm_array_for_each (proc, ra0, lra)
-Apply @var{proc} to each tuple of elements of @var{array0} @dots{}
-in row-major order. The value returned is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} array-index-map! ra proc
-@deffnx {C Function} scm_array_index_map_x (ra, proc)
-Apply @var{proc} to the indices of each element of @var{array} in
-turn, storing the result in the corresponding element. The value
-returned and the order of application are unspecified.
-
-One can implement @var{array-indexes} as
-@lisp
-(define (array-indexes array)
- (let ((ra (apply make-array #f (array-shape array))))
- (array-index-map! ra (lambda x x))
- ra))
-@end lisp
-Another example:
-@lisp
-(define (apl:index-generator n)
- (let ((v (make-uniform-vector n 1)))
- (array-index-map! v (lambda (i) i))
- v))
-@end lisp
-@end deffn
-
-@node Uniform Arrays
-@subsection Uniform Arrays
-@tpindex Uniform Arrays
-
-@noindent
-@dfn{Uniform arrays} have elements all of the
-same type and occupy less storage than conventional
-arrays. Uniform arrays with a single zero-based dimension
-are also known as @dfn{uniform vectors}. The procedures in
-this section can also be used on conventional arrays, vectors,
-bit-vectors and strings.
-
-@noindent
-When creating a uniform array, the type of data to be stored
-is indicated with a @var{prototype} argument. The following table
-lists the types available and example prototypes:
-
-@example
-prototype type printing character
-
-#t boolean (bit-vector) b
-#\a char (string) a
-#\nul byte (integer) y
-'s short (integer) h
-1 unsigned long (integer) u
--1 signed long (integer) e
-'l signed long long (integer) l
-1.0 float (single precision) s
-1/3 double (double precision float) i
-0+i complex (double precision) c
-() conventional vector
-@end example
-
-@noindent
-Unshared uniform arrays of characters with a single zero-based dimension
-are identical to strings:
-
-@example
-(make-uniform-array #\a 3) @result{}
-"aaa"
-@end example
-
-@noindent
-Unshared uniform arrays of booleans with a single zero-based dimension
-are identical to @ref{Bit Vectors, bit-vectors}.
-
-@example
-(make-uniform-array #t 3) @result{}
-#*111
-@end example
-
-@noindent
-Other uniform vectors are written in a form similar to that of vectors,
-except that a single character from the above table is put between
-@code{#} and @code{(}. For example, a uniform vector of signed
-long integers is displayed in the form @code{'#e(3 5 9)}.
-
-@deffn {Scheme Procedure} array? v [prot]
-Return @code{#t} if the @var{obj} is an array, and @code{#f} if not.
-
-The @var{prototype} argument is used with uniform arrays and is described
-elsewhere.
-@end deffn
-
-@deffn {Scheme Procedure} make-uniform-array prototype bound1 bound2 @dots{}
-Create and return a uniform array of type corresponding to
-@var{prototype} that has as many dimensions as there are @var{bound}s
-and fill it with @var{prototype}.
-@end deffn
-
-@deffn {Scheme Procedure} array-prototype ra
-@deffnx {C Function} scm_array_prototype (ra)
-Return an object that would produce an array of the same type
-as @var{array}, if used as the @var{prototype} for
-@code{make-uniform-array}.
-@end deffn
-
-@deffn {Scheme Procedure} list->uniform-array ndim prot lst
-@deffnx {Scheme Procedure} list->uniform-vector prot lst
-@deffnx {C Function} scm_list_to_uniform_array (ndim, prot, lst)
-Return a uniform array of the type indicated by prototype
-@var{prot} with elements the same as those of @var{lst}.
-Elements must be of the appropriate type, no coercions are
-done.
-@end deffn
-
-@deffn {Scheme Procedure} uniform-vector-fill! uve fill
-Store @var{fill} in every element of @var{uve}. The value returned is
-unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} uniform-vector-length v
-@deffnx {C Function} scm_uniform_vector_length (v)
-Return the number of elements in @var{uve}.
-@end deffn
-
-@deffn {Scheme Procedure} dimensions->uniform-array dims prot [fill]
-@deffnx {Scheme Procedure} make-uniform-vector length prototype [fill]
-@deffnx {C Function} scm_dimensions_to_uniform_array (dims, prot, fill)
-Create and return a uniform array or vector of type
-corresponding to @var{prototype} with dimensions @var{dims} or
-length @var{length}. If @var{fill} is supplied, it's used to
-fill the array, otherwise @var{prototype} is used.
-@end deffn
-
-@c Another compiled-closure. -twp
-
-@deffn {Scheme Procedure} uniform-array-read! ra [port_or_fd [start [end]]]
-@deffnx {Scheme Procedure} uniform-vector-read! uve [port-or-fdes] [start] [end]
-@deffnx {C Function} scm_uniform_array_read_x (ra, port_or_fd, start, end)
-Attempt to read all elements of @var{ura}, in lexicographic order, as
-binary objects from @var{port-or-fdes}.
-If an end of file is encountered,
-the objects up to that point are put into @var{ura}
-(starting at the beginning) and the remainder of the array is
-unchanged.
-
-The optional arguments @var{start} and @var{end} allow
-a specified region of a vector (or linearized array) to be read,
-leaving the remainder of the vector unchanged.
-
-@code{uniform-array-read!} returns the number of objects read.
-@var{port-or-fdes} may be omitted, in which case it defaults to the value
-returned by @code{(current-input-port)}.
-@end deffn
-
-@deffn {Scheme Procedure} uniform-array-write v [port_or_fd [start [end]]]
-@deffnx {Scheme Procedure} uniform-vector-write uve [port-or-fdes] [start] [end]
-@deffnx {C Function} scm_uniform_array_write (v, port_or_fd, start, end)
-Writes all elements of @var{ura} as binary objects to
-@var{port-or-fdes}.
-
-The optional arguments @var{start}
-and @var{end} allow
-a specified region of a vector (or linearized array) to be written.
-
-The number of objects actually written is returned.
-@var{port-or-fdes} may be
-omitted, in which case it defaults to the value returned by
-@code{(current-output-port)}.
-@end deffn
-
-@node Bit Vectors
-@subsection Bit Vectors
-
-@noindent
-Bit vectors are a specific type of uniform array: an array of booleans
-with a single zero-based index.
-
-@noindent
-They are displayed as a sequence of @code{0}s and
-@code{1}s prefixed by @code{#*}, e.g.,
-
-@example
-(make-uniform-vector 8 #t #f) @result{}
-#*00000000
-
-#b(#t #f #t) @result{}
-#*101
-@end example
-
-@deffn {Scheme Procedure} bit-count b bitvector
-@deffnx {C Function} scm_bit_count (b, bitvector)
-Return the number of occurrences of the boolean @var{b} in
-@var{bitvector}.
-@end deffn
-
-@deffn {Scheme Procedure} bit-position item v k
-@deffnx {C Function} scm_bit_position (item, v, k)
-Return the minimum index of an occurrence of @var{bool} in
-@var{bv} which is at least @var{k}. If no @var{bool} occurs
-within the specified range @code{#f} is returned.
-@end deffn
-
-@deffn {Scheme Procedure} bit-invert! v
-@deffnx {C Function} scm_bit_invert_x (v)
-Modify @var{bv} by replacing each element with its negation.
-@end deffn
-
-@deffn {Scheme Procedure} bit-set*! v kv obj
-@deffnx {C Function} scm_bit_set_star_x (v, kv, obj)
-If uve is a bit-vector @var{bv} and uve must be of the same
-length. If @var{bool} is @code{#t}, uve is OR'ed into
-@var{bv}; If @var{bool} is @code{#f}, the inversion of uve is
-AND'ed into @var{bv}.
-
-If uve is a unsigned long integer vector all the elements of uve
-must be between 0 and the @code{length} of @var{bv}. The bits
-of @var{bv} corresponding to the indexes in uve are set to
-@var{bool}. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} bit-count* v kv obj
-@deffnx {C Function} scm_bit_count_star (v, kv, obj)
-Return
-@lisp
-(bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).
-@end lisp
-@var{bv} is not modified.
-@end deffn
-
-
-@node Association Lists and Hash Tables
-@section Association Lists and Hash Tables
-
-This chapter discusses dictionary objects: data structures that are
-useful for organizing and indexing large bodies of information.
-
-@menu
-* Dictionary Types:: About dictionary types; what they're good for.
-* Association Lists:: List-based dictionaries.
-* Hash Tables:: Table-based dictionaries.
-@end menu
-
-@node Dictionary Types
-@subsection Dictionary Types
-
-A @dfn{dictionary} object is a data structure used to index
-information in a user-defined way. In standard Scheme, the main
-aggregate data types are lists and vectors. Lists are not really
-indexed at all, and vectors are indexed only by number
-(e.g. @code{(vector-ref foo 5)}). Often you will find it useful
-to index your data on some other type; for example, in a library
-catalog you might want to look up a book by the name of its
-author. Dictionaries are used to help you organize information in
-such a way.
-
-An @dfn{association list} (or @dfn{alist} for short) is a list of
-key-value pairs. Each pair represents a single quantity or
-object; the @code{car} of the pair is a key which is used to
-identify the object, and the @code{cdr} is the object's value.
-
-A @dfn{hash table} also permits you to index objects with
-arbitrary keys, but in a way that makes looking up any one object
-extremely fast. A well-designed hash system makes hash table
-lookups almost as fast as conventional array or vector references.
-
-Alists are popular among Lisp programmers because they use only
-the language's primitive operations (lists, @dfn{car}, @dfn{cdr}
-and the equality primitives). No changes to the language core are
-necessary. Therefore, with Scheme's built-in list manipulation
-facilities, it is very convenient to handle data stored in an
-association list. Also, alists are highly portable and can be
-easily implemented on even the most minimal Lisp systems.
-
-However, alists are inefficient, especially for storing large
-quantities of data. Because we want Guile to be useful for large
-software systems as well as small ones, Guile provides a rich set
-of tools for using either association lists or hash tables.
-
-@node Association Lists
-@subsection Association Lists
-@tpindex Association Lists
-@tpindex Alist
-
-@cindex Association List
-@cindex Alist
-@cindex Database
-
-An association list is a conventional data structure that is often used
-to implement simple key-value databases. It consists of a list of
-entries in which each entry is a pair. The @dfn{key} of each entry is
-the @code{car} of the pair and the @dfn{value} of each entry is the
-@code{cdr}.
-
-@example
-ASSOCIATION LIST ::= '( (KEY1 . VALUE1)
- (KEY2 . VALUE2)
- (KEY3 . VALUE3)
- @dots{}
- )
-@end example
-
-@noindent
-Association lists are also known, for short, as @dfn{alists}.
-
-The structure of an association list is just one example of the infinite
-number of possible structures that can be built using pairs and lists.
-As such, the keys and values in an association list can be manipulated
-using the general list structure procedures @code{cons}, @code{car},
-@code{cdr}, @code{set-car!}, @code{set-cdr!} and so on. However,
-because association lists are so useful, Guile also provides specific
-procedures for manipulating them.
-
-@menu
-* Alist Key Equality::
-* Adding or Setting Alist Entries::
-* Retrieving Alist Entries::
-* Removing Alist Entries::
-* Sloppy Alist Functions::
-* Alist Example::
-@end menu
-
-@node Alist Key Equality
-@subsubsection Alist Key Equality
-
-All of Guile's dedicated association list procedures, apart from
-@code{acons}, come in three flavours, depending on the level of equality
-that is required to decide whether an existing key in the association
-list is the same as the key that the procedure call uses to identify the
-required entry.
-
-@itemize @bullet
-@item
-Procedures with @dfn{assq} in their name use @code{eq?} to determine key
-equality.
-
-@item
-Procedures with @dfn{assv} in their name use @code{eqv?} to determine
-key equality.
-
-@item
-Procedures with @dfn{assoc} in their name use @code{equal?} to
-determine key equality.
-@end itemize
-
-@code{acons} is an exception because it is used to build association
-lists which do not require their entries' keys to be unique.
-
-@node Adding or Setting Alist Entries
-@subsubsection Adding or Setting Alist Entries
-
-@code{acons} adds a new entry to an association list and returns the
-combined association list. The combined alist is formed by consing the
-new entry onto the head of the alist specified in the @code{acons}
-procedure call. So the specified alist is not modified, but its
-contents become shared with the tail of the combined alist that
-@code{acons} returns.
-
-In the most common usage of @code{acons}, a variable holding the
-original association list is updated with the combined alist:
-
-@example
-(set! address-list (acons name address address-list))
-@end example
-
-In such cases, it doesn't matter that the old and new values of
-@code{address-list} share some of their contents, since the old value is
-usually no longer independently accessible.
-
-Note that @code{acons} adds the specified new entry regardless of
-whether the alist may already contain entries with keys that are, in
-some sense, the same as that of the new entry. Thus @code{acons} is
-ideal for building alists where there is no concept of key uniqueness.
-
-@example
-(set! task-list (acons 3 "pay gas bill" '()))
-task-list
-@result{}
-((3 . "pay gas bill"))
-
-(set! task-list (acons 3 "tidy bedroom" task-list))
-task-list
-@result{}
-((3 . "tidy bedroom") (3 . "pay gas bill"))
-@end example
-
-@code{assq-set!}, @code{assv-set!} and @code{assoc-set!} are used to add
-or replace an entry in an association list where there @emph{is} a
-concept of key uniqueness. If the specified association list already
-contains an entry whose key is the same as that specified in the
-procedure call, the existing entry is replaced by the new one.
-Otherwise, the new entry is consed onto the head of the old association
-list to create the combined alist. In all cases, these procedures
-return the combined alist.
-
-@code{assq-set!} and friends @emph{may} destructively modify the
-structure of the old association list in such a way that an existing
-variable is correctly updated without having to @code{set!} it to the
-value returned:
-
-@example
-address-list
-@result{}
-(("mary" . "34 Elm Road") ("james" . "16 Bow Street"))
-
-(assoc-set! address-list "james" "1a London Road")
-@result{}
-(("mary" . "34 Elm Road") ("james" . "1a London Road"))
-
-address-list
-@result{}
-(("mary" . "34 Elm Road") ("james" . "1a London Road"))
-@end example
-
-Or they may not:
-
-@example
-(assoc-set! address-list "bob" "11 Newington Avenue")
-@result{}
-(("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
- ("james" . "1a London Road"))
-
-address-list
-@result{}
-(("mary" . "34 Elm Road") ("james" . "1a London Road"))
-@end example
-
-The only safe way to update an association list variable when adding or
-replacing an entry like this is to @code{set!} the variable to the
-returned value:
-
-@example
-(set! address-list
- (assoc-set! address-list "bob" "11 Newington Avenue"))
-address-list
-@result{}
-(("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
- ("james" . "1a London Road"))
-@end example
-
-Because of this slight inconvenience, you may find it more convenient to
-use hash tables to store dictionary data. If your application will not
-be modifying the contents of an alist very often, this may not make much
-difference to you.
-
-If you need to keep the old value of an association list in a form
-independent from the list that results from modification by
-@code{acons}, @code{assq-set!}, @code{assv-set!} or @code{assoc-set!},
-use @code{list-copy} to copy the old association list before modifying
-it.
-
-@deffn {Scheme Procedure} acons key value alist
-@deffnx {C Function} scm_acons (key, value, alist)
-Add a new key-value pair to @var{alist}. A new pair is
-created whose car is @var{key} and whose cdr is @var{value}, and the
-pair is consed onto @var{alist}, and the new list is returned. This
-function is @emph{not} destructive; @var{alist} is not modified.
-@end deffn
-
-@deffn {Scheme Procedure} assq-set! alist key val
-@deffnx {Scheme Procedure} assv-set! alist key value
-@deffnx {Scheme Procedure} assoc-set! alist key value
-@deffnx {C Function} scm_assq_set_x (alist, key, val)
-@deffnx {C Function} scm_assv_set_x (alist, key, val)
-@deffnx {C Function} scm_assoc_set_x (alist, key, val)
-Reassociate @var{key} in @var{alist} with @var{value}: find any existing
-@var{alist} entry for @var{key} and associate it with the new
-@var{value}. If @var{alist} does not contain an entry for @var{key},
-add a new one. Return the (possibly new) alist.
-
-These functions do not attempt to verify the structure of @var{alist},
-and so may cause unusual results if passed an object that is not an
-association list.
-@end deffn
-
-@node Retrieving Alist Entries
-@subsubsection Retrieving Alist Entries
-@rnindex assq
-@rnindex assv
-@rnindex assoc
-
-@code{assq}, @code{assv} and @code{assoc} take an alist and a key as
-arguments and return the entry for that key if an entry exists, or
-@code{#f} if there is no entry for that key. Note that, in the cases
-where an entry exists, these procedures return the complete entry, that
-is @code{(KEY . VALUE)}, not just the value.
-
-@deffn {Scheme Procedure} assq key alist
-@deffnx {Scheme Procedure} assv key alist
-@deffnx {Scheme Procedure} assoc key alist
-@deffnx {C Function} scm_assq (key, alist)
-@deffnx {C Function} scm_assv (key, alist)
-@deffnx {C Function} scm_assoc (key, alist)
-Fetch the entry in @var{alist} that is associated with @var{key}. To
-decide whether the argument @var{key} matches a particular entry in
-@var{alist}, @code{assq} compares keys with @code{eq?}, @code{assv}
-uses @code{eqv?} and @code{assoc} uses @code{equal?}. If @var{key}
-cannot be found in @var{alist} (according to whichever equality
-predicate is in use), then return @code{#f}. These functions
-return the entire alist entry found (i.e. both the key and the value).
-@end deffn
-
-@code{assq-ref}, @code{assv-ref} and @code{assoc-ref}, on the other
-hand, take an alist and a key and return @emph{just the value} for that
-key, if an entry exists. If there is no entry for the specified key,
-these procedures return @code{#f}.
-
-This creates an ambiguity: if the return value is @code{#f}, it means
-either that there is no entry with the specified key, or that there
-@emph{is} an entry for the specified key, with value @code{#f}.
-Consequently, @code{assq-ref} and friends should only be used where it
-is known that an entry exists, or where the ambiguity doesn't matter
-for some other reason.
-
-@deffn {Scheme Procedure} assq-ref alist key
-@deffnx {Scheme Procedure} assv-ref alist key
-@deffnx {Scheme Procedure} assoc-ref alist key
-@deffnx {C Function} scm_assq_ref (alist, key)
-@deffnx {C Function} scm_assv_ref (alist, key)
-@deffnx {C Function} scm_assoc_ref (alist, key)
-Like @code{assq}, @code{assv} and @code{assoc}, except that only the
-value associated with @var{key} in @var{alist} is returned. These
-functions are equivalent to
-
-@lisp
-(let ((ent (@var{associator} @var{key} @var{alist})))
- (and ent (cdr ent)))
-@end lisp
-
-where @var{associator} is one of @code{assq}, @code{assv} or @code{assoc}.
-@end deffn
-
-@node Removing Alist Entries
-@subsubsection Removing Alist Entries
-
-To remove the element from an association list whose key matches a
-specified key, use @code{assq-remove!}, @code{assv-remove!} or
-@code{assoc-remove!} (depending, as usual, on the level of equality
-required between the key that you specify and the keys in the
-association list).
-
-As with @code{assq-set!} and friends, the specified alist may or may not
-be modified destructively, and the only safe way to update a variable
-containing the alist is to @code{set!} it to the value that
-@code{assq-remove!} and friends return.
-
-@example
-address-list
-@result{}
-(("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
- ("james" . "1a London Road"))
-
-(set! address-list (assoc-remove! address-list "mary"))
-address-list
-@result{}
-(("bob" . "11 Newington Avenue") ("james" . "1a London Road"))
-@end example
-
-Note that, when @code{assq/v/oc-remove!} is used to modify an
-association list that has been constructed only using the corresponding
-@code{assq/v/oc-set!}, there can be at most one matching entry in the
-alist, so the question of multiple entries being removed in one go does
-not arise. If @code{assq/v/oc-remove!} is applied to an association
-list that has been constructed using @code{acons}, or an
-@code{assq/v/oc-set!} with a different level of equality, or any mixture
-of these, it removes only the first matching entry from the alist, even
-if the alist might contain further matching entries. For example:
-
-@example
-(define address-list '())
-(set! address-list (assq-set! address-list "mary" "11 Elm Street"))
-(set! address-list (assq-set! address-list "mary" "57 Pine Drive"))
-address-list
-@result{}
-(("mary" . "57 Pine Drive") ("mary" . "11 Elm Street"))
-
-(set! address-list (assoc-remove! address-list "mary"))
-address-list
-@result{}
-(("mary" . "11 Elm Street"))
-@end example
-
-In this example, the two instances of the string "mary" are not the same
-when compared using @code{eq?}, so the two @code{assq-set!} calls add
-two distinct entries to @code{address-list}. When compared using
-@code{equal?}, both "mary"s in @code{address-list} are the same as the
-"mary" in the @code{assoc-remove!} call, but @code{assoc-remove!} stops
-after removing the first matching entry that it finds, and so one of the
-"mary" entries is left in place.
-
-@deffn {Scheme Procedure} assq-remove! alist key
-@deffnx {Scheme Procedure} assv-remove! alist key
-@deffnx {Scheme Procedure} assoc-remove! alist key
-@deffnx {C Function} scm_assq_remove_x (alist, key)
-@deffnx {C Function} scm_assv_remove_x (alist, key)
-@deffnx {C Function} scm_assoc_remove_x (alist, key)
-Delete the first entry in @var{alist} associated with @var{key}, and return
-the resulting alist.
-@end deffn
-
-@node Sloppy Alist Functions
-@subsubsection Sloppy Alist Functions
-
-@code{sloppy-assq}, @code{sloppy-assv} and @code{sloppy-assoc} behave
-like the corresponding non-@code{sloppy-} procedures, except that they
-return @code{#f} when the specified association list is not well-formed,
-where the non-@code{sloppy-} versions would signal an error.
-
-Specifically, there are two conditions for which the non-@code{sloppy-}
-procedures signal an error, which the @code{sloppy-} procedures handle
-instead by returning @code{#f}. Firstly, if the specified alist as a
-whole is not a proper list:
-
-@example
-(assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
-@result{}
-ERROR: In procedure assoc in expression (assoc "mary" (quote #)):
-ERROR: Wrong type argument in position 2 (expecting NULLP): "open sesame"
-ABORT: (wrong-type-arg)
-
-(sloppy-assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
-@result{}
-#f
-@end example
-
-@noindent
-Secondly, if one of the entries in the specified alist is not a pair:
-
-@example
-(assoc 2 '((1 . 1) 2 (3 . 9)))
-@result{}
-ERROR: In procedure assoc in expression (assoc 2 (quote #)):
-ERROR: Wrong type argument in position 2 (expecting CONSP): 2
-ABORT: (wrong-type-arg)
-
-(sloppy-assoc 2 '((1 . 1) 2 (3 . 9)))
-@result{}
-#f
-@end example
-
-Unless you are explicitly working with badly formed association lists,
-it is much safer to use the non-@code{sloppy-} procedures, because they
-help to highlight coding and data errors that the @code{sloppy-}
-versions would silently cover up.
-
-@deffn {Scheme Procedure} sloppy-assq key alist
-@deffnx {C Function} scm_sloppy_assq (key, alist)
-Behaves like @code{assq} but does not do any error checking.
-Recommended only for use in Guile internals.
-@end deffn
-
-@deffn {Scheme Procedure} sloppy-assv key alist
-@deffnx {C Function} scm_sloppy_assv (key, alist)
-Behaves like @code{assv} but does not do any error checking.
-Recommended only for use in Guile internals.
-@end deffn
-
-@deffn {Scheme Procedure} sloppy-assoc key alist
-@deffnx {C Function} scm_sloppy_assoc (key, alist)
-Behaves like @code{assoc} but does not do any error checking.
-Recommended only for use in Guile internals.
-@end deffn
-
-@node Alist Example
-@subsubsection Alist Example
-
-Here is a longer example of how alists may be used in practice.
-
-@lisp
-(define capitals '(("New York" . "Albany")
- ("Oregon" . "Salem")
- ("Florida" . "Miami")))
-
-;; What's the capital of Oregon?
-(assoc "Oregon" capitals) @result{} ("Oregon" . "Salem")
-(assoc-ref capitals "Oregon") @result{} "Salem"
-
-;; We left out South Dakota.
-(set! capitals
- (assoc-set! capitals "South Dakota" "Pierre"))
-capitals
-@result{} (("South Dakota" . "Pierre")
- ("New York" . "Albany")
- ("Oregon" . "Salem")
- ("Florida" . "Miami"))
-
-;; And we got Florida wrong.
-(set! capitals
- (assoc-set! capitals "Florida" "Tallahassee"))
-capitals
-@result{} (("South Dakota" . "Pierre")
- ("New York" . "Albany")
- ("Oregon" . "Salem")
- ("Florida" . "Tallahassee"))
-
-;; After Oregon secedes, we can remove it.
-(set! capitals
- (assoc-remove! capitals "Oregon"))
-capitals
-@result{} (("South Dakota" . "Pierre")
- ("New York" . "Albany")
- ("Florida" . "Tallahassee"))
-@end lisp
-
-@node Hash Tables
-@subsection Hash Tables
-@tpindex Hash Tables
-
-@c FIXME::martin: Review me!
-
-Hash tables are dictionaries which offer similar functionality as
-association lists: They provide a mapping from keys to values. The
-difference is that association lists need time linear in the size of
-elements when searching for entries, whereas hash tables can normally
-search in constant time. The drawback is that hash tables require a
-little bit more memory, and that you can not use the normal list
-procedures (@pxref{Lists}) for working with them.
-
-@menu
-* Hash Table Examples:: Demonstration of hash table usage.
-* Hash Table Reference:: Hash table procedure descriptions.
-@end menu
-
-
-@node Hash Table Examples
-@subsubsection Hash Table Examples
-
-@c FIXME::martin: Review me!
-
-For demonstration purposes, this section gives a few usage examples of
-some hash table procedures, together with some explanation what they do.
-
-First we start by creating a new hash table with 31 slots, and
-populate it with two key/value pairs.
-
-@lisp
-(define h (make-hash-table 31))
-
-(hashq-create-handle! h 'foo "bar")
-@result{}
-(foo . "bar")
-
-(hashq-create-handle! h 'braz "zonk")
-@result{}
-(braz . "zonk")
-
-(hashq-create-handle! h 'frob #f)
-@result{}
-(frob . #f)
-@end lisp
-
-You can get the value for a given key with the procedure
-@code{hashq-ref}, but the problem with this procedure is that you
-cannot reliably determine whether a key does exists in the table. The
-reason is that the procedure returns @code{#f} if the key is not in
-the table, but it will return the same value if the key is in the
-table and just happens to have the value @code{#f}, as you can see in
-the following examples.
-
-@lisp
-(hashq-ref h 'foo)
-@result{}
-"bar"
-
-(hashq-ref h 'frob)
-@result{}
-#f
-
-(hashq-ref h 'not-there)
-@result{}
-#f
-@end lisp
-
-Better is to use the procedure @code{hashq-get-handle}, which makes a
-distinction between the two cases. Just like @code{assq}, this
-procedure returns a key/value-pair on success, and @code{#f} if the
-key is not found.
-
-@lisp
-(hashq-get-handle h 'foo)
-@result{}
-(foo . "bar")
-
-(hashq-get-handle h 'not-there)
-@result{}
-#f
-@end lisp
-
-There is no procedure for calculating the number of key/value-pairs in
-a hash table, but @code{hash-fold} can be used for doing exactly that.
-
-@lisp
-(hash-fold (lambda (key value seed) (+ 1 seed)) 0 h)
-@result{}
-3
-@end lisp
-
-@node Hash Table Reference
-@subsubsection Hash Table Reference
-
-Like the association list functions, the hash table functions come
-in several varieties: @code{hashq}, @code{hashv}, and @code{hash}.
-The @code{hashq} functions use @code{eq?} to determine whether two
-keys match. The @code{hashv} functions use @code{eqv?}, and the
-@code{hash} functions use @code{equal?}.
-
-In each of the functions that follow, the @var{table} argument
-must be a vector. The @var{key} and @var{value} arguments may be
-any Scheme object.
-
-@deffn {Scheme Procedure} make-hash-table size
-Create a new hash table of @var{size} slots. Note that the number of
-slots does not limit the size of the table, it just tells how large
-the underlying vector will be. The @var{size} should be similar to
-the expected number of elements which will be added to the table, but
-they need not match. For good performance, it might be a good idea to
-use a prime number as the @var{size}.
-@end deffn
-
-@deffn {Scheme Procedure} hashq-ref table key [dflt]
-@deffnx {C Function} scm_hashq_ref (table, key, dflt)
-Look up @var{key} in the hash table @var{table}, and return the
-value (if any) associated with it. If @var{key} is not found,
-return @var{default} (or @code{#f} if no @var{default} argument
-is supplied). Uses @code{eq?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hashv-ref table key [dflt]
-@deffnx {C Function} scm_hashv_ref (table, key, dflt)
-Look up @var{key} in the hash table @var{table}, and return the
-value (if any) associated with it. If @var{key} is not found,
-return @var{default} (or @code{#f} if no @var{default} argument
-is supplied). Uses @code{eqv?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hash-ref table key [dflt]
-@deffnx {C Function} scm_hash_ref (table, key, dflt)
-Look up @var{key} in the hash table @var{table}, and return the
-value (if any) associated with it. If @var{key} is not found,
-return @var{default} (or @code{#f} if no @var{default} argument
-is supplied). Uses @code{equal?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hashq-set! table key val
-@deffnx {C Function} scm_hashq_set_x (table, key, val)
-Find the entry in @var{table} associated with @var{key}, and
-store @var{value} there. Uses @code{eq?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hashv-set! table key val
-@deffnx {C Function} scm_hashv_set_x (table, key, val)
-Find the entry in @var{table} associated with @var{key}, and
-store @var{value} there. Uses @code{eqv?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hash-set! table key val
-@deffnx {C Function} scm_hash_set_x (table, key, val)
-Find the entry in @var{table} associated with @var{key}, and
-store @var{value} there. Uses @code{equal?} for equality
-testing.
-@end deffn
-
-@deffn {Scheme Procedure} hashq-remove! table key
-@deffnx {C Function} scm_hashq_remove_x (table, key)
-Remove @var{key} (and any value associated with it) from
-@var{table}. Uses @code{eq?} for equality tests.
-@end deffn
-
-@deffn {Scheme Procedure} hashv-remove! table key
-@deffnx {C Function} scm_hashv_remove_x (table, key)
-Remove @var{key} (and any value associated with it) from
-@var{table}. Uses @code{eqv?} for equality tests.
-@end deffn
-
-@deffn {Scheme Procedure} hash-remove! table key
-@deffnx {C Function} scm_hash_remove_x (table, key)
-Remove @var{key} (and any value associated with it) from
-@var{table}. Uses @code{equal?} for equality tests.
-@end deffn
-
-The standard hash table functions may be too limited for some
-applications. For example, you may want a hash table to store
-strings in a case-insensitive manner, so that references to keys
-named ``foobar'', ``FOOBAR'' and ``FooBaR'' will all yield the
-same item. Guile provides you with @dfn{extended} hash tables
-that permit you to specify a hash function and associator function
-of your choosing. The functions described in the rest of this section
-can be used to implement such custom hash table structures.
-
-If you are unfamiliar with the inner workings of hash tables, then
-this facility will probably be a little too abstract for you to
-use comfortably. If you are interested in learning more, see an
-introductory textbook on data structures or algorithms for an
-explanation of how hash tables are implemented.
-
-@deffn {Scheme Procedure} hashq key size
-@deffnx {C Function} scm_hashq (key, size)
-Determine a hash value for @var{key} that is suitable for
-lookups in a hash table of size @var{size}, where @code{eq?} is
-used as the equality predicate. The function returns an
-integer in the range 0 to @var{size} - 1. Note that
-@code{hashq} may use internal addresses. Thus two calls to
-hashq where the keys are @code{eq?} are not guaranteed to
-deliver the same value if the key object gets garbage collected
-in between. This can happen, for example with symbols:
-@code{(hashq 'foo n) (gc) (hashq 'foo n)} may produce two
-different values, since @code{foo} will be garbage collected.
-@end deffn
-
-@deffn {Scheme Procedure} hashv key size
-@deffnx {C Function} scm_hashv (key, size)
-Determine a hash value for @var{key} that is suitable for
-lookups in a hash table of size @var{size}, where @code{eqv?} is
-used as the equality predicate. The function returns an
-integer in the range 0 to @var{size} - 1. Note that
-@code{(hashv key)} may use internal addresses. Thus two calls
-to hashv where the keys are @code{eqv?} are not guaranteed to
-deliver the same value if the key object gets garbage collected
-in between. This can happen, for example with symbols:
-@code{(hashv 'foo n) (gc) (hashv 'foo n)} may produce two
-different values, since @code{foo} will be garbage collected.
-@end deffn
-
-@deffn {Scheme Procedure} hash key size
-@deffnx {C Function} scm_hash (key, size)
-Determine a hash value for @var{key} that is suitable for
-lookups in a hash table of size @var{size}, where @code{equal?}
-is used as the equality predicate. The function returns an
-integer in the range 0 to @var{size} - 1.
-@end deffn
-
-@deffn {Scheme Procedure} hashx-ref hash assoc table key [dflt]
-@deffnx {C Function} scm_hashx_ref (hash, assoc, table, key, dflt)
-This behaves the same way as the corresponding @code{ref}
-function, but uses @var{hash} as a hash function and
-@var{assoc} to compare keys. @code{hash} must be a function
-that takes two arguments, a key to be hashed and a table size.
-@code{assoc} must be an associator function, like @code{assoc},
-@code{assq} or @code{assv}.
-
-By way of illustration, @code{hashq-ref table key} is
-equivalent to @code{hashx-ref hashq assq table key}.
-@end deffn
-
-@deffn {Scheme Procedure} hashx-set! hash assoc table key val
-@deffnx {C Function} scm_hashx_set_x (hash, assoc, table, key, val)
-This behaves the same way as the corresponding @code{set!}
-function, but uses @var{hash} as a hash function and
-@var{assoc} to compare keys. @code{hash} must be a function
-that takes two arguments, a key to be hashed and a table size.
-@code{assoc} must be an associator function, like @code{assoc},
-@code{assq} or @code{assv}.
-
- By way of illustration, @code{hashq-set! table key} is
-equivalent to @code{hashx-set! hashq assq table key}.
-@end deffn
-
-@deffn {Scheme Procedure} hashq-get-handle table key
-@deffnx {C Function} scm_hashq_get_handle (table, key)
-This procedure returns the @code{(key . value)} pair from the
-hash table @var{table}. If @var{table} does not hold an
-associated value for @var{key}, @code{#f} is returned.
-Uses @code{eq?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hashv-get-handle table key
-@deffnx {C Function} scm_hashv_get_handle (table, key)
-This procedure returns the @code{(key . value)} pair from the
-hash table @var{table}. If @var{table} does not hold an
-associated value for @var{key}, @code{#f} is returned.
-Uses @code{eqv?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hash-get-handle table key
-@deffnx {C Function} scm_hash_get_handle (table, key)
-This procedure returns the @code{(key . value)} pair from the
-hash table @var{table}. If @var{table} does not hold an
-associated value for @var{key}, @code{#f} is returned.
-Uses @code{equal?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hashx-get-handle hash assoc table key
-@deffnx {C Function} scm_hashx_get_handle (hash, assoc, table, key)
-This behaves the same way as the corresponding
-@code{-get-handle} function, but uses @var{hash} as a hash
-function and @var{assoc} to compare keys. @code{hash} must be
-a function that takes two arguments, a key to be hashed and a
-table size. @code{assoc} must be an associator function, like
-@code{assoc}, @code{assq} or @code{assv}.
-@end deffn
-
-@deffn {Scheme Procedure} hashq-create-handle! table key init
-@deffnx {C Function} scm_hashq_create_handle_x (table, key, init)
-This function looks up @var{key} in @var{table} and returns its handle.
-If @var{key} is not already present, a new handle is created which
-associates @var{key} with @var{init}.
-@end deffn
-
-@deffn {Scheme Procedure} hashv-create-handle! table key init
-@deffnx {C Function} scm_hashv_create_handle_x (table, key, init)
-This function looks up @var{key} in @var{table} and returns its handle.
-If @var{key} is not already present, a new handle is created which
-associates @var{key} with @var{init}.
-@end deffn
-
-@deffn {Scheme Procedure} hash-create-handle! table key init
-@deffnx {C Function} scm_hash_create_handle_x (table, key, init)
-This function looks up @var{key} in @var{table} and returns its handle.
-If @var{key} is not already present, a new handle is created which
-associates @var{key} with @var{init}.
-@end deffn
-
-@deffn {Scheme Procedure} hashx-create-handle! hash assoc table key init
-@deffnx {C Function} scm_hashx_create_handle_x (hash, assoc, table, key, init)
-This behaves the same way as the corresponding
-@code{-create-handle} function, but uses @var{hash} as a hash
-function and @var{assoc} to compare keys. @code{hash} must be
-a function that takes two arguments, a key to be hashed and a
-table size. @code{assoc} must be an associator function, like
-@code{assoc}, @code{assq} or @code{assv}.
-@end deffn
-
-@deffn {Scheme Procedure} hash-fold proc init table
-@deffnx {C Function} scm_hash_fold (proc, init, table)
-An iterator over hash-table elements.
-Accumulates and returns a result by applying PROC successively.
-The arguments to PROC are "(key value prior-result)" where key
-and value are successive pairs from the hash table TABLE, and
-prior-result is either INIT (for the first application of PROC)
-or the return value of the previous application of PROC.
-For example, @code{(hash-fold acons '() tab)} will convert a hash
-table into an a-list of key-value pairs.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-control.texi b/doc/ref/scheme-control.texi
deleted file mode 100644
index 184ccae9d..000000000
--- a/doc/ref/scheme-control.texi
+++ /dev/null
@@ -1,979 +0,0 @@
-@page
-@node Control Mechanisms
-@chapter Controlling the Flow of Program Execution
-
-@menu
-* begin:: Evaluating a sequence of expressions.
-* if cond case:: Simple conditional evaluation.
-* and or:: Conditional evaluation of a sequence.
-* while do:: Iteration mechanisms.
-* Continuations:: Continuations.
-* Multiple Values:: Returning and accepting multiple values.
-* Exceptions:: Throwing and catching exceptions.
-* Error Reporting:: Procedures for signaling errors.
-* Dynamic Wind:: Guarding against non-local entrance/exit.
-* Handling Errors:: How to handle errors in C code.
-@end menu
-
-
-@node begin
-@section Evaluating a Sequence of Expressions
-
-@c FIXME::martin: Review me!
-
-@c FIXME::martin: Maybe add examples?
-
-@cindex begin
-@cindex sequencing
-@cindex expression sequencing
-
-@code{begin} is used for grouping several expression together so that
-they syntactically are treated as if they were one expression. This is
-particularly important when syntactic expressions are used which only
-allow one expression, but the programmer wants to use more than one
-expression in that place. As an example, consider the conditional
-expression below:
-
-@lisp
-(if (> x 0)
- (begin (display "greater") (newline)))
-@end lisp
-
-If the two calls to @code{display} and @code{newline} were not embedded
-in a @code{begin}-statement, the call to @code{newline} would get
-misinterpreted as the else-branch of the @code{if}-expression.
-
-@deffn syntax begin expr1 expr2 @dots{}
-The expression(s) are evaluated in left-to-right order and the value
-of the last expression is returned as the value of the
-@code{begin}-expression. This expression type is used when the
-expressions before the last one are evaluated for their side effects.
-@end deffn
-
-@node if cond case
-@section Simple Conditional Evaluation
-
-@c FIXME::martin: Review me!
-
-@c FIXME::martin: Maybe add examples?
-
-@cindex conditional evaluation
-@cindex if
-@cindex case
-@cindex cond
-
-Guile provides three syntactic constructs for conditional evaluation.
-@code{if} is the normal if-then-else expression (with an optional else
-branch), @code{cond} is a conditional expression with multiple branches
-and @code{case} branches if an expression has one of a set of constant
-values.
-
-@deffn syntax if test consequent [alternate]
-All arguments may be arbitrary expressions. First, @var{test} is
-evaluated. If it returns a true value, the expression @var{consequent}
-is evaluated and @var{alternate} is ignored. If @var{test} evaluates to
-@code{#f}, @var{alternate} is evaluated instead. The value of the
-evaluated branch (@var{consequent} or @var{alternate}) is returned as
-the value of the @code{if} expression.
-
-When @var{alternate} is omitted and the @var{test} evaluates to
-@code{#f}, the value of the expression is not specified.
-@end deffn
-
-@deffn syntax cond clause1 clause2 @dots{}
-Each @code{cond}-clause must look like this:
-
-@lisp
-(@var{test} @var{expression} @dots{})
-@end lisp
-
-where @var{test} and @var{expression} are arbitrary expression, or like
-this
-
-@lisp
-(@var{test} => @var{expression}
-@end lisp
-
-where @var{expression} must evaluate to a procedure.
-
-The @var{test}s of the clauses are evaluated in order and as soon as one
-of them evaluates to a true values, the corresponding @var{expression}s
-are evaluated in order and the last value is returned as the value of
-the @code{cond}-expression. For the @code{=>} clause type,
-@var{expression} is evaluated and the resulting procedure is applied to
-the value of @var{test}. The result of this procedure application is
-then the result of the @code{cond}-expression.
-
-The @var{test} of the last @var{clause} may be the keyword @code{else}.
-Then, if none of the preceding @var{test}s is true, the @var{expression}s following the @code{else} are evaluated to produce the result of the @code{cond}-expression.
-@end deffn
-
-@deffn syntax case key clause1 clause2 @dots{}
-@var{key} may be any expression, the @var{clause}s must have the form
-
-@lisp
-((@var{datum1} @dots{}) @var{expr1} @var{expr2} @dots{})
-@end lisp
-
-and the last @var{clause} may have the form
-
-@lisp
-(else @var{expr1} @var{expr2} @dots{})
-@end lisp
-
-All @var{datum}s must be distinct. First, @var{key} is evaluated. The
-the result of this evaluation is compared against all @var{datum}s using
-@code{eqv?}. When this comparison succeeds, the expression(s) following
-the @var{datum} are evaluated from left to right, returning the value of
-the last expression as the result of the @code{case} expression.
-
-If the @var{key} matches no @var{datum} and there is an
-@code{else}-clause, the expressions following the @code{else} are
-evaluated. If there is no such clause, the result of the expression is
-unspecified.
-@end deffn
-
-
-@node and or
-@section Conditional Evaluation of a Sequence of Expressions
-
-@c FIXME::martin: Review me!
-
-@c FIXME::martin: Maybe add examples?
-
-@code{and} and @code{or} evaluate all their arguments, similar to
-@code{begin}, but evaluation stops as soon as one of the expressions
-evaluates to false or true, respectively.
-
-@deffn syntax and expr @dots{}
-Evaluate the @var{expr}s from left to right and stop evaluation as soon
-as one expression evaluates to @code{#f}; the remaining expressions are
-not evaluated. The value of the last evaluated expression is returned.
-If no expression evaluates to @code{#f}, the value of the last
-expression is returned.
-
-If used without expressions, @code{#t} is returned.
-@end deffn
-
-@deffn syntax or expr @dots{}
-Evaluate the @var{expr}s from left to right and stop evaluation as soon
-as one expression evaluates to a true value (that is, a value different
-from @code{#f}); the remaining expressions are not evaluated. The value
-of the last evaluated expression is returned. If all expressions
-evaluate to @code{#f}, @code{#f} is returned.
-
-If used without expressions, @code{#f} is returned.
-@end deffn
-
-
-@node while do
-@section Iteration mechanisms
-
-@c FIXME::martin: Review me!
-
-@c FIXME::martin: Maybe add examples?
-
-@cindex iteration
-@cindex looping
-@cindex named let
-
-Scheme has only few iteration mechanisms, mainly because iteration in
-Scheme programs is normally expressed using recursion. Nevertheless,
-R5RS defines a construct for programming loops, calling @code{do}. In
-addition, Guile has an explicit looping syntax called @code{while}.
-
-@deffn syntax do ((variable1 init1 step1) @dots{}) (test expr @dots{}) command @dots{}
-The @var{init} expressions are evaluated and the @var{variables} are
-bound to their values. Then looping starts with testing the @var{test}
-expression. If @var{test} evaluates to a true value, the @var{expr}
-following the @var{test} are evaluated and the value of the last
-@var{expr} is returned as the value of the @code{do} expression. If
-@var{test} evaluates to false, the @var{command}s are evaluated in
-order, the @var{step}s are evaluated and stored into the @var{variables}
-and the next iteration starts.
-
-Any of the @var{step} expressions may be omitted, so that the
-corresponding variable is not changed during looping.
-@end deffn
-
-@deffn syntax while cond body @dots{}
-Evaluate all expressions in @var{body} in order, as long as @var{cond}
-evaluates to a true value. The @var{cond} expression is tested before
-every iteration, so that the body is not evaluated at all if @var{cond}
-is @code{#f} right from the start.
-@end deffn
-
-@cindex named let
-Another very common way of expressing iteration in Scheme programs is
-the use of the so-called @dfn{named let}.
-
-Named let is a variant of @code{let} which creates a procedure and calls
-it in one step. Because of the newly created procedure, named let is
-more powerful than @code{do}--it can be used for iteration, but also
-for arbitrary recursion.
-
-@deffn syntax let variable bindings body
-For the definition of @var{bindings} see the documentation about
-@code{let} (@pxref{Local Bindings}).
-
-Named @code{let} works as follows:
-
-@itemize @bullet
-@item
-A new procedure which accepts as many arguments as are in @var{bindings}
-is created and bound locally (using @code{let}) to @var{variable}. The
-new procedure's formal argument names are the name of the
-@var{variables}.
-
-@item
-The @var{body} expressions are inserted into the newly created procedure.
-
-@item
-The procedure is called with the @var{init} expressions as the formal
-arguments.
-@end itemize
-
-The next example implements a loop which iterates (by recursion) 1000
-times.
-
-@lisp
-(let lp ((x 1000))
- (if (positive? x)
- (lp (- x 1))
- x))
-@result{}
-0
-@end lisp
-@end deffn
-
-
-@node Continuations
-@section Continuations
-
-@cindex call/cc
-@cindex call-with-current-continuation
-The ability to explicitly capture continuations using
-@code{call-with-current-continuation} (also often called @code{call/cc}
-for short), and to invoke such continuations later any number of times,
-and from any other point in a program, provides maybe the most powerful
-control structure known. All other control structures, such as loops
-and coroutines, can be emulated using continuations.
-
-@c NJFIXME - need a little something here about what continuations are
-@c and what they do for you.
-
-The implementation of continuations in Guile is not as efficient as one
-might hope, because it is constrained by the fact that Guile is designed
-to cooperate with programs written in other languages, such as C, which
-do not know about continuations. So continuations should be used when
-there is no other simple way of achieving the desired behaviour, or
-where the advantages of the elegant continuation mechanism outweigh the
-need for optimum performance. If you find yourself using @code{call/cc}
-for escape procedures and your program is running too slow, you might
-want to use exceptions (@pxref{Exceptions}) instead.
-
-@rnindex call-with-current-continuation
-@deffn {Scheme Procedure} call-with-current-continuation proc
-Capture the current continuation and call @var{proc} with the captured
-continuation as the single argument. This continuation can then be
-called with arbitrarily many arguments. Such a call will work like a
-goto to the invocation location of
-@code{call-with-current-continuation}, passing the arguments in a way
-that they are returned by the call to
-@code{call-with-current-continuation}. Since it is legal to store the
-captured continuation in a variable or to pass it to other procedures,
-it is possible that a procedure returns more than once, even if it is
-called only one time. This can be confusing at times.
-@end deffn
-
-@c FIXME::martin: Better example needed.
-@lisp
-(define kont #f)
-(call-with-current-continuation
- (lambda (k)
- (set! kont k)
- 1))
-@result{}
-1
-
-(kont 2)
-@result{}
-2
-@end lisp
-
-
-@node Multiple Values
-@section Returning and Accepting Multiple Values
-
-@c FIXME::martin: Review me!
-@cindex multiple values
-@cindex receive
-
-Scheme allows a procedure to return more than one value to its caller.
-This is quite different to other languages which only allow
-single-value returns. Returning multiple values is different from
-returning a list (or pair or vector) of values to the caller, because
-conceptually not @emph{one} compound object is returned, but several
-distinct values.
-
-The primitive procedures for handling multiple values are @code{values}
-and @code{call-with-values}. @code{values} is used for returning
-multiple values from a procedure. This is done by placing a call to
-@code{values} with zero or more arguments in tail position in a
-procedure body. @code{call-with-values} combines a procedure returning
-multiple values with a procedure which accepts these values as
-parameters.
-
-@rnindex values
-@deffn {Scheme Procedure} values . args
-@deffnx {C Function} scm_values (args)
-Delivers all of its arguments to its continuation. Except for
-continuations created by the @code{call-with-values} procedure,
-all continuations take exactly one value. The effect of
-passing no value or more than one value to continuations that
-were not created by @code{call-with-values} is unspecified.
-@end deffn
-
-@rnindex call-with-values
-@deffn {Scheme Procedure} call-with-values producer consumer
-Calls its @var{producer} argument with no values and a
-continuation that, when passed some values, calls the
-@var{consumer} procedure with those values as arguments. The
-continuation for the call to @var{consumer} is the continuation
-of the call to @code{call-with-values}.
-
-@example
-(call-with-values (lambda () (values 4 5))
- (lambda (a b) b))
- ==> 5
-
-@end example
-@example
-(call-with-values * -) ==> -1
-@end example
-@end deffn
-
-In addition to the fundamental procedures described above, Guile has a
-module which exports a syntax called @code{receive}, which is much more
-convenient. If you want to use it in your programs, you have to load
-the module @code{(ice-9 receive)} with the statement
-
-@lisp
-(use-modules (ice-9 receive))
-@end lisp
-
-@deffn {library syntax} receive formals expr body @dots{}
-Evaluate the expression @var{expr}, and bind the result values (zero or
-more) to the formal arguments in the formal argument list @var{formals}.
-@var{formals} must have the same syntax like the formal argument list
-used in @code{lambda} (@pxref{Lambda}). After binding the variables,
-the expressions in @var{body} @dots{} are evaluated in order.
-@end deffn
-
-
-@node Exceptions
-@section Exceptions
-@cindex error handling
-@cindex exception handling
-
-A common requirement in applications is to want to jump
-@dfn{non-locally} from the depths of a computation back to, say, the
-application's main processing loop. Usually, the place that is the
-target of the jump is somewhere in the calling stack of procedures that
-called the procedure that wants to jump back. For example, typical
-logic for a key press driven application might look something like this:
-
-@example
-main-loop:
- read the next key press and call dispatch-key
-
-dispatch-key:
- lookup the key in a keymap and call an appropriate procedure,
- say find-file
-
-find-file:
- interactively read the required file name, then call
- find-specified-file
-
-find-specified-file:
- check whether file exists; if not, jump back to main-loop
- @dots{}
-@end example
-
-The jump back to @code{main-loop} could be achieved by returning through
-the stack one procedure at a time, using the return value of each
-procedure to indicate the error condition, but Guile (like most modern
-programming languages) provides an additional mechanism called
-@dfn{exception handling} that can be used to implement such jumps much
-more conveniently.
-
-@menu
-* Exception Terminology:: Different ways to say the same thing.
-* Catch:: Setting up to catch exceptions.
-* Throw:: Throwing an exception.
-* Lazy Catch:: Catch without unwinding the stack.
-* Exception Implementation:: How Guile implements exceptions.
-@end menu
-
-
-@node Exception Terminology
-@subsection Exception Terminology
-
-There are several variations on the terminology for dealing with
-non-local jumps. It is useful to be aware of them, and to realize
-that they all refer to the same basic mechanism.
-
-@itemize @bullet
-@item
-Actually making a non-local jump may be called @dfn{raising an
-exception}, @dfn{raising a signal}, @dfn{throwing an exception} or
-@dfn{doing a long jump}. When the jump indicates an error condition,
-people may talk about @dfn{signalling}, @dfn{raising} or @dfn{throwing}
-@dfn{an error}.
-
-@item
-Handling the jump at its target may be referred to as @dfn{catching} or
-@dfn{handling} the @dfn{exception}, @dfn{signal} or, where an error
-condition is involved, @dfn{error}.
-@end itemize
-
-Where @dfn{signal} and @dfn{signalling} are used, special care is needed
-to avoid the risk of confusion with POSIX signals. (Especially
-considering that Guile handles POSIX signals by throwing a corresponding
-kind of exception: REFFIXME.)
-
-This manual prefers to speak of throwing and catching exceptions, since
-this terminology matches the corresponding Guile primitives.
-
-
-@node Catch
-@subsection Catching Exceptions
-
-@code{catch} is used to set up a target for a possible non-local jump.
-The arguments of a @code{catch} expression are a @dfn{key}, which
-restricts the set of exceptions to which this @code{catch} applies, a
-thunk that specifies the @dfn{normal case} code --- i.e. what should
-happen if no exceptions are thrown --- and a @dfn{handler} procedure
-that says what to do if an exception is thrown. Note that if the
-@dfn{normal case} thunk executes @dfn{normally}, which means without
-throwing any exceptions, the handler procedure is not executed at all.
-
-When an exception is thrown using the @code{throw} primitive, the first
-argument of the @code{throw} is a symbol that indicates the type of the
-exception. For example, Guile throws an exception using the symbol
-@code{numerical-overflow} to indicate numerical overflow errors such as
-division by zero:
-
-@lisp
-(/ 1 0)
-@result{}
-ABORT: (numerical-overflow)
-@end lisp
-
-The @var{key} argument in a @code{catch} expression corresponds to this
-symbol. @var{key} may be a specific symbol, such as
-@code{numerical-overflow}, in which case the @code{catch} applies
-specifically to exceptions of that type; or it may be @code{#t}, which
-means that the @code{catch} applies to all exceptions, irrespective of
-their type.
-
-The second argument of a @code{catch} expression should be a thunk
-(i.e. a procedure that accepts no arguments) that specifies the normal
-case code. The @code{catch} is active for the execution of this thunk,
-including any code called directly or indirectly by the thunk's body.
-Evaluation of the @code{catch} expression activates the catch and then
-calls this thunk.
-
-The third argument of a @code{catch} expression is a handler procedure.
-If an exception is thrown, this procedure is called with exactly the
-arguments specified by the @code{throw}. Therefore, the handler
-procedure must be designed to accept a number of arguments that
-corresponds to the number of arguments in all @code{throw} expressions
-that can be caught by this @code{catch}.
-
-@deffn {Scheme Procedure} catch key thunk handler
-@deffnx {C Function} scm_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:
-@lisp
-(handler key args ...)
-@end lisp
-
-@var{key} is a symbol or @code{#t}.
-
-@var{thunk} takes no arguments. If @var{thunk} returns
-normally, that is the return value of @code{catch}.
-
-Handler is invoked outside the scope of its own @code{catch}.
-If @var{handler} 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}.
-@end deffn
-
-If the handler procedure needs to match a variety of @code{throw}
-expressions with varying numbers of arguments, you should write it like
-this:
-
-@lisp
-(lambda (key . args)
- @dots{})
-@end lisp
-
-@noindent
-The @var{key} argument is guaranteed always to be present, because a
-@code{throw} without a @var{key} is not valid. The number and
-interpretation of the @var{args} varies from one type of exception to
-another, but should be specified by the documentation for each exception
-type.
-
-Note that, once the handler procedure is invoked, the catch that led to
-the handler procedure being called is no longer active. Therefore, if
-the handler procedure itself throws an exception, that exception can
-only be caught by another active catch higher up the call stack, if
-there is one.
-
-
-@node Throw
-@subsection Throwing Exceptions
-
-The @code{throw} primitive is used to throw an exception. One argument,
-the @var{key}, is mandatory, and must be a symbol; it indicates the type
-of exception that is being thrown. Following the @var{key},
-@code{throw} accepts any number of additional arguments, whose meaning
-depends on the exception type. The documentation for each possible type
-of exception should specify the additional arguments that are expected
-for that kind of exception.
-
-@deffn {Scheme Procedure} throw key . args
-@deffnx {C Function} scm_throw (key, args)
-Invoke the catch form matching @var{key}, passing @var{args} to the
-@var{handler}.
-
-@var{key} is a symbol. It will match catches of the same symbol or of
-@code{#t}.
-
-If there is no handler at all, Guile prints an error and then exits.
-@end deffn
-
-When an exception is thrown, it will be caught by the innermost
-@code{catch} expression that applies to the type of the thrown
-exception; in other words, the innermost @code{catch} whose @var{key} is
-@code{#t} or is the same symbol as that used in the @code{throw}
-expression. Once Guile has identified the appropriate @code{catch}, it
-handles the exception by applying that @code{catch} expression's handler
-procedure to the arguments of the @code{throw}.
-
-If there is no appropriate @code{catch} for a thrown exception, Guile
-prints an error to the current error port indicating an uncaught
-exception, and then exits. In practice, it is quite difficult to
-observe this behaviour, because Guile when used interactively installs a
-top level @code{catch} handler that will catch all exceptions and print
-an appropriate error message @emph{without} exiting. For example, this
-is what happens if you try to throw an unhandled exception in the
-standard Guile REPL; note that Guile's command loop continues after the
-error message:
-
-@lisp
-guile> (throw 'badex)
-<unnamed port>:3:1: In procedure gsubr-apply @dots{}
-<unnamed port>:3:1: unhandled-exception: badex
-ABORT: (misc-error)
-guile>
-@end lisp
-
-The default uncaught exception behaviour can be observed by evaluating a
-@code{throw} expression from the shell command line:
-
-@example
-$ guile -c "(begin (throw 'badex) (display \"here\\n\"))"
-guile: uncaught throw to badex: ()
-$
-@end example
-
-@noindent
-That Guile exits immediately following the uncaught exception
-is shown by the absence of any output from the @code{display}
-expression, because Guile never gets to the point of evaluating that
-expression.
-
-
-@node Lazy Catch
-@subsection Catch Without Unwinding
-
-A @dfn{lazy catch} is used in the same way as a normal @code{catch},
-with @var{key}, @var{thunk} and @var{handler} arguments specifying the
-exception type, normal case code and handler procedure, but differs in
-one important respect: the handler procedure is executed without
-unwinding the call stack from the context of the @code{throw} expression
-that caused the handler to be invoked.
-
-@deffn {Scheme Procedure} lazy-catch key thunk handler
-@deffnx {C Function} scm_lazy_catch (key, thunk, handler)
-This behaves exactly like @code{catch}, except that it does
-not unwind the stack before invoking @var{handler}.
-The @var{handler} procedure is not allowed to return:
-it must throw to another catch, or otherwise exit non-locally.
-@end deffn
-
-Typically, @var{handler} should save any desired state associated with
-the stack at the point where the corresponding @code{throw} occurred,
-and then throw an exception itself --- usually the same exception as the
-one it caught. If @var{handler} is invoked and does @emph{not} throw an
-exception, Guile itself throws an exception with key @code{misc-error}.
-
-Not unwinding the stack means that throwing an exception that is caught
-by a @code{lazy-catch} is @emph{almost} equivalent to calling the
-@code{lazy-catch}'s handler inline instead of each @code{throw}, and
-then omitting the surrounding @code{lazy-catch}. In other words,
-
-@lisp
-(lazy-catch 'key
- (lambda () @dots{} (throw 'key args @dots{}) @dots{})
- handler)
-@end lisp
-
-@noindent
-is @emph{almost} equivalent to
-
-@lisp
-((lambda () @dots{} (handler 'key args @dots{}) @dots{}))
-@end lisp
-
-@noindent
-But why only @emph{almost}? The difference is that with
-@code{lazy-catch} (as with normal @code{catch}), the dynamic context is
-unwound back to just outside the @code{lazy-catch} expression before
-invoking the handler. (For an introduction to what is meant by dynamic
-context, @xref{Dynamic Wind}.)
-
-Then, when the handler @emph{itself} throws an exception, that exception
-must be caught by some kind of @code{catch} (including perhaps another
-@code{lazy-catch}) higher up the call stack.
-
-The dynamic context also includes @code{with-fluids} blocks (REFFIXME),
-so the effect of unwinding the dynamic context can also be seen in fluid
-variable values. This is illustrated by the following code, in which
-the normal case thunk uses @code{with-fluids} to temporarily change the
-value of a fluid:
-
-@lisp
-(define f (make-fluid))
-(fluid-set! f "top level value")
-
-(define (handler . args)
- (cons (fluid-ref f) args))
-
-(lazy-catch 'foo
- (lambda ()
- (with-fluids ((f "local value"))
- (throw 'foo)))
- handler)
-@result{}
-("top level value" foo)
-
-((lambda ()
- (with-fluids ((f "local value"))
- (handler 'foo))))
-@result{}
-("local value" foo)
-@end lisp
-
-@noindent
-In the @code{lazy-catch} version, the unwinding of dynamic context
-restores @code{f} to its value outside the @code{with-fluids} block
-before the handler is invoked, so the handler's @code{(fluid-ref f)}
-returns the external value.
-
-@code{lazy-catch} is useful because it permits the implementation of
-debuggers and other reflective programming tools that need to access the
-state of the call stack at the exact point where an exception or an
-error is thrown. For an example of this, see REFFIXME:stack-catch.
-
-
-@node Exception Implementation
-@subsection How Guile Implements Exceptions
-
-It is traditional in Scheme to implement exception systems using
-@code{call-with-current-continuation}. Continuations
-(@pxref{Continuations}) are such a powerful concept that any other
-control mechanism --- including @code{catch} and @code{throw} --- can be
-implemented in terms of them.
-
-Guile does not implement @code{catch} and @code{throw} like this,
-though. Why not? Because Guile is specifically designed to be easy to
-integrate with applications written in C. In a mixed Scheme/C
-environment, the concept of @dfn{continuation} must logically include
-``what happens next'' in the C parts of the application as well as the
-Scheme parts, and it turns out that the only reasonable way of
-implementing continuations like this is to save and restore the complete
-C stack.
-
-So Guile's implementation of @code{call-with-current-continuation} is a
-stack copying one. This allows it to interact well with ordinary C
-code, but means that creating and calling a continuation is slowed down
-by the time that it takes to copy the C stack.
-
-The more targeted mechanism provided by @code{catch} and @code{throw}
-does not need to save and restore the C stack because the @code{throw}
-always jumps to a location higher up the stack of the code that executes
-the @code{throw}. Therefore Guile implements the @code{catch} and
-@code{throw} primitives independently of
-@code{call-with-current-continuation}, in a way that takes advantage of
-this @emph{upwards only} nature of exceptions.
-
-
-@node Error Reporting
-@section Procedures for Signaling Errors
-
-Guile provides a set of convenience procedures for signaling error
-conditions that are implemented on top of the exception primitives just
-described.
-
-@deffn {Scheme Procedure} error msg args @dots{}
-Raise an error with key @code{misc-error} and a message constructed by
-displaying @var{msg} and writing @var{args}.
-@end deffn
-
-@deffn {Scheme Procedure} scm-error key subr message args data
-@deffnx {C Function} scm_error_scm (key, subr, message, args, data)
-Raise an error with key @var{key}. @var{subr} can be a string
-naming the procedure associated with the error, or @code{#f}.
-@var{message} is the error message string, possibly containing
-@code{~S} and @code{~A} escapes. When an error is reported,
-these are replaced by formatting the corresponding members of
-@var{args}: @code{~A} (was @code{%s} in older versions of
-Guile) formats using @code{display} and @code{~S} (was
-@code{%S}) formats using @code{write}. @var{data} is a list or
-@code{#f} depending on @var{key}: if @var{key} is
-@code{system-error} then it should be a list containing the
-Unix @code{errno} value; If @var{key} is @code{signal} then it
-should be a list containing the Unix signal number; otherwise
-it will usually be @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} strerror err
-@deffnx {C Function} scm_strerror (err)
-Return the Unix error message corresponding to @var{err}, which
-must be an integer value.
-@end deffn
-
-@c begin (scm-doc-string "boot-9.scm" "false-if-exception")
-@deffn syntax false-if-exception expr
-Returns the result of evaluating its argument; however
-if an exception occurs then @code{#f} is returned instead.
-@end deffn
-@c end
-
-
-@node Dynamic Wind
-@section Dynamic Wind
-
-[FIXME: this is pasted in from Tom Lord's original guile.texi and should
-be reviewed]
-
-@rnindex dynamic-wind
-@deffn {Scheme Procedure} dynamic-wind in_guard thunk out_guard
-@deffnx {C Function} scm_dynamic_wind (in_guard, thunk, out_guard)
-All three arguments must be 0-argument procedures.
-@var{in_guard} is called, then @var{thunk}, then
-@var{out_guard}.
-
-If, any time during the execution of @var{thunk}, the
-continuation of the @code{dynamic_wind} expression is escaped
-non-locally, @var{out_guard} is called. If the continuation of
-the dynamic-wind is re-entered, @var{in_guard} is called. Thus
-@var{in_guard} and @var{out_guard} may be called any number of
-times.
-@lisp
-(define x 'normal-binding)
-@result{} x
-(define a-cont (call-with-current-continuation
- (lambda (escape)
- (let ((old-x x))
- (dynamic-wind
- ;; in-guard:
- ;;
- (lambda () (set! x 'special-binding))
-
- ;; thunk
- ;;
- (lambda () (display x) (newline)
- (call-with-current-continuation escape)
- (display x) (newline)
- x)
-
- ;; out-guard:
- ;;
- (lambda () (set! x old-x)))))))
-
-;; Prints:
-special-binding
-;; Evaluates to:
-@result{} a-cont
-x
-@result{} normal-binding
-(a-cont #f)
-;; Prints:
-special-binding
-;; Evaluates to:
-@result{} a-cont ;; the value of the (define a-cont...)
-x
-@result{} normal-binding
-a-cont
-@result{} special-binding
-@end lisp
-@end deffn
-
-
-@node Handling Errors
-@section How to Handle Errors in C Code
-
-Error handling is based on @code{catch} and @code{throw}. Errors are
-always thrown with a @var{key} and four arguments:
-
-@itemize @bullet
-@item
-@var{key}: a symbol which indicates the type of error. The symbols used
-by libguile are listed below.
-
-@item
-@var{subr}: the name of the procedure from which the error is thrown, or
-@code{#f}.
-
-@item
-@var{message}: a string (possibly language and system dependent)
-describing the error. The tokens @code{~A} and @code{~S} can be
-embedded within the message: they will be replaced with members of the
-@var{args} list when the message is printed. @code{~A} indicates an
-argument printed using @code{display}, while @code{~S} indicates an
-argument printed using @code{write}. @var{message} can also be
-@code{#f}, to allow it to be derived from the @var{key} by the error
-handler (may be useful if the @var{key} is to be thrown from both C and
-Scheme).
-
-@item
-@var{args}: a list of arguments to be used to expand @code{~A} and
-@code{~S} tokens in @var{message}. Can also be @code{#f} if no
-arguments are required.
-
-@item
-@var{rest}: a list of any additional objects required. e.g., when the
-key is @code{'system-error}, this contains the C errno value. Can also
-be @code{#f} if no additional objects are required.
-@end itemize
-
-In addition to @code{catch} and @code{throw}, the following Scheme
-facilities are available:
-
-@deffn {Scheme Procedure} scm-error key subr message args rest
-Throw an error, with arguments
-as described above.
-@end deffn
-
-@deffn {Scheme Procedure} error msg arg @dots{}
-Throw an error using the key @code{'misc-error}. The error
-message is created by displaying @var{msg} and writing the @var{args}.
-@end deffn
-
-@deffn {Scheme Procedure} display-error stack port subr message args rest
-@deffnx {C Function} scm_display_error (stack, port, subr, message, args, rest)
-Display an error message to the output port @var{port}.
-@var{stack} is the saved stack for the error, @var{subr} is
-the name of the procedure in which the error occurred and
-@var{message} is the actual error message, which may contain
-formatting instructions. These will format the arguments in
-the list @var{args} accordingly. @var{rest} is currently
-ignored.
-@end deffn
-
-The following are the error keys defined by libguile and the situations
-in which they are used:
-
-@itemize @bullet
-@item
-@code{error-signal}: thrown after receiving an unhandled fatal signal
-such as SIGSEGV, SIGBUS, SIGFPE etc. The @var{rest} argument in the throw
-contains the coded signal number (at present this is not the same as the
-usual Unix signal number).
-
-@item
-@code{system-error}: thrown after the operating system indicates an
-error condition. The @var{rest} argument in the throw contains the
-errno value.
-
-@item
-@code{numerical-overflow}: numerical overflow.
-
-@item
-@code{out-of-range}: the arguments to a procedure do not fall within the
-accepted domain.
-
-@item
-@code{wrong-type-arg}: an argument to a procedure has the wrong type.
-
-@item
-@code{wrong-number-of-args}: a procedure was called with the wrong number
-of arguments.
-
-@item
-@code{memory-allocation-error}: memory allocation error.
-
-@item
-@code{stack-overflow}: stack overflow error.
-
-@item
-@code{regex-error}: errors generated by the regular expression library.
-
-@item
-@code{misc-error}: other errors.
-@end itemize
-
-
-@subsection C Support
-
-SCM scm_error (SCM key, char *subr, char *message, SCM args, SCM rest)
-
-Throws an error, after converting the char * arguments to Scheme strings.
-subr is the Scheme name of the procedure, NULL is converted to #f.
-Likewise a NULL message is converted to #f.
-
-The following procedures invoke scm_error with various error keys and
-arguments. The first three call scm_error with the system-error key
-and automatically supply errno in the "rest" argument: scm_syserror
-generates messages using strerror, scm_sysmissing is used when
-facilities are not available. Care should be taken that the errno
-value is not reset (e.g. due to an interrupt).
-
-@itemize @bullet
-@item
-void scm_syserror (char *subr);
-@item
-void scm_syserror_msg (char *subr, char *message, SCM args);
-@item
-void scm_sysmissing (char *subr);
-@item
-void scm_num_overflow (char *subr);
-@item
-void scm_out_of_range (char *subr, SCM bad_value);
-@item
-void scm_wrong_num_args (SCM proc);
-@item
-void scm_wrong_type_arg (char *subr, int pos, SCM bad_value);
-@item
-void scm_memory_error (char *subr);
-@item
-static void scm_regex_error (char *subr, int code); (only used in rgx.c).
-@end itemize
-
-Exception handlers can also be installed from C, using
-scm_internal_catch, scm_lazy_catch, or scm_stack_catch from
-libguile/throw.c. These have not yet been documented, however the
-source contains some useful comments.
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-data.texi b/doc/ref/scheme-data.texi
deleted file mode 100755
index fc4a84afd..000000000
--- a/doc/ref/scheme-data.texi
+++ /dev/null
@@ -1,3086 +0,0 @@
-@page
-@node Simple Data Types
-@chapter Simple Generic Data Types
-
-This chapter describes those of Guile's simple data types which are
-primarily used for their role as items of generic data. By
-@dfn{simple} we mean data types that are not primarily used as
-containers to hold other data --- i.e. pairs, lists, vectors and so on.
-For the documentation of such @dfn{compound} data types, see
-@ref{Compound Data Types}.
-
-One of the great strengths of Scheme is that there is no straightforward
-distinction between ``data'' and ``functionality''. For example,
-Guile's support for dynamic linking could be described
-
-@itemize @bullet
-@item
-either in a ``data-centric'' way, as the behaviour and properties of the
-``dynamically linked object'' data type, and the operations that may be
-applied to instances of this type
-
-@item
-or in a ``functionality-centric'' way, as the set of procedures that
-constitute Guile's support for dynamic linking, in the context of the
-module system.
-@end itemize
-
-The contents of this chapter are, therefore, a matter of judgment. By
-@dfn{generic}, we mean to select those data types whose typical use as
-@emph{data} in a wide variety of programming contexts is more important
-than their use in the implementation of a particular piece of
-@emph{functionality}. The last section of this chapter provides
-references for all the data types that are documented not here but in a
-``functionality-centric'' way elsewhere in the manual.
-
-@menu
-* Booleans:: True/false values.
-* Numbers:: Numerical data types.
-* Characters:: New character names.
-* Strings:: Special things about strings.
-* Regular Expressions:: Pattern matching and substitution.
-* Symbols:: Symbols.
-* Keywords:: Self-quoting, customizable display keywords.
-* Other Types:: "Functionality-centric" data types.
-@end menu
-
-
-@node Booleans
-@section Booleans
-@tpindex Booleans
-
-The two boolean values are @code{#t} for true and @code{#f} for false.
-
-Boolean values are returned by predicate procedures, such as the general
-equality predicates @code{eq?}, @code{eqv?} and @code{equal?}
-(@pxref{Equality}) and numerical and string comparison operators like
-@code{string=?} (@pxref{String Comparison}) and @code{<=}
-(@pxref{Comparison}).
-
-@lisp
-(<= 3 8)
-@result{}
-#t
-
-(<= 3 -3)
-@result{}
-#f
-
-(equal? "house" "houses")
-@result{}
-#f
-
-(eq? #f #f)
-@result{}
-#t
-@end lisp
-
-In test condition contexts like @code{if} and @code{cond} (@pxref{if
-cond case}), where a group of subexpressions will be evaluated only if a
-@var{condition} expression evaluates to ``true'', ``true'' means any
-value at all except @code{#f}.
-
-@lisp
-(if #t "yes" "no")
-@result{}
-"yes"
-
-(if 0 "yes" "no")
-@result{}
-"yes"
-
-(if #f "yes" "no")
-@result{}
-"no"
-@end lisp
-
-A result of this asymmetry is that typical Scheme source code more often
-uses @code{#f} explicitly than @code{#t}: @code{#f} is necessary to
-represent an @code{if} or @code{cond} false value, whereas @code{#t} is
-not necessary to represent an @code{if} or @code{cond} true value.
-
-It is important to note that @code{#f} is @strong{not} equivalent to any
-other Scheme value. In particular, @code{#f} is not the same as the
-number 0 (like in C and C++), and not the same as the ``empty list''
-(like in some Lisp dialects).
-
-The @code{not} procedure returns the boolean inverse of its argument:
-
-@rnindex not
-@deffn {Scheme Procedure} not x
-@deffnx {C Function} scm_not (x)
-Return @code{#t} iff @var{x} is @code{#f}, else return @code{#f}.
-@end deffn
-
-The @code{boolean?} procedure is a predicate that returns @code{#t} if
-its argument is one of the boolean values, otherwise @code{#f}.
-
-@rnindex boolean?
-@deffn {Scheme Procedure} boolean? obj
-@deffnx {C Function} scm_boolean_p (obj)
-Return @code{#t} iff @var{obj} is either @code{#t} or @code{#f}.
-@end deffn
-
-
-@node Numbers
-@section Numerical data types
-@tpindex Numbers
-
-Guile supports a rich ``tower'' of numerical types --- integer,
-rational, real and complex --- and provides an extensive set of
-mathematical and scientific functions for operating on numerical
-data. This section of the manual documents those types and functions.
-
-You may also find it illuminating to read R5RS's presentation of numbers
-in Scheme, which is particularly clear and accessible: see
-@xref{Numbers,,,r5rs}.
-
-@menu
-* Numerical Tower:: Scheme's numerical "tower".
-* Integers:: Whole numbers.
-* Reals and Rationals:: Real and rational numbers.
-* Complex Numbers:: Complex numbers.
-* Exactness:: Exactness and inexactness.
-* Number Syntax:: Read syntax for numerical data.
-* Integer Operations:: Operations on integer values.
-* Comparison:: Comparison predicates.
-* Conversion:: Converting numbers to and from strings.
-* Complex:: Complex number operations.
-* Arithmetic:: Arithmetic functions.
-* Scientific:: Scientific functions.
-* Primitive Numerics:: Primitive numeric functions.
-* Bitwise Operations:: Logical AND, OR, NOT, and so on.
-* Random:: Random number generation.
-@end menu
-
-
-@node Numerical Tower
-@subsection Scheme's Numerical ``Tower''
-@rnindex number?
-
-Scheme's numerical ``tower'' consists of the following categories of
-numbers:
-
-@itemize @bullet
-@item
-integers (whole numbers)
-
-@item
-rationals (the set of numbers that can be expressed as P/Q where P and Q
-are integers)
-
-@item
-real numbers (the set of numbers that describes all possible positions
-along a one dimensional line)
-
-@item
-complex numbers (the set of numbers that describes all possible
-positions in a two dimensional space)
-@end itemize
-
-It is called a tower because each category ``sits on'' the one that
-follows it, in the sense that every integer is also a rational, every
-rational is also real, and every real number is also a complex number
-(but with zero imaginary part).
-
-Of these, Guile implements integers, reals and complex numbers as
-distinct types. Rationals are implemented as regards the read syntax
-for rational numbers that is specified by R5RS, but are immediately
-converted by Guile to the corresponding real number.
-
-The @code{number?} predicate may be applied to any Scheme value to
-discover whether the value is any of the supported numerical types.
-
-@deffn {Scheme Procedure} number? obj
-@deffnx {C Function} scm_number_p (obj)
-Return @code{#t} if @var{obj} is any kind of number, else @code{#f}.
-@end deffn
-
-For example:
-
-@lisp
-(number? 3)
-@result{}
-#t
-
-(number? "hello there!")
-@result{}
-#f
-
-(define pi 3.141592654)
-(number? pi)
-@result{}
-#t
-@end lisp
-
-The next few subsections document each of Guile's numerical data types
-in detail.
-
-@node Integers
-@subsection Integers
-
-@tpindex Integer numbers
-
-@rnindex integer?
-
-Integers are whole numbers, that is numbers with no fractional part,
-such as 2, 83 and -3789.
-
-Integers in Guile can be arbitrarily big, as shown by the following
-example.
-
-@lisp
-(define (factorial n)
- (let loop ((n n) (product 1))
- (if (= n 0)
- product
- (loop (- n 1) (* product n)))))
-
-(factorial 3)
-@result{}
-6
-
-(factorial 20)
-@result{}
-2432902008176640000
-
-(- (factorial 45))
-@result{}
--119622220865480194561963161495657715064383733760000000000
-@end lisp
-
-Readers whose background is in programming languages where integers are
-limited by the need to fit into just 4 or 8 bytes of memory may find
-this surprising, or suspect that Guile's representation of integers is
-inefficient. In fact, Guile achieves a near optimal balance of
-convenience and efficiency by using the host computer's native
-representation of integers where possible, and a more general
-representation where the required number does not fit in the native
-form. Conversion between these two representations is automatic and
-completely invisible to the Scheme level programmer.
-
-The infinities @code{+inf.0} and @code{-inf.0} are considered to be
-inexact integers. They are explained in detail in the next section,
-together with reals and rationals.
-
-@c REFFIXME Maybe point here to discussion of handling immediates/bignums
-@c on the C level, where the conversion is not so automatic - NJ
-
-@deffn {Scheme Procedure} integer? x
-@deffnx {C Function} scm_integer_p (x)
-Return @code{#t} if @var{x} is an integer number, else @code{#f}.
-
-@lisp
-(integer? 487)
-@result{}
-#t
-
-(integer? -3.4)
-@result{}
-#f
-
-(integer? +inf.0)
-@result{}
-#t
-@end lisp
-@end deffn
-
-
-@node Reals and Rationals
-@subsection Real and Rational Numbers
-@tpindex Real numbers
-@tpindex Rational numbers
-
-@rnindex real?
-@rnindex rational?
-
-Mathematically, the real numbers are the set of numbers that describe
-all possible points along a continuous, infinite, one-dimensional line.
-The rational numbers are the set of all numbers that can be written as
-fractions P/Q, where P and Q are integers. All rational numbers are
-also real, but there are real numbers that are not rational, for example
-the square root of 2, and pi.
-
-Guile represents both real and rational numbers approximately using a
-floating point encoding with limited precision. Even though the actual
-encoding is in binary, it may be helpful to think of it as a decimal
-number with a limited number of significant figures and a decimal point
-somewhere, since this corresponds to the standard notation for non-whole
-numbers. For example:
-
-@lisp
-0.34
--0.00000142857931198
--5648394822220000000000.0
-4.0
-@end lisp
-
-The limited precision of Guile's encoding means that any ``real'' number
-in Guile can be written in a rational form, by multiplying and then dividing
-by sufficient powers of 10 (or in fact, 2). For example,
-@code{-0.00000142857931198} is the same as @code{142857931198} divided by
-@code{100000000000000000}. In Guile's current incarnation, therefore,
-the @code{rational?} and @code{real?} predicates are equivalent.
-
-Another aspect of this equivalence is that Guile currently does not
-preserve the exactness that is possible with rational arithmetic.
-If such exactness is needed, it is of course possible to implement
-exact rational arithmetic at the Scheme level using Guile's arbitrary
-size integers.
-
-A planned future revision of Guile's numerical tower will make it
-possible to implement exact representations and arithmetic for both
-rational numbers and real irrational numbers such as square roots,
-and in such a way that the new kinds of number integrate seamlessly
-with those that are already implemented.
-
-Dividing by an exact zero leads to a error message, as one might
-expect. However, dividing by an inexact zero does not produce an
-error. Instead, the result of the division is either plus or minus
-infinity, depending on the sign of the divided number.
-
-The infinities are written @samp{+inf.0} and @samp{-inf.0},
-respectibly. This syntax is also recognized by @code{read} as an
-extension to the usual Scheme syntax.
-
-Dividing zero by zero yields something that is not a number at all:
-@samp{+nan.0}. This is the special 'not a number' value.
-
-On platforms that follow IEEE 754 for their floating point arithmetic,
-the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values are
-implemented using the corresponding IEEE 754 values. They behave in
-arithmetic operations like IEEE 754 describes it, i.e., @code{(=
-+nan.0 +nan.0) @result{#f}}.
-
-The infinities are inexact integers and are considered to be both even
-and odd. While @samp{+nan.0} is not @code{=} to itself, it is
-@code{eqv?} to itself.
-
-To test for the special values, use the functions @code{inf?} and
-@code{nan?}.
-
-@deffn {Scheme Procedure} real? obj
-@deffnx {C Function} scm_real_p (obj)
-Return @code{#t} if @var{obj} is a real number, else @code{#f}.
-Note that the sets of integer and rational values form subsets
-of the set of real numbers, so the predicate will also be fulfilled
-if @var{obj} is an integer number or a rational number.
-@end deffn
-
-@deffn {Scheme Procedure} rational? x
-@deffnx {C Function} scm_real_p (x)
-Return @code{#t} if @var{x} is a rational number, @code{#f}
-otherwise. Note that the set of integer values forms a subset of
-the set of rational numbers, i. e. the predicate will also be
-fulfilled if @var{x} is an integer number. Real numbers
-will also satisfy this predicate, because of their limited
-precision.
-@end deffn
-
-@deffn {Scheme Procedure} inf? x
-Return @code{#t} if @var{x} is either @samp{+inf.0} or @samp{-inf.0},
-@code{#f} otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} nan? x
-Return @code{#t} if @var{x} is @samp{+nan.0}, @code{#f} otherwise.
-@end deffn
-
-@node Complex Numbers
-@subsection Complex Numbers
-@tpindex Complex numbers
-
-@rnindex complex?
-
-Complex numbers are the set of numbers that describe all possible points
-in a two-dimensional space. The two coordinates of a particular point
-in this space are known as the @dfn{real} and @dfn{imaginary} parts of
-the complex number that describes that point.
-
-In Guile, complex numbers are written in rectangular form as the sum of
-their real and imaginary parts, using the symbol @code{i} to indicate
-the imaginary part.
-
-@lisp
-3+4i
-@result{}
-3.0+4.0i
-
-(* 3-8i 2.3+0.3i)
-@result{}
-9.3-17.5i
-@end lisp
-
-Guile represents a complex number as a pair of numbers both of which are
-real, so the real and imaginary parts of a complex number have the same
-properties of inexactness and limited precision as single real numbers.
-
-@deffn {Scheme Procedure} complex? x
-@deffnx {C Function} scm_number_p (x)
-Return @code{#t} if @var{x} is a complex number, @code{#f}
-otherwise. Note that the sets of real, rational and integer
-values form subsets of the set of complex numbers, i. e. the
-predicate will also be fulfilled if @var{x} is a real,
-rational or integer number.
-@end deffn
-
-
-@node Exactness
-@subsection Exact and Inexact Numbers
-@tpindex Exact numbers
-@tpindex Inexact numbers
-
-@rnindex exact?
-@rnindex inexact?
-@rnindex exact->inexact
-@rnindex inexact->exact
-
-R5RS requires that a calculation involving inexact numbers always
-produces an inexact result. To meet this requirement, Guile
-distinguishes between an exact integer value such as @code{5} and the
-corresponding inexact real value which, to the limited precision
-available, has no fractional part, and is printed as @code{5.0}. Guile
-will only convert the latter value to the former when forced to do so by
-an invocation of the @code{inexact->exact} procedure.
-
-@deffn {Scheme Procedure} exact? x
-@deffnx {C Function} scm_exact_p (x)
-Return @code{#t} if @var{x} is an exact number, @code{#f}
-otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} inexact? x
-@deffnx {C Function} scm_inexact_p (x)
-Return @code{#t} if @var{x} is an inexact number, @code{#f}
-else.
-@end deffn
-
-@deffn {Scheme Procedure} inexact->exact z
-@deffnx {C Function} scm_inexact_to_exact (z)
-Return an exact number that is numerically closest to @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "exact->inexact")
-@deffn {Scheme Procedure} exact->inexact z
-Convert the number @var{z} to its inexact representation.
-@end deffn
-
-
-@node Number Syntax
-@subsection Read Syntax for Numerical Data
-
-The read syntax for integers is a string of digits, optionally
-preceded by a minus or plus character, a code indicating the
-base in which the integer is encoded, and a code indicating whether
-the number is exact or inexact. The supported base codes are:
-
-@itemize @bullet
-@item
-@code{#b}, @code{#B} --- the integer is written in binary (base 2)
-
-@item
-@code{#o}, @code{#O} --- the integer is written in octal (base 8)
-
-@item
-@code{#d}, @code{#D} --- the integer is written in decimal (base 10)
-
-@item
-@code{#x}, @code{#X} --- the integer is written in hexadecimal (base 16).
-@end itemize
-
-If the base code is omitted, the integer is assumed to be decimal. The
-following examples show how these base codes are used.
-
-@lisp
--13
-@result{}
--13
-
-#d-13
-@result{}
--13
-
-#x-13
-@result{}
--19
-
-#b+1101
-@result{}
-13
-
-#o377
-@result{}
-255
-@end lisp
-
-The codes for indicating exactness (which can, incidentally, be applied
-to all numerical values) are:
-
-@itemize @bullet
-@item
-@code{#e}, @code{#E} --- the number is exact
-
-@item
-@code{#i}, @code{#I} --- the number is inexact.
-@end itemize
-
-If the exactness indicator is omitted, the integer is assumed to be exact,
-since Guile's internal representation for integers is always exact.
-Real numbers have limited precision similar to the precision of the
-@code{double} type in C. A consequence of the limited precision is that
-all real numbers in Guile are also rational, since any number R with a
-limited number of decimal places, say N, can be made into an integer by
-multiplying by 10^N.
-
-Guile also understands the syntax @samp{+inf.0} and @samp{-inf.0} for
-plus and minus infinity, respectively. The value must be written
-exactly as shown, that is, the always must have a sign and exactly one
-zero digit after the decimal point. It also understands @samp{+nan.0}
-and @samp{-nan.0} for the special 'not-a-number' value. The sign is
-ignored for 'not-a-number' and the value is always printed as @samp{+nan.0}.
-
-@node Integer Operations
-@subsection Operations on Integer Values
-@rnindex odd?
-@rnindex even?
-@rnindex quotient
-@rnindex remainder
-@rnindex modulo
-@rnindex gcd
-@rnindex lcm
-
-@deffn {Scheme Procedure} odd? n
-@deffnx {C Function} scm_odd_p (n)
-Return @code{#t} if @var{n} is an odd number, @code{#f}
-otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} even? n
-@deffnx {C Function} scm_even_p (n)
-Return @code{#t} if @var{n} is an even number, @code{#f}
-otherwise.
-@end deffn
-
-@c begin (texi-doc-string "guile" "quotient")
-@deffn {Scheme Procedure} quotient
-Return the quotient of the numbers @var{x} and @var{y}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "remainder")
-@deffn {Scheme Procedure} remainder
-Return the remainder of the numbers @var{x} and @var{y}.
-@lisp
-(remainder 13 4) @result{} 1
-(remainder -13 4) @result{} -1
-@end lisp
-@end deffn
-
-@c begin (texi-doc-string "guile" "modulo")
-@deffn {Scheme Procedure} modulo
-Return the modulo of the numbers @var{x} and @var{y}.
-@lisp
-(modulo 13 4) @result{} 1
-(modulo -13 4) @result{} 3
-@end lisp
-@end deffn
-
-@c begin (texi-doc-string "guile" "gcd")
-@deffn {Scheme Procedure} gcd
-Return the greatest common divisor of all arguments.
-If called without arguments, 0 is returned.
-@end deffn
-
-@c begin (texi-doc-string "guile" "lcm")
-@deffn {Scheme Procedure} lcm
-Return the least common multiple of the arguments.
-If called without arguments, 1 is returned.
-@end deffn
-
-
-@node Comparison
-@subsection Comparison Predicates
-@rnindex zero?
-@rnindex positive?
-@rnindex negative?
-
-@c begin (texi-doc-string "guile" "=")
-@deffn {Scheme Procedure} =
-Return @code{#t} if all parameters are numerically equal.
-@end deffn
-
-@c begin (texi-doc-string "guile" "<")
-@deffn {Scheme Procedure} <
-Return @code{#t} if the list of parameters is monotonically
-increasing.
-@end deffn
-
-@c begin (texi-doc-string "guile" ">")
-@deffn {Scheme Procedure} >
-Return @code{#t} if the list of parameters is monotonically
-decreasing.
-@end deffn
-
-@c begin (texi-doc-string "guile" "<=")
-@deffn {Scheme Procedure} <=
-Return @code{#t} if the list of parameters is monotonically
-non-decreasing.
-@end deffn
-
-@c begin (texi-doc-string "guile" ">=")
-@deffn {Scheme Procedure} >=
-Return @code{#t} if the list of parameters is monotonically
-non-increasing.
-@end deffn
-
-@c begin (texi-doc-string "guile" "zero?")
-@deffn {Scheme Procedure} zero?
-Return @code{#t} if @var{z} is an exact or inexact number equal to
-zero.
-@end deffn
-
-@c begin (texi-doc-string "guile" "positive?")
-@deffn {Scheme Procedure} positive?
-Return @code{#t} if @var{x} is an exact or inexact number greater than
-zero.
-@end deffn
-
-@c begin (texi-doc-string "guile" "negative?")
-@deffn {Scheme Procedure} negative?
-Return @code{#t} if @var{x} is an exact or inexact number less than
-zero.
-@end deffn
-
-
-@node Conversion
-@subsection Converting Numbers To and From Strings
-@rnindex number->string
-@rnindex string->number
-
-@deffn {Scheme Procedure} number->string n [radix]
-@deffnx {C Function} scm_number_to_string (n, radix)
-Return a string holding the external representation of the
-number @var{n} in the given @var{radix}. If @var{n} is
-inexact, a radix of 10 will be used.
-@end deffn
-
-@deffn {Scheme Procedure} string->number string [radix]
-@deffnx {C Function} scm_string_to_number (string, radix)
-Return a number of the maximally precise representation
-expressed by the given @var{string}. @var{radix} must be an
-exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
-is a default radix that may be overridden by an explicit radix
-prefix in @var{string} (e.g. "#o177"). If @var{radix} is not
-supplied, then the default radix is 10. If string is not a
-syntactically valid notation for a number, then
-@code{string->number} returns @code{#f}.
-@end deffn
-
-
-@node Complex
-@subsection Complex Number Operations
-@rnindex make-rectangular
-@rnindex make-polar
-@rnindex real-part
-@rnindex imag-part
-@rnindex magnitude
-@rnindex angle
-
-@deffn {Scheme Procedure} make-rectangular real imaginary
-@deffnx {C Function} scm_make_rectangular (real, imaginary)
-Return a complex number constructed of the given @var{real} and
-@var{imaginary} parts.
-@end deffn
-
-@deffn {Scheme Procedure} make-polar x y
-@deffnx {C Function} scm_make_polar (x, y)
-Return the complex number @var{x} * e^(i * @var{y}).
-@end deffn
-
-@c begin (texi-doc-string "guile" "real-part")
-@deffn {Scheme Procedure} real-part
-Return the real part of the number @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "imag-part")
-@deffn {Scheme Procedure} imag-part
-Return the imaginary part of the number @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "magnitude")
-@deffn {Scheme Procedure} magnitude
-Return the magnitude of the number @var{z}. This is the same as
-@code{abs} for real arguments, but also allows complex numbers.
-@end deffn
-
-@c begin (texi-doc-string "guile" "angle")
-@deffn {Scheme Procedure} angle
-Return the angle of the complex number @var{z}.
-@end deffn
-
-
-@node Arithmetic
-@subsection Arithmetic Functions
-@rnindex max
-@rnindex min
-@rnindex +
-@rnindex *
-@rnindex -
-@rnindex /
-@rnindex abs
-@rnindex floor
-@rnindex ceiling
-@rnindex truncate
-@rnindex round
-
-@c begin (texi-doc-string "guile" "+")
-@deffn {Scheme Procedure} + z1 @dots{}
-Return the sum of all parameter values. Return 0 if called without any
-parameters.
-@end deffn
-
-@c begin (texi-doc-string "guile" "-")
-@deffn {Scheme Procedure} - z1 z2 @dots{}
-If called with one argument @var{z1}, -@var{z1} is returned. Otherwise
-the sum of all but the first argument are subtracted from the first
-argument.
-@end deffn
-
-@c begin (texi-doc-string "guile" "*")
-@deffn {Scheme Procedure} * z1 @dots{}
-Return the product of all arguments. If called without arguments, 1 is
-returned.
-@end deffn
-
-@c begin (texi-doc-string "guile" "/")
-@deffn {Scheme Procedure} / z1 z2 @dots{}
-Divide the first argument by the product of the remaining arguments. If
-called with one argument @var{z1}, 1/@var{z1} is returned.
-@end deffn
-
-@c begin (texi-doc-string "guile" "abs")
-@deffn {Scheme Procedure} abs x
-@deffnx {C Function} scm_abs (x)
-Return the absolute value of @var{x}.
-
-@var{x} must be a number with zero imaginary part. To calculate the
-magnitude of a complex number, use @code{magnitude} instead.
-@end deffn
-
-@c begin (texi-doc-string "guile" "max")
-@deffn {Scheme Procedure} max x1 x2 @dots{}
-Return the maximum of all parameter values.
-@end deffn
-
-@c begin (texi-doc-string "guile" "min")
-@deffn {Scheme Procedure} min x1 x2 @dots{}
-Return the minimum of all parameter values.
-@end deffn
-
-@c begin (texi-doc-string "guile" "truncate")
-@deffn {Scheme Procedure} truncate
-Round the inexact number @var{x} towards zero.
-@end deffn
-
-@c begin (texi-doc-string "guile" "round")
-@deffn {Scheme Procedure} round x
-Round the inexact number @var{x} towards zero.
-@end deffn
-
-@c begin (texi-doc-string "guile" "floor")
-@deffn {Scheme Procedure} floor x
-Round the number @var{x} towards minus infinity.
-@end deffn
-
-@c begin (texi-doc-string "guile" "ceiling")
-@deffn {Scheme Procedure} ceiling x
-Round the number @var{x} towards infinity.
-@end deffn
-
-For the @code{truncate} and @code{round} procedures, the Guile library
-exports equivalent C functions, but taking and returning arguments of
-type @code{double} rather than the usual @code{SCM}.
-
-@deftypefn {C Function} double scm_truncate (double x)
-@deftypefnx {C Function} double scm_round (double x)
-@end deftypefn
-
-For @code{floor} and @code{ceiling}, the equivalent C functions are
-@code{floor} and @code{ceil} from the standard mathematics library
-(which also take and return @code{double} arguments).
-
-
-@node Scientific
-@subsection Scientific Functions
-
-The following procedures accept any kind of number as arguments,
-including complex numbers.
-
-@rnindex sqrt
-@c begin (texi-doc-string "guile" "sqrt")
-@deffn {Scheme Procedure} sqrt z
-Return the square root of @var{z}.
-@end deffn
-
-@rnindex expt
-@c begin (texi-doc-string "guile" "expt")
-@deffn {Scheme Procedure} expt z1 z2
-Return @var{z1} raised to the power of @var{z2}.
-@end deffn
-
-@rnindex sin
-@c begin (texi-doc-string "guile" "sin")
-@deffn {Scheme Procedure} sin z
-Return the sine of @var{z}.
-@end deffn
-
-@rnindex cos
-@c begin (texi-doc-string "guile" "cos")
-@deffn {Scheme Procedure} cos z
-Return the cosine of @var{z}.
-@end deffn
-
-@rnindex tan
-@c begin (texi-doc-string "guile" "tan")
-@deffn {Scheme Procedure} tan z
-Return the tangent of @var{z}.
-@end deffn
-
-@rnindex asin
-@c begin (texi-doc-string "guile" "asin")
-@deffn {Scheme Procedure} asin z
-Return the arcsine of @var{z}.
-@end deffn
-
-@rnindex acos
-@c begin (texi-doc-string "guile" "acos")
-@deffn {Scheme Procedure} acos z
-Return the arccosine of @var{z}.
-@end deffn
-
-@rnindex atan
-@c begin (texi-doc-string "guile" "atan")
-@deffn {Scheme Procedure} atan z
-Return the arctangent of @var{z}.
-@end deffn
-
-@rnindex exp
-@c begin (texi-doc-string "guile" "exp")
-@deffn {Scheme Procedure} exp z
-Return e to the power of @var{z}, where e is the base of natural
-logarithms (2.71828@dots{}).
-@end deffn
-
-@rnindex log
-@c begin (texi-doc-string "guile" "log")
-@deffn {Scheme Procedure} log z
-Return the natural logarithm of @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "log10")
-@deffn {Scheme Procedure} log10 z
-Return the base 10 logarithm of @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "sinh")
-@deffn {Scheme Procedure} sinh z
-Return the hyperbolic sine of @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "cosh")
-@deffn {Scheme Procedure} cosh z
-Return the hyperbolic cosine of @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "tanh")
-@deffn {Scheme Procedure} tanh z
-Return the hyperbolic tangent of @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "asinh")
-@deffn {Scheme Procedure} asinh z
-Return the hyperbolic arcsine of @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "acosh")
-@deffn {Scheme Procedure} acosh z
-Return the hyperbolic arccosine of @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "atanh")
-@deffn {Scheme Procedure} atanh z
-Return the hyperbolic arctangent of @var{z}.
-@end deffn
-
-
-@node Primitive Numerics
-@subsection Primitive Numeric Functions
-
-Many of Guile's numeric procedures which accept any kind of numbers as
-arguments, including complex numbers, are implemented as Scheme
-procedures that use the following real number-based primitives. These
-primitives signal an error if they are called with complex arguments.
-
-@c begin (texi-doc-string "guile" "$abs")
-@deffn {Scheme Procedure} $abs x
-Return the absolute value of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$sqrt")
-@deffn {Scheme Procedure} $sqrt x
-Return the square root of @var{x}.
-@end deffn
-
-@deffn {Scheme Procedure} $expt x y
-@deffnx {C Function} scm_sys_expt (x, y)
-Return @var{x} raised to the power of @var{y}. This
-procedure does not accept complex arguments.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$sin")
-@deffn {Scheme Procedure} $sin x
-Return the sine of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$cos")
-@deffn {Scheme Procedure} $cos x
-Return the cosine of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$tan")
-@deffn {Scheme Procedure} $tan x
-Return the tangent of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$asin")
-@deffn {Scheme Procedure} $asin x
-Return the arcsine of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$acos")
-@deffn {Scheme Procedure} $acos x
-Return the arccosine of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$atan")
-@deffn {Scheme Procedure} $atan x
-Return the arctangent of @var{x} in the range -PI/2 to PI/2.
-@end deffn
-
-@deffn {Scheme Procedure} $atan2 x y
-@deffnx {C Function} scm_sys_atan2 (x, y)
-Return the arc tangent of the two arguments @var{x} and
-@var{y}. This is similar to calculating the arc tangent of
-@var{x} / @var{y}, except that the signs of both arguments
-are used to determine the quadrant of the result. This
-procedure does not accept complex arguments.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$exp")
-@deffn {Scheme Procedure} $exp x
-Return e to the power of @var{x}, where e is the base of natural
-logarithms (2.71828@dots{}).
-@end deffn
-
-@c begin (texi-doc-string "guile" "$log")
-@deffn {Scheme Procedure} $log x
-Return the natural logarithm of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$sinh")
-@deffn {Scheme Procedure} $sinh x
-Return the hyperbolic sine of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$cosh")
-@deffn {Scheme Procedure} $cosh x
-Return the hyperbolic cosine of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$tanh")
-@deffn {Scheme Procedure} $tanh x
-Return the hyperbolic tangent of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$asinh")
-@deffn {Scheme Procedure} $asinh x
-Return the hyperbolic arcsine of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$acosh")
-@deffn {Scheme Procedure} $acosh x
-Return the hyperbolic arccosine of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$atanh")
-@deffn {Scheme Procedure} $atanh x
-Return the hyperbolic arctangent of @var{x}.
-@end deffn
-
-For the hyperbolic arc-functions, the Guile library exports C functions
-corresponding to these Scheme procedures, but taking and returning
-arguments of type @code{double} rather than the usual @code{SCM}.
-
-@deftypefn {C Function} double scm_asinh (double x)
-@deftypefnx {C Function} double scm_acosh (double x)
-@deftypefnx {C Function} double scm_atanh (double x)
-Return the hyperbolic arcsine, arccosine or arctangent of @var{x}
-respectively.
-@end deftypefn
-
-For all the other Scheme procedures above, except @code{expt} and
-@code{atan2} (whose entries specifically mention an equivalent C
-function), the equivalent C functions are those provided by the standard
-mathematics library. The mapping is as follows.
-
-@multitable {xx} {Scheme Procedure} {C Function}
-@item @tab Scheme Procedure @tab C Function
-
-@item @tab @code{$abs} @tab @code{fabs}
-@item @tab @code{$sqrt} @tab @code{sqrt}
-@item @tab @code{$sin} @tab @code{sin}
-@item @tab @code{$cos} @tab @code{cos}
-@item @tab @code{$tan} @tab @code{tan}
-@item @tab @code{$asin} @tab @code{asin}
-@item @tab @code{$acos} @tab @code{acos}
-@item @tab @code{$atan} @tab @code{atan}
-@item @tab @code{$exp} @tab @code{exp}
-@item @tab @code{$log} @tab @code{log}
-@item @tab @code{$sinh} @tab @code{sinh}
-@item @tab @code{$cosh} @tab @code{cosh}
-@item @tab @code{$tanh} @tab @code{tanh}
-@end multitable
-
-@noindent
-Naturally, these C functions expect and return @code{double} arguments.
-
-
-@node Bitwise Operations
-@subsection Bitwise Operations
-
-@deffn {Scheme Procedure} logand n1 n2
-Return the bitwise AND of the integer arguments.
-
-@lisp
-(logand) @result{} -1
-(logand 7) @result{} 7
-(logand #b111 #b011 #b001) @result{} 1
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} logior n1 n2
-Return the bitwise OR of the integer arguments.
-
-@lisp
-(logior) @result{} 0
-(logior 7) @result{} 7
-(logior #b000 #b001 #b011) @result{} 3
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} logxor n1 n2
-Return the bitwise XOR of the integer arguments. A bit is
-set in the result if it is set in an odd number of arguments.
-@lisp
-(logxor) @result{} 0
-(logxor 7) @result{} 7
-(logxor #b000 #b001 #b011) @result{} 2
-(logxor #b000 #b001 #b011 #b011) @result{} 1
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} lognot n
-@deffnx {C Function} scm_lognot (n)
-Return the integer which is the 2s-complement of the integer
-argument.
-
-@lisp
-(number->string (lognot #b10000000) 2)
- @result{} "-10000001"
-(number->string (lognot #b0) 2)
- @result{} "-1"
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} logtest j k
-@deffnx {C Function} scm_logtest (j, k)
-@lisp
-(logtest j k) @equiv{} (not (zero? (logand j k)))
-
-(logtest #b0100 #b1011) @result{} #f
-(logtest #b0100 #b0111) @result{} #t
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} logbit? index j
-@deffnx {C Function} scm_logbit_p (index, j)
-@lisp
-(logbit? index j) @equiv{} (logtest (integer-expt 2 index) j)
-
-(logbit? 0 #b1101) @result{} #t
-(logbit? 1 #b1101) @result{} #f
-(logbit? 2 #b1101) @result{} #t
-(logbit? 3 #b1101) @result{} #t
-(logbit? 4 #b1101) @result{} #f
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} ash n cnt
-@deffnx {C Function} scm_ash (n, cnt)
-The function ash performs an arithmetic shift left by @var{cnt}
-bits (or shift right, if @var{cnt} is negative). 'Arithmetic'
-means, that the function does not guarantee to keep the bit
-structure of @var{n}, but rather guarantees that the result
-will always be rounded towards minus infinity. Therefore, the
-results of ash and a corresponding bitwise shift will differ if
-@var{n} is negative.
-
-Formally, the function returns an integer equivalent to
-@code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}.
-
-@lisp
-(number->string (ash #b1 3) 2) @result{} "1000"
-(number->string (ash #b1010 -1) 2) @result{} "101"
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} logcount n
-@deffnx {C Function} scm_logcount (n)
-Return the number of bits in integer @var{n}. If integer is
-positive, the 1-bits in its binary representation are counted.
-If negative, the 0-bits in its two's-complement binary
-representation are counted. If 0, 0 is returned.
-
-@lisp
-(logcount #b10101010)
- @result{} 4
-(logcount 0)
- @result{} 0
-(logcount -2)
- @result{} 1
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} integer-length n
-@deffnx {C Function} scm_integer_length (n)
-Return the number of bits necessary to represent @var{n}.
-
-@lisp
-(integer-length #b10101010)
- @result{} 8
-(integer-length 0)
- @result{} 0
-(integer-length #b1111)
- @result{} 4
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} integer-expt n k
-@deffnx {C Function} scm_integer_expt (n, k)
-Return @var{n} raised to the non-negative integer exponent
-@var{k}.
-
-@lisp
-(integer-expt 2 5)
- @result{} 32
-(integer-expt -3 3)
- @result{} -27
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} bit-extract n start end
-@deffnx {C Function} scm_bit_extract (n, start, end)
-Return the integer composed of the @var{start} (inclusive)
-through @var{end} (exclusive) bits of @var{n}. The
-@var{start}th bit becomes the 0-th bit in the result.
-
-@lisp
-(number->string (bit-extract #b1101101010 0 4) 2)
- @result{} "1010"
-(number->string (bit-extract #b1101101010 4 9) 2)
- @result{} "10110"
-@end lisp
-@end deffn
-
-
-@node Random
-@subsection Random Number Generation
-
-@deffn {Scheme Procedure} copy-random-state [state]
-@deffnx {C Function} scm_copy_random_state (state)
-Return a copy of the random state @var{state}.
-@end deffn
-
-@deffn {Scheme Procedure} random n [state]
-@deffnx {C Function} scm_random (n, state)
-Return a number in [0,N).
-
-Accepts a positive integer or real n and returns a
-number of the same type between zero (inclusive) and
-N (exclusive). The values returned have a uniform
-distribution.
-
-The optional argument @var{state} must be of the type produced
-by @code{seed->random-state}. It defaults to the value of the
-variable @var{*random-state*}. This object is used to maintain
-the state of the pseudo-random-number generator and is altered
-as a side effect of the random operation.
-@end deffn
-
-@deffn {Scheme Procedure} random:exp [state]
-@deffnx {C Function} scm_random_exp (state)
-Return an inexact real in an exponential distribution with mean
-1. For an exponential distribution with mean u use (* u
-(random:exp)).
-@end deffn
-
-@deffn {Scheme Procedure} random:hollow-sphere! v [state]
-@deffnx {C Function} scm_random_hollow_sphere_x (v, state)
-Fills vect with inexact real random numbers
-the sum of whose squares is equal to 1.0.
-Thinking of vect as coordinates in space of
-dimension n = (vector-length vect), the coordinates
-are uniformly distributed over the surface of the
-unit n-sphere.
-@end deffn
-
-@deffn {Scheme Procedure} random:normal [state]
-@deffnx {C Function} scm_random_normal (state)
-Return an inexact real in a normal distribution. The
-distribution used has mean 0 and standard deviation 1. For a
-normal distribution with mean m and standard deviation d use
-@code{(+ m (* d (random:normal)))}.
-@end deffn
-
-@deffn {Scheme Procedure} random:normal-vector! v [state]
-@deffnx {C Function} scm_random_normal_vector_x (v, state)
-Fills vect with inexact real random numbers that are
-independent and standard normally distributed
-(i.e., with mean 0 and variance 1).
-@end deffn
-
-@deffn {Scheme Procedure} random:solid-sphere! v [state]
-@deffnx {C Function} scm_random_solid_sphere_x (v, state)
-Fills vect with inexact real random numbers
-the sum of whose squares is less than 1.0.
-Thinking of vect as coordinates in space of
-dimension n = (vector-length vect), the coordinates
-are uniformly distributed within the unit n-sphere.
-The sum of the squares of the numbers is returned.
-@end deffn
-
-@deffn {Scheme Procedure} random:uniform [state]
-@deffnx {C Function} scm_random_uniform (state)
-Return a uniformly distributed inexact real random number in
-[0,1).
-@end deffn
-
-@deffn {Scheme Procedure} seed->random-state seed
-@deffnx {C Function} scm_seed_to_random_state (seed)
-Return a new random state using @var{seed}.
-@end deffn
-
-
-@node Characters
-@section Characters
-@tpindex Characters
-
-Most of the characters in the ASCII character set may be referred to by
-name: for example, @code{#\tab}, @code{#\esc}, @code{#\stx}, and so on.
-The following table describes the ASCII names for each character.
-
-@multitable @columnfractions .25 .25 .25 .25
-@item 0 = @code{#\nul}
- @tab 1 = @code{#\soh}
- @tab 2 = @code{#\stx}
- @tab 3 = @code{#\etx}
-@item 4 = @code{#\eot}
- @tab 5 = @code{#\enq}
- @tab 6 = @code{#\ack}
- @tab 7 = @code{#\bel}
-@item 8 = @code{#\bs}
- @tab 9 = @code{#\ht}
- @tab 10 = @code{#\nl}
- @tab 11 = @code{#\vt}
-@item 12 = @code{#\np}
- @tab 13 = @code{#\cr}
- @tab 14 = @code{#\so}
- @tab 15 = @code{#\si}
-@item 16 = @code{#\dle}
- @tab 17 = @code{#\dc1}
- @tab 18 = @code{#\dc2}
- @tab 19 = @code{#\dc3}
-@item 20 = @code{#\dc4}
- @tab 21 = @code{#\nak}
- @tab 22 = @code{#\syn}
- @tab 23 = @code{#\etb}
-@item 24 = @code{#\can}
- @tab 25 = @code{#\em}
- @tab 26 = @code{#\sub}
- @tab 27 = @code{#\esc}
-@item 28 = @code{#\fs}
- @tab 29 = @code{#\gs}
- @tab 30 = @code{#\rs}
- @tab 31 = @code{#\us}
-@item 32 = @code{#\sp}
-@end multitable
-
-The @code{delete} character (octal 177) may be referred to with the name
-@code{#\del}.
-
-Several characters have more than one name:
-
-@itemize @bullet
-@item
-@code{#\space}, @code{#\sp}
-@item
-@code{#\newline}, @code{#\nl}
-@item
-@code{#\tab}, @code{#\ht}
-@item
-@code{#\backspace}, @code{#\bs}
-@item
-@code{#\return}, @code{#\cr}
-@item
-@code{#\page}, @code{#\np}
-@item
-@code{#\null}, @code{#\nul}
-@end itemize
-
-@rnindex char?
-@deffn {Scheme Procedure} char? x
-@deffnx {C Function} scm_char_p (x)
-Return @code{#t} iff @var{x} is a character, else @code{#f}.
-@end deffn
-
-@rnindex char=?
-@deffn {Scheme Procedure} char=? x y
-Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}.
-@end deffn
-
-@rnindex char<?
-@deffn {Scheme Procedure} char<? x y
-Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence,
-else @code{#f}.
-@end deffn
-
-@rnindex char<=?
-@deffn {Scheme Procedure} char<=? x y
-Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
-ASCII sequence, else @code{#f}.
-@end deffn
-
-@rnindex char>?
-@deffn {Scheme Procedure} char>? x y
-Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
-sequence, else @code{#f}.
-@end deffn
-
-@rnindex char>=?
-@deffn {Scheme Procedure} char>=? x y
-Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
-ASCII sequence, else @code{#f}.
-@end deffn
-
-@rnindex char-ci=?
-@deffn {Scheme Procedure} char-ci=? x y
-Return @code{#t} iff @var{x} is the same character as @var{y} ignoring
-case, else @code{#f}.
-@end deffn
-
-@rnindex char-ci<?
-@deffn {Scheme Procedure} char-ci<? x y
-Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence
-ignoring case, else @code{#f}.
-@end deffn
-
-@rnindex char-ci<=?
-@deffn {Scheme Procedure} char-ci<=? x y
-Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
-ASCII sequence ignoring case, else @code{#f}.
-@end deffn
-
-@rnindex char-ci>?
-@deffn {Scheme Procedure} char-ci>? x y
-Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
-sequence ignoring case, else @code{#f}.
-@end deffn
-
-@rnindex char-ci>=?
-@deffn {Scheme Procedure} char-ci>=? x y
-Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
-ASCII sequence ignoring case, else @code{#f}.
-@end deffn
-
-@rnindex char-alphabetic?
-@deffn {Scheme Procedure} char-alphabetic? chr
-@deffnx {C Function} scm_char_alphabetic_p (chr)
-Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
-Alphabetic means the same thing as the isalpha C library function.
-@end deffn
-
-@rnindex char-numeric?
-@deffn {Scheme Procedure} char-numeric? chr
-@deffnx {C Function} scm_char_numeric_p (chr)
-Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
-Numeric means the same thing as the isdigit C library function.
-@end deffn
-
-@rnindex char-whitespace?
-@deffn {Scheme Procedure} char-whitespace? chr
-@deffnx {C Function} scm_char_whitespace_p (chr)
-Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
-Whitespace means the same thing as the isspace C library function.
-@end deffn
-
-@rnindex char-upper-case?
-@deffn {Scheme Procedure} char-upper-case? chr
-@deffnx {C Function} scm_char_upper_case_p (chr)
-Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
-Uppercase means the same thing as the isupper C library function.
-@end deffn
-
-@rnindex char-lower-case?
-@deffn {Scheme Procedure} char-lower-case? chr
-@deffnx {C Function} scm_char_lower_case_p (chr)
-Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
-Lowercase means the same thing as the islower C library function.
-@end deffn
-
-@deffn {Scheme Procedure} char-is-both? chr
-@deffnx {C Function} scm_char_is_both_p (chr)
-Return @code{#t} iff @var{chr} is either uppercase or lowercase, else @code{#f}.
-Uppercase and lowercase are as defined by the isupper and islower
-C library functions.
-@end deffn
-
-@rnindex char->integer
-@deffn {Scheme Procedure} char->integer chr
-@deffnx {C Function} scm_char_to_integer (chr)
-Return the number corresponding to ordinal position of @var{chr} in the
-ASCII sequence.
-@end deffn
-
-@rnindex integer->char
-@deffn {Scheme Procedure} integer->char n
-@deffnx {C Function} scm_integer_to_char (n)
-Return the character at position @var{n} in the ASCII sequence.
-@end deffn
-
-@rnindex char-upcase
-@deffn {Scheme Procedure} char-upcase chr
-@deffnx {C Function} scm_char_upcase (chr)
-Return the uppercase character version of @var{chr}.
-@end deffn
-
-@rnindex char-downcase
-@deffn {Scheme Procedure} char-downcase chr
-@deffnx {C Function} scm_char_downcase (chr)
-Return the lowercase character version of @var{chr}.
-@end deffn
-
-
-@node Strings
-@section Strings
-@tpindex Strings
-
-Strings are fixed-length sequences of characters. They can be created
-by calling constructor procedures, but they can also literally get
-entered at the REPL or in Scheme source files.
-
-Guile provides a rich set of string processing procedures, because text
-handling is very important when Guile is used as a scripting language.
-
-Strings always carry the information about how many characters they are
-composed of with them, so there is no special end-of-string character,
-like in C. That means that Scheme strings can contain any character,
-even the NUL character @code{'\0'}. But note: Since most operating
-system calls dealing with strings (such as for file operations) expect
-strings to be zero-terminated, they might do unexpected things when
-called with string containing unusual characters.
-
-@menu
-* String Syntax:: Read syntax for strings.
-* String Predicates:: Testing strings for certain properties.
-* String Constructors:: Creating new string objects.
-* List/String Conversion:: Converting from/to lists of characters.
-* String Selection:: Select portions from strings.
-* String Modification:: Modify parts or whole strings.
-* String Comparison:: Lexicographic ordering predicates.
-* String Searching:: Searching in strings.
-* Alphabetic Case Mapping:: Convert the alphabetic case of strings.
-* Appending Strings:: Appending strings to form a new string.
-@end menu
-
-@node String Syntax
-@subsection String Read Syntax
-
-The read syntax for strings is an arbitrarily long sequence of
-characters enclosed in double quotes (@code{"}). @footnote{Actually, the
-current implementation restricts strings to a length of 2^24
-characters.} If you want to insert a double quote character into a
-string literal, it must be prefixed with a backslash @code{\} character
-(called an @dfn{escape character}).
-
-The following are examples of string literals:
-
-@lisp
-"foo"
-"bar plonk"
-"Hello World"
-"\"Hi\", he said."
-@end lisp
-
-@c FIXME::martin: What about escape sequences like \r, \n etc.?
-
-@node String Predicates
-@subsection String Predicates
-
-The following procedures can be used to check whether a given string
-fulfills some specified property.
-
-@rnindex string?
-@deffn {Scheme Procedure} string? obj
-@deffnx {C Function} scm_string_p (obj)
-Return @code{#t} if @var{obj} is a string, else @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} string-null? str
-@deffnx {C Function} scm_string_null_p (str)
-Return @code{#t} if @var{str}'s length is zero, and
-@code{#f} otherwise.
-@lisp
-(string-null? "") @result{} #t
-y @result{} "foo"
-(string-null? y) @result{} #f
-@end lisp
-@end deffn
-
-@node String Constructors
-@subsection String Constructors
-
-The string constructor procedures create new string objects, possibly
-initializing them with some specified character data.
-
-@c FIXME::martin: list->string belongs into `List/String Conversion'
-
-@rnindex string
-@rnindex list->string
-@deffn {Scheme Procedure} string . chrs
-@deffnx {Scheme Procedure} list->string chrs
-@deffnx {C Function} scm_string (chrs)
-Return a newly allocated string composed of the arguments,
-@var{chrs}.
-@end deffn
-
-@rnindex make-string
-@deffn {Scheme Procedure} make-string k [chr]
-@deffnx {C Function} scm_make_string (k, chr)
-Return a newly allocated string of
-length @var{k}. If @var{chr} is given, then all elements of
-the string are initialized to @var{chr}, otherwise the contents
-of the @var{string} are unspecified.
-@end deffn
-
-@node List/String Conversion
-@subsection List/String conversion
-
-When processing strings, it is often convenient to first convert them
-into a list representation by using the procedure @code{string->list},
-work with the resulting list, and then convert it back into a string.
-These procedures are useful for similar tasks.
-
-@rnindex string->list
-@deffn {Scheme Procedure} string->list str
-@deffnx {C Function} scm_string_to_list (str)
-Return a newly allocated list of the characters that make up
-the given string @var{str}. @code{string->list} and
-@code{list->string} are inverses as far as @samp{equal?} is
-concerned.
-@end deffn
-
-@deffn {Scheme Procedure} string-split str chr
-@deffnx {C Function} scm_string_split (str, chr)
-Split the string @var{str} into the a list of the substrings delimited
-by appearances of the character @var{chr}. Note that an empty substring
-between separator characters will result in an empty string in the
-result list.
-
-@lisp
-(string-split "root:x:0:0:root:/root:/bin/bash" #\:)
-@result{}
-("root" "x" "0" "0" "root" "/root" "/bin/bash")
-
-(string-split "::" #\:)
-@result{}
-("" "" "")
-
-(string-split "" #\:)
-@result{}
-("")
-@end lisp
-@end deffn
-
-
-@node String Selection
-@subsection String Selection
-
-Portions of strings can be extracted by these procedures.
-@code{string-ref} delivers individual characters whereas
-@code{substring} can be used to extract substrings from longer strings.
-
-@rnindex string-length
-@deffn {Scheme Procedure} string-length string
-@deffnx {C Function} scm_string_length (string)
-Return the number of characters in @var{string}.
-@end deffn
-
-@rnindex string-ref
-@deffn {Scheme Procedure} string-ref str k
-@deffnx {C Function} scm_string_ref (str, k)
-Return character @var{k} of @var{str} using zero-origin
-indexing. @var{k} must be a valid index of @var{str}.
-@end deffn
-
-@rnindex string-copy
-@deffn {Scheme Procedure} string-copy str
-@deffnx {C Function} scm_string_copy (str)
-Return a newly allocated copy of the given @var{string}.
-@end deffn
-
-@rnindex substring
-@deffn {Scheme Procedure} substring str start [end]
-@deffnx {C Function} scm_substring (str, start, end)
-Return a newly allocated string formed from the characters
-of @var{str} beginning with index @var{start} (inclusive) and
-ending with index @var{end} (exclusive).
-@var{str} must be a string, @var{start} and @var{end} must be
-exact integers satisfying:
-
-0 <= @var{start} <= @var{end} <= (string-length @var{str}).
-@end deffn
-
-@node String Modification
-@subsection String Modification
-
-These procedures are for modifying strings in-place. This means that the
-result of the operation is not a new string; instead, the original string's
-memory representation is modified.
-
-@rnindex string-set!
-@deffn {Scheme Procedure} string-set! str k chr
-@deffnx {C Function} scm_string_set_x (str, k, chr)
-Store @var{chr} in element @var{k} of @var{str} and return
-an unspecified value. @var{k} must be a valid index of
-@var{str}.
-@end deffn
-
-@rnindex string-fill!
-@deffn {Scheme Procedure} string-fill! str chr
-@deffnx {C Function} scm_string_fill_x (str, chr)
-Store @var{char} in every element of the given @var{string} and
-return an unspecified value.
-@end deffn
-
-@deffn {Scheme Procedure} substring-fill! str start end fill
-@deffnx {C Function} scm_substring_fill_x (str, start, end, fill)
-Change every character in @var{str} between @var{start} and
-@var{end} to @var{fill}.
-
-@lisp
-(define y "abcdefg")
-(substring-fill! y 1 3 #\r)
-y
-@result{} "arrdefg"
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} substring-move! str1 start1 end1 str2 start2
-@deffnx {C Function} scm_substring_move_x (str1, start1, end1, str2, start2)
-Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}
-into @var{str2} beginning at position @var{start2}.
-@var{str1} and @var{str2} can be the same string.
-@end deffn
-
-
-@node String Comparison
-@subsection String Comparison
-
-The procedures in this section are similar to the character ordering
-predicates (@pxref{Characters}), but are defined on character sequences.
-They all return @code{#t} on success and @code{#f} on failure. The
-predicates ending in @code{-ci} ignore the character case when comparing
-strings.
-
-
-@rnindex string=?
-@deffn {Scheme Procedure} string=? s1 s2
-Lexicographic equality predicate; return @code{#t} if the two
-strings are the same length and contain the same characters in
-the same positions, otherwise return @code{#f}.
-
-The procedure @code{string-ci=?} treats upper and lower case
-letters as though they were the same character, but
-@code{string=?} treats upper and lower case as distinct
-characters.
-@end deffn
-
-@rnindex string<?
-@deffn {Scheme Procedure} string<? s1 s2
-Lexicographic ordering predicate; return @code{#t} if @var{s1}
-is lexicographically less than @var{s2}.
-@end deffn
-
-@rnindex string<=?
-@deffn {Scheme Procedure} string<=? s1 s2
-Lexicographic ordering predicate; return @code{#t} if @var{s1}
-is lexicographically less than or equal to @var{s2}.
-@end deffn
-
-@rnindex string>?
-@deffn {Scheme Procedure} string>? s1 s2
-Lexicographic ordering predicate; return @code{#t} if @var{s1}
-is lexicographically greater than @var{s2}.
-@end deffn
-
-@rnindex string>=?
-@deffn {Scheme Procedure} string>=? s1 s2
-Lexicographic ordering predicate; return @code{#t} if @var{s1}
-is lexicographically greater than or equal to @var{s2}.
-@end deffn
-
-@rnindex string-ci=?
-@deffn {Scheme Procedure} string-ci=? s1 s2
-Case-insensitive string equality predicate; return @code{#t} if
-the two strings are the same length and their component
-characters match (ignoring case) at each position; otherwise
-return @code{#f}.
-@end deffn
-
-@rnindex string-ci<
-@deffn {Scheme Procedure} string-ci<? s1 s2
-Case insensitive lexicographic ordering predicate; return
-@code{#t} if @var{s1} is lexicographically less than @var{s2}
-regardless of case.
-@end deffn
-
-@rnindex string<=?
-@deffn {Scheme Procedure} string-ci<=? s1 s2
-Case insensitive lexicographic ordering predicate; return
-@code{#t} if @var{s1} is lexicographically less than or equal
-to @var{s2} regardless of case.
-@end deffn
-
-@rnindex string-ci>?
-@deffn {Scheme Procedure} string-ci>? s1 s2
-Case insensitive lexicographic ordering predicate; return
-@code{#t} if @var{s1} is lexicographically greater than
-@var{s2} regardless of case.
-@end deffn
-
-@rnindex string-ci>=?
-@deffn {Scheme Procedure} string-ci>=? s1 s2
-Case insensitive lexicographic ordering predicate; return
-@code{#t} if @var{s1} is lexicographically greater than or
-equal to @var{s2} regardless of case.
-@end deffn
-
-
-@node String Searching
-@subsection String Searching
-
-When searching for the index of a character in a string, these
-procedures can be used.
-
-@deffn {Scheme Procedure} string-index str chr [frm [to]]
-@deffnx {C Function} scm_string_index (str, chr, frm, to)
-Return the index of the first occurrence of @var{chr} in
-@var{str}. The optional integer arguments @var{frm} and
-@var{to} limit the search to a portion of the string. This
-procedure essentially implements the @code{index} or
-@code{strchr} functions from the C library.
-
-@lisp
-(string-index "weiner" #\e)
-@result{} 1
-
-(string-index "weiner" #\e 2)
-@result{} 4
-
-(string-index "weiner" #\e 2 4)
-@result{} #f
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} string-rindex str chr [frm [to]]
-@deffnx {C Function} scm_string_rindex (str, chr, frm, to)
-Like @code{string-index}, but search from the right of the
-string rather than from the left. This procedure essentially
-implements the @code{rindex} or @code{strrchr} functions from
-the C library.
-
-@lisp
-(string-rindex "weiner" #\e)
-@result{} 4
-
-(string-rindex "weiner" #\e 2 4)
-@result{} #f
-
-(string-rindex "weiner" #\e 2 5)
-@result{} 4
-@end lisp
-@end deffn
-
-@node Alphabetic Case Mapping
-@subsection Alphabetic Case Mapping
-
-These are procedures for mapping strings to their upper- or lower-case
-equivalents, respectively, or for capitalizing strings.
-
-@deffn {Scheme Procedure} string-upcase str
-@deffnx {C Function} scm_string_upcase (str)
-Return a freshly allocated string containing the characters of
-@var{str} in upper case.
-@end deffn
-
-@deffn {Scheme Procedure} string-upcase! str
-@deffnx {C Function} scm_string_upcase_x (str)
-Destructively upcase every character in @var{str} and return
-@var{str}.
-@lisp
-y @result{} "arrdefg"
-(string-upcase! y) @result{} "ARRDEFG"
-y @result{} "ARRDEFG"
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} string-downcase str
-@deffnx {C Function} scm_string_downcase (str)
-Return a freshly allocation string containing the characters in
-@var{str} in lower case.
-@end deffn
-
-@deffn {Scheme Procedure} string-downcase! str
-@deffnx {C Function} scm_string_downcase_x (str)
-Destructively downcase every character in @var{str} and return
-@var{str}.
-@lisp
-y @result{} "ARRDEFG"
-(string-downcase! y) @result{} "arrdefg"
-y @result{} "arrdefg"
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} string-capitalize str
-@deffnx {C Function} scm_string_capitalize (str)
-Return a freshly allocated string with the characters in
-@var{str}, where the first character of every word is
-capitalized.
-@end deffn
-
-@deffn {Scheme Procedure} string-capitalize! str
-@deffnx {C Function} scm_string_capitalize_x (str)
-Upcase the first character of every word in @var{str}
-destructively and return @var{str}.
-
-@lisp
-y @result{} "hello world"
-(string-capitalize! y) @result{} "Hello World"
-y @result{} "Hello World"
-@end lisp
-@end deffn
-
-
-@node Appending Strings
-@subsection Appending Strings
-
-The procedure @code{string-append} appends several strings together to
-form a longer result string.
-
-@rnindex string-append
-@deffn {Scheme Procedure} string-append . args
-@deffnx {C Function} scm_string_append (args)
-Return a newly allocated string whose characters form the
-concatenation of the given strings, @var{args}.
-@end deffn
-
-
-@node Regular Expressions
-@section Regular Expressions
-@tpindex Regular expressions
-
-@cindex regular expressions
-@cindex regex
-@cindex emacs regexp
-
-A @dfn{regular expression} (or @dfn{regexp}) is a pattern that
-describes a whole class of strings. A full description of regular
-expressions and their syntax is beyond the scope of this manual;
-an introduction can be found in the Emacs manual (@pxref{Regexps,
-, Syntax of Regular Expressions, emacs, The GNU Emacs Manual}), or
-in many general Unix reference books.
-
-If your system does not include a POSIX regular expression library, and
-you have not linked Guile with a third-party regexp library such as Rx,
-these functions will not be available. You can tell whether your Guile
-installation includes regular expression support by checking whether the
-@code{*features*} list includes the @code{regex} symbol.
-
-@menu
-* Regexp Functions:: Functions that create and match regexps.
-* Match Structures:: Finding what was matched by a regexp.
-* Backslash Escapes:: Removing the special meaning of regexp
- meta-characters.
-@end menu
-
-[FIXME: it may be useful to include an Examples section. Parts of this
-interface are bewildering on first glance.]
-
-@node Regexp Functions
-@subsection Regexp Functions
-
-By default, Guile supports POSIX extended regular expressions.
-That means that the characters @samp{(}, @samp{)}, @samp{+} and
-@samp{?} are special, and must be escaped if you wish to match the
-literal characters.
-
-This regular expression interface was modeled after that
-implemented by SCSH, the Scheme Shell. It is intended to be
-upwardly compatible with SCSH regular expressions.
-
-@c begin (scm-doc-string "regex.scm" "string-match")
-@deffn {Scheme Procedure} string-match pattern str [start]
-Compile the string @var{pattern} into a regular expression and compare
-it with @var{str}. The optional numeric argument @var{start} specifies
-the position of @var{str} at which to begin matching.
-
-@code{string-match} returns a @dfn{match structure} which
-describes what, if anything, was matched by the regular
-expression. @xref{Match Structures}. If @var{str} does not match
-@var{pattern} at all, @code{string-match} returns @code{#f}.
-@end deffn
-
-Each time @code{string-match} is called, it must compile its
-@var{pattern} argument into a regular expression structure. This
-operation is expensive, which makes @code{string-match} inefficient if
-the same regular expression is used several times (for example, in a
-loop). For better performance, you can compile a regular expression in
-advance and then match strings against the compiled regexp.
-
-@deffn {Scheme Procedure} make-regexp pat . flags
-@deffnx {C Function} scm_make_regexp (pat, flags)
-Compile the regular expression described by @var{pat}, and
-return the compiled regexp structure. If @var{pat} does not
-describe a legal regular expression, @code{make-regexp} throws
-a @code{regular-expression-syntax} error.
-
-The @var{flags} arguments change the behavior of the compiled
-regular expression. The following flags may be supplied:
-
-@table @code
-@item regexp/icase
-Consider uppercase and lowercase letters to be the same when
-matching.
-@item regexp/newline
-If a newline appears in the target string, then permit the
-@samp{^} and @samp{$} operators to match immediately after or
-immediately before the newline, respectively. Also, the
-@samp{.} and @samp{[^...]} operators will never match a newline
-character. The intent of this flag is to treat the target
-string as a buffer containing many lines of text, and the
-regular expression as a pattern that may match a single one of
-those lines.
-@item regexp/basic
-Compile a basic (``obsolete'') regexp instead of the extended
-(``modern'') regexps that are the default. Basic regexps do
-not consider @samp{|}, @samp{+} or @samp{?} to be special
-characters, and require the @samp{@{...@}} and @samp{(...)}
-metacharacters to be backslash-escaped (@pxref{Backslash
-Escapes}). There are several other differences between basic
-and extended regular expressions, but these are the most
-significant.
-@item regexp/extended
-Compile an extended regular expression rather than a basic
-regexp. This is the default behavior; this flag will not
-usually be needed. If a call to @code{make-regexp} includes
-both @code{regexp/basic} and @code{regexp/extended} flags, the
-one which comes last will override the earlier one.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} regexp-exec rx str [start [flags]]
-@deffnx {C Function} scm_regexp_exec (rx, str, start, flags)
-Match the compiled regular expression @var{rx} against
-@code{str}. If the optional integer @var{start} argument is
-provided, begin matching from that position in the string.
-Return a match structure describing the results of the match,
-or @code{#f} if no match could be found.
-
-The @var{flags} arguments change the matching behavior.
-The following flags may be supplied:
-
-@table @code
-@item regexp/notbol
-Operator @samp{^} always fails (unless @code{regexp/newline}
-is used). Use this when the beginning of the string should
-not be considered the beginning of a line.
-@item regexp/noteol
-Operator @samp{$} always fails (unless @code{regexp/newline}
-is used). Use this when the end of the string should not be
-considered the end of a line.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} regexp? obj
-@deffnx {C Function} scm_regexp_p (obj)
-Return @code{#t} if @var{obj} is a compiled regular expression,
-or @code{#f} otherwise.
-@end deffn
-
-Regular expressions are commonly used to find patterns in one string and
-replace them with the contents of another string.
-
-@c begin (scm-doc-string "regex.scm" "regexp-substitute")
-@deffn {Scheme Procedure} regexp-substitute port match [item@dots{}]
-Write to the output port @var{port} selected contents of the match
-structure @var{match}. Each @var{item} specifies what should be
-written, and may be one of the following arguments:
-
-@itemize @bullet
-@item
-A string. String arguments are written out verbatim.
-
-@item
-An integer. The submatch with that number is written.
-
-@item
-The symbol @samp{pre}. The portion of the matched string preceding
-the regexp match is written.
-
-@item
-The symbol @samp{post}. The portion of the matched string following
-the regexp match is written.
-@end itemize
-
-@var{port} may be @code{#f}, in which case nothing is written; instead,
-@code{regexp-substitute} constructs a string from the specified
-@var{item}s and returns that.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "regexp-substitute")
-@deffn {Scheme Procedure} regexp-substitute/global port regexp target [item@dots{}]
-Similar to @code{regexp-substitute}, but can be used to perform global
-substitutions on @var{str}. Instead of taking a match structure as an
-argument, @code{regexp-substitute/global} takes two string arguments: a
-@var{regexp} string describing a regular expression, and a @var{target}
-string which should be matched against this regular expression.
-
-Each @var{item} behaves as in @var{regexp-substitute}, with the
-following exceptions:
-
-@itemize @bullet
-@item
-A function may be supplied. When this function is called, it will be
-passed one argument: a match structure for a given regular expression
-match. It should return a string to be written out to @var{port}.
-
-@item
-The @samp{post} symbol causes @code{regexp-substitute/global} to recurse
-on the unmatched portion of @var{str}. This @emph{must} be supplied in
-order to perform global search-and-replace on @var{str}; if it is not
-present among the @var{item}s, then @code{regexp-substitute/global} will
-return after processing a single match.
-@end itemize
-@end deffn
-
-@node Match Structures
-@subsection Match Structures
-
-@cindex match structures
-
-A @dfn{match structure} is the object returned by @code{string-match} and
-@code{regexp-exec}. It describes which portion of a string, if any,
-matched the given regular expression. Match structures include: a
-reference to the string that was checked for matches; the starting and
-ending positions of the regexp match; and, if the regexp included any
-parenthesized subexpressions, the starting and ending positions of each
-submatch.
-
-In each of the regexp match functions described below, the @code{match}
-argument must be a match structure returned by a previous call to
-@code{string-match} or @code{regexp-exec}. Most of these functions
-return some information about the original target string that was
-matched against a regular expression; we will call that string
-@var{target} for easy reference.
-
-@c begin (scm-doc-string "regex.scm" "regexp-match?")
-@deffn {Scheme Procedure} regexp-match? obj
-Return @code{#t} if @var{obj} is a match structure returned by a
-previous call to @code{regexp-exec}, or @code{#f} otherwise.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:substring")
-@deffn {Scheme Procedure} match:substring match [n]
-Return the portion of @var{target} matched by subexpression number
-@var{n}. Submatch 0 (the default) represents the entire regexp match.
-If the regular expression as a whole matched, but the subexpression
-number @var{n} did not match, return @code{#f}.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:start")
-@deffn {Scheme Procedure} match:start match [n]
-Return the starting position of submatch number @var{n}.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:end")
-@deffn {Scheme Procedure} match:end match [n]
-Return the ending position of submatch number @var{n}.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:prefix")
-@deffn {Scheme Procedure} match:prefix match
-Return the unmatched portion of @var{target} preceding the regexp match.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:suffix")
-@deffn {Scheme Procedure} match:suffix match
-Return the unmatched portion of @var{target} following the regexp match.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:count")
-@deffn {Scheme Procedure} match:count match
-Return the number of parenthesized subexpressions from @var{match}.
-Note that the entire regular expression match itself counts as a
-subexpression, and failed submatches are included in the count.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:string")
-@deffn {Scheme Procedure} match:string match
-Return the original @var{target} string.
-@end deffn
-
-@node Backslash Escapes
-@subsection Backslash Escapes
-
-Sometimes you will want a regexp to match characters like @samp{*} or
-@samp{$} exactly. For example, to check whether a particular string
-represents a menu entry from an Info node, it would be useful to match
-it against a regexp like @samp{^* [^:]*::}. However, this won't work;
-because the asterisk is a metacharacter, it won't match the @samp{*} at
-the beginning of the string. In this case, we want to make the first
-asterisk un-magic.
-
-You can do this by preceding the metacharacter with a backslash
-character @samp{\}. (This is also called @dfn{quoting} the
-metacharacter, and is known as a @dfn{backslash escape}.) When Guile
-sees a backslash in a regular expression, it considers the following
-glyph to be an ordinary character, no matter what special meaning it
-would ordinarily have. Therefore, we can make the above example work by
-changing the regexp to @samp{^\* [^:]*::}. The @samp{\*} sequence tells
-the regular expression engine to match only a single asterisk in the
-target string.
-
-Since the backslash is itself a metacharacter, you may force a regexp to
-match a backslash in the target string by preceding the backslash with
-itself. For example, to find variable references in a @TeX{} program,
-you might want to find occurrences of the string @samp{\let\} followed
-by any number of alphabetic characters. The regular expression
-@samp{\\let\\[A-Za-z]*} would do this: the double backslashes in the
-regexp each match a single backslash in the target string.
-
-@c begin (scm-doc-string "regex.scm" "regexp-quote")
-@deffn {Scheme Procedure} regexp-quote str
-Quote each special character found in @var{str} with a backslash, and
-return the resulting string.
-@end deffn
-
-@strong{Very important:} Using backslash escapes in Guile source code
-(as in Emacs Lisp or C) can be tricky, because the backslash character
-has special meaning for the Guile reader. For example, if Guile
-encounters the character sequence @samp{\n} in the middle of a string
-while processing Scheme code, it replaces those characters with a
-newline character. Similarly, the character sequence @samp{\t} is
-replaced by a horizontal tab. Several of these @dfn{escape sequences}
-are processed by the Guile reader before your code is executed.
-Unrecognized escape sequences are ignored: if the characters @samp{\*}
-appear in a string, they will be translated to the single character
-@samp{*}.
-
-This translation is obviously undesirable for regular expressions, since
-we want to be able to include backslashes in a string in order to
-escape regexp metacharacters. Therefore, to make sure that a backslash
-is preserved in a string in your Guile program, you must use @emph{two}
-consecutive backslashes:
-
-@lisp
-(define Info-menu-entry-pattern (make-regexp "^\\* [^:]*"))
-@end lisp
-
-The string in this example is preprocessed by the Guile reader before
-any code is executed. The resulting argument to @code{make-regexp} is
-the string @samp{^\* [^:]*}, which is what we really want.
-
-This also means that in order to write a regular expression that matches
-a single backslash character, the regular expression string in the
-source code must include @emph{four} backslashes. Each consecutive pair
-of backslashes gets translated by the Guile reader to a single
-backslash, and the resulting double-backslash is interpreted by the
-regexp engine as matching a single backslash character. Hence:
-
-@lisp
-(define tex-variable-pattern (make-regexp "\\\\let\\\\=[A-Za-z]*"))
-@end lisp
-
-The reason for the unwieldiness of this syntax is historical. Both
-regular expression pattern matchers and Unix string processing systems
-have traditionally used backslashes with the special meanings
-described above. The POSIX regular expression specification and ANSI C
-standard both require these semantics. Attempting to abandon either
-convention would cause other kinds of compatibility problems, possibly
-more severe ones. Therefore, without extending the Scheme reader to
-support strings with different quoting conventions (an ungainly and
-confusing extension when implemented in other languages), we must adhere
-to this cumbersome escape syntax.
-
-
-@node Symbols
-@section Symbols
-@tpindex Symbols
-
-Symbols in Scheme are widely used in three ways: as items of discrete
-data, as lookup keys for alists and hash tables, and to denote variable
-references.
-
-A @dfn{symbol} is similar to a string in that it is defined by a
-sequence of characters. The sequence of characters is known as the
-symbol's @dfn{name}. In the usual case --- that is, where the symbol's
-name doesn't include any characters that could be confused with other
-elements of Scheme syntax --- a symbol is written in a Scheme program by
-writing the sequence of characters that make up the name, @emph{without}
-any quotation marks or other special syntax. For example, the symbol
-whose name is ``multiply-by-2'' is written, simply:
-
-@lisp
-multiply-by-2
-@end lisp
-
-Notice how this differs from a @emph{string} with contents
-``multiply-by-2'', which is written with double quotation marks, like
-this:
-
-@lisp
-"multiply-by-2"
-@end lisp
-
-Looking beyond how they are written, symbols are different from strings
-in two important respects.
-
-The first important difference is uniqueness. If the same-looking
-string is read twice from two different places in a program, the result
-is two @emph{different} string objects whose contents just happen to be
-the same. If, on the other hand, the same-looking symbol is read twice
-from two different places in a program, the result is the @emph{same}
-symbol object both times.
-
-Given two read symbols, you can use @code{eq?} to test whether they are
-the same (that is, have the same name). @code{eq?} is the most
-efficient comparison operator in Scheme, and comparing two symbols like
-this is as fast as comparing, for example, two numbers. Given two
-strings, on the other hand, you must use @code{equal?} or
-@code{string=?}, which are much slower comparison operators, to
-determine whether the strings have the same contents.
-
-@lisp
-(define sym1 (quote hello))
-(define sym2 (quote hello))
-(eq? sym1 sym2) @result{} #t
-
-(define str1 "hello")
-(define str2 "hello")
-(eq? str1 str2) @result{} #f
-(equal? str1 str2) @result{} #t
-@end lisp
-
-The second important difference is that symbols, unlike strings, are not
-self-evaluating. This is why we need the @code{(quote @dots{})}s in the
-example above: @code{(quote hello)} evaluates to the symbol named
-"hello" itself, whereas an unquoted @code{hello} is @emph{read} as the
-symbol named "hello" and evaluated as a variable reference @dots{} about
-which more below (@pxref{Symbol Variables}).
-
-@menu
-* Symbol Data:: Symbols as discrete data.
-* Symbol Keys:: Symbols as lookup keys.
-* Symbol Variables:: Symbols as denoting variables.
-* Symbol Primitives:: Operations related to symbols.
-* Symbol Props:: Function slots and property lists.
-* Symbol Read Syntax:: Extended read syntax for symbols.
-* Symbol Uninterned:: Uninterned symbols.
-@end menu
-
-
-@node Symbol Data
-@subsection Symbols as Discrete Data
-
-Numbers and symbols are similar to the extent that they both lend
-themselves to @code{eq?} comparison. But symbols are more descriptive
-than numbers, because a symbol's name can be used directly to describe
-the concept for which that symbol stands.
-
-For example, imagine that you need to represent some colours in a
-computer program. Using numbers, you would have to choose arbitrarily
-some mapping between numbers and colours, and then take care to use that
-mapping consistently:
-
-@lisp
-;; 1=red, 2=green, 3=purple
-
-(if (eq? (colour-of car) 1)
- ...)
-@end lisp
-
-@noindent
-You can make the mapping more explicit and the code more readable by
-defining constants:
-
-@lisp
-(define red 1)
-(define green 2)
-(define purple 3)
-
-(if (eq? (colour-of car) red)
- ...)
-@end lisp
-
-@noindent
-But the simplest and clearest approach is not to use numbers at all, but
-symbols whose names specify the colours that they refer to:
-
-@lisp
-(if (eq? (colour-of car) 'red)
- ...)
-@end lisp
-
-The descriptive advantages of symbols over numbers increase as the set
-of concepts that you want to describe grows. Suppose that a car object
-can have other properties as well, such as whether it has or uses:
-
-@itemize @bullet
-@item
-automatic or manual transmission
-@item
-leaded or unleaded fuel
-@item
-power steering (or not).
-@end itemize
-
-@noindent
-Then a car's combined property set could be naturally represented and
-manipulated as a list of symbols:
-
-@lisp
-(properties-of car1)
-@result{}
-(red manual unleaded power-steering)
-
-(if (memq 'power-steering (properties-of car1))
- (display "Unfit people can drive this car.\n")
- (display "You'll need strong arms to drive this car!\n"))
-@print{}
-Unfit people can drive this car.
-@end lisp
-
-Remember, the fundamental property of symbols that we are relying on
-here is that an occurrence of @code{'red} in one part of a program is an
-@emph{indistinguishable} symbol from an occurrence of @code{'red} in
-another part of a program; this means that symbols can usefully be
-compared using @code{eq?}. At the same time, symbols have naturally
-descriptive names. This combination of efficiency and descriptive power
-makes them ideal for use as discrete data.
-
-
-@node Symbol Keys
-@subsection Symbols as Lookup Keys
-
-Given their efficiency and descriptive power, it is natural to use
-symbols as the keys in an association list or hash table.
-
-To illustrate this, consider a more structured representation of the car
-properties example from the preceding subsection. Rather than
-mixing all the properties up together in a flat list, we could use an
-association list like this:
-
-@lisp
-(define car1-properties '((colour . red)
- (transmission . manual)
- (fuel . unleaded)
- (steering . power-assisted)))
-@end lisp
-
-Notice how this structure is more explicit and extensible than the flat
-list. For example it makes clear that @code{manual} refers to the
-transmission rather than, say, the windows or the locking of the car.
-It also allows further properties to use the same symbols among their
-possible values without becoming ambiguous:
-
-@lisp
-(define car1-properties '((colour . red)
- (transmission . manual)
- (fuel . unleaded)
- (steering . power-assisted)
- (seat-colour . red)
- (locking . manual)))
-@end lisp
-
-With a representation like this, it is easy to use the efficient
-@code{assq-XXX} family of procedures (@pxref{Association Lists}) to
-extract or change individual pieces of information:
-
-@lisp
-(assq-ref car1-properties 'fuel) @result{} unleaded
-(assq-ref car1-properties 'transmission) @result{} manual
-
-(assq-set! car1-properties 'seat-colour 'black)
-@result{}
-((colour . red)
- (transmission . manual)
- (fuel . unleaded)
- (steering . power-assisted)
- (seat-colour . black)
- (locking . manual)))
-@end lisp
-
-Hash tables also have keys, and exactly the same arguments apply to the
-use of symbols in hash tables as in association lists. The hash value
-that Guile uses to decide where to add a symbol-keyed entry to a hash
-table can be obtained by calling the @code{symbol-hash} procedure:
-
-@deffn {Scheme Procedure} symbol-hash symbol
-@deffnx {C Function} scm_symbol_hash (symbol)
-Return a hash value for @var{symbol}.
-@end deffn
-
-See @ref{Hash Tables} for information about hash tables in general, and
-for why you might choose to use a hash table rather than an association
-list.
-
-
-@node Symbol Variables
-@subsection Symbols as Denoting Variables
-
-When an unquoted symbol in a Scheme program is evaluated, it is
-interpreted as a variable reference, and the result of the evaluation is
-the appropriate variable's value.
-
-For example, when the expression @code{(string-length "abcd")} is read
-and evaluated, the sequence of characters @code{string-length} is read
-as the symbol whose name is "string-length". This symbol is associated
-with a variable whose value is the procedure that implements string
-length calculation. Therefore evaluation of the @code{string-length}
-symbol results in that procedure.
-
-The details of the connection between an unquoted symbol and the
-variable to which it refers are explained elsewhere. See @ref{Binding
-Constructs}, for how associations between symbols and variables are
-created, and @ref{Modules}, for how those associations are affected by
-Guile's module system.
-
-
-@node Symbol Primitives
-@subsection Operations Related to Symbols
-
-Given any Scheme value, you can determine whether it is a symbol using
-the @code{symbol?} primitive:
-
-@rnindex symbol?
-@deffn {Scheme Procedure} symbol? obj
-@deffnx {C Function} scm_symbol_p (obj)
-Return @code{#t} if @var{obj} is a symbol, otherwise return
-@code{#f}.
-@end deffn
-
-Once you know that you have a symbol, you can obtain its name as a
-string by calling @code{symbol->string}. Note that Guile differs by
-default from R5RS on the details of @code{symbol->string} as regards
-case-sensitivity:
-
-@rnindex symbol->string
-@deffn {Scheme Procedure} symbol->string s
-@deffnx {C Function} scm_symbol_to_string (s)
-Return the name of symbol @var{s} as a string. By default, Guile reads
-symbols case-sensitively, so the string returned will have the same case
-variation as the sequence of characters that caused @var{s} to be
-created.
-
-If Guile is set to read symbols case-insensitively (as specified by
-R5RS), and @var{s} comes into being as part of a literal expression
-(@pxref{Literal expressions,,,r5rs, The Revised^5 Report on Scheme}) or
-by a call to the @code{read} or @code{string-ci->symbol} procedures,
-Guile converts any alphabetic characters in the symbol's name to
-lower case before creating the symbol object, so the string returned
-here will be in lower case.
-
-If @var{s} was created by @code{string->symbol}, the case of characters
-in the string returned will be the same as that in the string that was
-passed to @code{string->symbol}, regardless of Guile's case-sensitivity
-setting at the time @var{s} was created.
-
-It is an error to apply mutation procedures like @code{string-set!} to
-strings returned by this procedure.
-@end deffn
-
-Most symbols are created by writing them literally in code. However it
-is also possible to create symbols programmatically using the following
-@code{string->symbol} and @code{string-ci->symbol} procedures:
-
-@rnindex string->symbol
-@deffn {Scheme Procedure} string->symbol string
-@deffnx {C Function} scm_string_to_symbol (string)
-Return the symbol whose name is @var{string}. This procedure can create
-symbols with names containing special characters or letters in the
-non-standard case, but it is usually a bad idea to create such symbols
-because in some implementations of Scheme they cannot be read as
-themselves.
-@end deffn
-
-@deffn {Scheme Procedure} string-ci->symbol str
-@deffnx {C Function} scm_string_ci_to_symbol (str)
-Return the symbol whose name is @var{str}. If Guile is currently
-reading symbols case-insensitively, @var{str} is converted to lowercase
-before the returned symbol is looked up or created.
-@end deffn
-
-The following examples illustrate Guile's detailed behaviour as regards
-the case-sensitivity of symbols:
-
-@lisp
-(read-enable 'case-insensitive) ; R5RS compliant behaviour
-
-(symbol->string 'flying-fish) @result{} "flying-fish"
-(symbol->string 'Martin) @result{} "martin"
-(symbol->string
- (string->symbol "Malvina")) @result{} "Malvina"
-
-(eq? 'mISSISSIppi 'mississippi) @result{} #t
-(string->symbol "mISSISSIppi") @result{} mISSISSIppi
-(eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
-(eq? 'LolliPop
- (string->symbol (symbol->string 'LolliPop))) @result{} #t
-(string=? "K. Harper, M.D."
- (symbol->string
- (string->symbol "K. Harper, M.D."))) @result{} #t
-
-(read-disable 'case-insensitive) ; Guile default behaviour
-
-(symbol->string 'flying-fish) @result{} "flying-fish"
-(symbol->string 'Martin) @result{} "Martin"
-(symbol->string
- (string->symbol "Malvina")) @result{} "Malvina"
-
-(eq? 'mISSISSIppi 'mississippi) @result{} #f
-(string->symbol "mISSISSIppi") @result{} mISSISSIppi
-(eq? 'bitBlt (string->symbol "bitBlt")) @result{} #t
-(eq? 'LolliPop
- (string->symbol (symbol->string 'LolliPop))) @result{} #t
-(string=? "K. Harper, M.D."
- (symbol->string
- (string->symbol "K. Harper, M.D."))) @result{} #t
-@end lisp
-
-Finally, some applications, especially those that generate new Scheme
-code dynamically, need to generate symbols for use in the generated
-code. The @code{gensym} primitive meets this need:
-
-@deffn {Scheme Procedure} gensym [prefix]
-@deffnx {C Function} scm_gensym (prefix)
-Create a new symbol with a name constructed from a prefix and a counter
-value. The string @var{prefix} can be specified as an optional
-argument. Default prefix is @samp{ g}. The counter is increased by 1
-at each call. There is no provision for resetting the counter.
-@end deffn
-
-The symbols generated by @code{gensym} are @emph{likely} to be unique,
-since their names begin with a space and it is only otherwise possible
-to generate such symbols if a programmer goes out of their way to do
-so. The 1.8 release of Guile will include a way of creating
-symbols that are @emph{guaranteed} to be unique.
-
-
-@node Symbol Props
-@subsection Function Slots and Property Lists
-
-In traditional Lisp dialects, symbols are often understood as having
-three kinds of value at once:
-
-@itemize @bullet
-@item
-a @dfn{variable} value, which is used when the symbol appears in
-code in a variable reference context
-
-@item
-a @dfn{function} value, which is used when the symbol appears in
-code in a function name position (i.e. as the first element in an
-unquoted list)
-
-@item
-a @dfn{property list} value, which is used when the symbol is given as
-the first argument to Lisp's @code{put} or @code{get} functions.
-@end itemize
-
-Although Scheme (as one of its simplifications with respect to Lisp)
-does away with the distinction between variable and function namespaces,
-Guile currently retains some elements of the traditional structure in
-case they turn out to be useful when implementing translators for other
-languages, in particular Emacs Lisp.
-
-Specifically, Guile symbols have two extra slots. for a symbol's
-property list, and for its ``function value.'' The following procedures
-are provided to access these slots.
-
-@deffn {Scheme Procedure} symbol-fref symbol
-@deffnx {C Function} scm_symbol_fref (symbol)
-Return the contents of @var{symbol}'s @dfn{function slot}.
-@end deffn
-
-@deffn {Scheme Procedure} symbol-fset! symbol value
-@deffnx {C Function} scm_symbol_fset_x (symbol, value)
-Set the contents of @var{symbol}'s function slot to @var{value}.
-@end deffn
-
-@deffn {Scheme Procedure} symbol-pref symbol
-@deffnx {C Function} scm_symbol_pref (symbol)
-Return the @dfn{property list} currently associated with @var{symbol}.
-@end deffn
-
-@deffn {Scheme Procedure} symbol-pset! symbol value
-@deffnx {C Function} scm_symbol_pset_x (symbol, value)
-Set @var{symbol}'s property list to @var{value}.
-@end deffn
-
-@deffn {Scheme Procedure} symbol-property sym prop
-From @var{sym}'s property list, return the value for property
-@var{prop}. The assumption is that @var{sym}'s property list is an
-association list whose keys are distinguished from each other using
-@code{equal?}; @var{prop} should be one of the keys in that list. If
-the property list has no entry for @var{prop}, @code{symbol-property}
-returns @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} set-symbol-property sym prop val
-In @var{sym}'s property list, set the value for property @var{prop} to
-@var{val}, or add a new entry for @var{prop}, with value @var{val}, if
-none already exists. For the structure of the property list, see
-@code{symbol-property}.
-@end deffn
-
-@deffn {Scheme Procedure} symbol-property-remove! sym prop
-From @var{sym}'s property list, remove the entry for property
-@var{prop}, if there is one. For the structure of the property list,
-see @code{symbol-property}.
-@end deffn
-
-Support for these extra slots may be removed in a future release, and it
-is probably better to avoid using them. (In release 1.6, Guile itself
-uses the property list slot sparingly, and the function slot not at
-all.) For a more modern and Schemely approach to properties, see
-@ref{Object Properties}.
-
-
-@node Symbol Read Syntax
-@subsection Extended Read Syntax for Symbols
-
-The read syntax for a symbol is a sequence of letters, digits, and
-@dfn{extended alphabetic characters}, beginning with a character that
-cannot begin a number. In addition, the special cases of @code{+},
-@code{-}, and @code{...} are read as symbols even though numbers can
-begin with @code{+}, @code{-} or @code{.}.
-
-Extended alphabetic characters may be used within identifiers as if
-they were letters. The set of extended alphabetic characters is:
-
-@example
-! $ % & * + - . / : < = > ? @@ ^ _ ~
-@end example
-
-In addition to the standard read syntax defined above (which is taken
-from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on
-Scheme})), Guile provides an extended symbol read syntax that allows the
-inclusion of unusual characters such as space characters, newlines and
-parentheses. If (for whatever reason) you need to write a symbol
-containing characters not mentioned above, you can do so as follows.
-
-@itemize @bullet
-@item
-Begin the symbol with the characters @code{#@{},
-
-@item
-write the characters of the symbol and
-
-@item
-finish the symbol with the characters @code{@}#}.
-@end itemize
-
-Here are a few examples of this form of read syntax. The first symbol
-needs to use extended syntax because it contains a space character, the
-second because it contains a line break, and the last because it looks
-like a number.
-
-@lisp
-#@{foo bar@}#
-
-#@{what
-ever@}#
-
-#@{4242@}#
-@end lisp
-
-Although Guile provides this extended read syntax for symbols,
-widespread usage of it is discouraged because it is not portable and not
-very readable.
-
-
-@node Symbol Uninterned
-@subsection Uninterned Symbols
-
-What makes symbols useful is that they are automatically kept unique.
-There are no two symbols that are distinct objects but have the same
-name. But of course, there is no rule without exception. In addition
-to the normal symbols that have been discussed up to now, you can also
-create special @dfn{uninterned} symbols that behave slightly
-differently.
-
-To understand what is different about them and why they might be useful,
-we look at how normal symbols are actually kept unique.
-
-Whenever Guile wants to find the symbol with a specific name, for
-example during @code{read} or when executing @code{string->symbol}, it
-first looks into a table of all existing symbols to find out whether a
-symbol with the given name already exists. When this is the case, Guile
-just returns that symbol. When not, a new symbol with the name is
-created and entered into the table so that it can be found later.
-
-Sometimes you might want to create a symbol that is guaranteed `fresh',
-i.e. a symbol that did not exist previously. You might also want to
-somehow guarantee that no one else will ever unintentionally stumble
-across your symbol in the future. These properties of a symbol are
-often needed when generating code during macro expansion. When
-introducing new temporary variables, you want to guarantee that they
-don't conflict with variables in other people's code.
-
-The simplest way to arrange for this is to create a new symbol but
-not enter it into the global table of all symbols. That way, no one
-will ever get access to your symbol by chance. Symbols that are not in
-the table are called @dfn{uninterned}. Of course, symbols that
-@emph{are} in the table are called @dfn{interned}.
-
-You create new uninterned symbols with the function @code{make-symbol}.
-You can test whether a symbol is interned or not with
-@code{symbol-interned?}.
-
-Uninterned symbols break the rule that the name of a symbol uniquely
-identifies the symbol object. Because of this, they can not be written
-out and read back in like interned symbols. Currently, Guile has no
-support for reading uninterned symbols. Note that the function
-@code{gensym} does not return uninterned symbols for this reason.
-
-@deffn {Scheme Procedure} make-symbol name
-@deffnx {C Function} scm_make_symbol (name)
-Return a new uninterned symbol with the name @var{name}. The returned
-symbol is guaranteed to be unique and future calls to
-@code{string->symbol} will not return it.
-@end deffn
-
-@deffn {Scheme Procedure} symbol-interned? symbol
-@deffnx {C Function} scm_symbol_interned_p (symbol)
-Return @code{#t} if @var{symbol} is interned, otherwise return
-@code{#f}.
-@end deffn
-
-For example:
-
-@lisp
-(define foo-1 (string->symbol "foo"))
-(define foo-2 (string->symbol "foo"))
-(define foo-3 (make-symbol "foo"))
-(define foo-4 (make-symbol "foo"))
-
-(eq? foo-1 foo-2)
-@result{} #t
-; Two interned symbols with the same name are the same object,
-
-(eq? foo-1 foo-3)
-@result{} #f
-; but a call to make-symbol with the same name returns a
-; distinct object.
-
-(eq? foo-3 foo-4)
-@result{} #f
-; A call to make-symbol always returns a new object, even for
-; the same name.
-
-foo-3
-@result{} #<uninterned-symbol foo 8085290>
-; Uninterned symbols print differently from interned symbols,
-
-(symbol? foo-3)
-@result{} #t
-; but they are still symbols,
-
-(symbol-interned? foo-3)
-@result{} #f
-; just not interned.
-@end lisp
-
-
-@node Keywords
-@section Keywords
-@tpindex Keywords
-
-Keywords are self-evaluating objects with a convenient read syntax that
-makes them easy to type.
-
-Guile's keyword support conforms to R5RS, and adds a (switchable) read
-syntax extension to permit keywords to begin with @code{:} as well as
-@code{#:}.
-
-@menu
-* Why Use Keywords?:: Motivation for keyword usage.
-* Coding With Keywords:: How to use keywords.
-* Keyword Read Syntax:: Read syntax for keywords.
-* Keyword Procedures:: Procedures for dealing with keywords.
-* Keyword Primitives:: The underlying primitive procedures.
-@end menu
-
-@node Why Use Keywords?
-@subsection Why Use Keywords?
-
-Keywords are useful in contexts where a program or procedure wants to be
-able to accept a large number of optional arguments without making its
-interface unmanageable.
-
-To illustrate this, consider a hypothetical @code{make-window}
-procedure, which creates a new window on the screen for drawing into
-using some graphical toolkit. There are many parameters that the caller
-might like to specify, but which could also be sensibly defaulted, for
-example:
-
-@itemize @bullet
-@item
-color depth -- Default: the color depth for the screen
-
-@item
-background color -- Default: white
-
-@item
-width -- Default: 600
-
-@item
-height -- Default: 400
-@end itemize
-
-If @code{make-window} did not use keywords, the caller would have to
-pass in a value for each possible argument, remembering the correct
-argument order and using a special value to indicate the default value
-for that argument:
-
-@lisp
-(make-window 'default ;; Color depth
- 'default ;; Background color
- 800 ;; Width
- 100 ;; Height
- @dots{}) ;; More make-window arguments
-@end lisp
-
-With keywords, on the other hand, defaulted arguments are omitted, and
-non-default arguments are clearly tagged by the appropriate keyword. As
-a result, the invocation becomes much clearer:
-
-@lisp
-(make-window #:width 800 #:height 100)
-@end lisp
-
-On the other hand, for a simpler procedure with few arguments, the use
-of keywords would be a hindrance rather than a help. The primitive
-procedure @code{cons}, for example, would not be improved if it had to
-be invoked as
-
-@lisp
-(cons #:car x #:cdr y)
-@end lisp
-
-So the decision whether to use keywords or not is purely pragmatic: use
-them if they will clarify the procedure invocation at point of call.
-
-@node Coding With Keywords
-@subsection Coding With Keywords
-
-If a procedure wants to support keywords, it should take a rest argument
-and then use whatever means is convenient to extract keywords and their
-corresponding arguments from the contents of that rest argument.
-
-The following example illustrates the principle: the code for
-@code{make-window} uses a helper procedure called
-@code{get-keyword-value} to extract individual keyword arguments from
-the rest argument.
-
-@lisp
-(define (get-keyword-value args keyword default)
- (let ((kv (memq keyword args)))
- (if (and kv (>= (length kv) 2))
- (cadr kv)
- default)))
-
-(define (make-window . args)
- (let ((depth (get-keyword-value args #:depth screen-depth))
- (bg (get-keyword-value args #:bg "white"))
- (width (get-keyword-value args #:width 800))
- (height (get-keyword-value args #:height 100))
- @dots{})
- @dots{}))
-@end lisp
-
-But you don't need to write @code{get-keyword-value}. The @code{(ice-9
-optargs)} module provides a set of powerful macros that you can use to
-implement keyword-supporting procedures like this:
-
-@lisp
-(use-modules (ice-9 optargs))
-
-(define (make-window . args)
- (let-keywords args #f ((depth screen-depth)
- (bg "white")
- (width 800)
- (height 100))
- ...))
-@end lisp
-
-@noindent
-Or, even more economically, like this:
-
-@lisp
-(use-modules (ice-9 optargs))
-
-(define* (make-window #:key (depth screen-depth)
- (bg "white")
- (width 800)
- (height 100))
- ...)
-@end lisp
-
-For further details on @code{let-keywords}, @code{define*} and other
-facilities provided by the @code{(ice-9 optargs)} module, see
-@ref{Optional Arguments}.
-
-
-@node Keyword Read Syntax
-@subsection Keyword Read Syntax
-
-Guile, by default, only recognizes the keyword syntax specified by R5RS.
-A token of the form @code{#:NAME}, where @code{NAME} has the same syntax
-as a Scheme symbol (@pxref{Symbol Read Syntax}), is the external
-representation of the keyword named @code{NAME}. Keyword objects print
-using this syntax as well, so values containing keyword objects can be
-read back into Guile. When used in an expression, keywords are
-self-quoting objects.
-
-If the @code{keyword} read option is set to @code{'prefix}, Guile also
-recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens
-of the form @code{:NAME} are read as symbols, as required by R5RS.
-
-To enable and disable the alternative non-R5RS keyword syntax, you use
-the @code{read-options} procedure documented in @ref{General option
-interface} and @ref{Reader options}.
-
-@smalllisp
-(read-set! keywords 'prefix)
-
-#:type
-@result{}
-#:type
-
-:type
-@result{}
-#:type
-
-(read-set! keywords #f)
-
-#:type
-@result{}
-#:type
-
-:type
-@print{}
-ERROR: In expression :type:
-ERROR: Unbound variable: :type
-ABORT: (unbound-variable)
-@end smalllisp
-
-@node Keyword Procedures
-@subsection Keyword Procedures
-
-The following procedures can be used for converting symbols to keywords
-and back.
-
-@deffn {Scheme Procedure} symbol->keyword sym
-Return a keyword with the same characters as in @var{sym}.
-@end deffn
-
-@deffn {Scheme Procedure} keyword->symbol kw
-Return a symbol with the same characters as in @var{kw}.
-@end deffn
-
-
-@node Keyword Primitives
-@subsection Keyword Primitives
-
-Internally, a keyword is implemented as something like a tagged symbol,
-where the tag identifies the keyword as being self-evaluating, and the
-symbol, known as the keyword's @dfn{dash symbol} has the same name as
-the keyword name but prefixed by a single dash. For example, the
-keyword @code{#:name} has the corresponding dash symbol @code{-name}.
-
-Most keyword objects are constructed automatically by the reader when it
-reads a token beginning with @code{#:}. However, if you need to
-construct a keyword object programmatically, you can do so by calling
-@code{make-keyword-from-dash-symbol} with the corresponding dash symbol
-(as the reader does). The dash symbol for a keyword object can be
-retrieved using the @code{keyword-dash-symbol} procedure.
-
-@deffn {Scheme Procedure} make-keyword-from-dash-symbol symbol
-@deffnx {C Function} scm_make_keyword_from_dash_symbol (symbol)
-Make a keyword object from a @var{symbol} that starts with a dash.
-@end deffn
-
-@deffn {Scheme Procedure} keyword? obj
-@deffnx {C Function} scm_keyword_p (obj)
-Return @code{#t} if the argument @var{obj} is a keyword, else
-@code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} keyword-dash-symbol keyword
-@deffnx {C Function} scm_keyword_dash_symbol (keyword)
-Return the dash symbol for @var{keyword}.
-This is the inverse of @code{make-keyword-from-dash-symbol}.
-@end deffn
-
-
-@node Other Types
-@section ``Functionality-Centric'' Data Types
-
-Procedures and macros are documented in their own chapter: see
-@ref{Procedures and Macros}.
-
-Variable objects are documented as part of the description of Guile's
-module system: see @ref{Variables}.
-
-Asyncs, dynamic roots and fluids are described in the chapter on
-scheduling: see @ref{Scheduling}.
-
-Hooks are documented in the chapter on general utility functions: see
-@ref{Hooks}.
-
-Ports are described in the chapter on I/O: see @ref{Input and Output}.
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-debug.texi b/doc/ref/scheme-debug.texi
deleted file mode 100644
index 670bd0884..000000000
--- a/doc/ref/scheme-debug.texi
+++ /dev/null
@@ -1,206 +0,0 @@
-@page
-@node Debugging
-@chapter Debugging Infrastructure
-
-@deffn {Scheme Procedure} debug-options-interface [setting]
-@deffnx {C Function} scm_debug_options (setting)
-Option interface for the debug options. Instead of using
-this procedure directly, use the procedures @code{debug-enable},
-@code{debug-disable}, @code{debug-set!} and @code{debug-options}.
-@end deffn
-
-
-@section Using Traps
-
-@deffn {Scheme Procedure} with-traps thunk
-@deffnx {C Function} scm_with_traps (thunk)
-Call @var{thunk} with traps enabled.
-@end deffn
-
-@deffn {Scheme Procedure} debug-object? obj
-@deffnx {C Function} scm_debug_object_p (obj)
-Return @code{#t} if @var{obj} is a debug object.
-@end deffn
-
-
-@section Capturing the Stack or Innermost Stack Frame
-
-When an error occurs in a running program, or the program hits a
-breakpoint, its state at that point can be represented by a @dfn{stack}
-of all the evaluations and procedure applications that are logically in
-progress at that time, each of which is known as a @dfn{frame}. The
-programmer can learn more about the program's state at the point of
-interruption or error by inspecting the stack and its frames.
-
-@deffn {Scheme Procedure} make-stack obj . args
-@deffnx {C Function} scm_make_stack (obj, args)
-Create a new stack. If @var{obj} is @code{#t}, the current
-evaluation stack is used for creating the stack frames,
-otherwise the frames are taken from @var{obj} (which must be
-either a debug object or a continuation).
-
-@var{args} should be a list containing any combination of
-integer, procedure and @code{#t} values.
-
-These values specify various ways of cutting away uninteresting
-stack frames from the top and bottom of the stack that
-@code{make-stack} returns. They come in pairs like this:
-@code{(@var{inner_cut_1} @var{outer_cut_1} @var{inner_cut_2}
-@var{outer_cut_2} @dots{})}.
-
-Each @var{inner_cut_N} can be @code{#t}, an integer, or a
-procedure. @code{#t} means to cut away all frames up to but
-excluding the first user module frame. An integer means to cut
-away exactly that number of frames. A procedure means to cut
-away all frames up to but excluding the application frame whose
-procedure matches the specified one.
-
-Each @var{outer_cut_N} can be an integer or a procedure. An
-integer means to cut away that number of frames. A procedure
-means to cut away frames down to but excluding the application
-frame whose procedure matches the specified one.
-
-If the @var{outer_cut_N} of the last pair is missing, it is
-taken as 0.
-@end deffn
-
-@deffn {Scheme Procedure} last-stack-frame obj
-@deffnx {C Function} scm_last_stack_frame (obj)
-Return a stack which consists of a single frame, which is the
-last stack frame for @var{obj}. @var{obj} must be either a
-debug object or a continuation.
-@end deffn
-
-
-@section Examining the Stack
-
-@deffn {Scheme Procedure} stack? obj
-@deffnx {C Function} scm_stack_p (obj)
-Return @code{#t} if @var{obj} is a calling stack.
-@end deffn
-
-@deffn {Scheme Procedure} stack-id stack
-@deffnx {C Function} scm_stack_id (stack)
-Return the identifier given to @var{stack} by @code{start-stack}.
-@end deffn
-
-@deffn {Scheme Procedure} stack-length stack
-@deffnx {C Function} scm_stack_length (stack)
-Return the length of @var{stack}.
-@end deffn
-
-@deffn {Scheme Procedure} stack-ref stack index
-@deffnx {C Function} scm_stack_ref (stack, index)
-Return the @var{index}'th frame from @var{stack}.
-@end deffn
-
-@deffn {Scheme Procedure} display-backtrace stack port [first [depth]]
-@deffnx {C Function} scm_display_backtrace (stack, port, first, depth)
-Display a backtrace to the output port @var{port}. @var{stack}
-is the stack to take the backtrace from, @var{first} specifies
-where in the stack to start and @var{depth} how much frames
-to display. Both @var{first} and @var{depth} can be @code{#f},
-which means that default values will be used.
-@end deffn
-
-
-@section Examining Stack Frames
-
-@deffn {Scheme Procedure} frame? obj
-@deffnx {C Function} scm_frame_p (obj)
-Return @code{#t} if @var{obj} is a stack frame.
-@end deffn
-
-@deffn {Scheme Procedure} frame-number frame
-@deffnx {C Function} scm_frame_number (frame)
-Return the frame number of @var{frame}.
-@end deffn
-
-@deffn {Scheme Procedure} frame-previous frame
-@deffnx {C Function} scm_frame_previous (frame)
-Return the previous frame of @var{frame}, or @code{#f} if
-@var{frame} is the first frame in its stack.
-@end deffn
-
-@deffn {Scheme Procedure} frame-next frame
-@deffnx {C Function} scm_frame_next (frame)
-Return the next frame of @var{frame}, or @code{#f} if
-@var{frame} is the last frame in its stack.
-@end deffn
-
-@deffn {Scheme Procedure} frame-source frame
-@deffnx {C Function} scm_frame_source (frame)
-Return the source of @var{frame}.
-@end deffn
-
-@deffn {Scheme Procedure} frame-procedure? frame
-@deffnx {C Function} scm_frame_procedure_p (frame)
-Return @code{#t} if a procedure is associated with @var{frame}.
-@end deffn
-
-@deffn {Scheme Procedure} frame-procedure frame
-@deffnx {C Function} scm_frame_procedure (frame)
-Return the procedure for @var{frame}, or @code{#f} if no
-procedure is associated with @var{frame}.
-@end deffn
-
-@deffn {Scheme Procedure} frame-arguments frame
-@deffnx {C Function} scm_frame_arguments (frame)
-Return the arguments of @var{frame}.
-@end deffn
-
-@deffn {Scheme Procedure} frame-evaluating-args? frame
-@deffnx {C Function} scm_frame_evaluating_args_p (frame)
-Return @code{#t} if @var{frame} contains evaluated arguments.
-@end deffn
-
-@deffn {Scheme Procedure} frame-overflow? frame
-@deffnx {C Function} scm_frame_overflow_p (frame)
-Return @code{#t} if @var{frame} is an overflow frame.
-@end deffn
-
-@deffn {Scheme Procedure} frame-real? frame
-@deffnx {C Function} scm_frame_real_p (frame)
-Return @code{#t} if @var{frame} is a real frame.
-@end deffn
-
-@deffn {Scheme Procedure} display-application frame [port [indent]]
-@deffnx {C Function} scm_display_application (frame, port, indent)
-Display a procedure application @var{frame} to the output port
-@var{port}. @var{indent} specifies the indentation of the
-output.
-@end deffn
-
-
-@section Decoding Memoized Source Expressions
-
-@deffn {Scheme Procedure} memoized? obj
-@deffnx {C Function} scm_memoized_p (obj)
-Return @code{#t} if @var{obj} is memoized.
-@end deffn
-
-@deffn {Scheme Procedure} unmemoize m
-@deffnx {C Function} scm_unmemoize (m)
-Unmemoize the memoized expression @var{m},
-@end deffn
-
-@deffn {Scheme Procedure} memoized-environment m
-@deffnx {C Function} scm_memoized_environment (m)
-Return the environment of the memoized expression @var{m}.
-@end deffn
-
-
-@section Starting a New Stack
-
-@deffn {Scheme Syntax} start-stack id exp
-Evaluate @var{exp} on a new calling stack with identity @var{id}. If
-@var{exp} is interrupted during evaluation, backtraces will not display
-frames farther back than @var{exp}'s top-level form. This macro is a
-way of artificially limiting backtraces and stack procedures, largely as
-a convenience to the user.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-evaluation.texi b/doc/ref/scheme-evaluation.texi
deleted file mode 100644
index b73f8316d..000000000
--- a/doc/ref/scheme-evaluation.texi
+++ /dev/null
@@ -1,426 +0,0 @@
-@page
-@node Read/Load/Eval
-@chapter Reading and Evaluating Scheme Code
-
-This chapter describes Guile functions that are concerned with reading,
-loading and evaluating Scheme code at run time.
-
-@menu
-* Scheme Syntax:: Standard and extended Scheme syntax.
-* Scheme Read:: Reading Scheme code.
-* Fly Evaluation:: Procedures for on the fly evaluation.
-* Loading:: Loading Scheme code from file.
-* Delayed Evaluation:: Postponing evaluation until it is needed.
-* Local Evaluation:: Evaluation in a local environment.
-* Evaluator Behaviour:: Modifying Guile's evaluator.
-@end menu
-
-
-@node Scheme Syntax
-@section Scheme Syntax: Standard and Guile Extensions
-
-@menu
-* Expression Syntax::
-* Comments::
-* Block Comments::
-* Case Sensitivity::
-* Keyword Syntax::
-* Reader Extensions::
-@end menu
-
-
-@node Expression Syntax
-@subsection Expression Syntax
-
-
-@node Comments
-@subsection Comments
-
-@c FIXME::martin: Review me!
-
-Comments in Scheme source files are written by starting them with a
-semicolon character (@code{;}). The comment then reaches up to the end
-of the line. Comments can begin at any column, and the may be inserted
-on the same line as Scheme code.
-
-@lisp
-; Comment
-;; Comment too
-(define x 1) ; Comment after expression
-(let ((y 1))
- ;; Display something.
- (display y)
-;;; Comment at left margin.
- (display (+ y 1)))
-@end lisp
-
-It is common to use a single semicolon for comments following
-expressions on a line, to use two semicolons for comments which are
-indented like code, and three semicolons for comments which start at
-column 0, even if they are inside an indented code block. This
-convention is used when indenting code in Emacs' Scheme mode.
-
-
-@node Block Comments
-@subsection Block Comments
-
-@c FIXME::martin: Review me!
-
-@cindex multiline comments
-In addition to the standard line comments defined by R5RS, Guile has
-another comment type for multiline comments, called @dfn{block
-comments}. This type of comment begins with the character sequence
-@code{#!} and ends with the characters @code{!#}, which must appear on a
-line of their own. These comments are compatible with the block
-comments in the Scheme Shell @file{scsh} (@pxref{The Scheme shell
-(scsh)}). The characters @code{#!} were chosen because they are the
-magic characters used in shell scripts for indicating that the name of
-the program for executing the script follows on the same line.
-
-Thus a Guile script often starts like this.
-
-@lisp
-#! /usr/local/bin/guile -s
-!#
-@end lisp
-
-More details on Guile scripting can be found in the scripting section
-(@pxref{Guile Scripting}).
-
-
-@node Case Sensitivity
-@subsection Case Sensitivity
-
-@c FIXME::martin: Review me!
-
-Scheme as defined in R5RS is not case sensitive when reading symbols.
-Guile, on the contrary is case sensitive by default, so the identifiers
-
-@lisp
-guile-whuzzy
-Guile-Whuzzy
-@end lisp
-
-are the same in R5RS Scheme, but are different in Guile.
-
-It is possible to turn off case sensitivity in Guile by setting the
-reader option @code{case-insensitive}. More on reader options can be
-found at (@pxref{Reader options}).
-
-@lisp
-(read-enable 'case-insensitive)
-@end lisp
-
-Note that this is seldom a problem, because Scheme programmers tend not
-to use uppercase letters in their identifiers anyway.
-
-
-@node Keyword Syntax
-@subsection Keyword Syntax
-
-
-@node Reader Extensions
-@subsection Reader Extensions
-
-@deffn {Scheme Procedure} read-hash-extend chr proc
-@deffnx {C Function} scm_read_hash_extend (chr, proc)
-Install the procedure @var{proc} for reading expressions
-starting with the character sequence @code{#} and @var{chr}.
-@var{proc} will be called with two arguments: the character
-@var{chr} and the port to read further data from. The object
-returned will be the return value of @code{read}.
-@end deffn
-
-
-@node Scheme Read
-@section Reading Scheme Code
-
-@rnindex read
-@deffn {Scheme Procedure} read [port]
-@deffnx {C Function} scm_read (port)
-Read an s-expression from the input port @var{port}, or from
-the current input port if @var{port} is not specified.
-Any whitespace before the next token is discarded.
-@end deffn
-
-The behaviour of Guile's Scheme reader can be modified by manipulating
-its read options. For more information about options, @xref{General
-option interface}. If you want to know which reader options are
-available, @xref{Reader options}.
-
-@c FIXME::martin: This is taken from libguile/options.c. Is there
-@c actually a difference between 'help and 'full?
-
-@deffn {Scheme Procedure} read-options [setting]
-Display the current settings of the read options. If @var{setting} is
-omitted, only a short form of the current read options is printed.
-Otherwise, @var{setting} should be one of the following symbols:
-@table @code
-@item help
-Display the complete option settings.
-@item full
-Like @code{help}, but also print programmer options.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} read-enable option-name
-@deffnx {Scheme Procedure} read-disable option-name
-@deffnx {Scheme Procedure} read-set! option-name value
-Modify the read options. @code{read-enable} should be used with boolean
-options and switches them on, @code{read-disable} switches them off.
-@code{read-set!} can be used to set an option to a specific value.
-@end deffn
-
-@deffn {Scheme Procedure} read-options-interface [setting]
-@deffnx {C Function} scm_read_options (setting)
-Option interface for the read options. Instead of using
-this procedure directly, use the procedures @code{read-enable},
-@code{read-disable}, @code{read-set!} and @code{read-options}.
-@end deffn
-
-
-@node Fly Evaluation
-@section Procedures for On the Fly Evaluation
-
-@xref{Environments}.
-
-@rnindex eval
-@c ARGFIXME environment/environment specifier
-@deffn {Scheme Procedure} eval exp module
-@deffnx {C Function} scm_eval (exp, module)
-Evaluate @var{exp}, a list representing a Scheme expression,
-in the top-level environment specified by @var{module}.
-While @var{exp} is evaluated (using @code{primitive-eval}),
-@var{module} is made the current module. The current module
-is reset to its previous value when @var{eval} returns.
-@end deffn
-
-@rnindex interaction-environment
-@deffn {Scheme Procedure} interaction-environment
-@deffnx {C Function} scm_interaction_environment ()
-Return a specifier for the environment that contains
-implementation--defined bindings, typically a superset of those
-listed in the report. The intent is that this procedure will
-return the environment in which the implementation would
-evaluate expressions dynamically typed by the user.
-@end deffn
-
-@deffn {Scheme Procedure} eval-string string
-@deffnx {C Function} scm_eval_string (string)
-Evaluate @var{string} as the text representation of a Scheme
-form or forms, and return whatever value they produce.
-Evaluation takes place in the environment returned by the
-procedure @code{interaction-environment}.
-@end deffn
-
-@deffn {Scheme Procedure} apply:nconc2last lst
-@deffnx {C Function} scm_nconc2last (lst)
-Given a list (@var{arg1} @dots{} @var{args}), this function
-conses the @var{arg1} @dots{} arguments onto the front of
-@var{args}, and returns the resulting list. Note that
-@var{args} is a list; thus, the argument to this function is
-a list whose last element is a list.
-Note: Rather than do new consing, @code{apply:nconc2last}
-destroys its argument, so use with care.
-@end deffn
-
-@rnindex apply
-@deffn {Scheme Procedure} apply proc arg1 @dots{} args
-@var{proc} must be a procedure and @var{args} must be a list. Call
-@var{proc} with the elements of the list @code{(append (list @var{arg1}
-@dots{}) @var{args})} as the actual arguments.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-eval exp
-@deffnx {C Function} scm_primitive_eval (exp)
-Evaluate @var{exp} in the top-level environment specified by
-the current module.
-@end deffn
-
-
-@node Loading
-@section Loading Scheme Code from File
-
-@rnindex load
-@deffn {Scheme Procedure} load filename
-Load @var{filename} and evaluate its contents in the top-level
-environment. The load paths are not searched. If the variable
-@code{%load-hook} is defined, it should be bound to a procedure that
-will be called before any code is loaded. See documentation for
-@code{%load-hook} later in this section.
-@end deffn
-
-@deffn {Scheme Procedure} load-from-path filename
-Similar to @code{load}, but searches for @var{filename} in the load
-paths.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-load filename
-@deffnx {C Function} scm_primitive_load (filename)
-Load the file named @var{filename} and evaluate its contents in
-the top-level environment. The load paths are not searched;
-@var{filename} must either be a full pathname or be a pathname
-relative to the current directory. If the variable
-@code{%load-hook} is defined, it should be bound to a procedure
-that will be called before any code is loaded. See the
-documentation for @code{%load-hook} later in this section.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-load-path filename
-@deffnx {C Function} scm_primitive_load_path (filename)
-Search @var{%load-path} for the file named @var{filename} and
-load it into the top-level environment. If @var{filename} is a
-relative pathname and is not found in the list of search paths,
-an error is signalled.
-@end deffn
-
-@deffn {Scheme Procedure} %search-load-path filename
-@deffnx {C Function} scm_sys_search_load_path (filename)
-Search @var{%load-path} for the file named @var{filename},
-which must be readable by the current user. If @var{filename}
-is found in the list of paths to search or is an absolute
-pathname, return its full pathname. Otherwise, return
-@code{#f}. Filenames may have any of the optional extensions
-in the @code{%load-extensions} list; @code{%search-load-path}
-will try each extension automatically.
-@end deffn
-
-@defvar %load-hook
-A procedure to be run whenever @code{primitive-load} is called. If this
-procedure is defined, it will be called with the filename argument that
-was passed to @code{primitive-load}.
-
-@example
-(define %load-hook (lambda (file)
- (display "Loading ")
- (display file)
- (write-line "...."))) @result{} undefined
-(load-from-path "foo.scm")
-@print{} Loading /usr/local/share/guile/site/foo.scm....
-@end example
-
-@end defvar
-
-@deffn {Scheme Procedure} current-load-port
-@deffnx {C Function} scm_current_load_port ()
-Return the current-load-port.
-The load port is used internally by @code{primitive-load}.
-@end deffn
-
-@defvar %load-extensions
-A list of default file extensions for files containing Scheme code.
-@code{%search-load-path} tries each of these extensions when looking for
-a file to load. By default, @code{%load-extensions} is bound to the
-list @code{("" ".scm")}.
-@end defvar
-
-
-@node Delayed Evaluation
-@section Delayed Evaluation
-
-[delay]
-
-@deffn {Scheme Procedure} promise? obj
-@deffnx {C Function} scm_promise_p (obj)
-Return true if @var{obj} is a promise, i.e. a delayed computation
-(@pxref{Delayed evaluation,,,r5rs.info,The Revised^5 Report on Scheme}).
-@end deffn
-
-@rnindex force
-@deffn {Scheme Procedure} force x
-@deffnx {C Function} scm_force (x)
-If the promise @var{x} has not been computed yet, compute and
-return @var{x}, otherwise just return the previously computed
-value.
-@end deffn
-
-
-@node Local Evaluation
-@section Local Evaluation
-
-[the-environment]
-
-@deffn {Scheme Procedure} local-eval exp [env]
-@deffnx {C Function} scm_local_eval (exp, env)
-Evaluate @var{exp} in its environment. If @var{env} is supplied,
-it is the environment in which to evaluate @var{exp}. Otherwise,
-@var{exp} must be a memoized code object (in which case, its environment
-is implicit).
-@end deffn
-
-
-@node Evaluator Behaviour
-@section Evaluator Behaviour
-
-@c FIXME::martin: Maybe this node name is bad, but the old name clashed with
-@c `Evaluator options' under `Options and Config'.
-
-The behaviour of Guile's evaluator can be modified by manipulating the
-evaluator options. For more information about options, @xref{General
-option interface}. If you want to know which evaluator options are
-available, @xref{Evaluator options}.
-
-@c FIXME::martin: This is taken from libguile/options.c. Is there
-@c actually a difference between 'help and 'full?
-
-@deffn {Scheme Procedure} eval-options [setting]
-Display the current settings of the evaluator options. If @var{setting}
-is omitted, only a short form of the current evaluator options is
-printed. Otherwise, @var{setting} should be one of the following
-symbols:
-@table @code
-@item help
-Display the complete option settings.
-@item full
-Like @code{help}, but also print programmer options.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} eval-enable option-name
-@deffnx {Scheme Procedure} eval-disable option-name
-@deffnx {Scheme Procedure} eval-set! option-name value
-Modify the evaluator options. @code{eval-enable} should be used with boolean
-options and switches them on, @code{eval-disable} switches them off.
-@code{eval-set!} can be used to set an option to a specific value.
-@end deffn
-
-@deffn {Scheme Procedure} eval-options-interface [setting]
-@deffnx {C Function} scm_eval_options_interface (setting)
-Option interface for the evaluation options. Instead of using
-this procedure directly, use the procedures @code{eval-enable},
-@code{eval-disable}, @code{eval-set!} and @code{eval-options}.
-@end deffn
-
-@c FIXME::martin: Why aren't these procedure named like the other options
-@c procedures?
-
-@deffn {Scheme Procedure} traps [setting]
-Display the current settings of the evaluator traps options. If
-@var{setting} is omitted, only a short form of the current evaluator
-traps options is printed. Otherwise, @var{setting} should be one of the
-following symbols:
-@table @code
-@item help
-Display the complete option settings.
-@item full
-Like @code{help}, but also print programmer options.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} trap-enable option-name
-@deffnx {Scheme Procedure} trap-disable option-name
-@deffnx {Scheme Procedure} trap-set! option-name value
-Modify the evaluator options. @code{trap-enable} should be used with boolean
-options and switches them on, @code{trap-disable} switches them off.
-@code{trap-set!} can be used to set an option to a specific value.
-@end deffn
-
-@deffn {Scheme Procedure} evaluator-traps-interface [setting]
-@deffnx {C Function} scm_evaluator_traps (setting)
-Option interface for the evaluator trap options.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-ideas.texi b/doc/ref/scheme-ideas.texi
deleted file mode 100644
index 98ed953e8..000000000
--- a/doc/ref/scheme-ideas.texi
+++ /dev/null
@@ -1,1459 +0,0 @@
-@page
-@node Basic Ideas
-@chapter Basic Ideas in Scheme
-
-In this chapter, we introduce the basic concepts that underpin the
-elegance and power of the Scheme language.
-
-Readers who already possess a background knowledge of Scheme may happily
-skip this chapter. For the reader who is new to the language, however,
-the following discussions on data, procedures, expressions and closure
-are designed to provide a minimum level of Scheme understanding that is
-more or less assumed by the reference chapters that follow.
-
-The style of this introductory material aims about halfway between the
-terse precision of R5RS and the discursive randomness of a Scheme
-tutorial.
-
-@menu
-* About Data:: Latent typing, types, values and variables.
-* About Procedures:: The representation and use of procedures.
-* About Expressions:: All kinds of expressions and their meaning.
-* About Closure:: Closure, scoping and environments.
-@end menu
-
-
-@node About Data
-@section Data Types, Values and Variables
-
-This section discusses the representation of data types and values, what
-it means for Scheme to be a @dfn{latently typed} language, and the role
-of variables. We conclude by introducing the Scheme syntaxes for
-defining a new variable, and for changing the value of an existing
-variable.
-
-@menu
-* Latent Typing:: Scheme as a "latently typed" language.
-* Values and Variables:: About data types, values and variables.
-* Definition:: Defining variables and setting their values.
-@end menu
-
-
-@node Latent Typing
-@subsection Latent Typing
-
-The term @dfn{latent typing} is used to describe a computer language,
-such as Scheme, for which you cannot, @emph{in general}, simply look at
-a program's source code and determine what type of data will be
-associated with a particular variable, or with the result of a
-particular expression.
-
-Sometimes, of course, you @emph{can} tell from the code what the type of
-an expression will be. If you have a line in your program that sets the
-variable @code{x} to the numeric value 1, you can be certain that,
-immediately after that line has executed (and in the absence of multiple
-threads), @code{x} has the numeric value 1. Or if you write a procedure
-that is designed to concatenate two strings, it is likely that the rest
-of your application will always invoke this procedure with two string
-parameters, and quite probable that the procedure would go wrong in some
-way if it was ever invoked with parameters that were not both strings.
-
-Nevertheless, the point is that there is nothing in Scheme which
-requires the procedure parameters always to be strings, or @code{x}
-always to hold a numeric value, and there is no way of declaring in your
-program that such constraints should always be obeyed. In the same
-vein, there is no way to declare the expected type of a procedure's
-return value.
-
-Instead, the types of variables and expressions are only known -- in
-general -- at run time. If you @emph{need} to check at some point that
-a value has the expected type, Scheme provides run time procedures that
-you can invoke to do so. But equally, it can be perfectly valid for two
-separate invocations of the same procedure to specify arguments with
-different types, and to return values with different types.
-
-The next subsection explains what this means in practice, for the ways
-that Scheme programs use data types, values and variables.
-
-
-@node Values and Variables
-@subsection Values and Variables
-
-Scheme provides many data types that you can use to represent your data.
-Primitive types include characters, strings, numbers and procedures.
-Compound types, which allow a group of primitive and compound values to
-be stored together, include lists, pairs, vectors and multi-dimensional
-arrays. In addition, Guile allows applications to define their own data
-types, with the same status as the built-in standard Scheme types.
-
-As a Scheme program runs, values of all types pop in and out of
-existence. Sometimes values are stored in variables, but more commonly
-they pass seamlessly from being the result of one computation to being
-one of the parameters for the next.
-
-Consider an example. A string value is created because the interpreter
-reads in a literal string from your program's source code. Then a
-numeric value is created as the result of calculating the length of the
-string. A second numeric value is created by doubling the calculated
-length. Finally the program creates a list with two elements -- the
-doubled length and the original string itself -- and stores this list in
-a program variable.
-
-All of the values involved here -- in fact, all values in Scheme --
-carry their type with them. In other words, every value ``knows,'' at
-runtime, what kind of value it is. A number, a string, a list,
-whatever.
-
-A variable, on the other hand, has no fixed type. A variable --
-@code{x}, say -- is simply the name of a location -- a box -- in which
-you can store any kind of Scheme value. So the same variable in a
-program may hold a number at one moment, a list of procedures the next,
-and later a pair of strings. The ``type'' of a variable -- insofar as
-the idea is meaningful at all -- is simply the type of whatever value
-the variable happens to be storing at a particular moment.
-
-
-@node Definition
-@subsection Defining and Setting Variables
-
-To define a new variable, you use Scheme's @code{define} syntax like
-this:
-
-@lisp
-(define @var{variable-name} @var{value})
-@end lisp
-
-This makes a new variable called @var{variable-name} and stores
-@var{value} in it as the variable's initial value. For example:
-
-@lisp
-;; Make a variable `x' with initial numeric value 1.
-(define x 1)
-
-;; Make a variable `organization' with an initial string value.
-(define organization "Free Software Foundation")
-@end lisp
-
-(In Scheme, a semicolon marks the beginning of a comment that continues
-until the end of the line. So the lines beginning @code{;;} are
-comments.)
-
-Changing the value of an already existing variable is very similar,
-except that @code{define} is replaced by the Scheme syntax @code{set!},
-like this:
-
-@lisp
-(set! @var{variable-name} @var{new-value})
-@end lisp
-
-Remember that variables do not have fixed types, so @var{new-value} may
-have a completely different type from whatever was previously stored in
-the location named by @var{variable-name}. Both of the following
-examples are therefore correct.
-
-@lisp
-;; Change the value of `x' to 5.
-(set! x 5)
-
-;; Change the value of `organization' to the FSF's street number.
-(set! organization 545)
-@end lisp
-
-In these examples, @var{value} and @var{new-value} are literal numeric
-or string values. In general, however, @var{value} and @var{new-value}
-can be any Scheme expression. Even though we have not yet covered the
-forms that Scheme expressions can take (@pxref{About Expressions}), you
-can probably guess what the following @code{set!} example does@dots{}
-
-@lisp
-(set! x (+ x 1))
-@end lisp
-
-(Note: this is not a complete description of @code{define} and
-@code{set!}, because we need to introduce some other aspects of Scheme
-before the missing pieces can be filled in. If, however, you are
-already familiar with the structure of Scheme, you may like to read
-about those missing pieces immediately by jumping ahead to the following
-references.
-
-@itemize @bullet
-@item
-@ref{Lambda Alternatives}, to read about an alternative form of the
-@code{define} syntax that can be used when defining new procedures.
-
-@item
-@ref{Procedures with Setters}, to read about an alternative form of the
-@code{set!} syntax that helps with changing a single value in the depths
-of a compound data structure.)
-
-@item
-@xref{Internal Definitions}, to read about using @code{define} other
-than at top level in a Scheme program, including a discussion of when it
-works to use @code{define} rather than @code{set!} to change the value
-of an existing variable.
-@end itemize
-
-
-@node About Procedures
-@section The Representation and Use of Procedures
-
-This section introduces the basics of using and creating Scheme
-procedures. It discusses the representation of procedures as just
-another kind of Scheme value, and shows how procedure invocation
-expressions are constructed. We then explain how @code{lambda} is used
-to create new procedures, and conclude by presenting the various
-shorthand forms of @code{define} that can be used instead of writing an
-explicit @code{lambda} expression.
-
-@menu
-* Procedures as Values:: Procedures are values like everything else.
-* Simple Invocation:: How to write a simple procedure invocation.
-* Creating a Procedure:: How to create your own procedures.
-* Lambda Alternatives:: Other ways of writing procedure definitions.
-@end menu
-
-
-@node Procedures as Values
-@subsection Procedures as Values
-
-One of the great simplifications of Scheme is that a procedure is just
-another type of value, and that procedure values can be passed around
-and stored in variables in exactly the same way as, for example, strings
-and lists. When we talk about a built-in standard Scheme procedure such
-as @code{open-input-file}, what we actually mean is that there is a
-pre-defined top level variable called @code{open-input-file}, whose
-value is a procedure that implements what R5RS says that
-@code{open-input-file} should do.
-
-Note that this is quite different from many dialects of Lisp ---
-including Emacs Lisp --- in which a program can use the same name with
-two quite separate meanings: one meaning identifies a Lisp function,
-while the other meaning identifies a Lisp variable, whose value need
-have nothing to do with the function that is associated with the first
-meaning. In these dialects, functions and variables are said to live in
-different @dfn{namespaces}.
-
-In Scheme, on the other hand, all names belong to a single unified
-namespace, and the variables that these names identify can hold any kind
-of Scheme value, including procedure values.
-
-One consequence of the ``procedures as values'' idea is that, if you
-don't happen to like the standard name for a Scheme procedure, you can
-change it.
-
-For example, @code{call-with-current-continuation} is a very important
-standard Scheme procedure, but it also has a very long name! So, many
-programmers use the following definition to assign the same procedure
-value to the more convenient name @code{call/cc}.
-
-@lisp
-(define call/cc call-with-current-continuation)
-@end lisp
-
-Let's understand exactly how this works. The definition creates a new
-variable @code{call/cc}, and then sets its value to the value of the
-variable @code{call-with-current-continuation}; the latter value is a
-procedure that implements the behaviour that R5RS specifies under the
-name ``call-with-current-continuation''. So @code{call/cc} ends up
-holding this value as well.
-
-Now that @code{call/cc} holds the required procedure value, you could
-choose to use @code{call-with-current-continuation} for a completely
-different purpose, or just change its value so that you will get an
-error if you accidentally use @code{call-with-current-continuation} as a
-procedure in your program rather than @code{call/cc}. For example:
-
-@lisp
-(set! call-with-current-continuation "Not a procedure any more!")
-@end lisp
-
-Or you could just leave @code{call-with-current-continuation} as it was.
-It's perfectly fine for more than one variable to hold the same
-procedure value.
-
-
-@node Simple Invocation
-@subsection Simple Procedure Invocation
-
-A procedure invocation in Scheme is written like this:
-
-@lisp
-(@var{procedure} [@var{arg1} [@var{arg2} @dots{}]])
-@end lisp
-
-In this expression, @var{procedure} can be any Scheme expression whose
-value is a procedure. Most commonly, however, @var{procedure} is simply
-the name of a variable whose value is a procedure.
-
-For example, @code{string-append} is a standard Scheme procedure whose
-behaviour is to concatenate together all the arguments, which are
-expected to be strings, that it is given. So the expression
-
-@lisp
-(string-append "/home" "/" "andrew")
-@end lisp
-
-@noindent
-is a procedure invocation whose result is the string value
-@code{"/home/andrew"}.
-
-Similarly, @code{string-length} is a standard Scheme procedure that
-returns the length of a single string argument, so
-
-@lisp
-(string-length "abc")
-@end lisp
-
-@noindent
-is a procedure invocation whose result is the numeric value 3.
-
-Each of the parameters in a procedure invocation can itself be any
-Scheme expression. Since a procedure invocation is itself a type of
-expression, we can put these two examples together to get
-
-@lisp
-(string-length (string-append "/home" "/" "andrew"))
-@end lisp
-
-@noindent
---- a procedure invocation whose result is the numeric value 12.
-
-(You may be wondering what happens if the two examples are combined the
-other way round. If we do this, we can make a procedure invocation
-expression that is @emph{syntactically} correct:
-
-@lisp
-(string-append "/home" (string-length "abc"))
-@end lisp
-
-@noindent
-but when this expression is executed, it will cause an error, because
-the result of @code{(string-length "abc")} is a numeric value, and
-@code{string-append} is not designed to accept a numeric value as one of
-its arguments.)
-
-
-@node Creating a Procedure
-@subsection Creating and Using a New Procedure
-
-Scheme has lots of standard procedures, and Guile provides all of these
-via predefined top level variables. All of these standard procedures
-are documented in the later chapters of this reference manual.
-
-Before very long, though, you will want to create new procedures that
-encapsulate aspects of your own applications' functionality. To do
-this, you can use the famous @code{lambda} syntax.
-
-For example, the value of the following Scheme expression
-
-@lisp
-(lambda (name address) @var{expression} @dots{})
-@end lisp
-
-@noindent
-is a newly created procedure that takes two arguments:
-@code{name} and @code{address}. The behaviour of the
-new procedure is determined by the sequence of @var{expression}s in the
-@dfn{body} of the procedure definition. (Typically, these
-@var{expression}s would use the arguments in some way, or else there
-wouldn't be any point in giving them to the procedure.) When invoked,
-the new procedure returns a value that is the value of the last
-@var{expression} in the procedure body.
-
-To make things more concrete, let's suppose that the two arguments are
-both strings, and that the purpose of this procedure is to form a
-combined string that includes these arguments. Then the full lambda
-expression might look like this:
-
-@lisp
-(lambda (name address)
- (string-append "Name=" name ":Address=" address))
-@end lisp
-
-We noted in the previous subsection that the @var{procedure} part of a
-procedure invocation expression can be any Scheme expression whose value
-is a procedure. But that's exactly what a lambda expression is! So we
-can use a lambda expression directly in a procedure invocation, like
-this:
-
-@lisp
-((lambda (name address)
- (string-append "Name=" name ":Address=" address))
- "FSF"
- "Cambridge")
-@end lisp
-
-@noindent
-This is a valid procedure invocation expression, and its result is the
-string @code{"Name=FSF:Address=Cambridge"}.
-
-It it more common, though, to store the procedure value in a variable ---
-
-@lisp
-(define make-combined-string
- (lambda (name address)
- (string-append "Name=" name ":Address=" address)))
-@end lisp
-
-@noindent
---- and then to use the variable name in the procedure invocation:
-
-@lisp
-(make-combined-string "FSF" "Cambridge")
-@end lisp
-
-@noindent
-Which has exactly the same result.
-
-It's important to note that procedures created using @code{lambda} have
-exactly the same status as the standard built in Scheme procedures, and
-can be invoked, passed around, and stored in variables in exactly the
-same ways.
-
-
-@node Lambda Alternatives
-@subsection Lambda Alternatives
-
-Since it is so common in Scheme programs to want to create a procedure
-and then store it in a variable, there is an alternative form of the
-@code{define} syntax that allows you to do just that.
-
-A @code{define} expression of the form
-
-@lisp
-(define (@var{name} [@var{arg1} [@var{arg2} @dots{}]])
- @var{expression} @dots{})
-@end lisp
-
-@noindent
-is exactly equivalent to the longer form
-
-@lisp
-(define @var{name}
- (lambda ([@var{arg1} [@var{arg2} @dots{}]])
- @var{expression} @dots{}))
-@end lisp
-
-So, for example, the definition of @code{make-combined-string} in the
-previous subsection could equally be written:
-
-@lisp
-(define (make-combined-string name address)
- (string-append "Name=" name ":Address=" address))
-@end lisp
-
-This kind of procedure definition creates a procedure that requires
-exactly the expected number of arguments. There are two further forms
-of the @code{lambda} expression, which create a procedure that can
-accept a variable number of arguments:
-
-@lisp
-(lambda (@var{arg1} @dots{} . @var{args}) @var{expression} @dots{})
-
-(lambda @var{args} @var{expression} @dots{})
-@end lisp
-
-@noindent
-The corresponding forms of the alternative @code{define} syntax are:
-
-@lisp
-(define (@var{name} @var{arg1} @dots{} . @var{args}) @var{expression} @dots{})
-
-(define (@var{name} . @var{args}) @var{expression} @dots{})
-@end lisp
-
-@noindent
-For details on how these forms work, see @xref{Lambda}.
-
-(It could be argued that the alternative @code{define} forms are rather
-confusing, especially for newcomers to the Scheme language, as they hide
-both the role of @code{lambda} and the fact that procedures are values
-that are stored in variables in the some way as any other kind of value.
-On the other hand, they are very convenient, and they are also a good
-example of another of Scheme's powerful features: the ability to specify
-arbitrary syntactic transformations at run time, which can be applied to
-subsequently read input.)
-
-
-@node About Expressions
-@section Expressions and Evaluation
-
-So far, we have met expressions that @emph{do} things, such as the
-@code{define} expressions that create and initialize new variables, and
-we have also talked about expressions that have @emph{values}, for
-example the value of the procedure invocation expression:
-
-@lisp
-(string-append "/home" "/" "andrew")
-@end lisp
-
-@noindent
-but we haven't yet been precise about what causes an expression like
-this procedure invocation to be reduced to its ``value'', or how the
-processing of such expressions relates to the execution of a Scheme
-program as a whole.
-
-This section clarifies what we mean by an expression's value, by
-introducing the idea of @dfn{evaluation}. It discusses the side effects
-that evaluation can have, explains how each of the various types of
-Scheme expression is evaluated, and describes the behaviour and use of
-the Guile REPL as a mechanism for exploring evaluation. The section
-concludes with a very brief summary of Scheme's common syntactic
-expressions.
-
-@menu
-* Evaluating:: How a Scheme program is executed.
-* The REPL:: Interacting with the Guile interpreter.
-* Syntax Summary:: Common syntactic expressions -- in brief.
-@end menu
-
-
-@node Evaluating
-@subsection Evaluating Expressions and Executing Programs
-
-In Scheme, the process of executing an expression is known as
-@dfn{evaluation}. Evaluation has two kinds of result:
-
-@itemize @bullet
-@item
-the @dfn{value} of the evaluated expression
-
-@item
-the @dfn{side effects} of the evaluation, which consist of any effects of
-evaluating the expression that are not represented by the value.
-@end itemize
-
-Of the expressions that we have met so far, @code{define} and
-@code{set!} expressions have side effects --- the creation or
-modification of a variable --- but no value; @code{lambda} expressions
-have values --- the newly constructed procedures --- but no side
-effects; and procedure invocation expressions, in general, have either
-values, or side effects, or both.
-
-It is tempting to try to define more intuitively what we mean by
-``value'' and ``side effects'', and what the difference between them is.
-In general, though, this is extremely difficult. It is also
-unnecessary; instead, we can quite happily define the behaviour of a
-Scheme program by specifying how Scheme executes a program as a whole,
-and then by describing the value and side effects of evaluation for each
-type of expression individually.
-
-@noindent
-So, some@footnote{These definitions are approximate. For the whole and
-detailed truth, see @xref{Formal syntax and semantics,R5RS
-syntax,,r5rs}.} definitions@dots{}
-
-@itemize @bullet
-
-@item
-A Scheme program consists of a sequence of expressions.
-
-@item
-A Scheme interpreter executes the program by evaluating these
-expressions in order, one by one.
-
-@item
-An expression can be
-
-@itemize @bullet
-@item
-a piece of literal data, such as a number @code{2.3} or a string
-@code{"Hello world!"}
-@item
-a variable name
-@item
-a procedure invocation expression
-@item
-one of Scheme's special syntactic expressions.
-@end itemize
-@end itemize
-
-@noindent
-The following subsections describe how each of these types of expression
-is evaluated.
-
-@menu
-* Eval Literal:: Evaluating literal data.
-* Eval Variable:: Evaluating variable references.
-* Eval Procedure:: Evaluating procedure invocation expressions.
-* Eval Special:: Evaluating special syntactic expressions.
-@end menu
-
-@node Eval Literal
-@subsubsection Evaluating Literal Data
-
-When a literal data expression is evaluated, the value of the expression
-is simply the value that the expression describes. The evaluation of a
-literal data expression has no side effects.
-
-@noindent
-So, for example,
-
-@itemize @bullet
-@item
-the value of the expression @code{"abc"} is the string value
-@code{"abc"}
-
-@item
-the value of the expression @code{3+4i} is the complex number 3 + 4i
-
-@item
-the value of the expression @code{#(1 2 3)} is a three-element vector
-containing the numeric values 1, 2 and 3.
-@end itemize
-
-For any data type which can be expressed literally like this, the syntax
-of the literal data expression for that data type --- in other words,
-what you need to write in your code to indicate a literal value of that
-type --- is known as the data type's @dfn{read syntax}. This manual
-specifies the read syntax for each such data type in the section that
-describes that data type.
-
-Some data types do not have a read syntax. Procedures, for example,
-cannot be expressed as literal data; they must be created using a
-@code{lambda} expression (@pxref{Creating a Procedure}) or implicitly
-using the shorthand form of @code{define} (@pxref{Lambda Alternatives}).
-
-
-@node Eval Variable
-@subsubsection Evaluating a Variable Reference
-
-When an expression that consists simply of a variable name is evaluated,
-the value of the expression is the value of the named variable. The
-evaluation of a variable reference expression has no side effects.
-
-So, after
-
-@lisp
-(define key "Paul Evans")
-@end lisp
-
-@noindent
-the value of the expression @code{key} is the string value @code{"Paul
-Evans"}. If @var{key} is then modified by
-
-@lisp
-(set! key 3.74)
-@end lisp
-
-@noindent
-the value of the expression @code{key} is the numeric value 3.74.
-
-If there is no variable with the specified name, evaluation of the
-variable reference expression signals an error.
-
-
-@node Eval Procedure
-@subsubsection Evaluating a Procedure Invocation Expression
-
-This is where evaluation starts getting interesting! As already noted,
-a procedure invocation expression has the form
-
-@lisp
-(@var{procedure} [@var{arg1} [@var{arg2} @dots{}]])
-@end lisp
-
-@noindent
-where @var{procedure} must be an expression whose value, when evaluated,
-is a procedure.
-
-The evaluation of a procedure invocation expression like this proceeds
-by
-
-@itemize @bullet
-@item
-evaluating individually the expressions @var{procedure}, @var{arg1},
-@var{arg2}, and so on
-
-@item
-calling the procedure that is the value of the @var{procedure}
-expression with the list of values obtained from the evaluations of
-@var{arg1}, @var{arg2} etc. as its parameters.
-@end itemize
-
-For a procedure defined in Scheme, ``calling the procedure with the list
-of values as its parameters'' means binding the values to the
-procedure's formal parameters and then evaluating the sequence of
-expressions that make up the body of the procedure definition. The
-value of the procedure invocation expression is the value of the last
-evaluated expression in the procedure body. The side effects of calling
-the procedure are the combination of the side effects of the sequence of
-evaluations of expressions in the procedure body.
-
-For a built-in procedure, the value and side-effects of calling the
-procedure are best described by that procedure's documentation.
-
-Note that the complete side effects of evaluating a procedure invocation
-expression consist not only of the side effects of the procedure call,
-but also of any side effects of the preceding evaluation of the
-expressions @var{procedure}, @var{arg1}, @var{arg2}, and so on.
-
-To illustrate this, let's look again at the procedure invocation
-expression:
-
-@lisp
-(string-length (string-append "/home" "/" "andrew"))
-@end lisp
-
-In the outermost expression, @var{procedure} is @code{string-length} and
-@var{arg1} is @code{(string-append "/home" "/" "andrew")}.
-
-@itemize @bullet
-@item
-Evaluation of @code{string-length}, which is a variable, gives a
-procedure value that implements the expected behaviour for
-``string-length''.
-
-@item
-Evaluation of @code{(string-append "/home" "/" "andrew")}, which is
-another procedure invocation expression, means evaluating each of
-
-@itemize @bullet
-@item
-@code{string-append}, which gives a procedure value that implements the
-expected behaviour for ``string-append''
-
-@item
-@code{"/home"}, which gives the string value @code{"/home"}
-
-@item
-@code{"/"}, which gives the string value @code{"/"}
-
-@item
-@code{"andrew"}, which gives the string value @code{"andrew"}
-@end itemize
-
-and then invoking the procedure value with this list of string values as
-its arguments. The resulting value is a single string value that is the
-concatenation of all the arguments, namely @code{"/home/andrew"}.
-@end itemize
-
-In the evaluation of the outermost expression, the interpreter can now
-invoke the procedure value obtained from @var{procedure} with the value
-obtained from @var{arg1} as its arguments. The resulting value is a
-numeric value that is the length of the argument string, which is 12.
-
-
-@node Eval Special
-@subsubsection Evaluating Special Syntactic Expressions
-
-When a procedure invocation expression is evaluated, the procedure and
-@emph{all} the argument expressions must be evaluated before the
-procedure can be invoked. Special syntactic expressions are special
-because they are able to manipulate their arguments in an unevaluated
-form, and can choose whether to evaluate any or all of the argument
-expressions.
-
-Why is this needed? Consider a program fragment that asks the user
-whether or not to delete a file, and then deletes the file if the user
-answers yes.
-
-@lisp
-(if (string=? (read-answer "Should I delete this file?")
- "yes")
- (delete-file file))
-@end lisp
-
-If the outermost @code{(if @dots{})} expression here was a procedure
-invocation expression, the expression @code{(delete-file file)}, whose
-side effect is to actually delete a file, would already have been
-evaluated before the @code{if} procedure even got invoked! Clearly this
-is no use --- the whole point of an @code{if} expression is that the
-@dfn{consequent} expression is only evaluated if the condition of the
-@code{if} expression is ``true''.
-
-Therefore @code{if} must be special syntax, not a procedure. Other
-special syntaxes that we have already met are @code{define}, @code{set!}
-and @code{lambda}. @code{define} and @code{set!} are syntax because
-they need to know the variable @emph{name} that is given as the first
-argument in a @code{define} or @code{set!} expression, not that
-variable's value. @code{lambda} is syntax because it does not
-immediately evaluate the expressions that define the procedure body;
-instead it creates a procedure object that incorporates these
-expressions so that they can be evaluated in the future, when that
-procedure is invoked.
-
-The rules for evaluating each special syntactic expression are specified
-individually for each special syntax. For a summary of standard special
-syntax, see @xref{Syntax Summary}.
-
-
-@node The REPL
-@subsection Using the Guile REPL
-
-If you start Guile without specifying a particular program for it to
-execute, Guile enters its standard Read Evaluate Print Loop --- or
-@dfn{REPL} for short. In this mode, Guile repeatedly reads in the next
-Scheme expression that the user types, evaluates it, and prints the
-resulting value.
-
-The REPL is a useful mechanism for exploring the evaluation behaviour
-described in the previous subsection. If you type @code{string-append},
-for example, the REPL replies @code{#<primitive-procedure
-string-append>}, illustrating the relationship between the variable
-@code{string-append} and the procedure value stored in that variable.
-
-In this manual, the notation @result{} is used to mean ``evaluates
-to''. Wherever you see an example of the form
-
-@lisp
-@var{expression}
-@result{}
-@var{result}
-@end lisp
-
-@noindent
-feel free to try it out yourself by typing @var{expression} into the
-REPL and checking that it gives the expected @var{result}.
-
-
-@node Syntax Summary
-@subsection Summary of Common Syntax
-
-This subsection lists the most commonly used Scheme syntactic
-expressions, simply so that you will recognize common special syntax
-when you see it. For a full description of each of these syntaxes,
-follow the appropriate reference.
-
-@code{lambda} (@pxref{Lambda}) is used to construct procedure objects.
-
-@code{define} (@pxref{Top Level}) is used to create a new variable and
-set its initial value.
-
-@code{set!} (@pxref{Top Level}) is used to modify an existing variable's
-value.
-
-@code{let}, @code{let*} and @code{letrec} (@pxref{Local Bindings})
-create an inner lexical environment for the evaluation of a sequence of
-expressions, in which a specified set of local variables is bound to the
-values of a corresponding set of expressions. For an introduction to
-environments, see @xref{About Closure}.
-
-@code{begin} (@pxref{begin}) executes a sequence of expressions in order
-and returns the value of the last expression. Note that this is not the
-same as a procedure which returns its last argument, because the
-evaluation of a procedure invocation expression does not guarantee to
-evaluate the arguments in order.
-
-@code{if} and @code{cond} (@pxref{if cond case}) provide conditional
-evaluation of argument expressions depending on whether one or more
-conditions evaluate to ``true'' or ``false''.
-
-@code{case} (@pxref{if cond case}) provides conditional evaluation of
-argument expressions depending on whether a variable has one of a
-specified group of values.
-
-@code{and} (@pxref{and or}) executes a sequence of expressions in order
-until either there are no expressions left, or one of them evaluates to
-``false''.
-
-@code{or} (@pxref{and or}) executes a sequence of expressions in order
-until either there are no expressions left, or one of them evaluates to
-``true''.
-
-
-@node About Closure
-@section The Concept of Closure
-
-@cindex closure
-
-The concept of @dfn{closure} is the idea that a lambda expression
-``captures'' the variable bindings that are in lexical scope at the
-point where the lambda expression occurs. The procedure created by the
-lambda expression can refer to and mutate the captured bindings, and the
-values of those bindings persist between procedure calls.
-
-This section explains and explores the various parts of this idea in
-more detail.
-
-@menu
-* About Environments:: Names, locations, values and environments.
-* Local Variables:: Local variables and local environments.
-* Chaining:: Environment chaining.
-* Lexical Scope:: The meaning of lexical scoping.
-* Closure:: Explaining the concept of closure.
-* Serial Number:: Example 1: a serial number generator.
-* Shared Variable:: Example 2: a shared persistent variable.
-* Callback Closure:: Example 3: the callback closure problem.
-* OO Closure:: Example 4: object orientation.
-@end menu
-
-@node About Environments
-@subsection Names, Locations, Values and Environments
-
-@cindex location
-@cindex environment
-@cindex vcell
-@cindex top level environment
-@cindex environment, top level
-
-We said earlier that a variable name in a Scheme program is associated
-with a location in which any kind of Scheme value may be stored.
-(Incidentally, the term ``vcell'' is often used in Lisp and Scheme
-circles as an alternative to ``location''.) Thus part of what we mean
-when we talk about ``creating a variable'' is in fact establishing an
-association between a name, or identifier, that is used by the Scheme
-program code, and the variable location to which that name refers.
-Although the value that is stored in that location may change, the
-location to which a given name refers is always the same.
-
-We can illustrate this by breaking down the operation of the
-@code{define} syntax into three parts: @code{define}
-
-@itemize @bullet
-@item
-creates a new location
-
-@item
-establishes an association between that location and the name specified
-as the first argument of the @code{define} expression
-
-@item
-stores in that location the value obtained by evaluating the second
-argument of the @code{define} expression.
-@end itemize
-
-A collection of associations between names and locations is called an
-@dfn{environment}. When you create a top level variable in a program
-using @code{define}, the name-location association for that variable is
-added to the ``top level'' environment. The ``top level'' environment
-also includes name-location associations for all the procedures that are
-supplied by standard Scheme.
-
-It is also possible to create environments other than the top level one,
-and to create variable bindings, or name-location associations, in those
-environments. This ability is a key ingredient in the concept of
-closure; the next subsection shows how it is done.
-
-
-@node Local Variables
-@subsection Local Variables and Environments
-
-@cindex local variable
-@cindex variable, local
-@cindex local environment
-@cindex environment, local
-
-We have seen how to create top level variables using the @code{define}
-syntax (@pxref{Definition}). It is often useful to create variables
-that are more limited in their scope, typically as part of a procedure
-body. In Scheme, this is done using the @code{let} syntax, or one of
-its modified forms @code{let*} and @code{letrec}. These syntaxes are
-described in full later in the manual (@pxref{Local Bindings}). Here
-our purpose is to illustrate their use just enough that we can see how
-local variables work.
-
-For example, the following code uses a local variable @code{s} to
-simplify the computation of the area of a triangle given the lengths of
-its three sides.
-
-@lisp
-(define a 5.3)
-(define b 4.7)
-(define c 2.8)
-
-(define area
- (let ((s (/ (+ a b c) 2)))
- (sqrt (* s (- s a) (- s b) (- s c)))))
-@end lisp
-
-The effect of the @code{let} expression is to create a new environment
-and, within this environment, an association between the name @code{s}
-and a new location whose initial value is obtained by evaluating
-@code{(/ (+ a b c) 2)}. The expressions in the body of the @code{let},
-namely @code{(sqrt (* s (- s a) (- s b) (- s c)))}, are then evaluated
-in the context of the new environment, and the value of the last
-expression evaluated becomes the value of the whole @code{let}
-expression, and therefore the value of the variable @code{area}.
-
-
-@node Chaining
-@subsection Environment Chaining
-
-@cindex shadowing an imported variable binding
-@cindex chaining environments
-
-In the example of the previous subsection, we glossed over an important
-point. The body of the @code{let} expression in that example refers not
-only to the local variable @code{s}, but also to the top level variables
-@code{a}, @code{b}, @code{c} and @code{sqrt}. (@code{sqrt} is the
-standard Scheme procedure for calculating a square root.) If the body
-of the @code{let} expression is evaluated in the context of the
-@emph{local} @code{let} environment, how does the evaluation get at the
-values of these top level variables?
-
-The answer is that the local environment created by a @code{let}
-expression automatically has a reference to its containing environment
---- in this case the top level environment --- and that the Scheme
-interpreter automatically looks for a variable binding in the containing
-environment if it doesn't find one in the local environment. More
-generally, every environment except for the top level one has a
-reference to its containing environment, and the interpreter keeps
-searching back up the chain of environments --- from most local to top
-level --- until it either finds a variable binding for the required
-identifier or exhausts the chain.
-
-This description also determines what happens when there is more than
-one variable binding with the same name. Suppose, continuing the
-example of the previous subsection, that there was also a pre-existing
-top level variable @code{s} created by the expression:
-
-@lisp
-(define s "Some beans, my lord!")
-@end lisp
-
-Then both the top level environment and the local @code{let} environment
-would contain bindings for the name @code{s}. When evaluating code
-within the @code{let} body, the interpreter looks first in the local
-@code{let} environment, and so finds the binding for @code{s} created by
-the @code{let} syntax. Even though this environment has a reference to
-the top level environment, which also has a binding for @code{s}, the
-interpreter doesn't get as far as looking there. When evaluating code
-outside the @code{let} body, the interpreter looks up variable names in
-the top level environment, so the name @code{s} refers to the top level
-variable.
-
-Within the @code{let} body, the binding for @code{s} in the local
-environment is said to @dfn{shadow} the binding for @code{s} in the top
-level environment.
-
-
-@node Lexical Scope
-@subsection Lexical Scope
-
-The rules that we have just been describing are the details of how
-Scheme implements ``lexical scoping''. This subsection takes a brief
-diversion to explain what lexical scope means in general and to present
-an example of non-lexical scoping.
-
-``Lexical scope'' in general is the idea that
-
-@itemize @bullet
-@item
-an identifier at a particular place in a program always refers to the
-same variable location --- where ``always'' means ``every time that the
-containing expression is executed'', and that
-
-@item
-the variable location to which it refers can be determined by static
-examination of the source code context in which that identifier appears,
-without having to consider the flow of execution through the program as
-a whole.
-@end itemize
-
-In practice, lexical scoping is the norm for most programming languages,
-and probably corresponds to what you would intuitively consider to be
-``normal''. You may even be wondering how the situation could possibly
---- and usefully --- be otherwise. To demonstrate that another kind of
-scoping is possible, therefore, and to compare it against lexical
-scoping, the following subsection presents an example of non-lexical
-scoping and examines in detail how its behavior differs from the
-corresponding lexically scoped code.
-
-@menu
-* Scoping Example:: An example of non-lexical scoping.
-@end menu
-
-
-@node Scoping Example
-@subsubsection An Example of Non-Lexical Scoping
-
-To demonstrate that non-lexical scoping does exist and can be useful, we
-present the following example from Emacs Lisp, which is a ``dynamically
-scoped'' language.
-
-@lisp
-(defvar currency-abbreviation "USD")
-
-(defun currency-string (units hundredths)
- (concat currency-abbreviation
- (number-to-string units)
- "."
- (number-to-string hundredths)))
-
-(defun french-currency-string (units hundredths)
- (let ((currency-abbreviation "FRF"))
- (currency-string units hundredths)))
-@end lisp
-
-The question to focus on here is: what does the identifier
-@code{currency-abbreviation} refer to in the @code{currency-string}
-function? The answer, in Emacs Lisp, is that all variable bindings go
-onto a single stack, and that @code{currency-abbreviation} refers to the
-topmost binding from that stack which has the name
-``currency-abbreviation''. The binding that is created by the
-@code{defvar} form, to the value @code{"USD"}, is only relevant if none
-of the code that calls @code{currency-string} rebinds the name
-``currency-abbreviation'' in the meanwhile.
-
-The second function @code{french-currency-string} works precisely by
-taking advantage of this behaviour. It creates a new binding for the
-name ``currency-abbreviation'' which overrides the one established by
-the @code{defvar} form.
-
-@lisp
-;; Note! This is Emacs Lisp evaluation, not Scheme!
-(french-currency-string 33 44)
-@result{}
-"FRF33.44"
-@end lisp
-
-Now let's look at the corresponding, @emph{lexically scoped} Scheme
-code:
-
-@lisp
-(define currency-abbreviation "USD")
-
-(define (currency-string units hundredths)
- (string-append currency-abbreviation
- (number->string units)
- "."
- (number->string hundredths)))
-
-(define (french-currency-string units hundredths)
- (let ((currency-abbreviation "FRF"))
- (currency-string units hundredths)))
-@end lisp
-
-According to the rules of lexical scoping, the
-@code{currency-abbreviation} in @code{currency-string} refers to the
-variable location in the innermost environment at that point in the code
-which has a binding for @code{currency-abbreviation}, which is the
-variable location in the top level environment created by the preceding
-@code{(define currency-abbreviation @dots{})} expression.
-
-In Scheme, therefore, the @code{french-currency-string} procedure does
-not work as intended. The variable binding that it creates for
-``currency-abbreviation'' is purely local to the code that forms the
-body of the @code{let} expression. Since this code doesn't directly use
-the name ``currency-abbreviation'' at all, the binding is pointless.
-
-@lisp
-(french-currency-string 33 44)
-@result{}
-"USD33.44"
-@end lisp
-
-This begs the question of how the Emacs Lisp behaviour can be
-implemented in Scheme. In general, this is a design question whose
-answer depends upon the problem that is being addressed. In this case,
-the best answer may be that @code{currency-string} should be
-redesigned so that it can take an optional third argument. This third
-argument, if supplied, is interpreted as a currency abbreviation that
-overrides the default.
-
-It is possible to change @code{french-currency-string} so that it mostly
-works without changing @code{currency-string}, but the fix is inelegant,
-and susceptible to interrupts that could leave the
-@code{currency-abbreviation} variable in the wrong state:
-
-@lisp
-(define (french-currency-string units hundredths)
- (set! currency-abbreviation "FRF")
- (let ((result (currency-string units hundredths)))
- (set! currency-abbreviation "USD")
- result))
-@end lisp
-
-The key point here is that the code does not create any local binding
-for the identifier @code{currency-abbreviation}, so all occurrences of
-this identifier refer to the top level variable.
-
-
-@node Closure
-@subsection Closure
-
-Consider a @code{let} expression that doesn't contain any
-@code{lambda}s:
-
-@lisp
-(let ((s (/ (+ a b c) 2)))
- (sqrt (* s (- s a) (- s b) (- s c))))
-@end lisp
-
-@noindent
-When the Scheme interpreter evaluates this, it
-
-@itemize @bullet
-@item
-creates a new environment with a reference to the environment that was
-current when it encountered the @code{let}
-
-@item
-creates a variable binding for @code{s} in the new environment, with
-value given by @code{(/ (+ a b c) 2)}
-
-@item
-evaluates the expression in the body of the @code{let} in the context of
-the new local environment, and remembers the value @code{V}
-
-@item
-forgets the local environment
-
-@item
-continues evaluating the expression that contained the @code{let}, using
-the value @code{V} as the value of the @code{let} expression, in the
-context of the containing environment.
-@end itemize
-
-After the @code{let} expression has been evaluated, the local
-environment that was created is simply forgotten, and there is no longer
-any way to access the binding that was created in this environment. If
-the same code is evaluated again, it will follow the same steps again,
-creating a second new local environment that has no connection with the
-first, and then forgetting this one as well.
-
-If the @code{let} body contains a @code{lambda} expression, however, the
-local environment is @emph{not} forgotten. Instead, it becomes
-associated with the procedure that is created by the @code{lambda}
-expression, and is reinstated every time that that procedure is called.
-In detail, this works as follows.
-
-@itemize @bullet
-@item
-When the Scheme interpreter evaluates a @code{lambda} expression, to
-create a procedure object, it stores the current environment as part of
-the procedure definition.
-
-@item
-Then, whenever that procedure is called, the interpreter reinstates the
-environment that is stored in the procedure definition and evaluates the
-procedure body within the context of that environment.
-@end itemize
-
-The result is that the procedure body is always evaluated in the context
-of the environment that was current when the procedure was created.
-
-This is what is meant by @dfn{closure}. The next few subsections
-present examples that explore the usefulness of this concept.
-
-
-@node Serial Number
-@subsection Example 1: A Serial Number Generator
-
-This example uses closure to create a procedure with a variable binding
-that is private to the procedure, like a local variable, but whose value
-persists between procedure calls.
-
-@lisp
-(define (make-serial-number-generator)
- (let ((current-serial-number 0))
- (lambda ()
- (set! current-serial-number (+ current-serial-number 1))
- current-serial-number)))
-
-(define entry-sn-generator (make-serial-number-generator))
-
-(entry-sn-generator)
-@result{}
-1
-
-(entry-sn-generator)
-@result{}
-2
-@end lisp
-
-When @code{make-serial-number-generator} is called, it creates a local
-environment with a binding for @code{current-serial-number} whose
-initial value is 0, then, within this environment, creates a procedure.
-The local environment is stored within the created procedure object and
-so persists for the lifetime of the created procedure.
-
-Every time the created procedure is invoked, it increments the value of
-the @code{current-serial-number} binding in the captured environment and
-then returns the current value.
-
-Note that @code{make-serial-number-generator} can be called again to
-create a second serial number generator that is independent of the
-first. Every new invocation of @code{make-serial-number-generator}
-creates a new local @code{let} environment and returns a new procedure
-object with an association to this environment.
-
-
-@node Shared Variable
-@subsection Example 2: A Shared Persistent Variable
-
-This example uses closure to create two procedures, @code{get-balance}
-and @code{deposit}, that both refer to the same captured local
-environment so that they can both access the @code{balance} variable
-binding inside that environment. The value of this variable binding
-persists between calls to either procedure.
-
-Note that the captured @code{balance} variable binding is private to
-these two procedures: it is not directly accessible to any other code.
-It can only be accessed indirectly via @code{get-balance} or
-@code{deposit}, as illustrated by the @code{withdraw} procedure.
-
-@lisp
-(define get-balance #f)
-(define deposit #f)
-
-(let ((balance 0))
- (set! get-balance
- (lambda ()
- balance))
- (set! deposit
- (lambda (amount)
- (set! balance (+ balance amount))
- balance)))
-
-(define (withdraw amount)
- (deposit (- amount)))
-
-(get-balance)
-@result{}
-0
-
-(deposit 50)
-@result{}
-50
-
-(withdraw 75)
-@result{}
--25
-@end lisp
-
-An important detail here is that the @code{get-balance} and
-@code{deposit} variables must be set up by @code{define}ing them at top
-level and then @code{set!}ing their values inside the @code{let} body.
-Using @code{define} within the @code{let} body would not work: this
-would create variable bindings within the local @code{let} environment
-that would not be accessible at top level.
-
-
-@node Callback Closure
-@subsection Example 3: The Callback Closure Problem
-
-A frequently used programming model for library code is to allow an
-application to register a callback function for the library to call when
-some particular event occurs. It is often useful for the application to
-make several such registrations using the same callback function, for
-example if several similar library events can be handled using the same
-application code, but the need then arises to distinguish the callback
-function calls that are associated with one callback registration from
-those that are associated with different callback registrations.
-
-In languages without the ability to create functions dynamically, this
-problem is usually solved by passing a @code{user_data} parameter on the
-registration call, and including the value of this parameter as one of
-the parameters on the callback function. Here is an example of
-declarations using this solution in C:
-
-@example
-typedef void (event_handler_t) (int event_type,
- void *user_data);
-
-void register_callback (int event_type,
- event_handler_t *handler,
- void *user_data);
-@end example
-
-In Scheme, closure can be used to achieve the same functionality without
-requiring the library code to store a @code{user-data} for each callback
-registration.
-
-@lisp
-;; In the library:
-
-(define (register-callback event-type handler-proc)
- @dots{})
-
-;; In the application:
-
-(define (make-handler event-type user-data)
- (lambda ()
- @dots{}
- <code referencing event-type and user-data>
- @dots{}))
-
-(register-callback event-type
- (make-handler event-type @dots{}))
-@end lisp
-
-As far as the library is concerned, @code{handler-proc} is a procedure
-with no arguments, and all the library has to do is call it when the
-appropriate event occurs. From the application's point of view, though,
-the handler procedure has used closure to capture an environment that
-includes all the context that the handler code needs ---
-@code{event-type} and @code{user-data} --- to handle the event
-correctly.
-
-
-@node OO Closure
-@subsection Example 4: Object Orientation
-
-Closure is the capture of an environment, containing persistent variable
-bindings, within the definition of a procedure or a set of related
-procedures. This is rather similar to the idea in some object oriented
-languages of encapsulating a set of related data variables inside an
-``object'', together with a set of ``methods'' that operate on the
-encapsulated data. The following example shows how closure can be used
-to emulate the ideas of objects, methods and encapsulation in Scheme.
-
-@lisp
-(define (make-account)
- (let ((balance 0))
- (define (get-balance)
- balance)
- (define (deposit amount)
- (set! balance (+ balance amount))
- balance)
- (define (withdraw amount)
- (deposit (- amount)))
-
- (lambda args
- (apply
- (case (car args)
- ((get-balance) get-balance)
- ((deposit) deposit)
- ((withdraw) withdraw)
- (else (error "Invalid method!")))
- (cdr args)))))
-@end lisp
-
-Each call to @code{make-account} creates and returns a new procedure,
-created by the expression in the example code that begins ``(lambda
-args''.
-
-@lisp
-(define my-account (make-account))
-
-my-account
-@result{}
-#<procedure args>
-@end lisp
-
-This procedure acts as an account object with methods
-@code{get-balance}, @code{deposit} and @code{withdraw}. To apply one of
-the methods to the account, you call the procedure with a symbol
-indicating the required method as the first parameter, followed by any
-other parameters that are required by that method.
-
-@lisp
-(my-account 'get-balance)
-@result{}
-0
-
-(my-account 'withdraw 5)
-@result{}
--5
-
-(my-account 'deposit 396)
-@result{}
-391
-
-(my-account 'get-balance)
-@result{}
-391
-@end lisp
-
-Note how, in this example, both the current balance and the helper
-procedures @code{get-balance}, @code{deposit} and @code{withdraw}, used
-to implement the guts of the account object's methods, are all stored in
-variable bindings within the private local environment captured by the
-@code{lambda} expression that creates the account object procedure.
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-indices.texi b/doc/ref/scheme-indices.texi
deleted file mode 100644
index acecb3ff4..000000000
--- a/doc/ref/scheme-indices.texi
+++ /dev/null
@@ -1,10 +0,0 @@
-@page
-@node R5RS Index
-@unnumbered R5RS Index
-
-@printindex rn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-intro.texi b/doc/ref/scheme-intro.texi
deleted file mode 100644
index 22e875339..000000000
--- a/doc/ref/scheme-intro.texi
+++ /dev/null
@@ -1,36 +0,0 @@
-@page
-@node Guile Scheme
-@chapter Guile's Implementation of Scheme
-
-Guile's core language is Scheme, which is specified and described in the
-series of reports known as @dfn{RnRS}. @dfn{RnRS} is shorthand for the
-@iftex
-@dfn{Revised$^n$ Report on the Algorithmic Language Scheme}.
-@end iftex
-@ifnottex
-@dfn{Revised^n Report on the Algorithmic Language Scheme}.
-@end ifnottex
-The current latest revision of RnRS is version 5
-(@pxref{Top,R5RS,,r5rs}), and Guile 1.4 is fully compliant with the
-Scheme specification in this revision.
-
-But Guile, like most Scheme implementations, also goes beyond R5RS in
-many ways, because R5RS does not give specifications (or even
-recommendations) regarding many issues that are important in practical
-programming. Some of the areas where Guile extends R5RS are:
-
-@itemize @bullet
-@item
-Guile's interactive documentation system
-
-@item
-Guile's support for POSIX-compliant network programming
-
-@item
-GOOPS -- Guile's framework for object oriented programming.
-@end itemize
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-io.texi b/doc/ref/scheme-io.texi
deleted file mode 100644
index 3df790051..000000000
--- a/doc/ref/scheme-io.texi
+++ /dev/null
@@ -1,1116 +0,0 @@
-@page
-@node Input and Output
-@chapter Input and Output
-
-@menu
-* Ports:: The idea of the port abstraction.
-* Reading:: Procedures for reading from a port.
-* Writing:: Procedures for writing to a port.
-* Closing:: Procedures to close a port.
-* Random Access:: Moving around a random access port.
-* Line/Delimited:: Read and write lines or delimited text.
-* Block Reading and Writing:: Reading and writing blocks of text.
-* Default Ports:: Defaults for input, output and errors.
-* Port Types:: Types of port and how to make them.
-* I/O Extensions:: Using and extending ports in C.
-@end menu
-
-
-@node Ports
-@section Ports
-
-[Concept of the port abstraction.]
-
-Sequential input/output in Scheme is represented by operations on a
-@dfn{port}. Characters can be read from an input port and
-written to an output port. This chapter explains the operations
-that Guile provides for working with ports.
-
-The formal definition of a port is very generic: an input port is
-simply ``an object which can deliver characters on command,'' and
-an output port is ``an object which can accept characters.''
-Because this definition is so loose, it is easy to write functions
-that simulate ports in software. @dfn{Soft ports} and @dfn{string
-ports} are two interesting and powerful examples of this technique.
-
-@rnindex input-port?
-@deffn {Scheme Procedure} input-port? x
-@deffnx {C Function} scm_input_port_p (x)
-Return @code{#t} if @var{x} is an input port, otherwise return
-@code{#f}. Any object satisfying this predicate also satisfies
-@code{port?}.
-@end deffn
-
-@rnindex output-port?
-@deffn {Scheme Procedure} output-port? x
-@deffnx {C Function} scm_output_port_p (x)
-Return @code{#t} if @var{x} is an output port, otherwise return
-@code{#f}. Any object satisfying this predicate also satisfies
-@code{port?}.
-@end deffn
-
-@deffn {Scheme Procedure} port? x
-@deffnx {C Function} scm_port_p (x)
-Return a boolean indicating whether @var{x} is a port.
-Equivalent to @code{(or (input-port? @var{x}) (output-port?
-@var{x}))}.
-@end deffn
-
-
-@node Reading
-@section Reading
-
-[Generic procedures for reading from ports.]
-
-@rnindex eof-object?
-@deffn {Scheme Procedure} eof-object? x
-@deffnx {C Function} scm_eof_object_p (x)
-Return @code{#t} if @var{x} is an end-of-file object; otherwise
-return @code{#f}.
-@end deffn
-
-@rnindex char-ready?
-@deffn {Scheme Procedure} char-ready? [port]
-@deffnx {C Function} scm_char_ready_p (port)
-Return @code{#t} if a character is ready on input @var{port}
-and return @code{#f} otherwise. If @code{char-ready?} returns
-@code{#t} then the next @code{read-char} operation on
-@var{port} is guaranteed not to hang. If @var{port} is a file
-port at end of file then @code{char-ready?} returns @code{#t}.
-@footnote{@code{char-ready?} exists to make it possible for a
-program to accept characters from interactive ports without
-getting stuck waiting for input. Any input editors associated
-with such ports must make sure that characters whose existence
-has been asserted by @code{char-ready?} cannot be rubbed out.
-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.}
-@end deffn
-
-@rnindex read-char?
-@deffn {Scheme Procedure} read-char [port]
-@deffnx {C Function} scm_read_char (port)
-Return the next character available from @var{port}, updating
-@var{port} to point to the following character. If no more
-characters are available, the end-of-file object is returned.
-@end deffn
-
-@rnindex peek-char?
-@deffn {Scheme Procedure} peek-char [port]
-@deffnx {C Function} scm_peek_char (port)
-Return the next character available from @var{port},
-@emph{without} updating @var{port} to point to the following
-character. If no more characters are available, the
-end-of-file object is returned.@footnote{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} on the same
-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.}
-@end deffn
-
-@deffn {Scheme Procedure} unread-char cobj [port]
-@deffnx {C Function} scm_unread_char (cobj, port)
-Place @var{char} in @var{port} so that it will be read by the
-next read operation. If called multiple times, the unread characters
-will be read again in last-in first-out order. If @var{port} is
-not supplied, the current input port is used.
-@end deffn
-
-@deffn {Scheme Procedure} unread-string str port
-@deffnx {C Function} scm_unread_string (str, port)
-Place the string @var{str} in @var{port} so that its characters will be
-read in subsequent read operations. If called multiple times, the
-unread characters will be read again in last-in first-out order. If
-@var{port} is not supplied, the current-input-port is used.
-@end deffn
-
-@deffn {Scheme Procedure} drain-input port
-@deffnx {C Function} scm_drain_input (port)
-This procedure clears a port's input buffers, similar
-to the way that force-output clears the output buffer. The
-contents of the buffers are returned as a single string, e.g.,
-
-@lisp
-(define p (open-input-file ...))
-(drain-input p) => empty string, nothing buffered yet.
-(unread-char (read-char p) p)
-(drain-input p) => initial chars from p, up to the buffer size.
-@end lisp
-
-Draining the buffers may be useful for cleanly finishing
-buffered I/O so that the file descriptor can be used directly
-for further input.
-@end deffn
-
-@deffn {Scheme Procedure} port-column port
-@deffnx {Scheme Procedure} port-line port
-@deffnx {C Function} scm_port_column (port)
-@deffnx {C Function} scm_port_line (port)
-Return the current column number or line number of @var{port},
-using the current input port if none is specified. If the number is
-unknown, the result is #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.)
-@end deffn
-
-@deffn {Scheme Procedure} set-port-column! port column
-@deffnx {Scheme Procedure} set-port-line! port line
-@deffnx {C Function} scm_set_port_column_x (port, column)
-@deffnx {C Function} scm_set_port_line_x (port, line)
-Set the current column or line number of @var{port}, using the
-current input port if none is specified.
-@end deffn
-
-@node Writing
-@section Writing
-
-[Generic procedures for writing to ports.]
-
-@deffn {Scheme Procedure} get-print-state port
-@deffnx {C Function} scm_get_print_state (port)
-Return the print state of the port @var{port}. If @var{port}
-has no associated print state, @code{#f} is returned.
-@end deffn
-
-@rnindex display
-@deffn {Scheme Procedure} display obj [port]
-Send a representation of @var{obj} to @var{current-output-port}.
-Optional second arg @var{port} specifies an alternative output port.
-The representation is similar to that produced by @code{write} (REFFIXME),
-the differences being strings are not quoted (and their characters are not
-escaped), and characters are rendered as if with @code{write-char}.
-@end deffn
-
-@rnindex newline
-@deffn {Scheme Procedure} newline [port]
-@deffnx {C Function} scm_newline (port)
-Send a newline to @var{port}.
-If @var{port} is omitted, send to the current output port.
-@end deffn
-
-@deffn {Scheme Procedure} port-with-print-state port pstate
-@deffnx {C Function} scm_port_with_print_state (port, pstate)
-Create a new port which behaves like @var{port}, but with an
-included print state @var{pstate}.
-@end deffn
-
-@deffn {Scheme Procedure} print-options-interface [setting]
-@deffnx {C Function} scm_print_options (setting)
-Option interface for the print options. Instead of using
-this procedure directly, use the procedures
-@code{print-enable}, @code{print-disable}, @code{print-set!}
-and @code{print-options}.
-@end deffn
-
-@deffn {Scheme Procedure} simple-format destination message . args
-@deffnx {C Function} scm_simple_format (destination, message, args)
-Write @var{message} to @var{destination}, defaulting to
-the current output port.
-@var{message} can contain @code{~A} (was @code{%s}) and
-@code{~S} (was @code{%S}) escapes. When printed,
-the escapes are replaced with corresponding members of
-@var{ARGS}:
-@code{~A} formats using @code{display} and @code{~S} formats
-using @code{write}.
-If @var{destination} is @code{#t}, then use the current output
-port, if @var{destination} is @code{#f}, then return a string
-containing the formatted text. Does not add a trailing newline.
-@end deffn
-
-@rnindex write-char
-@deffn {Scheme Procedure} write-char chr [port]
-@deffnx {C Function} scm_write_char (chr, port)
-Send character @var{chr} to @var{port}.
-@end deffn
-
-@findex fflush
-@deffn {Scheme Procedure} force-output [port]
-@deffnx {C Function} scm_force_output (port)
-Flush the specified output port, or the current output port if @var{port}
-is omitted. The current output buffer contents are passed to the
-underlying port implementation (e.g., in the case of fports, the
-data will be written to the file and the output buffer will be cleared.)
-It has no effect on an unbuffered port.
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} flush-all-ports
-@deffnx {C Function} scm_flush_all_ports ()
-Equivalent to calling @code{force-output} on
-all open output ports. The return value is unspecified.
-@end deffn
-
-
-@node Closing
-@section Closing
-
-@deffn {Scheme Procedure} close-port port
-@deffnx {C Function} scm_close_port (port)
-Close the specified port object. Return @code{#t} if it
-successfully closes a port or @code{#f} if it was already
-closed. An exception may be raised if an error occurs, for
-example when flushing buffered output. See also @ref{Ports and
-File Descriptors, close}, for a procedure which can close file
-descriptors.
-@end deffn
-
-@rnindex close-input-port
-@deffn {Scheme Procedure} close-input-port port
-@deffnx {C Function} scm_close_input_port (port)
-Close the specified input port object. The routine has no effect if
-the file has already been closed. An exception may be raised if an
-error occurs. The value returned is unspecified.
-
-See also @ref{Ports and File Descriptors, close}, for a procedure
-which can close file descriptors.
-@end deffn
-
-@rnindex close-output-port
-@deffn {Scheme Procedure} close-output-port port
-@deffnx {C Function} scm_close_output_port (port)
-Close the specified output port object. The routine has no effect if
-the file has already been closed. An exception may be raised if an
-error occurs. The value returned is unspecified.
-
-See also @ref{Ports and File Descriptors, close}, for a procedure
-which can close file descriptors.
-@end deffn
-
-@deffn {Scheme Procedure} port-closed? port
-@deffnx {C Function} scm_port_closed_p (port)
-Return @code{#t} if @var{port} is closed or @code{#f} if it is
-open.
-@end deffn
-
-
-@node Random Access
-@section Random Access
-
-@deffn {Scheme Procedure} seek fd_port offset whence
-@deffnx {C Function} scm_seek (fd_port, offset, whence)
-Sets the current position of @var{fd/port} to the integer
-@var{offset}, which is interpreted according to the value of
-@var{whence}.
-
-One of the following variables should be supplied for
-@var{whence}:
-@defvar SEEK_SET
-Seek from the beginning of the file.
-@end defvar
-@defvar SEEK_CUR
-Seek from the current position.
-@end defvar
-@defvar SEEK_END
-Seek from the end of the file.
-@end defvar
-If @var{fd/port} is a file descriptor, the underlying system
-call is @code{lseek}. @var{port} may be a string port.
-
-The value returned is the new position in the file. This means
-that the current position of a port can be obtained using:
-@lisp
-(seek port 0 SEEK_CUR)
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} ftell fd_port
-@deffnx {C Function} scm_ftell (fd_port)
-Return an integer representing the current position of
-@var{fd/port}, measured from the beginning. Equivalent to:
-
-@lisp
-(seek port 0 SEEK_CUR)
-@end lisp
-@end deffn
-
-@findex truncate
-@findex ftruncate
-@deffn {Scheme Procedure} truncate-file object [length]
-@deffnx {C Function} scm_truncate_file (object, length)
-Truncates the object referred to by @var{object} to at most
-@var{length} bytes. @var{object} can be a string containing a
-file name or an integer file descriptor or a port.
-@var{length} may be omitted if @var{object} is not a file name,
-in which case the truncation occurs at the current port.
-position. The return value is unspecified.
-@end deffn
-
-@node Line/Delimited
-@section Line Oriented and Delimited Text
-
-The delimited-I/O module can be accessed with:
-
-@smalllisp
-(use-modules (ice-9 rdelim))
-@end smalllisp
-
-It can be used to read or write lines of text, or read text delimited by
-a specified set of characters. It's similar to the @code{(scsh rdelim)}
-module from guile-scsh, but does not use multiple values or character
-sets and has an extra procedure @code{write-line}.
-
-@c begin (scm-doc-string "rdelim.scm" "read-line")
-@deffn {Scheme Procedure} read-line [port] [handle-delim]
-Return a line of text from @var{port} if specified, otherwise from the
-value returned by @code{(current-input-port)}. Under Unix, a line of text
-is terminated by the first end-of-line character or by end-of-file.
-
-If @var{handle-delim} is specified, it should be one of the following
-symbols:
-@table @code
-@item trim
-Discard the terminating delimiter. This is the default, but it will
-be impossible to tell whether the read terminated with a delimiter or
-end-of-file.
-@item concat
-Append the terminating delimiter (if any) to the returned string.
-@item peek
-Push the terminating delimiter (if any) back on to the port.
-@item split
-Return a pair containing the string read from the port and the
-terminating delimiter or end-of-file object.
-@end table
-@end deffn
-
-@c begin (scm-doc-string "rdelim.scm" "read-line!")
-@deffn {Scheme Procedure} read-line! buf [port]
-Read a line of text into the supplied string @var{buf} and return the
-number of characters added to @var{buf}. If @var{buf} is filled, then
-@code{#f} is returned.
-Read from @var{port} if
-specified, otherwise from the value returned by @code{(current-input-port)}.
-@end deffn
-
-@c begin (scm-doc-string "rdelim.scm" "read-delimited")
-@deffn {Scheme Procedure} read-delimited delims [port] [handle-delim]
-Read text until one of the characters in the string @var{delims} is found
-or end-of-file is reached. Read from @var{port} if supplied, otherwise
-from the value returned by @code{(current-input-port)}.
-@var{handle-delim} takes the same values as described for @code{read-line}.
-@end deffn
-
-@c begin (scm-doc-string "rdelim.scm" "read-delimited!")
-@deffn {Scheme Procedure} read-delimited! delims buf [port] [handle-delim] [start] [end]
-Read text into the supplied string @var{buf} and return the number of
-characters added to @var{buf} (subject to @var{handle-delim}, which takes
-the same values specified for @code{read-line}. If @var{buf} is filled,
-@code{#f} is returned for both the number of characters read and the
-delimiter. Also terminates if one of the characters in the string
-@var{delims} is found
-or end-of-file is reached. Read from @var{port} if supplied, otherwise
-from the value returned by @code{(current-input-port)}.
-@end deffn
-
-@deffn {Scheme Procedure} write-line obj [port]
-@deffnx {C Function} scm_write_line (obj, port)
-Display @var{obj} and a newline character to @var{port}. If
-@var{port} is not specified, @code{(current-output-port)} is
-used. This function is equivalent to:
-@lisp
-(display obj [port])
-(newline [port])
-@end lisp
-@end deffn
-
-Some of the abovementioned I/O functions rely on the following C
-primitives. These will mainly be of interest to people hacking Guile
-internals.
-
-@deffn {Scheme Procedure} %read-delimited! delims str gobble [port [start [end]]]
-@deffnx {C Function} scm_read_delimited_x (delims, str, gobble, port, start, end)
-Read characters from @var{port} into @var{str} until one of the
-characters in the @var{delims} string is encountered. If
-@var{gobble} is true, discard the delimiter character;
-otherwise, leave it in the input stream for the next read. If
-@var{port} is not specified, use the value of
-@code{(current-input-port)}. If @var{start} or @var{end} are
-specified, store data only into the substring of @var{str}
-bounded by @var{start} and @var{end} (which default to the
-beginning and end of the string, respectively).
-
- Return a pair consisting of the delimiter that terminated the
-string and the number of characters read. If reading stopped
-at the end of file, the delimiter returned is the
-@var{eof-object}; if the string was filled without encountering
-a delimiter, this value is @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} %read-line [port]
-@deffnx {C Function} scm_read_line (port)
-Read a newline-terminated line from @var{port}, allocating storage as
-necessary. The newline terminator (if any) is removed from the string,
-and a pair consisting of the line and its delimiter is returned. The
-delimiter may be either a newline or the @var{eof-object}; if
-@code{%read-line} is called at the end of file, it returns the pair
-@code{(#<eof> . #<eof>)}.
-@end deffn
-
-@node Block Reading and Writing
-@section Block reading and writing
-
-The Block-string-I/O module can be accessed with:
-
-@smalllisp
-(use-modules (ice-9 rw))
-@end smalllisp
-
-It currently contains procedures that help to implement the
-@code{(scsh rw)} module in guile-scsh.
-
-@deffn {Scheme Procedure} read-string!/partial str [port_or_fdes [start [end]]]
-@deffnx {C Function} scm_read_string_x_partial (str, port_or_fdes, start, end)
-Read characters from a port or file descriptor into a
-string @var{str}. A port must have an underlying file
-descriptor --- a so-called fport. This procedure is
-scsh-compatible and can efficiently read large strings.
-It will:
-
-@itemize
-@item
-attempt to fill the entire string, unless the @var{start}
-and/or @var{end} arguments are supplied. i.e., @var{start}
-defaults to 0 and @var{end} defaults to
-@code{(string-length str)}
-@item
-use the current input port if @var{port_or_fdes} is not
-supplied.
-@item
-return fewer than the requested number of characters in some
-cases, e.g., on end of file, if interrupted by a signal, or if
-not all the characters are immediately available.
-@item
-wait indefinitely for some input if no characters are
-currently available,
-unless the port is in non-blocking mode.
-@item
-read characters from the port's input buffers if available,
-instead from the underlying file descriptor.
-@item
-return @code{#f} if end-of-file is encountered before reading
-any characters, otherwise return the number of characters
-read.
-@item
-return 0 if the port is in non-blocking mode and no characters
-are immediately available.
-@item
-return 0 if the request is for 0 bytes, with no
-end-of-file check.
-@end itemize
-@end deffn
-
-@deffn {Scheme Procedure} write-string/partial str [port_or_fdes [start [end]]]
-@deffnx {C Function} scm_write_string_partial (str, port_or_fdes, start, end)
-Write characters from a string @var{str} to a port or file
-descriptor. A port must have an underlying file descriptor
---- a so-called fport. This procedure is
-scsh-compatible and can efficiently write large strings.
-It will:
-
-@itemize
-@item
-attempt to write the entire string, unless the @var{start}
-and/or @var{end} arguments are supplied. i.e., @var{start}
-defaults to 0 and @var{end} defaults to
-@code{(string-length str)}
-@item
-use the current output port if @var{port_of_fdes} is not
-supplied.
-@item
-in the case of a buffered port, store the characters in the
-port's output buffer, if all will fit. If they will not fit
-then any existing buffered characters will be flushed
-before attempting
-to write the new characters directly to the underlying file
-descriptor. If the port is in non-blocking mode and
-buffered characters can not be flushed immediately, then an
-@code{EAGAIN} system-error exception will be raised (Note:
-scsh does not support the use of non-blocking buffered ports.)
-@item
-write fewer than the requested number of
-characters in some cases, e.g., if interrupted by a signal or
-if not all of the output can be accepted immediately.
-@item
-wait indefinitely for at least one character
-from @var{str} to be accepted by the port, unless the port is
-in non-blocking mode.
-@item
-return the number of characters accepted by the port.
-@item
-return 0 if the port is in non-blocking mode and can not accept
-at least one character from @var{str} immediately
-@item
-return 0 immediately if the request size is 0 bytes.
-@end itemize
-@end deffn
-
-@node Default Ports
-@section Default Ports for Input, Output and Errors
-
-@rnindex current-input-port
-@deffn {Scheme Procedure} current-input-port
-@deffnx {C Function} scm_current_input_port ()
-Return the current input port. This is the default port used
-by many input procedures. Initially, @code{current-input-port}
-returns the @dfn{standard input} in Unix and C terminology.
-@end deffn
-
-@rnindex current-output-port
-@deffn {Scheme Procedure} current-output-port
-@deffnx {C Function} scm_current_output_port ()
-Return the current output port. This is the default port used
-by many output procedures. Initially,
-@code{current-output-port} returns the @dfn{standard output} in
-Unix and C terminology.
-@end deffn
-
-@deffn {Scheme Procedure} current-error-port
-@deffnx {C Function} scm_current_error_port ()
-Return the port to which errors and warnings should be sent (the
-@dfn{standard error} in Unix and C terminology).
-@end deffn
-
-@deffn {Scheme Procedure} set-current-input-port port
-@deffnx {Scheme Procedure} set-current-output-port port
-@deffnx {Scheme Procedure} set-current-error-port port
-@deffnx {C Function} scm_set_current_input_port (port)
-@deffnx {C Function} scm_set_current_output_port (port)
-@deffnx {C Function} scm_set_current_error_port (port)
-Change the ports returned by @code{current-input-port},
-@code{current-output-port} and @code{current-error-port}, respectively,
-so that they use the supplied @var{port} for input or output.
-@end deffn
-
-@deffn {Scheme Procedure} set-current-output-port port
-Set the current default output port to PORT.
-@end deffn
-
-@deffn {Scheme Procedure} set-current-error-port port
-Set the current default error port to PORT.
-@end deffn
-
-
-@node Port Types
-@section Types of Port
-
-[Types of port; how to make them.]
-
-@menu
-* File Ports:: Ports on an operating system file.
-* String Ports:: Ports on a Scheme string.
-* Soft Ports:: Ports on arbitrary Scheme procedures.
-* Void Ports:: Ports on nothing at all.
-@end menu
-
-
-@node File Ports
-@subsection File Ports
-
-The following procedures are used to open file ports.
-See also @ref{Ports and File Descriptors, open}, for an interface
-to the Unix @code{open} system call.
-
-@deffn {Scheme Procedure} open-file filename mode
-@deffnx {C Function} scm_open_file (filename, mode)
-Open the file whose name is @var{filename}, and return a port
-representing that file. The attributes of the port are
-determined by the @var{mode} string. The way in which this is
-interpreted is similar to C stdio. The first character must be
-one of the following:
-@table @samp
-@item r
-Open an existing file for input.
-@item w
-Open a file for output, creating it if it doesn't already exist
-or removing its contents if it does.
-@item a
-Open a file for output, creating it if it doesn't already
-exist. All writes to the port will go to the end of the file.
-The "append mode" can be turned off while the port is in use
-@pxref{Ports and File Descriptors, fcntl}
-@end table
-The following additional characters can be appended:
-@table @samp
-@item +
-Open the port for both input and output. E.g., @code{r+}: open
-an existing file for both input and output.
-@item 0
-Create an "unbuffered" port. In this case input and output
-operations are passed directly to the underlying port
-implementation without additional buffering. This is likely to
-slow down I/O operations. The buffering mode can be changed
-while a port is in use @pxref{Ports and File Descriptors,
-setvbuf}
-@item l
-Add line-buffering to the port. The port output buffer will be
-automatically flushed whenever a newline character is written.
-@end table
-In theory we could create read/write ports which were buffered
-in one direction only. However this isn't included in the
-current interfaces. If a file cannot be opened with the access
-requested, @code{open-file} throws an exception.
-@end deffn
-
-@rnindex open-input-file
-@deffn {Scheme Procedure} open-input-file filename
-Open @var{filename} for input. Equivalent to
-@smalllisp
-(open-file @var{filename} "r")
-@end smalllisp
-@end deffn
-
-@rnindex open-output-file
-@deffn {Scheme Procedure} open-output-file filename
-Open @var{filename} for output. Equivalent to
-@smalllisp
-(open-file @var{filename} "w")
-@end smalllisp
-@end deffn
-
-@rnindex call-with-input-file
-@deffn {Scheme Procedure} call-with-input-file file proc
-@var{proc} should be a procedure of one argument, and @var{file} should
-be a string naming a file. The file must already exist. These
-procedures call @var{proc} with one argument: the port obtained by
-opening the named file for input or output. If the file cannot be
-opened, an error is signalled. If the procedure returns, then the port
-is closed automatically and the value yielded by the procedure is
-returned. If the procedure does not return, then the port will not be
-closed automatically unless it is possible to prove that the port will
-never again be used for a read or write operation.
-@end deffn
-
-@rnindex call-with-output-file
-@deffn {Scheme Procedure} call-with-output-file file proc
-@var{proc} should be a procedure of one argument, and @var{file} should
-be a string naming a file. The behaviour is unspecified if the file
-already exists. These procedures call @var{proc} with one argument: the
-port obtained by opening the named file for input or output. If the
-file cannot be opened, an error is signalled. If the procedure returns,
-then the port is closed automatically and the value yielded by the
-procedure is returned. If the procedure does not return, then the port
-will not be closed automatically unless it is possible to prove that the
-port will never again be used for a read or write operation.
-@end deffn
-
-@rnindex with-input-from-file
-@deffn {Scheme Procedure} with-input-from-file file thunk
-@var{thunk} must be a procedure of no arguments, and @var{file} must be
-a string naming a file. The file must already exist. The file is opened
-for input, an input port connected to it is made the default value
-returned by @code{current-input-port}, and the @var{thunk} is called
-with no arguments. When the @var{thunk} returns, the port is closed and
-the previous default is restored. Returns the value yielded by
-@var{thunk}. If an escape procedure is used to escape from the
-continuation of these procedures, their behavior is implementation
-dependent.
-@end deffn
-
-@rnindex with-output-to-file
-@deffn {Scheme Procedure} with-output-to-file file thunk
-@var{thunk} must be a procedure of no arguments, and @var{file} must be
-a string naming a file. The effect is unspecified if the file already
-exists. The file is opened for output, an output port connected to it
-is made the default value returned by @code{current-output-port}, and
-the @var{thunk} is called with no arguments. When the @var{thunk}
-returns, the port is closed and the previous default is restored.
-Returns the value yielded by @var{thunk}. If an escape procedure is
-used to escape from the continuation of these procedures, their behavior
-is implementation dependent.
-@end deffn
-
-@deffn {Scheme Procedure} with-error-to-file file thunk
-@var{thunk} must be a procedure of no arguments, and @var{file} must be
-a string naming a file. The effect is unspecified if the file already
-exists. The file is opened for output, an output port connected to it
-is made the default value returned by @code{current-error-port}, and the
-@var{thunk} is called with no arguments. When the @var{thunk} returns,
-the port is closed and the previous default is restored. Returns the
-value yielded by @var{thunk}. If an escape procedure is used to escape
-from the continuation of these procedures, their behavior is
-implementation dependent.
-@end deffn
-
-@deffn {Scheme Procedure} port-mode port
-@deffnx {C Function} scm_port_mode (port)
-Return the port modes associated with the open port @var{port}.
-These will not necessarily be identical to the modes used when
-the port was opened, since modes such as "append" which are
-used only during port creation are not retained.
-@end deffn
-
-@deffn {Scheme Procedure} port-filename port
-@deffnx {C Function} scm_port_filename (port)
-Return the filename associated with @var{port}. This function returns
-the strings "standard input", "standard output" and "standard error"
-when called on the current input, output and error ports respectively.
-@end deffn
-
-@deffn {Scheme Procedure} set-port-filename! port filename
-@deffnx {C Function} scm_set_port_filename_x (port, filename)
-Change the filename associated with @var{port}, using the current input
-port if none is specified. Note that this does not change the port's
-source of data, but only the value that is returned by
-@code{port-filename} and reported in diagnostic output.
-@end deffn
-
-@deffn {Scheme Procedure} file-port? obj
-@deffnx {C Function} scm_file_port_p (obj)
-Determine whether @var{obj} is a port that is related to a file.
-@end deffn
-
-
-@node String Ports
-@subsection String Ports
-
-The following allow string ports to be opened by analogy to R4R*
-file port facilities:
-
-@deffn {Scheme Procedure} call-with-output-string proc
-@deffnx {C Function} scm_call_with_output_string (proc)
-Calls the one-argument procedure @var{proc} with a newly created output
-port. When the function returns, the string composed of the characters
-written into the port is returned.
-@end deffn
-
-@deffn {Scheme Procedure} call-with-input-string string proc
-@deffnx {C Function} scm_call_with_input_string (string, proc)
-Calls the one-argument procedure @var{proc} with a newly
-created input port from which @var{string}'s contents may be
-read. The value yielded by the @var{proc} is returned.
-@end deffn
-
-@deffn {Scheme Procedure} with-output-to-string thunk
-Calls the zero-argument procedure @var{thunk} with the current output
-port set temporarily to a new string port. It returns a string
-composed of the characters written to the current output.
-@end deffn
-
-@deffn {Scheme Procedure} with-input-from-string string thunk
-Calls the zero-argument procedure @var{thunk} with the current input
-port set temporarily to a string port opened on the specified
-@var{string}. The value yielded by @var{thunk} is returned.
-@end deffn
-
-@deffn {Scheme Procedure} open-input-string str
-@deffnx {C Function} scm_open_input_string (str)
-Take a string and return an 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.
-@end deffn
-
-@deffn {Scheme Procedure} open-output-string
-@deffnx {C Function} scm_open_output_string ()
-Return an 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.
-@end deffn
-
-@deffn {Scheme Procedure} get-output-string port
-@deffnx {C Function} scm_get_output_string (port)
-Given an output port created by @code{open-output-string},
-return a string consisting of the characters that have been
-output to the port so far.
-@end deffn
-
-A string port can be used in many procedures which accept a port
-but which are not dependent on implementation details of fports.
-E.g., seeking and truncating will work on a string port,
-but trying to extract the file descriptor number will fail.
-
-
-@node Soft Ports
-@subsection Soft Ports
-
-A @dfn{soft-port} is a port based on a vector of procedures capable of
-accepting or delivering characters. It allows emulation of I/O ports.
-
-@deffn {Scheme Procedure} make-soft-port pv modes
-@deffnx {C Function} scm_make_soft_port (pv, modes)
-Return a port capable of receiving or delivering characters as
-specified by the @var{modes} string (@pxref{File Ports,
-open-file}). @var{pv} must be a vector of length 5. Its
-components are as follows:
-
-@enumerate 0
-@item
-procedure accepting one character for output
-@item
-procedure accepting a string for output
-@item
-thunk for flushing output
-@item
-thunk for getting one character
-@item
-thunk for closing port (not by garbage collection)
-@end enumerate
-
-For an output-only port only elements 0, 1, 2, and 4 need be
-procedures. For an input-only port only elements 3 and 4 need
-be procedures. Thunks 2 and 4 can instead be @code{#f} if
-there is no useful operation for them to perform.
-
-If thunk 3 returns @code{#f} or an @code{eof-object}
-(@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on
-Scheme}) it indicates that the port has reached end-of-file.
-For example:
-
-@lisp
-(define stdout (current-output-port))
-(define p (make-soft-port
- (vector
- (lambda (c) (write c stdout))
- (lambda (s) (display s stdout))
- (lambda () (display "." stdout))
- (lambda () (char-upcase (read-char)))
- (lambda () (display "@@" stdout)))
- "rw"))
-
-(write p p) @result{} #<input-output: soft 8081e20>
-@end lisp
-@end deffn
-
-
-@node Void Ports
-@subsection Void Ports
-
-This kind of port causes any data to be discarded when written to, and
-always returns the end-of-file object when read from.
-
-@deffn {Scheme Procedure} %make-void-port mode
-@deffnx {C Function} scm_sys_make_void_port (mode)
-Create and return a new void port. A void port acts like
-@file{/dev/null}. The @var{mode} argument
-specifies the input/output modes for this port: see the
-documentation for @code{open-file} in @ref{File Ports}.
-@end deffn
-
-
-@node I/O Extensions
-@section Using and Extending Ports in C
-
-@menu
-* C Port Interface:: Using ports from C.
-* Port Implementation:: How to implement a new port type in C.
-@end menu
-
-
-@node C Port Interface
-@subsection C Port Interface
-
-This section describes how to use Scheme ports from C.
-
-@subsubsection Port basics
-
-There are two main data structures. A port type object (ptob) is of
-type @code{scm_ptob_descriptor}. A port instance is of type
-@code{scm_port}. Given an @code{SCM} variable which points to a port,
-the corresponding C port object can be obtained using the
-@code{SCM_PTAB_ENTRY} macro. The ptob can be obtained by using
-@code{SCM_PTOBNUM} to give an index into the @code{scm_ptobs}
-global array.
-
-@subsubsection Port buffers
-
-An input port always has a read buffer and an output port always has a
-write buffer. However the size of these buffers is not guaranteed to be
-more than one byte (e.g., the @code{shortbuf} field in @code{scm_port}
-which is used when no other buffer is allocated). The way in which the
-buffers are allocated depends on the implementation of the ptob. For
-example in the case of an fport, buffers may be allocated with malloc
-when the port is created, but in the case of an strport the underlying
-string is used as the buffer.
-
-@subsubsection The @code{rw_random} flag
-
-Special treatment is required for ports which can be seeked at random.
-Before various operations, such as seeking the port or changing from
-input to output on a bidirectional port or vice versa, the port
-implementation must be given a chance to update its state. The write
-buffer is updated by calling the @code{flush} ptob procedure and the
-input buffer is updated by calling the @code{end_input} ptob procedure.
-In the case of an fport, @code{flush} causes buffered output to be
-written to the file descriptor, while @code{end_input} causes the
-descriptor position to be adjusted to account for buffered input which
-was never read.
-
-The special treatment must be performed if the @code{rw_random} flag in
-the port is non-zero.
-
-@subsubsection The @code{rw_active} variable
-
-The @code{rw_active} variable in the port is only used if
-@code{rw_random} is set. It's defined as an enum with the following
-values:
-
-@table @code
-@item SCM_PORT_READ
-the read buffer may have unread data.
-
-@item SCM_PORT_WRITE
-the write buffer may have unwritten data.
-
-@item SCM_PORT_NEITHER
-neither the write nor the read buffer has data.
-@end table
-
-@subsubsection Reading from a port.
-
-To read from a port, it's possible to either call existing libguile
-procedures such as @code{scm_getc} and @code{scm_read_line} or to read
-data from the read buffer directly. Reading from the buffer involves
-the following steps:
-
-@enumerate
-@item
-Flush output on the port, if @code{rw_active} is @code{SCM_PORT_WRITE}.
-
-@item
-Fill the read buffer, if it's empty, using @code{scm_fill_input}.
-
-@item Read the data from the buffer and update the read position in
-the buffer. Steps 2) and 3) may be repeated as many times as required.
-
-@item Set rw_active to @code{SCM_PORT_READ} if @code{rw_random} is set.
-
-@item update the port's line and column counts.
-@end enumerate
-
-@subsubsection Writing to a port.
-
-To write data to a port, calling @code{scm_lfwrite} should be sufficient for
-most purposes. This takes care of the following steps:
-
-@enumerate
-@item
-End input on the port, if @code{rw_active} is @code{SCM_PORT_READ}.
-
-@item
-Pass the data to the ptob implementation using the @code{write} ptob
-procedure. The advantage of using the ptob @code{write} instead of
-manipulating the write buffer directly is that it allows the data to be
-written in one operation even if the port is using the single-byte
-@code{shortbuf}.
-
-@item
-Set @code{rw_active} to @code{SCM_PORT_WRITE} if @code{rw_random}
-is set.
-@end enumerate
-
-
-@node Port Implementation
-@subsection Port Implementation
-
-This section describes how to implement a new port type in C.
-
-As described in the previous section, a port type object (ptob) is
-a structure of type @code{scm_ptob_descriptor}. A ptob is created by
-calling @code{scm_make_port_type}.
-
-All of the elements of the ptob, apart from @code{name}, are procedures
-which collectively implement the port behaviour. Creating a new port
-type mostly involves writing these procedures.
-
-@code{scm_make_port_type} initializes three elements of the structure
-(@code{name}, @code{fill_input} and @code{write}) from its arguments.
-The remaining elements are initialized with default values and can be
-set later if required.
-
-@table @code
-@item name
-A pointer to a NUL terminated string: the name of the port type. This
-is the only element of @code{scm_ptob_descriptor} which is not
-a procedure. Set via the first argument to @code{scm_make_port_type}.
-
-@item mark
-Called during garbage collection to mark any SCM objects that a port
-object may contain. It doesn't need to be set unless the port has
-@code{SCM} components. Set using @code{scm_set_port_mark}.
-
-@item free
-Called when the port is collected during gc. It
-should free any resources used by the port.
-Set using @code{scm_set_port_free}.
-
-@item print
-Called when @code{write} is called on the port object, to print a
-port description. e.g., for an fport it may produce something like:
-@code{#<input: /etc/passwd 3>}. Set using @code{scm_set_port_print}.
-
-@item equalp
-Not used at present. Set using @code{scm_set_port_equalp}.
-
-@item close
-Called when the port is closed, unless it was collected during gc. It
-should free any resources used by the port.
-Set using @code{scm_set_port_close}.
-
-@item write
-Accept data which is to be written using the port. The port implementation
-may choose to buffer the data instead of processing it directly.
-Set via the third argument to @code{scm_make_port_type}.
-
-@item flush
-Complete the processing of buffered output data. Reset the value of
-@code{rw_active} to @code{SCM_PORT_NEITHER}.
-Set using @code{scm_set_port_flush}.
-
-@item end_input
-Perform any synchronization required when switching from input to output
-on the port. Reset the value of @code{rw_active} to @code{SCM_PORT_NEITHER}.
-Set using @code{scm_set_port_end_input}.
-
-@item fill_input
-Read new data into the read buffer and return the first character. It
-can be assumed that the read buffer is empty when this procedure is called.
-Set via the second argument to @code{scm_make_port_type}.
-
-@item input_waiting
-Return a lower bound on the number of bytes that could be read from the
-port without blocking. It can be assumed that the current state of
-@code{rw_active} is @code{SCM_PORT_NEITHER}.
-Set using @code{scm_set_port_input_waiting}.
-
-@item seek
-Set the current position of the port. The procedure can not make
-any assumptions about the value of @code{rw_active} when it's
-called. It can reset the buffers first if desired by using something
-like:
-
-@example
- if (pt->rw_active == SCM_PORT_READ)
- scm_end_input (object);
- else if (pt->rw_active == SCM_PORT_WRITE)
- ptob->flush (object);
-@end example
-
-However note that this will have the side effect of discarding any data
-in the unread-char buffer, in addition to any side effects from the
-@code{end_input} and @code{flush} ptob procedures. This is undesirable
-when seek is called to measure the current position of the port, i.e.,
-@code{(seek p 0 SEEK_CUR)}. The libguile fport and string port
-implementations take care to avoid this problem.
-
-The procedure is set using @code{scm_set_port_seek}.
-
-@item truncate
-Truncate the port data to be specified length. It can be assumed that the
-current state of @code{rw_active} is @code{SCM_PORT_NEITHER}.
-Set using @code{scm_set_port_truncate}.
-
-@end table
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-memory.texi b/doc/ref/scheme-memory.texi
deleted file mode 100644
index d6f0584c6..000000000
--- a/doc/ref/scheme-memory.texi
+++ /dev/null
@@ -1,396 +0,0 @@
-@page
-@node Memory Management
-@chapter Memory Management and Garbage Collection
-
-@menu
-* Garbage Collection::
-* Memory Blocks::
-* Weak References::
-* Guardians::
-@end menu
-
-
-@node Garbage Collection
-@section Garbage Collection
-
-@deffn {Scheme Procedure} gc
-@deffnx {C Function} scm_gc ()
-Scans all of SCM objects and reclaims for further use those that are
-no longer accessible. You normally don't need to call this function
-explicitely. It is called automatically when appropriate.
-@end deffn
-
-@deffn {Scheme Procedure} gc-stats
-@deffnx {C Function} scm_gc_stats ()
-Return an association list of statistics about Guile's current
-use of storage.
-@end deffn
-
-
-@node Memory Blocks
-@section Memory Blocks
-
-In C programs, dynamic management of memory blocks is normally done
-with the functions malloc, realloc, and free. Guile has additional
-functions for dynamic memory allocation that are integrated into the
-garbage collector and the error reporting system.
-
-Memory blocks that are associated with Scheme objects (for example a
-smob) should be allocated and freed with @code{scm_gc_malloc} and
-@code{scm_gc_free}. The function @code{scm_gc_malloc} will either
-return a valid pointer or signal an error. It will also assume that
-the new memory can be freed by a garbage collection. The garbage
-collector uses this information to decide when to try to actually
-collect some garbage. Memory blocks allocated with
-@code{scm_gc_malloc} must be freed with @code{scm_gc_free}.
-
-For memory that is not associated with a Scheme object, you can use
-@code{scm_malloc} instead of @code{malloc}. Like
-@code{scm_gc_malloc}, it will either return a valid pointer or signal
-an error. However, it will not assume that the new memory block can
-be freed by a garbage collection. The memory can be freed with
-@code{free}.
-
-There is also @code{scm_gc_realloc} and @code{scm_realloc}, to be used
-in place of @code{realloc} when appropriate.
-
-For really specialized needs, take at look at
-@code{scm_gc_register_collectable_memory} and
-@code{scm_gc_unregister_collectable_memory}.
-
-@deftypefn {C Function} void *scm_malloc (size_t @var{size})
-Allocate @var{size} bytes of memory and return a pointer to it. When
-@var{size} is 0, return @code{NULL}. When not enough memory is
-available, signal an error. This function runs the GC to free up some
-memory when it deems it appropriate.
-
-The memory is allocated by the libc @code{malloc} function and can be
-freed with @code{free}. There is no @code{scm_free} function to go
-with @code{scm_malloc} to make it easier to pass memory back and forth
-between different modules.
-@end deftypefn
-
-@deftypefn {C Function} void *scm_realloc (void *@var{mem}, size_t @var{new_size})
-Change the size of the memory block at @var{mem} to @var{new_size} and
-return its new location. When @var{new_size} is 0, this is the same
-as calling @code{free} on @var{mem} and @code{NULL} is returned. When
-@var{mem} is @code{NULL}, this function behaves like @code{scm_malloc}
-and allocates a new block of size @var{new_size}.
-
-When not enough memory is available, signal an error. This function
-runs the GC to free up some memory when it deems it appropriate.
-@end deftypefn
-
-@deftypefn {C Function} void scm_gc_register_collectable_memory (void *@var{mem}, size_t @var{size}, const char *@var{what})
-Informs the GC that the memory at @var{mem} of size @var{size} can
-potentially be freed during a GC. That is, announce that @var{mem} is
-part of a GC controlled object and when the GC happens to free that
-object, @var{size} bytes will be freed along with it. The GC will
-@strong{not} free the memory itself, it will just know that so-and-so
-much bytes of memory are associated with GC controlled objects and the
-memory system figures this into its decisions when to run a GC.
-
-@var{mem} does not need to come from @code{scm_malloc}. You can only
-call this function once for every memory block.
-
-The @var{what} argument is used for statistical purposes. It should
-describe the type of object that the memory will be used for so that
-users can identify just what strange objects are eating up their
-memory.
-@end deftypefn
-
-@deftypefn {C Function} void scm_gc_unregister_collectable_memory (void *@var{mem}, size_t @var{size})
-Informs the GC that the memory at @var{mem} of size @var{size} is no
-longer associated with a GC controlled object. You must take care to
-match up every call to @code{scm_gc_register_collectable_memory} with
-a call to @code{scm_gc_unregister_collectable_memory}. If you don't do
-this, the GC might have a wrong impression of what is going on and run
-much less efficiently than it could.
-@end deftypefn
-
-@deftypefn {C Function} void *scm_gc_malloc (size_t @var{size}, const char *@var{what})
-@deftypefnx {C Function} void *scm_gc_realloc (void *@var{mem}, size_t @var{old_size}, size_t @var{new_size}, const char *@var{what});
-Like @code{scm_malloc} or @code{scm_realloc}, but also call
-@code{scm_gc_register_collectable_memory}. Note that you need to pass
-the old size of a reallocated memory block as well. See below for a
-motivation.
-@end deftypefn
-
-@deftypefn {C Function} void scm_gc_free (void *@var{mem}, size_t @var{size}, const char *@var{what})
-Like @code{free}, but also call @code{scm_gc_unregister_collectable_memory}.
-
-Note that you need to explicitely pass the @var{size} parameter. This
-is done since it should normally be easy to provide this parameter
-(for memory that is associated with GC controlled objects) and this
-frees us from tracking this value in the GC itself, which will keep
-the memory management overhead very low.
-@end deftypefn
-
-@deffn {Scheme Procedure} malloc-stats
-Return an alist ((@var{what} . @var{n}) ...) describing number
-of malloced objects.
-@var{what} is the second argument to @code{scm_gc_malloc},
-@var{n} is the number of objects of that type currently
-allocated.
-@end deffn
-
-
-@subsection Upgrading from scm_must_malloc et al.
-
-Version 1.6 of Guile and earlier did not have the functions from the
-previous section. In their place, it had the functions
-@code{scm_must_malloc}, @code{scm_must_realloc} and
-@code{scm_must_free}. This section explains why we want you to stop
-using them, and how to do this.
-
-The functions @code{scm_must_malloc} and @code{scm_must_realloc}
-behaved like @code{scm_gc_malloc} and @code{scm_gc_realloc} do now,
-respectively. They would inform the GC about the newly allocated
-memory via the internal equivalent of
-@code{scm_gc_register_collectable_memory}. However,
-@code{scm_must_free} did not unregister the memory it was about to
-free. The usual way to unregister memory was to return its size from
-a smob free function.
-
-This disconnectedness of the actual freeing of memory and reporting
-this to the GC proved to be bad in practice. It was easy to make
-mistakes and report the wrong size because allocating and freeing was
-not done with symmetric code, and because it is cumbersome to compute
-the total size of nested data structures that were freed with multiple
-calls to @code{scm_must_free}. Additionally, there was no equivalent
-to @code{scm_malloc}, and it was tempting to just use
-@code{scm_must_malloc} and never to tell the GC that the memory has
-been freed.
-
-The effect was that the internal statistics kept by the GC drifted out
-of sync with reality and could even overflow in long running programs.
-When this happened, the result was a dramatic increase in (senseless)
-GC activity which would effectively stop the program dead.
-
-The functions @code{scm_done_malloc} and @code{scm_done_free} were
-introduced to help restore balance to the force, but existing bugs did
-not magically disappear, of course.
-
-Therefore we decided to force everybody to review their code by
-deprecating the existing functions and introducing new ones in their
-place that are hopefully easier to use correctly.
-
-For every use of @code{scm_must_malloc} you need to decide whether to
-use @code{scm_malloc} or @code{scm_gc_malloc} in its place. When the
-memory block is not part of a smob or some other Scheme object whose
-lifetime is ultimately managed by the garbage collector, use
-@code{scm_malloc} and @code{free}. When it is part of a smob, use
-@code{scm_gc_malloc} and change the smob free function to use
-@code{scm_gc_free} instead of @code{scm_must_free} or @code{free} and
-make it return zero.
-
-The important thing is to always pair @code{scm_malloc} with
-@code{free}; and to always pair @code{scm_gc_malloc} with
-@code{scm_gc_free}.
-
-The same reasoning applies to @code{scm_must_realloc} and
-@code{scm_realloc} versus @code{scm_gc_realloc}.
-
-
-@node Weak References
-@section Weak References
-
-[FIXME: This chapter is based on Mikael Djurfeldt's answer to a
-question by Michael Livshin. Any mistakes are not theirs, of course. ]
-
-Weak references let you attach bookkeeping information to data so that
-the additional information automatically disappears when the original
-data is no longer in use and gets garbage collected. In a weak key hash,
-the hash entry for that key disappears as soon as the key is no longer
-referenced from anywhere else. For weak value hashes, the same happens
-as soon as the value is no longer in use. Entries in a doubly weak hash
-disappear when either the key or the value are not used anywhere else
-anymore.
-
-Object properties offer the same kind of functionality as weak key
-hashes in many situations. (@pxref{Object Properties})
-
-Here's an example (a little bit strained perhaps, but one of the
-examples is actually used in Guile):
-
-Assume that you're implementing a debugging system where you want to
-associate information about filename and position of source code
-expressions with the expressions themselves.
-
-Hashtables can be used for that, but if you use ordinary hash tables
-it will be impossible for the scheme interpreter to "forget" old
-source when, for example, a file is reloaded.
-
-To implement the mapping from source code expressions to positional
-information it is necessary to use weak-key tables since we don't want
-the expressions to be remembered just because they are in our table.
-
-To implement a mapping from source file line numbers to source code
-expressions you would use a weak-value table.
-
-To implement a mapping from source code expressions to the procedures
-they constitute a doubly-weak table has to be used.
-
-@menu
-* Weak key hashes::
-* Weak vectors::
-@end menu
-
-
-@node Weak key hashes
-@subsection Weak key hashes
-
-@deffn {Scheme Procedure} make-weak-key-hash-table size
-@deffnx {Scheme Procedure} make-weak-value-hash-table size
-@deffnx {Scheme Procedure} make-doubly-weak-hash-table size
-@deffnx {C Function} scm_make_weak_key_hash_table (size)
-@deffnx {C Function} scm_make_weak_value_hash_table (size)
-@deffnx {C Function} scm_make_doubly_weak_hash_table (size)
-Return a weak hash table with @var{size} buckets. As with any
-hash table, choosing a good size for the table requires some
-caution.
-
-You can modify weak hash tables in exactly the same way you
-would modify regular hash tables. (@pxref{Hash Tables})
-@end deffn
-
-@deffn {Scheme Procedure} weak-key-hash-table? obj
-@deffnx {Scheme Procedure} weak-value-hash-table? obj
-@deffnx {Scheme Procedure} doubly-weak-hash-table? obj
-@deffnx {C Function} scm_weak_key_hash_table_p (obj)
-@deffnx {C Function} scm_weak_value_hash_table_p (obj)
-@deffnx {C Function} scm_doubly_weak_hash_table_p (obj)
-Return @code{#t} if @var{obj} is the specified weak hash
-table. Note that a doubly weak hash table is neither a weak key
-nor a weak value hash table.
-@end deffn
-
-@deffn {Scheme Procedure} make-weak-value-hash-table k
-@end deffn
-
-@deffn {Scheme Procedure} weak-value-hash-table? x
-@end deffn
-
-@deffn {Scheme Procedure} make-doubly-weak-hash-table k
-@end deffn
-
-@deffn {Scheme Procedure} doubly-weak-hash-table? x
-@end deffn
-
-
-@node Weak vectors
-@subsection Weak vectors
-
-Weak vectors are mainly useful in Guile's implementation of weak hash
-tables.
-
-@deffn {Scheme Procedure} make-weak-vector size [fill]
-@deffnx {C Function} scm_make_weak_vector (size, fill)
-Return a weak vector with @var{size} elements. If the optional
-argument @var{fill} is given, all entries in the vector will be
-set to @var{fill}. The default value for @var{fill} is the
-empty list.
-@end deffn
-
-@deffn {Scheme Procedure} weak-vector . l
-@deffnx {Scheme Procedure} list->weak-vector l
-@deffnx {C Function} scm_weak_vector (l)
-Construct a weak vector from a list: @code{weak-vector} uses
-the list of its arguments while @code{list->weak-vector} uses
-its only argument @var{l} (a list) to construct a weak vector
-the same way @code{list->vector} would.
-@end deffn
-
-@deffn {Scheme Procedure} weak-vector? obj
-@deffnx {C Function} scm_weak_vector_p (obj)
-Return @code{#t} if @var{obj} is a weak vector. Note that all
-weak hashes are also weak vectors.
-@end deffn
-
-
-@node Guardians
-@section Guardians
-
-@deffn {Scheme Procedure} make-guardian [greedy?]
-@deffnx {C Function} scm_make_guardian (greedy_p)
-Create a new guardian.
-A guardian protects a set of objects from garbage collection,
-allowing a program to apply cleanup or other actions.
-
-@code{make-guardian} returns a procedure representing the guardian.
-Calling the guardian procedure with an argument adds the
-argument to the guardian's set of protected objects.
-Calling the guardian procedure without an argument returns
-one of the protected objects which are ready for garbage
-collection, or @code{#f} if no such object is available.
-Objects which are returned in this way are removed from
-the guardian.
-
-@code{make-guardian} takes one optional argument that says whether the
-new guardian should be greedy or sharing. If there is any chance
-that any object protected by the guardian may be resurrected,
-then you should make the guardian greedy (this is the default).
-
-See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993)
-"Guardians in a Generation-Based Garbage Collector".
-ACM SIGPLAN Conference on Programming Language Design
-and Implementation, June 1993.
-
-(the semantics are slightly different at this point, but the
-paper still (mostly) accurately describes the interface).
-@end deffn
-
-@deffn {Scheme Procedure} destroy-guardian! guardian
-@deffnx {C Function} scm_destroy_guardian_x (guardian)
-Destroys @var{guardian}, by making it impossible to put any more
-objects in it or get any objects from it. It also unguards any
-objects guarded by @var{guardian}.
-@end deffn
-
-@deffn {Scheme Procedure} guardian-greedy? guardian
-@deffnx {C Function} scm_guardian_greedy_p (guardian)
-Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} guardian-destroyed? guardian
-@deffnx {C Function} scm_guardian_destroyed_p (guardian)
-Return @code{#t} if @var{guardian} has been destroyed, otherwise @code{#f}.
-@end deffn
-
-
-@page
-@node Objects
-@chapter Objects
-
-@deffn {Scheme Procedure} entity? obj
-@deffnx {C Function} scm_entity_p (obj)
-Return @code{#t} if @var{obj} is an entity.
-@end deffn
-
-@deffn {Scheme Procedure} operator? obj
-@deffnx {C Function} scm_operator_p (obj)
-Return @code{#t} if @var{obj} is an operator.
-@end deffn
-
-@deffn {Scheme Procedure} set-object-procedure! obj proc
-@deffnx {C Function} scm_set_object_procedure_x (obj, proc)
-Set the object procedure of @var{obj} to @var{proc}.
-@var{obj} must be either an entity or an operator.
-@end deffn
-
-@deffn {Scheme Procedure} make-class-object metaclass layout
-@deffnx {C Function} scm_make_class_object (metaclass, layout)
-Create a new class object of class @var{metaclass}, with the
-slot layout specified by @var{layout}.
-@end deffn
-
-@deffn {Scheme Procedure} make-subclass-object class layout
-@deffnx {C Function} scm_make_subclass_object (class, layout)
-Create a subclass object of @var{class}, with the slot layout
-specified by @var{layout}.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-modules.texi b/doc/ref/scheme-modules.texi
deleted file mode 100644
index c9279258c..000000000
--- a/doc/ref/scheme-modules.texi
+++ /dev/null
@@ -1,909 +0,0 @@
-@page
-@node Modules
-@chapter Modules
-@cindex modules
-
-When programs become large, naming conflicts can occur when a function
-or global variable defined in one file has the same name as a function
-or global variable in another file. Even just a @emph{similarity}
-between function names can cause hard-to-find bugs, since a programmer
-might type the wrong function name.
-
-The approach used to tackle this problem is called @emph{information
-encapsulation}, which consists of packaging functional units into a
-given name space that is clearly separated from other name spaces.
-@cindex encapsulation
-@cindex information encapsulation
-@cindex name space
-
-The language features that allow this are usually called @emph{the
-module system} because programs are broken up into modules that are
-compiled separately (or loaded separately in an interpreter).
-
-Older languages, like C, have limited support for name space
-manipulation and protection. In C a variable or function is public by
-default, and can be made local to a module with the @code{static}
-keyword. But you cannot reference public variables and functions from
-another module with different names.
-
-More advanced module systems have become a common feature in recently
-designed languages: ML, Python, Perl, and Modula 3 all allow the
-@emph{renaming} of objects from a foreign module, so they will not
-clutter the global name space.
-@cindex name space - private
-
-In addition, Guile offers variables as first-class objects. They can
-be used for interacting with the module system.
-
-@menu
-* provide and require:: The SLIB feature mechanism.
-* Environments:: R5RS top-level environments.
-* The Guile module system:: How Guile does it.
-* Dynamic Libraries:: Loading libraries of compiled code at run time.
-* Variables:: First-class variables.
-@end menu
-
-@node provide and require
-@section provide and require
-
-Aubrey Jaffer, mostly to support his portable Scheme library SLIB,
-implemented a provide/require mechanism for many Scheme implementations.
-Library files in SLIB @emph{provide} a feature, and when user programs
-@emph{require} that feature, the library file is loaded in.
-
-For example, the file @file{random.scm} in the SLIB package contains the
-line
-
-@smalllisp
-(provide 'random)
-@end smalllisp
-
-so to use its procedures, a user would type
-
-@smalllisp
-(require 'random)
-@end smalllisp
-
-and they would magically become available, @emph{but still have the same
-names!} So this method is nice, but not as good as a full-featured
-module system.
-
-When SLIB is used with Guile, provide and require can be used to access
-its facilities.
-
-@node Environments
-@section Environments
-@cindex environment
-
-Scheme, as defined in R5RS, does @emph{not} have a full module system.
-However it does define the concept of a top-level @dfn{environment}.
-Such an environment maps identifiers (symbols) to Scheme objects such
-as procedures and lists: @ref{About Closure}. In other words, it
-implements a set of @dfn{bindings}.
-
-Environments in R5RS can be passed as the second argument to
-@code{eval} (@pxref{Fly Evaluation}). Three procedures are defined to
-return environments: @code{scheme-report-environment},
-@code{null-environment} and @code{interaction-environment} (@pxref{Fly
-Evaluation}).
-
-In addition, in Guile any module can be used as an R5RS environment,
-i.e., passed as the second argument to @code{eval}.
-
-@deffn {Scheme Procedure} scheme-report-environment version
-@deffnx {Scheme Procedure} null-environment version
-@var{version} must be the exact integer `5', corresponding to revision
-5 of the Scheme report (the Revised^5 Report on Scheme).
-@code{scheme-report-environment} returns a specifier for an
-environment that is empty except for all bindings defined in the
-report that are either required or both optional and supported by the
-implementation. @code{null-environment} returns a specifier for an
-environment that is empty except for the (syntactic) bindings for all
-syntactic keywords defined in the report that are either required or
-both optional and supported by the implementation.
-
-Currently Guile does not support values of @var{version} for other
-revisions of the report.
-
-The effect of assigning (through the use of @code{eval}) a variable
-bound in a @code{scheme-report-environment} (for example @code{car})
-is unspecified. Currently the environments specified by
-@code{scheme-report-environment} are not immutable in Guile.
-@end deffn
-
-@node The Guile module system
-@section The Guile module system
-
-The Guile module system extends the concept of environments, discussed
-in the previous section, with mechanisms to define, use and customise
-sets of bindings.
-
-In 1996 Tom Lord implemented a full-featured module system for Guile which
-allows loading Scheme source files into a private name space. This system has
-been in available since at least Guile version 1.1.
-
-For Guile version 1.5.0 and later, the system has been improved to have better
-integration from C code, more fine-grained user control over interfaces, and
-documentation.
-
-Although it is anticipated that the module system implementation will
-change in the future, the Scheme programming interface described in this
-manual should be considered stable. The C programming interface is
-considered relatively stable, although at the time of this writing,
-there is still some flux.
-@c fixme: Review: Need better C code interface commentary.
-
-@menu
-* General Information about Modules:: Guile module basics.
-* Using Guile Modules:: How to use existing modules.
-* Creating Guile Modules:: How to package your code into modules.
-* More Module Procedures:: Low-level module code.
-* Module System Quirks:: Strange things to be aware of.
-* Included Guile Modules:: Which modules come with Guile?
-@end menu
-
-@node General Information about Modules
-@subsection General Information about Modules
-
-A Guile module can be thought of as a collection of named procedures,
-variables and macros. More precisely, it is a set of @dfn{bindings}
-of symbols (names) to Scheme objects.
-
-An environment is a mapping from identifiers (or symbols) to locations,
-i.e., a set of bindings.
-There are top-level environments and lexical environments.
-Environment in which a lambda is excuted is remembered as part of its
-definition.
-
-Within a module, all bindings are visible. Certain bindings
-can be declared @dfn{public}, in which case they are added to the
-module's so-called @dfn{export list}; this set of public bindings is
-called the module's @dfn{public interface} (@pxref{Creating Guile
-Modules}).
-
-A client module @dfn{uses} a providing module's bindings by either
-accessing the providing module's public interface, or by building a
-custom interface (and then accessing that). In a custom interface, the
-client module can @dfn{select} which bindings to access and can also
-algorithmically @dfn{rename} bindings. In contrast, when using the
-providing module's public interface, the entire export list is available
-without renaming (@pxref{Using Guile Modules}).
-
-To use a module, it must be found and loaded. All Guile modules have
-a unique @dfn{module name}, which is a list of one or more symbols.
-Examples are @code{(ice-9 popen)} or @code{(srfi srfi-11)}. When
-Guile searches for the code of a module, it constructs the name of the
-file to load by concatenating the name elements with slashes between
-the elements and appending a number of file name extensions from the
-list @code{%load-extensions} (@pxref{Loading}). The resulting file
-name is then searched in all directories in the variable
-@code{%load-path} (@pxref{Install Config}). For example, the
-@code{(ice-9 popen)} module would result in the filename
-@code{ice-9/popen.scm} and searched in the installation directories of
-Guile and in all other directories in the load path.
-
-@c FIXME::martin: Not sure about this, maybe someone knows better?
-Every module has a so-called syntax transformer associated with it.
-This is a procedure which performs all syntax transformation for the
-time the module is read in and evaluated. When working with modules,
-you can manipulate the current syntax transformer using the
-@code{use-syntax} syntactic form or the @code{#:use-syntax} module
-definition option (@pxref{Creating Guile Modules}).
-
-Please note that there are some problems with the current module system
-you should keep in mind (@pxref{Module System Quirks}). We hope to
-address these eventually.
-
-
-@node Using Guile Modules
-@subsection Using Guile Modules
-
-To use a Guile module is to access either its public interface or a
-custom interface (@pxref{General Information about Modules}). Both
-types of access are handled by the syntactic form @code{use-modules},
-which accepts one or more interface specifications and, upon
-evaluation, arranges for those interfaces to be available to the
-current module. This process may include locating and loading code
-for a given module if that code has not yet been loaded, following
-%load-path (@pxref{Install Config}).
-
-An @dfn{interface specification} has one of two forms. The first
-variation is simply to name the module, in which case its public
-interface is the one accessed. For example:
-
-@smalllisp
-(use-modules (ice-9 popen))
-@end smalllisp
-
-Here, the interface specification is @code{(ice-9 popen)}, and the
-result is that the current module now has access to @code{open-pipe},
-@code{close-pipe}, @code{open-input-pipe}, and so on (@pxref{Included
-Guile Modules}).
-
-Note in the previous example that if the current module had already
-defined @code{open-pipe}, that definition would be overwritten by the
-definition in @code{(ice-9 popen)}. For this reason (and others), there
-is a second variation of interface specification that not only names a
-module to be accessed, but also selects bindings from it and renames
-them to suit the current module's needs. For example:
-
-@smalllisp
-(use-modules ((ice-9 popen)
- :select ((open-pipe . pipe-open) close-pipe)
- :renamer (symbol-prefix-proc 'unixy:)))
-@end smalllisp
-
-Here, the interface specification is more complex than before, and the
-result is that a custom interface with only two bindings is created and
-subsequently accessed by the current module. The mapping of old to new
-names is as follows:
-
-@c Use `smallexample' since `table' is ugly. --ttn
-@smallexample
-(ice-9 popen) sees: current module sees:
-open-pipe unixy:pipe-open
-close-pipe unixy:close-pipe
-@end smallexample
-
-This example also shows how to use the convenience procedure
-@code{symbol-prefix-proc}.
-
-@c begin (scm-doc-string "boot-9.scm" "symbol-prefix-proc")
-@deffn {Scheme Procedure} symbol-prefix-proc prefix-sym
-Return a procedure that prefixes its arg (a symbol) with
-@var{prefix-sym}.
-@c Insert gratuitous C++ slam here. --ttn
-@end deffn
-
-@c begin (scm-doc-string "boot-9.scm" "use-modules")
-@deffn syntax use-modules spec @dots{}
-Resolve each interface specification @var{spec} into an interface and
-arrange for these to be accessible by the current module. The return
-value is unspecified.
-
-@var{spec} can be a list of symbols, in which case it names a module
-whose public interface is found and used.
-
-@var{spec} can also be of the form:
-
-@smalllisp
- (MODULE-NAME [:select SELECTION] [:renamer RENAMER])
-@end smalllisp
-
-in which case a custom interface is newly created and used.
-@var{module-name} is a list of symbols, as above; @var{selection} is a
-list of selection-specs; and @var{renamer} is a procedure that takes a
-symbol and returns its new name. A selection-spec is either a symbol or
-a pair of symbols @code{(ORIG . SEEN)}, where @var{orig} is the name in
-the used module and @var{seen} is the name in the using module. Note
-that @var{seen} is also passed through @var{renamer}.
-
-The @code{:select} and @code{:renamer} clauses are optional. If both are
-omitted, the returned interface has no bindings. If the @code{:select}
-clause is omitted, @var{renamer} operates on the used module's public
-interface.
-
-Signal error if module name is not resolvable.
-@end deffn
-
-
-@c FIXME::martin: Is this correct, and is there more to say?
-@c FIXME::martin: Define term and concept `system transformer' somewhere.
-
-@deffn syntax use-syntax module-name
-Load the module @code{module-name} and use its system
-transformer as the system transformer for the currently defined module,
-as well as installing it as the current system transformer.
-@end deffn
-
-
-@node Creating Guile Modules
-@subsection Creating Guile Modules
-
-When you want to create your own modules, you have to take the following
-steps:
-
-@itemize @bullet
-@item
-Create a Scheme source file and add all variables and procedures you wish
-to export, or which are required by the exported procedures.
-
-@item
-Add a @code{define-module} form at the beginning.
-
-@item
-Export all bindings which should be in the public interface, either
-by using @code{define-public} or @code{export} (both documented below).
-@end itemize
-
-@c begin (scm-doc-string "boot-9.scm" "define-module")
-@deffn syntax define-module module-name [options @dots{}]
-@var{module-name} is of the form @code{(hierarchy file)}. One
-example of this is
-
-@smalllisp
-(define-module (ice-9 popen))
-@end smalllisp
-
-@code{define-module} makes this module available to Guile programs under
-the given @var{module-name}.
-
-The @var{options} are keyword/value pairs which specify more about the
-defined module. The recognized options and their meaning is shown in
-the following table.
-
-@c fixme: Should we use "#:" or ":"?
-
-@table @code
-@item #:use-module @var{interface-specification}
-Equivalent to a @code{(use-modules @var{interface-specification})}
-(@pxref{Using Guile Modules}).
-
-@item #:use-syntax @var{module}
-Use @var{module} when loading the currently defined module, and install
-it as the syntax transformer.
-
-@item #:autoload @var{module} @var{symbol}
-Load @var{module} whenever @var{symbol} is accessed.
-
-@item #:export @var{list}
-Export all identifiers in @var{list}, which must be a list of symbols.
-This is equivalent to @code{(export @var{list})} in the module body.
-
-@item #:no-backtrace
-Tell Guile not to record information for procedure backtraces when
-executing the procedures in this module.
-
-@item #:pure
-Create a @dfn{pure} module, that is a module which does not contain any
-of the standard procedure bindings except for the syntax forms. This is
-useful if you want to create @dfn{safe} modules, that is modules which
-do not know anything about dangerous procedures.
-@end table
-
-@end deffn
-@c end
-
-@deffn syntax export variable @dots{}
-Add all @var{variable}s (which must be symbols) to the list of exported
-bindings of the current module.
-@end deffn
-
-@c begin (scm-doc-string "boot-9.scm" "define-public")
-@deffn syntax define-public @dots{}
-Equivalent to @code{(begin (define foo ...) (export foo))}.
-@end deffn
-@c end
-
-
-@node More Module Procedures
-@subsection More Module Procedures
-
-@c FIXME::martin: Review me!
-
-@c FIXME::martin: Should this procedure be documented and supported
-@c at all?
-
-The procedures in this section are useful if you want to dig into the
-innards of Guile's module system. If you don't know precisely what you
-do, you should probably avoid using any of them.
-
-@deffn {Scheme Procedure} standard-eval-closure module
-@deffnx {C Function} scm_standard_eval_closure (module)
-Return an eval closure for the module @var{module}.
-@end deffn
-
-
-@node Module System Quirks
-@subsection Module System Quirks
-
-Although the programming interfaces are relatively stable, the Guile
-module system itself is still evolving. Here are some situations where
-usage surpasses design.
-
-@itemize @bullet
-
-@item
-When using a module which exports a macro definition, the other module
-must export all bindings the macro expansion uses, too, because the
-expanded code would otherwise not be able to see these definitions and
-issue a ``variable unbound'' error, or worse, would use another binding
-which might be present in the scope of the expansion.
-
-@item
-When two or more used modules export bindings with the same names, the
-last accessed module wins, and the exported binding of that last module
-will silently be used. This might lead to hard-to-find errors because
-wrong procedures or variables are used. To avoid this kind of
-@dfn{name-clash} situation, use a custom interface specification
-(@pxref{Using Guile Modules}). (We include this entry for the possible
-benefit of users of Guile versions previous to 1.5.0, when custom
-interfaces were added to the module system.)
-
-@item
-[Add other quirks here.]
-
-@end itemize
-
-
-@node Included Guile Modules
-@subsection Included Guile Modules
-
-@c FIXME::martin: Review me!
-
-Some modules are included in the Guile distribution; here are references
-to the entries in this manual which describe them in more detail:
-
-@table @strong
-@item boot-9
-boot-9 is Guile's initialization module, and it is always loaded when
-Guile starts up.
-
-@item (ice-9 debug)
-Mikael Djurfeldt's source-level debugging support for Guile
-(@pxref{Debugging Features}).
-
-@item (ice-9 threads)
-Guile's support for multi threaded execution (@pxref{Scheduling}).
-
-@item (ice-9 rdelim)
-Line- and character-delimited input (@pxref{Line/Delimited}).
-
-@item (ice-9 rw)
-Block string input/output (@pxref{Block Reading and Writing}).
-
-@item (ice-9 documentation)
-Online documentation (REFFIXME).
-
-@item (srfi srfi-1)
-A library providing a lot of useful list and pair processing
-procedures (@pxref{SRFI-1}).
-
-@item (srfi srfi-2)
-Support for @code{and-let*} (@pxref{SRFI-2}).
-
-@item (srfi srfi-4)
-Support for homogeneous numeric vectors (@pxref{SRFI-4}).
-
-@item (srfi srfi-6)
-Support for some additional string port procedures (@pxref{SRFI-6}).
-
-@item (srfi srfi-8)
-Multiple-value handling with @code{receive} (@pxref{SRFI-8}).
-
-@item (srfi srfi-9)
-Record definition with @code{define-record-type} (@pxref{SRFI-9}).
-
-@item (srfi srfi-10)
-Read hash extension @code{#,()} (@pxref{SRFI-10}).
-
-@item (srfi srfi-11)
-Multiple-value handling with @code{let-values} and @code{let-values*}
-(@pxref{SRFI-11}).
-
-@item (srfi srfi-13)
-String library (@pxref{SRFI-13}).
-
-@item (srfi srfi-14)
-Character-set library (@pxref{SRFI-14}).
-
-@item (srfi srfi-17)
-Getter-with-setter support (@pxref{SRFI-17}).
-
-@item (ice-9 slib)
-This module contains hooks for using Aubrey Jaffer's portable Scheme
-library SLIB from Guile (@pxref{SLIB}).
-
-@c FIXME::martin: This module is not in the distribution. Remove it
-@c from here?
-@item (ice-9 jacal)
-This module contains hooks for using Aubrey Jaffer's symbolic math
-package Jacal from Guile (@pxref{JACAL}).
-@end table
-
-
-@node Dynamic Libraries
-@section Dynamic Libraries
-
-Most modern Unices have something called @dfn{shared libraries}. This
-ordinarily means that they have the capability to share the executable
-image of a library between several running programs to save memory and
-disk space. But generally, shared libraries give a lot of additional
-flexibility compared to the traditional static libraries. In fact,
-calling them `dynamic' libraries is as correct as calling them `shared'.
-
-Shared libraries really give you a lot of flexibility in addition to the
-memory and disk space savings. When you link a program against a shared
-library, that library is not closely incorporated into the final
-executable. Instead, the executable of your program only contains
-enough information to find the needed shared libraries when the program
-is actually run. Only then, when the program is starting, is the final
-step of the linking process performed. This means that you need not
-recompile all programs when you install a new, only slightly modified
-version of a shared library. The programs will pick up the changes
-automatically the next time they are run.
-
-Now, when all the necessary machinery is there to perform part of the
-linking at run-time, why not take the next step and allow the programmer
-to explicitly take advantage of it from within his program? Of course,
-many operating systems that support shared libraries do just that, and
-chances are that Guile will allow you to access this feature from within
-your Scheme programs. As you might have guessed already, this feature
-is called @dfn{dynamic linking}@footnote{Some people also refer to the
-final linking stage at program startup as `dynamic linking', so if you
-want to make yourself perfectly clear, it is probably best to use the
-more technical term @dfn{dlopening}, as suggested by Gordon Matzigkeit
-in his libtool documentation.}
-
-As with many aspects of Guile, there is a low-level way to access the
-dynamic linking apparatus, and a more high-level interface that
-integrates dynamically linked libraries into the module system.
-
-@menu
-* Low level dynamic linking::
-* Compiled Code Modules::
-* Dynamic Linking and Compiled Code Modules::
-@end menu
-
-@node Low level dynamic linking
-@subsection Low level dynamic linking
-
-When using the low level procedures to do your dynamic linking, you have
-complete control over which library is loaded when and what gets done
-with it.
-
-@deffn {Scheme Procedure} dynamic-link filename
-@deffnx {C Function} scm_dynamic_link (filename)
-Find the shared object (shared library) denoted by
-@var{filename} and link it into the running Guile
-application. The returned
-scheme object is a ``handle'' for the library which can
-be passed to @code{dynamic-func}, @code{dynamic-call} etc.
-
-Searching for object files is system dependent. Normally,
-if @var{filename} does have an explicit directory it will
-be searched for in locations
-such as @file{/usr/lib} and @file{/usr/local/lib}.
-@end deffn
-
-@deffn {Scheme Procedure} dynamic-object? obj
-@deffnx {C Function} scm_dynamic_object_p (obj)
-Return @code{#t} if @var{obj} is a dynamic object handle,
-or @code{#f} otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} dynamic-unlink dobj
-@deffnx {C Function} scm_dynamic_unlink (dobj)
-Unlink a dynamic object from the application, if possible. The
-object must have been linked by @code{dynamic-link}, with
-@var{dobj} the corresponding handle. After this procedure
-is called, the handle can no longer be used to access the
-object.
-@end deffn
-
-@deffn {Scheme Procedure} dynamic-func name dobj
-@deffnx {C Function} scm_dynamic_func (name, dobj)
-Return a ``handle'' for the function @var{name} in the
-shared object referred to by @var{dobj}. The handle
-can be passed to @code{dynamic-call} to actually
-call the function.
-
-Regardless whether your C compiler prepends an underscore
-@samp{_} to the global names in a program, you should
-@strong{not} include this underscore in @var{name}
-since it will be added automatically when necessary.
-@end deffn
-
-@deffn {Scheme Procedure} dynamic-call func dobj
-@deffnx {C Function} scm_dynamic_call (func, dobj)
-Call a C function in a dynamic object. Two styles of
-invocation are supported:
-
-@itemize @bullet
-@item @var{func} can be a function handle returned by
-@code{dynamic-func}. In this case @var{dobj} is
-ignored
-@item @var{func} can be a string with the name of the
-function to call, with @var{dobj} the handle of the
-dynamic object in which to find the function.
-This is equivalent to
-@smallexample
-
-(dynamic-call (dynamic-func @var{func} @var{dobj}) #f)
-@end smallexample
-@end itemize
-
-In either case, the function is passed no arguments
-and its return value is ignored.
-@end deffn
-
-@deffn {Scheme Procedure} dynamic-args-call func dobj args
-@deffnx {C Function} scm_dynamic_args_call (func, dobj, args)
-Call the C function indicated by @var{func} and @var{dobj},
-just like @code{dynamic-call}, but pass it some arguments and
-return its return value. The C function is expected to take
-two arguments and return an @code{int}, just like @code{main}:
-@smallexample
-int c_func (int argc, char **argv);
-@end smallexample
-
-The parameter @var{args} must be a list of strings and is
-converted into an array of @code{char *}. The array is passed
-in @var{argv} and its size in @var{argc}. The return value is
-converted to a Scheme number and returned from the call to
-@code{dynamic-args-call}.
-@end deffn
-
-Here is a small example that may work on GNU/Linux:
-
-@smallexample
-(define libc-obj (dynamic-link "libc.so"))
-libc-obj
-@result{} #<dynamic-object "libc.so">
-(dynamic-args-call 'rand libc-obj '())
-@result{} 269167349
-(dynamic-unlink libc-obj)
-libc-obj
-@result{} #<dynamic-object "libc.so" (unlinked)>
-@end smallexample
-
-As you can see, after calling @code{dynamic-unlink} on a dynamically
-linked library, it is marked as @samp{(unlinked)} and you are no longer
-able to use it with @code{dynamic-call}, etc. Whether the library is
-really removed from you program is system-dependent and will generally
-not happen when some other parts of your program still use it. In the
-example above, @code{libc} is almost certainly not removed from your
-program because it is badly needed by almost everything.
-
-The functions to call a function from a dynamically linked library,
-@code{dynamic-call} and @code{dynamic-args-call}, are not very powerful.
-They are mostly intended to be used for calling specially written
-initialization functions that will then add new primitives to Guile.
-For example, we do not expect that you will dynamically link
-@file{libX11} with @code{dynamic-link} and then construct a beautiful
-graphical user interface just by using @code{dynamic-call} and
-@code{dynamic-args-call}. Instead, the usual way would be to write a
-special Guile<->X11 glue library that has intimate knowledge about both
-Guile and X11 and does whatever is necessary to make them inter-operate
-smoothly. This glue library could then be dynamically linked into a
-vanilla Guile interpreter and activated by calling its initialization
-function. That function would add all the new types and primitives to
-the Guile interpreter that it has to offer.
-
-From this setup the next logical step is to integrate these glue
-libraries into the module system of Guile so that you can load new
-primitives into a running system just as you can load new Scheme code.
-
-There is, however, another possibility to get a more thorough access to
-the functions contained in a dynamically linked library. Anthony Green
-has written @file{libffi}, a library that implements a @dfn{foreign
-function interface} for a number of different platforms. With it, you
-can extend the Spartan functionality of @code{dynamic-call} and
-@code{dynamic-args-call} considerably. There is glue code available in
-the Guile contrib archive to make @file{libffi} accessible from Guile.
-
-@node Compiled Code Modules
-@subsection Putting Compiled Code into Modules
-
-@c FIXME::martin: Change all gh_ references to their scm_ equivalents.
-
-The new primitives that you add to Guile with @code{gh_new_procedure}
-or with any of the other mechanisms are normally placed into the same
-module as all the other builtin procedures (like @code{display}).
-However, it is also possible to put new primitives into their own
-module.
-
-The mechanism for doing so is not very well thought out and is likely to
-change when the module system of Guile itself is revised, but it is
-simple and useful enough to document it as it stands.
-
-What @code{gh_new_procedure} and the functions used by the snarfer
-really do is to add the new primitives to whatever module is the
-@emph{current module} when they are called. This is analogous to the
-way Scheme code is put into modules: the @code{define-module} expression
-at the top of a Scheme source file creates a new module and makes it the
-current module while the rest of the file is evaluated. The
-@code{define} expressions in that file then add their new definitions to
-this current module.
-
-Therefore, all we need to do is to make sure that the right module is
-current when calling @code{gh_new_procedure} for our new primitives.
-
-@node Dynamic Linking and Compiled Code Modules
-@subsection Dynamic Linking and Compiled Code Modules
-
-The most interesting application of dynamically linked libraries is
-probably to use them for providing @emph{compiled code modules} to
-Scheme programs. As much fun as programming in Scheme is, every now and
-then comes the need to write some low-level C stuff to make Scheme even
-more fun.
-
-Not only can you put these new primitives into their own module (see the
-previous section), you can even put them into a shared library that is
-only then linked to your running Guile image when it is actually
-needed.
-
-An example will hopefully make everything clear. Suppose we want to
-make the Bessel functions of the C library available to Scheme in the
-module @samp{(math bessel)}. First we need to write the appropriate
-glue code to convert the arguments and return values of the functions
-from Scheme to C and back. Additionally, we need a function that will
-add them to the set of Guile primitives. Because this is just an
-example, we will only implement this for the @code{j0} function.
-
-@c FIXME::martin: Change all gh_ references to their scm_ equivalents.
-
-@smallexample
-#include <math.h>
-#include <guile/gh.h>
-
-SCM
-j0_wrapper (SCM x)
-@{
- return gh_double2scm (j0 (gh_scm2double (x)));
-@}
-
-void
-init_math_bessel ()
-@{
- gh_new_procedure1_0 ("j0", j0_wrapper);
-@}
-@end smallexample
-
-We can already try to bring this into action by manually calling the low
-level functions for performing dynamic linking. The C source file needs
-to be compiled into a shared library. Here is how to do it on
-GNU/Linux, please refer to the @code{libtool} documentation for how to
-create dynamically linkable libraries portably.
-
-@smallexample
-gcc -shared -o libbessel.so -fPIC bessel.c
-@end smallexample
-
-Now fire up Guile:
-
-@smalllisp
-(define bessel-lib (dynamic-link "./libbessel.so"))
-(dynamic-call "init_math_bessel" bessel-lib)
-(j0 2)
-@result{} 0.223890779141236
-@end smalllisp
-
-The filename @file{./libbessel.so} should be pointing to the shared
-library produced with the @code{gcc} command above, of course. The
-second line of the Guile interaction will call the
-@code{init_math_bessel} function which in turn will register the C
-function @code{j0_wrapper} with the Guile interpreter under the name
-@code{j0}. This function becomes immediately available and we can call
-it from Scheme.
-
-Fun, isn't it? But we are only half way there. This is what
-@code{apropos} has to say about @code{j0}:
-
-@smallexample
-(apropos 'j0)
-@print{} the-root-module: j0 #<primitive-procedure j0>
-@end smallexample
-
-As you can see, @code{j0} is contained in the root module, where all
-the other Guile primitives like @code{display}, etc live. In general,
-a primitive is put into whatever module is the @dfn{current module} at
-the time @code{gh_new_procedure} is called.
-
-A compiled module should have a specially named @dfn{module init
-function}. Guile knows about this special name and will call that
-function automatically after having linked in the shared library. For
-our example, we add the following code to @file{bessel.c}:
-
-@smallexample
-void scm_init_math_bessel_module ()
-@{
- /* contents currently unavailable. */
-@}
-@end smallexample
-
-The general pattern for the name of a module init function is:
-@samp{scm_init_}, followed by the name of the module where the
-individual hierarchical components are concatenated with underscores,
-followed by @samp{_module}.
-
-After @file{libbessel.so} has been rebuild, we need to place the shared
-library into the right place.
-
-Once the module has been correctly installed, it should be possible to
-use it like this:
-
-@smallexample
-guile> (use-modules (math bessel))
-guile> (j0 2)
-0.223890779141236
-guile> (apropos 'j0)
-@print{} bessel: j0 #<primitive-procedure j0>
-@end smallexample
-
-That's it!
-
-@node Variables
-@section Variables
-@tpindex Variables
-
-Each module has its own hash table, sometimes known as an @dfn{obarray},
-that maps the names defined in that module to their corresponding
-variable objects.
-
-A variable is a box-like object that can hold any Scheme value. It is
-said to be @dfn{undefined} if its box holds a special Scheme value that
-denotes undefined-ness (which is different from all other Scheme values,
-including for example @code{#f}); otherwise the variable is
-@dfn{defined}.
-
-On its own, a variable object is anonymous. A variable is said to be
-@dfn{bound} when it is associated with a name in some way, usually a
-symbol in a module obarray. When this happens, the relationship is
-mutual: the variable is bound to the name (in that module), and the name
-(in that module) is bound to the variable.
-
-(That's the theory, anyway. In practice, defined-ness and bound-ness
-sometimes get confused, because Lisp and Scheme implementations have
-often conflated --- or deliberately drawn no distinction between --- a
-name that is unbound and a name that is bound to a variable whose value
-is undefined. We will try to be clear about the difference and explain
-any confusion where it is unavoidable.)
-
-Variables do not have a read syntax. Most commonly they are created and
-bound implicitly by @code{define} expressions: a top-level @code{define}
-expression of the form
-
-@lisp
-(define @var{name} @var{value})
-@end lisp
-
-@noindent
-creates a variable with initial value @var{value} and binds it to the
-name @var{name} in the current module. But they can also be created
-dynamically by calling one of the constructor procedures
-@code{make-variable} and @code{make-undefined-variable}.
-
-First-class variables are especially useful for interacting with the
-current module system (@pxref{The Guile module system}).
-
-@deffn {Scheme Procedure} make-undefined-variable
-@deffnx {C Function} scm_make_undefined_variable ()
-Return a variable that is initially unbound.
-@end deffn
-
-@deffn {Scheme Procedure} make-variable init
-@deffnx {C Function} scm_make_variable (init)
-Return a variable initialized to value @var{init}.
-@end deffn
-
-@deffn {Scheme Procedure} variable-bound? var
-@deffnx {C Function} scm_variable_bound_p (var)
-Return @code{#t} iff @var{var} is bound to a value.
-Throws an error if @var{var} is not a variable object.
-@end deffn
-
-@deffn {Scheme Procedure} variable-ref var
-@deffnx {C Function} scm_variable_ref (var)
-Dereference @var{var} and return its value.
-@var{var} must be a variable object; see @code{make-variable}
-and @code{make-undefined-variable}.
-@end deffn
-
-@deffn {Scheme Procedure} variable-set! var val
-@deffnx {C Function} scm_variable_set_x (var, val)
-Set the value of the variable @var{var} to @var{val}.
-@var{var} must be a variable object, @var{val} can be any
-value. Return an unspecified value.
-@end deffn
-
-@deffn {Scheme Procedure} variable? obj
-@deffnx {C Function} scm_variable_p (obj)
-Return @code{#t} iff @var{obj} is a variable object, else
-return @code{#f}.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-options.texi b/doc/ref/scheme-options.texi
deleted file mode 100644
index 63b7a2c57..000000000
--- a/doc/ref/scheme-options.texi
+++ /dev/null
@@ -1,651 +0,0 @@
-@page
-@node Options and Config
-@chapter Runtime Options and Configuration
-
-Guile's behaviour can be modified by setting options. For example, is
-the language that Guile accepts case sensitive, or should the debugger
-automatically show a backtrace on error?
-
-Guile has two levels of interface for managing options: a low-level
-control interface, and a user-level interface which allows the enabling
-or disabling of options.
-
-Moreover, the options are classified in groups according to whether they
-configure @emph{reading}, @emph{printing}, @emph{debugging} or
-@emph{evaluating}.
-
-@menu
-* General option interface::
-* Reader options::
-* Printing options::
-* Debugger options::
-* Evaluator options::
-* Evaluator trap options::
-* Examples of option use::
-* Install Config:: Installation and configuration data.
-* Feature Tracking:: Available features in the Guile process.
-@end menu
-
-@node General option interface
-@section General option interface
-
-We will use the expression @code{<group>} to represent @code{read},
-@code{print}, @code{debug} or @code{evaluator}.
-
-@subheading Low level
-
-@c NJFIXME
-@deffn {Scheme Procedure} <group>-options-interface
-@deffnx {Scheme Procedure} read-options-interface [SOME-INT]
-@deffnx {Scheme Procedure} print-options-interface [SOME-INT]
-@deffnx {Scheme Procedure} evaluator-traps-interface [SOME-INT]
-@deffnx {Scheme Procedure} read-options-interface [SOME-INT]
-[FIXME: I have just taken the comments for C routine scm_options that
-implements all of these. It needs to be presented better.]
-
-If scm_options is called without arguments, the current option setting
-is returned. If the argument is an option setting, options are altered
-and the old setting is returned. If the argument isn't a list, a list
-of sublists is returned, where each sublist contains option name, value
-and documentation string.
-@end deffn
-
-
-@subheading User level
-
-@c @deftp {Data type} scm_option
-@c @code{scm_option} is used to represent run time options. It can be a
-@c @emph{boolean} type, in which case the option will be set by the strings
-@c @code{"yes"} and @code{"no"}. It can be a
-@c @end deftp
-
-@c NJFIXME
-@deffn {Scheme Procedure} <group>-options [arg]
-@deffnx {Scheme Procedure} read-options [arg]
-@deffnx {Scheme Procedure} print-options [arg]
-@deffnx {Scheme Procedure} debug-options [arg]
-@deffnx {Scheme Procedure} traps [arg]
-These functions list the options in their group. The optional argument
-@var{arg} is a symbol which modifies the form in which the options are
-presented.
-
-With no arguments, @code{<group>-options} returns the values of the
-options in that particular group. If @var{arg} is @code{'help}, a
-description of each option is given. If @var{arg} is @code{'full},
-programmers' options are also shown.
-
-@var{arg} can also be a list representing the state of all options. In
-this case, the list contains single symbols (for enabled boolean
-options) and symbols followed by values.
-@end deffn
-[FIXME: I don't think 'full is ever any different from 'help. What's
-up?]
-
-@c NJFIXME
-@deffn {Scheme Procedure} <group>-enable option-symbol
-@deffnx {Scheme Procedure} read-enable option-symbol
-@deffnx {Scheme Procedure} print-enable option-symbol
-@deffnx {Scheme Procedure} debug-enable option-symbol
-@deffnx {Scheme Procedure} trap-enable option-symbol
-These functions set the specified @var{option-symbol} in their options
-group. They only work if the option is boolean, and throw an error
-otherwise.
-@end deffn
-
-@c NJFIXME
-@deffn {Scheme Procedure} <group>-disable option-symbol
-@deffnx {Scheme Procedure} read-disable option-symbol
-@deffnx {Scheme Procedure} print-disable option-symbol
-@deffnx {Scheme Procedure} debug-disable option-symbol
-@deffnx {Scheme Procedure} trap-disable option-symbol
-These functions turn off the specified @var{option-symbol} in their
-options group. They only work if the option is boolean, and throw an
-error otherwise.
-@end deffn
-
-@c NJFIXME
-@deffn syntax <group>-set! option-symbol value
-@deffnx syntax read-set! option-symbol value
-@deffnx syntax print-set! option-symbol value
-@deffnx syntax debug-set! option-symbol value
-@deffnx syntax trap-set! option-symbol value
-These functions set a non-boolean @var{option-symbol} to the specified
-@var{value}.
-@end deffn
-
-
-@node Reader options
-@section Reader options
-@cindex options - read
-@cindex read options
-
-Here is the list of reader options generated by typing
-@code{(read-options 'full)} in Guile. You can also see the default
-values.
-
-@smalllisp
-keywords #f Style of keyword recognition: #f or 'prefix
-case-insensitive no Convert symbols to lower case.
-positions yes Record positions of source code expressions.
-copy no Copy source code expressions.
-@end smalllisp
-
-Notice that while Standard Scheme is case insensitive, to ease
-translation of other Lisp dialects, notably Emacs Lisp, into Guile,
-Guile is case-sensitive by default.
-
-To make Guile case insensitive, you can type
-
-@smalllisp
-(read-enable 'case-insensitive)
-@end smalllisp
-
-@node Printing options
-@section Printing options
-
-Here is the list of print options generated by typing
-@code{(print-options 'full)} in Guile. You can also see the default
-values.
-
-@smallexample
-source no Print closures with source.
-closure-hook #f Hook for printing closures.
-@end smallexample
-
-
-@node Evaluator options
-@section Evaluator options
-
-These are the evaluator options with their default values, as they are
-printed by typing @code{(eval-options 'full)} in Guile.
-
-@smallexample
-stack 22000 Size of thread stacks (in machine words).
-@end smallexample
-
-@node Evaluator trap options
-@section Evaluator trap options
-[FIXME: These flags, together with their corresponding handlers, are not
-user level options. Probably this entire section should be moved to the
-documentation about the low-level programmer debugging interface.]
-
-Here is the list of evaluator trap options generated by typing
-@code{(traps 'full)} in Guile. You can also see the default values.
-
-@smallexample
-exit-frame no Trap when exiting eval or apply.
-apply-frame no Trap when entering apply.
-enter-frame no Trap when eval enters new frame.
-traps yes Enable evaluator traps.
-@end smallexample
-
-@deffn apply-frame-handler key cont tailp
-Called when a procedure is being applied.
-
-Called if:
-
-@itemize @bullet
-@item
-evaluator traps are enabled [traps interface], and
-@item
-either
-@itemize @minus
-@item
-@code{apply-frame} is enabled [traps interface], or
-@item
-trace mode is on [debug-options interface], and the procedure being
-called has the trace property enabled.
-@end itemize
-@end itemize
-
-If cheap traps are enabled [debug-options interface], @var{cont} is a
-debug object, otherwise it is a restartable continuation.
-
-@var{tailp} is true if this is a tail call
-@end deffn
-
-@deffn exit-frame-handler key cont retval
-Called when a value is returned from a procedure.
-
-Called if:
-
-@itemize @bullet
-@item
-evaluator traps are enabled [traps interface], and
-@item
-either
-@itemize @minus
-@item
- @code{exit-frame} is enabled [traps interface], or
-@item
-trace mode is on [debug-options interface], and the procedure being
-called has the trace property enabled.
-@end itemize
-@end itemize
-
-If cheap traps are enabled [debug-options interface], @var{cont} is a
-debug object, otherwise it is a restartable continuation.
-
-@var{retval} is the return value.
-@end deffn
-
-@node Debugger options
-@section Debugger options
-
-Here is the list of print options generated by typing
-@code{(debug-options 'full)} in Guile. You can also see the default
-values.
-
-@smallexample
-stack 20000 Stack size limit (0 = no check).
-debug yes Use the debugging evaluator.
-backtrace no Show backtrace on error.
-depth 20 Maximal length of printed backtrace.
-maxdepth 1000 Maximal number of stored backtrace frames.
-frames 3 Maximum number of tail-recursive frames in backtrace.
-indent 10 Maximal indentation in backtrace.
-backwards no Display backtrace in anti-chronological order.
-procnames yes Record procedure names at definition.
-trace no *Trace mode.
-breakpoints no *Check for breakpoints.
-cheap yes *Flyweight representation of the stack at traps.
-@end smallexample
-
-@subsection Stack overflow
-
-@cindex overflow, stack
-@cindex stack overflow
-Stack overflow errors are caused by a computation trying to use more
-stack space than has been enabled by the @code{stack} option. They are
-reported like this:
-
-@lisp
-(non-tail-recursive-factorial 500)
-@print{}
-ERROR: Stack overflow
-ABORT: (stack-overflow)
-@end lisp
-
-If you get an error like this, you can either try rewriting your code to
-use less stack space, or increase the maximum stack size. To increase
-the maximum stack size, use @code{debug-set!}, for example:
-
-@lisp
-(debug-set! stack 200000)
-@result{}
-(show-file-name #t stack 200000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)
-
-(non-tail-recursive-factorial 500)
-@result{}
-122013682599111006870123878542304692625357434@dots{}
-@end lisp
-
-If you prefer to try rewriting your code, you may be able to save stack
-space by making some of your procedures @dfn{tail recursive}. For a
-description of what this means, see @ref{Proper tail
-recursion,,,r5rs,The Revised^5 Report on Scheme}.
-
-
-@node Examples of option use
-@section Examples of option use
-
-Here is an example of a session in which some read and debug option
-handling procedures are used. In this example, the user
-
-@enumerate
-@item
-Notices that the symbols @code{abc} and @code{aBc} are not the same
-@item
-Examines the @code{read-options}, and sees that @code{case-insensitive}
-is set to ``no''.
-@item
-Enables @code{case-insensitive}
-@item
-Verifies that now @code{aBc} and @code{abc} are the same
-@item
-Disables @code{case-insensitive} and enables debugging @code{backtrace}
-@item
-Reproduces the error of displaying @code{aBc} with backtracing enabled
-[FIXME: this last example is lame because there is no depth in the
-backtrace. Need to give a better example, possibly putting debugging
-option examples in a separate session.]
-@end enumerate
-
-
-@smalllisp
-guile> (define abc "hello")
-guile> abc
-"hello"
-guile> aBc
-ERROR: In expression aBc:
-ERROR: Unbound variable: aBc
-ABORT: (misc-error)
-
-Type "(backtrace)" to get more information.
-guile> (read-options 'help)
-keywords #f Style of keyword recognition: #f or 'prefix
-case-insensitive no Convert symbols to lower case.
-positions yes Record positions of source code expressions.
-copy no Copy source code expressions.
-guile> (debug-options 'help)
-stack 20000 Stack size limit (0 = no check).
-debug yes Use the debugging evaluator.
-backtrace no Show backtrace on error.
-depth 20 Maximal length of printed backtrace.
-maxdepth 1000 Maximal number of stored backtrace frames.
-frames 3 Maximum number of tail-recursive frames in backtrace.
-indent 10 Maximal indentation in backtrace.
-backwards no Display backtrace in anti-chronological order.
-procnames yes Record procedure names at definition.
-trace no *Trace mode.
-breakpoints no *Check for breakpoints.
-cheap yes *Flyweight representation of the stack at traps.
-guile> (read-enable 'case-insensitive)
-(keywords #f case-insensitive positions)
-guile> aBc
-"hello"
-guile> (read-disable 'case-insensitive)
-(keywords #f positions)
-guile> (debug-enable 'backtrace)
-(stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap)
-guile> aBc
-
-Backtrace:
-0* aBc
-
-ERROR: In expression aBc:
-ERROR: Unbound variable: aBc
-ABORT: (misc-error)
-guile>
-@end smalllisp
-
-
-@node Install Config
-@section Installation and Configuration Data
-
-It is often useful to have site-specific information about the current
-Guile installation. This chapter describes how to find out about
-Guile's configuration at run time.
-
-@deffn {Scheme Procedure} version
-@deffnx {Scheme Procedure} major-version
-@deffnx {Scheme Procedure} minor-version
-@deffnx {Scheme Procedure} micro-version
-@deffnx {C Function} scm_version ()
-@deffnx {C Function} scm_major_version ()
-@deffnx {C Function} scm_minor_version ()
-@deffnx {C Function} scm_micro_version ()
-Return a string describing Guile's version number, or its major, minor
-or micro version number, respectively.
-
-@lisp
-(version) @result{} "1.6.0"
-(major-version) @result{} "1"
-(minor-version) @result{} "6"
-(micro-version) @result{} "0"
-@end lisp
-@end deffn
-
-@c NJFIXME not in libguile!
-@deffn {Scheme Procedure} libguile-config-stamp
-Return a string describing the date on which @code{libguile} was
-configured. This is used to determine whether the Guile core
-interpreter and the ice-9 runtime have grown out of date with one
-another.
-@end deffn
-
-@deffn {Scheme Procedure} %package-data-dir
-@deffnx {C Function} scm_sys_package_data_dir ()
-Return the name of the directory where Scheme packages, modules and
-libraries are kept. On most Unix systems, this will be
-@samp{/usr/local/share/guile}.
-@end deffn
-
-@deffn {Scheme Procedure} %library-dir
-@deffnx {C Function} scm_sys_library_dir ()
-Return the directory where the Guile Scheme library files are installed.
-E.g., may return "/usr/share/guile/1.3.5".
-@end deffn
-
-@deffn {Scheme Procedure} %site-dir
-@deffnx {C Function} scm_sys_site_dir ()
-Return the directory where the Guile site files are installed.
-E.g., may return "/usr/share/guile/site".
-@end deffn
-
-@deffn {Scheme Procedure} parse-path path [tail]
-@deffnx {C Function} scm_parse_path (path, tail)
-Parse @var{path}, which is expected to be a colon-separated
-string, into a list and return the resulting list with
-@var{tail} appended. If @var{path} is @code{#f}, @var{tail}
-is returned.
-@end deffn
-
-@deffn {Scheme Procedure} search-path path filename [extensions]
-@deffnx {C Function} scm_search_path (path, filename, extensions)
-Search @var{path} for a directory containing a file named
-@var{filename}. The file must be readable, and not a directory.
-If we find one, return its full filename; otherwise, return
-@code{#f}. If @var{filename} is absolute, return it unchanged.
-If given, @var{extensions} is a list of strings; for each
-directory in @var{path}, we search for @var{filename}
-concatenated with each @var{extension}.
-@end deffn
-
-@defvar %load-path
-List of directories which should be searched for Scheme
-modules and libraries.
-@end defvar
-
-@defvar %guile-build-info
-Alist of information collected during the building of a particular
-@code{guile} program. Entries can be grouped into one of several
-categories: directories, env vars, and versioning info.
-
-Briefly, here are the keys in @code{%guile-build-info}, by group:
-@itemize @bullet
-@item directories
-srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir, libexecdir,
-datadir, sysconfdir, sharedstatedir, localstatedir, libdir, infodir,
-mandir, includedir, pkgdatadir, pkglibdir, pkgincludedir
-@item env vars
-LIBS
-@item versioning info
-guileversion, libguileinterface, buildstamp
-@end itemize
-
-Values are all strings. The value for @code{LIBS} is typically found also as
-a part of "guile-config link" output. The value for @code{guileversion} has
-form X.Y.Z, and should be the same as returned by @code{version}. The value
-for @code{libguileinterface} is libtool compatible and has form
-CURRENT:REVISION:AGE. The value for @code{buildstamp} is the output of the
-date(1) command.
-
-In the source, @code{%guile-build-info} is initialized from
-libguile/libpath.h, which is completely generated, so deleting this file
-before a build guarantees up-to-date values for that build.
-@end defvar
-
-
-@node Feature Tracking
-@section Feature Tracking
-
-Guile has a Scheme level variable @code{*features*} that keeps track to
-some extent of the features that are available in a running Guile.
-@code{*features*} is a list of symbols, for example @code{threads}, each
-of which describes a feature of the running Guile process.
-
-@defvar *features*
-A list of symbols describing available features of the Guile process.
-@end defvar
-
-You shouldn't modify the @code{*features*} variable directly using
-@code{set!}. Instead, see the procedures that are provided for this
-purpose in the following subsection.
-
-@menu
-* Feature Manipulation:: Checking for and advertising features.
-* Common Feature Symbols:: Commonly available features.
-@end menu
-
-
-@node Feature Manipulation
-@subsection Feature Manipulation
-
-To check whether a particular feature is available, use the
-@code{provided?} procedure:
-
-@deffn {Scheme Procedure} provided? feature
-@deffnx {Deprecated Scheme Procedure} feature? feature
-Return @code{#t} if the specified @var{feature} is available, otherwise
-@code{#f}.
-@end deffn
-
-To advertise a feature from your own Scheme code, you can use the
-@code{provide} procedure:
-
-@deffn {Scheme Procedure} provide feature
-Add @var{feature} to the list of available features in this Guile
-process.
-@end deffn
-
-For C code, the equivalent function takes its feature name as a
-@code{char *} argument for convenience:
-
-@deftypefn {C Function} void scm_add_feature (const char *str)
-Add a symbol with name @var{str} to the list of available features in
-this Guile process.
-@end deftypefn
-
-
-@node Common Feature Symbols
-@subsection Common Feature Symbols
-
-In general, a particular feature may be available for one of two
-reasons. Either because the Guile library was configured and compiled
-with that feature enabled --- i.e. the feature is built into the library
-on your system. Or because some C or Scheme code that was dynamically
-loaded by Guile has added that feature to the list.
-
-In the first category, here are the features that the current version of
-Guile may define (depending on how it is built), and what they mean.
-
-@table @code
-@item array
-Indicates support for arrays (@pxref{Arrays}).
-
-@item array-for-each
-Indicates availability of @code{array-for-each} and other array mapping
-procedures (@pxref{Array Mapping}).
-
-@item char-ready?
-Indicates that the @code{char-ready?} function is available
-(@pxref{Reading}).
-
-@item complex
-Indicates support for complex numbers.
-
-@item current-time
-Indicates availability of time-related functions: @code{times},
-@code{get-internal-run-time} and so on (@pxref{Time}).
-
-@item debug-extensions
-Indicates that the debugging evaluator is available, together with the
-options for controlling it.
-
-@item delay
-Indicates support for promises (@pxref{Delayed Evaluation}).
-
-@item EIDs
-Indicates that the @code{geteuid} and @code{getegid} really return
-effective user and group IDs (@pxref{Processes}).
-
-@item inexact
-Indicates support for inexact numbers.
-
-@item i/o-extensions
-Indicates availability of the following extended I/O procedures:
-@code{ftell}, @code{redirect-port}, @code{dup->fdes}, @code{dup2},
-@code{fileno}, @code{isatty?}, @code{fdopen},
-@code{primitive-move->fdes} and @code{fdes->ports} (@pxref{Ports and
-File Descriptors}).
-
-@item net-db
-Indicates availability of network database functions:
-@code{scm_gethost}, @code{scm_getnet}, @code{scm_getproto},
-@code{scm_getserv}, @code{scm_sethost}, @code{scm_setnet}, @code{scm_setproto},
-@code{scm_setserv}, and their `byXXX' variants (@pxref{Network
-Databases}).
-
-@item posix
-Indicates support for POSIX functions: @code{pipe}, @code{getgroups},
-@code{kill}, @code{execl} and so on (@pxref{POSIX}).
-
-@item random
-Indicates availability of random number generation functions:
-@code{random}, @code{copy-random-state}, @code{random-uniform} and so on
-(@pxref{Random}).
-
-@item reckless
-Indicates that Guile was built with important checks omitted --- you
-should never see this!
-
-@item regex
-Indicates support for POSIX regular expressions using
-@code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp
-Functions}).
-
-@item socket
-Indicates availability of socket-related functions: @code{socket},
-@code{bind}, @code{connect} and so on (@pxref{Network Sockets and
-Communication}).
-
-@item sort
-Indicates availability of sorting and merging functions
-(@pxref{Sorting}).
-
-@item system
-Indicates that the @code{system} function is available
-(@pxref{Processes}).
-
-@item threads
-Indicates support for multithreading (@pxref{Threads}).
-
-@item values
-Indicates support for multiple return values using @code{values} and
-@code{call-with-values} (@pxref{Multiple Values}).
-@end table
-
-Available features in the second category depend, by definition, on what
-additional code your Guile process has loaded in. The following table
-lists features that you might encounter for this reason.
-
-@table @code
-@item defmacro
-Indicates that the @code{defmacro} macro is available (@pxref{Macros}).
-
-@item describe
-Indicates that the @code{(oop goops describe)} module has been loaded,
-which provides a procedure for describing the contents of GOOPS
-instances.
-
-@item readline
-Indicates that Guile has loaded in Readline support, for command line
-editing (@pxref{Readline Support}).
-
-@item record
-Indicates support for record definition using @code{make-record-type}
-and friends (@pxref{Records}).
-@end table
-
-Although these tables may seem exhaustive, it is probably unwise in
-practice to rely on them, as the correspondences between feature symbols
-and available procedures/behaviour are not strictly defined. If you are
-writing code that needs to check for the existence of some procedure, it
-is probably safer to do so directly using the @code{defined?} procedure
-than to test for the corresponding feature using @code{feature?}.
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-procedures.texi b/doc/ref/scheme-procedures.texi
deleted file mode 100644
index 36f840ecc..000000000
--- a/doc/ref/scheme-procedures.texi
+++ /dev/null
@@ -1,816 +0,0 @@
-@page
-@node Procedures and Macros
-@chapter Procedures and Macros
-
-@menu
-* Lambda:: Basic procedure creation using lambda.
-* Optional Arguments:: Handling keyword, optional and rest arguments.
-* Procedure Properties:: Procedure properties and meta-information.
-* Procedures with Setters:: Procedures with setters.
-* Macros:: Lisp style macro definitions.
-* Syntax Rules:: Support for R5RS @code{syntax-rules}.
-* Syntax Case:: Support for the @code{syntax-case} system.
-* Internal Macros:: Guile's internal representation.
-@end menu
-
-
-@node Lambda
-@section Lambda: Basic Procedure Creation
-
-@c FIXME::martin: Review me!
-
-A @code{lambda} expression evaluates to a procedure. The environment
-which is in effect when a @code{lambda} expression is evaluated is
-enclosed in the newly created procedure, this is referred to as a
-@dfn{closure} (@pxref{About Closure}).
-
-When a procedure created by @code{lambda} is called with some actual
-arguments, the environment enclosed in the procedure is extended by
-binding the variables named in the formal argument list to new locations
-and storing the actual arguments into these locations. Then the body of
-the @code{lambda} expression is evaluation sequentially. The result of
-the last expression in the procedure body is then the result of the
-procedure invocation.
-
-The following examples will show how procedures can be created using
-@code{lambda}, and what you can do with these procedures.
-
-@lisp
-(lambda (x) (+ x x)) @result{} @r{a procedure}
-((lambda (x) (+ x x)) 4) @result{} 8
-@end lisp
-
-The fact that the environment in effect when creating a procedure is
-enclosed in the procedure is shown with this example:
-
-@lisp
-(define add4
- (let ((x 4))
- (lambda (y) (+ x y))))
-(add4 6) @result{} 10
-@end lisp
-
-
-@deffn syntax lambda formals body
-@var{formals} should be a formal argument list as described in the
-following table.
-
-@table @code
-@item (@var{variable1} @dots{})
-The procedure takes a fixed number of arguments; when the procedure is
-called, the arguments will be stored into the newly created location for
-the formal variables.
-@item @var{variable}
-The procedure takes any number of arguments; when the procedure is
-called, the sequence of actual arguments will converted into a list and
-stored into the newly created location for the formal variable.
-@item (@var{variable1} @dots{} @var{variablen} . @var{variablen+1})
-If a space-delimited period precedes the last variable, then the
-procedure takes @var{n} or more variables where @var{n} is the number
-of formal arguments before the period. There must be at least one
-argument before the period. The first @var{n} actual arguments will be
-stored into the newly allocated locations for the first @var{n} formal
-arguments and the sequence of the remaining actual arguments is
-converted into a list and the stored into the location for the last
-formal argument. If there are exactly @var{n} actual arguments, the
-empty list is stored into the location of the last formal argument.
-@end table
-
-@var{body} is a sequence of Scheme expressions which are evaluated in
-order when the procedure is invoked.
-@end deffn
-
-
-@node Optional Arguments
-@section Optional Arguments
-
-@c FIXME::martin: Review me!
-
-Scheme procedures, as defined in R5RS, can either handle a fixed number
-of actual arguments, or a fixed number of actual arguments followed by
-arbitrarily many additional arguments. Writing procedures of variable
-arity can be useful, but unfortunately, the syntactic means for handling
-argument lists of varying length is a bit inconvenient. It is possible
-to give names to the fixed number of argument, but the remaining
-(optional) arguments can be only referenced as a list of values
-(@pxref{Lambda}).
-
-Guile comes with the module @code{(ice-9 optargs)}, which makes using
-optional arguments much more convenient. In addition, this module
-provides syntax for handling keywords in argument lists
-(@pxref{Keywords}).
-
-Before using any of the procedures or macros defined in this section,
-you have to load the module @code{(ice-9 optargs)} with the statement:
-
-@lisp
-(use-modules (ice-9 optargs))
-@end lisp
-
-@menu
-* let-optional Reference:: Locally binding optional arguments.
-* let-keywords Reference:: Locally binding keywords arguments.
-* lambda* Reference:: Creating advanced argument handling procedures.
-* define* Reference:: Defining procedures and macros.
-@end menu
-
-
-@node let-optional Reference
-@subsection let-optional Reference
-
-@c FIXME::martin: Review me!
-
-The syntax @code{let-optional} and @code{let-optional*} are for
-destructuring rest argument lists and giving names to the various list
-elements. @code{let-optional} binds all variables simultaneously, while
-@code{let-optional*} binds them sequentially, consistent with @code{let}
-and @code{let*} (@pxref{Local Bindings}).
-
-@deffn {library syntax} let-optional rest-arg (binding @dots{}) expr @dots{}
-@deffnx {library syntax} let-optional* rest-arg (binding @dots{}) expr @dots{}
-These two macros give you an optional argument interface that is very
-@dfn{Schemey} and introduces no fancy syntax. They are compatible with
-the scsh macros of the same name, but are slightly extended. Each of
-@var{binding} may be of one of the forms @var{var} or @code{(@var{var}
-@var{default-value})}. @var{rest-arg} should be the rest-argument of the
-procedures these are used from. The items in @var{rest-arg} are
-sequentially bound to the variable names are given. When @var{rest-arg}
-runs out, the remaining vars are bound either to the default values or
-left unbound if no default value was specified. @var{rest-arg} remains
-bound to whatever may have been left of @var{rest-arg}.
-
-After binding the variables, the expressions @var{expr} @dots{} are
-evaluated in order.
-@end deffn
-
-
-@node let-keywords Reference
-@subsection let-keywords Reference
-
-@c FIXME::martin: Review me!
-
-@code{let-keywords} and @code{let-keywords*} are used for extracting
-values from argument lists which use keywords instead of argument
-position for binding local variables to argument values.
-
-@code{let-keywords} binds all variables simultaneously, while
-@code{let-keywords*} binds them sequentially, consistent with @code{let}
-and @code{let*} (@pxref{Local Bindings}).
-
-@deffn {library syntax} let-keywords rest-arg allow-other-keys? (binding @dots{}) expr @dots{}
-@deffnx {library syntax} let-keywords rest-arg allow-other-keys? (binding @dots{}) expr @dots{}
-These macros pick out keyword arguments from @var{rest-arg}, but do not
-modify it. This is consistent at least with Common Lisp, which
-duplicates keyword arguments in the rest argument. More explanation of what
-keyword arguments in a lambda list look like can be found below in
-the documentation for @code{lambda*}
- (@pxref{lambda* Reference}). @var{binding}s can have the same form as
-for @code{let-optional}. If @var{allow-other-keys?} is false, an error
-will be thrown if anything that looks like a keyword argument but does
-not match a known keyword parameter will result in an error.
-
-After binding the variables, the expressions @var{expr} @dots{} are
-evaluated in order.
-@end deffn
-
-
-@node lambda* Reference
-@subsection lambda* Reference
-
-@c FIXME::martin: Review me!
-
-When using optional and keyword argument lists, using @code{lambda} for
-creating procedures and using @code{let-optional} or @code{let-keywords}
-is a bit lengthy. Therefore, @code{lambda*} is provided, which combines
-the features of those macros into a single convenient syntax.
-
-For quick reference, here is the syntax of the formal argument list for
-@code{lambda*} (brackets are used to indicate grouping only):
-
-@example
-ext-param-list ::= [identifier]* [#:optional [ext-var-decl]+]?
- [#:key [ext-var-decl]+ [#:allow-other-keys]?]?
- [[#:rest identifier]|[. identifier]]?
-
-ext-var-decl ::= identifier | ( identifier expression )
-@end example
-
-The characters `*', `+' and `?' are not to be taken literally; they mean
-respectively, zero or more occurrences, one or more occurrences, and one
-or zero occurrences.
-
-@deffn {library syntax} lambda* formals body
-@code{lambda*} creates a procedure that takes optional arguments. These
-are specified by putting them inside brackets at the end of the
-parameter list, but before any dotted rest argument. For example,
-
-@lisp
-(lambda* (a b #:optional c d . e) '())
-@end lisp
-
-creates a procedure with fixed arguments @var{a} and @var{b}, optional
-arguments @var{c} and @var{d}, and rest argument @var{e}. If the
-optional arguments are omitted in a call, the variables for them are
-unbound in the procedure. This can be checked with the @code{bound?}
-macro (documented below).
-
-@code{lambda*} can also take keyword arguments. For example, a procedure
-defined like this:
-
-@lisp
-(lambda* (#:key xyzzy larch) '())
-@end lisp
-
-can be called with any of the argument lists @code{(#:xyzzy 11)}
-@code{(#:larch 13)} @code{(#:larch 42 #:xyzzy 19)} @code{()}. Whichever
-arguments are given as keywords are bound to values.
-
-Optional and keyword arguments can also be given default values
-which they take on when they are not present in a call, by giving a
-two-item list in place of an optional argument, for example in:
-
-@lisp
-(lambda* (foo #:optional (bar 42) #:key (baz 73))
- (list foo bar baz))
-@end lisp
-
-@var{foo} is a fixed argument, @var{bar} is an optional argument with
-default value 42, and baz is a keyword argument with default value 73.
-Default value expressions are not evaluated unless they are needed and
-until the procedure is called.
-
-@code{lambda*} also supports two more special parameter list keywords.
-
-@code{lambda*}-defined procedures now throw an error by default if a
-keyword other than one of those specified is found in the actual
-passed arguments. However, specifying @code{#:allow-other-keys}
-immediately after the keyword argument declarations restores the
-previous behavior of ignoring unknown keywords. @code{lambda*} also now
-guarantees that if the same keyword is passed more than once, the
-last one passed is the one that takes effect. For example,
-
-@lisp
-((lambda* (#:key (heads 0) (tails 0)) (display (list heads tails)))
- #:heads 37 #:tails 42 #:heads 99)
-@end lisp
-
-would result in (99 47) being displayed.
-
-@code{#:rest} is also now provided as a synonym for the dotted syntax
-rest argument. The argument lists @code{(a . b)} and @code{(a #:rest b)}
-are equivalent in all respects to @code{lambda*}. This is provided for
-more similarity to DSSSL, MIT-Scheme and Kawa among others, as well as
-for refugees from other Lisp dialects.
-@end deffn
-
-@deffn {library syntax} bound? variable
-Check if a variable is bound in the current environment.
-
-The procedure @code{defined?} doesn't quite cut it as it stands, since
-it only checks bindings in the top-level environment, not those in local
-scope only.
-@end deffn
-
-
-@node define* Reference
-@subsection define* Reference
-
-@c FIXME::martin: Review me!
-
-Just like @code{define} has a shorthand notation for defining procedures
-(@pxref{Lambda Alternatives}), @code{define*} is provided as an
-abbreviation of the combination of @code{define} and @code{lambda*}.
-
-@code{define*-public} is the @code{lambda*} version of
-@code{define-public}; @code{defmacro*} and @code{defmacro*-public} exist
-for defining macros with the improved argument list handling
-possibilities. The @code{-public} versions not only define the
-procedures/macros, but also export them from the current module.
-
-@deffn {library syntax} define* formals body
-@deffnx {library syntax} define*-public formals body
-@code{define*} and @code{define*-public} support optional arguments with
-a similar syntax to @code{lambda*}. They also support arbitrary-depth
-currying, just like Guile's define. Some examples:
-
-@lisp
-(define* (x y #:optional a (z 3) #:key w . u)
- (display (list y z u)))
-@end lisp
-defines a procedure @code{x} with a fixed argument @var{y}, an optional
-argument @var{a}, another optional argument @var{z} with default value 3,
-a keyword argument @var{w}, and a rest argument @var{u}.
-
-@lisp
-(define-public* ((foo #:optional bar) #:optional baz) '())
-@end lisp
-
-This illustrates currying. A procedure @code{foo} is defined, which,
-when called with an optional argument @var{bar}, returns a procedure
-that takes an optional argument @var{baz}.
-
-Of course, @code{define*[-public]} also supports @code{#:rest} and
-@code{#:allow-other-keys} in the same way as @code{lambda*}.
-@end deffn
-
-@deffn {library syntax} defmacro* name formals body
-@deffnx {library syntax} defmacro*-public name formals body
-These are just like @code{defmacro} and @code{defmacro-public} except that they
-take @code{lambda*}-style extended parameter lists, where @code{#:optional},
-@code{#:key}, @code{#:allow-other-keys} and @code{#:rest} are allowed with the usual
-semantics. Here is an example of a macro with an optional argument:
-
-@lisp
-(defmacro* transmorgify (a #:optional b)
- (a 1))
-@end lisp
-@end deffn
-
-
-@node Procedure Properties
-@section Procedure Properties and Meta-information
-
-@c FIXME::martin: Review me!
-
-Procedures always have attached the environment in which they were
-created and information about how to apply them to actual arguments. In
-addition to that, properties and meta-information can be stored with
-procedures. The procedures in this section can be used to test whether
-a given procedure satisfies a condition; and to access and set a
-procedure's property.
-
-The first group of procedures are predicates to test whether a Scheme
-object is a procedure, or a special procedure, respectively.
-@code{procedure?} is the most general predicates, it returns @code{#t}
-for any kind of procedure. @code{closure?} does not return @code{#t}
-for primitive procedures, and @code{thunk?} only returns @code{#t} for
-procedures which do not accept any arguments.
-
-@rnindex procedure?
-@deffn {Scheme Procedure} procedure? obj
-@deffnx {C Function} scm_procedure_p (obj)
-Return @code{#t} if @var{obj} is a procedure.
-@end deffn
-
-@deffn {Scheme Procedure} closure? obj
-@deffnx {C Function} scm_closure_p (obj)
-Return @code{#t} if @var{obj} is a closure.
-@end deffn
-
-@deffn {Scheme Procedure} thunk? obj
-@deffnx {C Function} scm_thunk_p (obj)
-Return @code{#t} if @var{obj} is a thunk.
-@end deffn
-
-@c FIXME::martin: Is that true?
-@cindex procedure properties
-Procedure properties are general properties to be attached to
-procedures. These can be the name of a procedure or other relevant
-information, such as debug hints.
-
-@deffn {Scheme Procedure} procedure-name proc
-@deffnx {C Function} scm_procedure_name (proc)
-Return the name of the procedure @var{proc}
-@end deffn
-
-@deffn {Scheme Procedure} procedure-source proc
-@deffnx {C Function} scm_procedure_source (proc)
-Return the source of the procedure @var{proc}.
-@end deffn
-
-@deffn {Scheme Procedure} procedure-environment proc
-@deffnx {C Function} scm_procedure_environment (proc)
-Return the environment of the procedure @var{proc}.
-@end deffn
-
-@deffn {Scheme Procedure} procedure-properties proc
-@deffnx {C Function} scm_procedure_properties (proc)
-Return @var{obj}'s property list.
-@end deffn
-
-@deffn {Scheme Procedure} procedure-property obj key
-@deffnx {C Function} scm_procedure_property (obj, key)
-Return the property of @var{obj} with name @var{key}.
-@end deffn
-
-@deffn {Scheme Procedure} set-procedure-properties! proc alist
-@deffnx {C Function} scm_set_procedure_properties_x (proc, alist)
-Set @var{obj}'s property list to @var{alist}.
-@end deffn
-
-@deffn {Scheme Procedure} set-procedure-property! obj key value
-@deffnx {C Function} scm_set_procedure_property_x (obj, key, value)
-In @var{obj}'s property list, set the property named @var{key} to
-@var{value}.
-@end deffn
-
-@cindex procedure documentation
-Documentation for a procedure can be accessed with the procedure
-@code{procedure-documentation}.
-
-@deffn {Scheme Procedure} procedure-documentation proc
-@deffnx {C Function} scm_procedure_documentation (proc)
-Return the documentation string associated with @code{proc}. By
-convention, if a procedure contains more than one expression and the
-first expression is a string constant, that string is assumed to contain
-documentation for that procedure.
-@end deffn
-
-@cindex source properties
-@c FIXME::martin: Is the following true?
-Source properties are properties which are related to the source code of
-a procedure, such as the line and column numbers, the file name etc.
-
-@deffn {Scheme Procedure} set-source-properties! obj plist
-@deffnx {C Function} scm_set_source_properties_x (obj, plist)
-Install the association list @var{plist} as the source property
-list for @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} set-source-property! obj key datum
-@deffnx {C Function} scm_set_source_property_x (obj, key, datum)
-Set the source property of object @var{obj}, which is specified by
-@var{key} to @var{datum}. Normally, the key will be a symbol.
-@end deffn
-
-@deffn {Scheme Procedure} source-properties obj
-@deffnx {C Function} scm_source_properties (obj)
-Return the source property association list of @var{obj}.
-@end deffn
-
-
-@deffn {Scheme Procedure} source-property obj key
-@deffnx {C Function} scm_source_property (obj, key)
-Return the source property specified by @var{key} from
-@var{obj}'s source property list.
-@end deffn
-
-
-@node Procedures with Setters
-@section Procedures with Setters
-
-@c FIXME::martin: Review me!
-
-@c FIXME::martin: Document `operator struct'.
-
-@cindex procedure with setter
-@cindex setter
-A @dfn{procedure with setter} is a special kind of procedure which
-normally behaves like any accessor procedure, that is a procedure which
-accesses a data structure. The difference is that this kind of
-procedure has a so-called @dfn{setter} attached, which is a procedure
-for storing something into a data structure.
-
-Procedures with setters are treated specially when the procedure appears
-in the special form @code{set!} (REFFIXME). How it works is best shown
-by example.
-
-Suppose we have a procedure called @code{foo-ref}, which accepts two
-arguments, a value of type @code{foo} and an integer. The procedure
-returns the value stored at the given index in the @code{foo} object.
-Let @code{f} be a variable containing such a @code{foo} data
-structure.@footnote{Working definitions would be:
-@lisp
-(define foo-ref vector-ref)
-(define foo-set! vector-set!)
-(define f (make-vector 2 #f))
-@end lisp
-}
-
-@lisp
-(foo-ref f 0) @result{} bar
-(foo-ref f 1) @result{} braz
-@end lisp
-
-Also suppose that a corresponding setter procedure called
-@code{foo-set!} does exist.
-
-@lisp
-(foo-set! f 0 'bla)
-(foo-ref f 0) @result{} bla
-@end lisp
-
-Now we could create a new procedure called @code{foo}, which is a
-procedure with setter, by calling @code{make-procedure-with-setter} with
-the accessor and setter procedures @code{foo-ref} and @code{foo-set!}.
-Let us call this new procedure @code{foo}.
-
-@lisp
-(define foo (make-procedure-with-setter foo-ref foo-set!))
-@end lisp
-
-@code{foo} can from now an be used to either read from the data
-structure stored in @code{f}, or to write into the structure.
-
-@lisp
-(set! (foo f 0) 'dum)
-(foo f 0) @result{} dum
-@end lisp
-
-@deffn {Scheme Procedure} make-procedure-with-setter procedure setter
-@deffnx {C Function} scm_make_procedure_with_setter (procedure, setter)
-Create a new procedure which behaves like @var{procedure}, but
-with the associated setter @var{setter}.
-@end deffn
-
-@deffn {Scheme Procedure} procedure-with-setter? obj
-@deffnx {C Function} scm_procedure_with_setter_p (obj)
-Return @code{#t} if @var{obj} is a procedure with an
-associated setter procedure.
-@end deffn
-
-@deffn {Scheme Procedure} procedure proc
-@deffnx {C Function} scm_procedure (proc)
-Return the procedure of @var{proc}, which must be either a
-procedure with setter, or an operator struct.
-@end deffn
-
-@deffn {Scheme Procedure} setter proc
-Return the setter of @var{proc}, which must be either a procedure with
-setter or an operator struct.
-@end deffn
-
-
-@node Macros
-@section Lisp Style Macro Definitions
-
-@cindex macros
-@cindex transformation
-Macros are objects which cause the expression that they appear in to be
-transformed in some way @emph{before} being evaluated. In expressions
-that are intended for macro transformation, the identifier that names
-the relevant macro must appear as the first element, like this:
-
-@lisp
-(@var{macro-name} @var{macro-args} @dots{})
-@end lisp
-
-In Lisp-like languages, the traditional way to define macros is very
-similar to procedure definitions. The key differences are that the
-macro definition body should return a list that describes the
-transformed expression, and that the definition is marked as a macro
-definition (rather than a procedure definition) by the use of a
-different definition keyword: in Lisp, @code{defmacro} rather than
-@code{defun}, and in Scheme, @code{define-macro} rather than
-@code{define}.
-
-@fnindex defmacro
-@fnindex define-macro
-Guile supports this style of macro definition using both @code{defmacro}
-and @code{define-macro}. The only difference between them is how the
-macro name and arguments are grouped together in the definition:
-
-@lisp
-(defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
-@end lisp
-
-@noindent
-is the same as
-
-@lisp
-(define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
-@end lisp
-
-@noindent
-The difference is analogous to the corresponding difference between
-Lisp's @code{defun} and Scheme's @code{define}.
-
-@code{false-if-exception}, from the @file{boot-9.scm} file in the Guile
-distribution, is a good example of macro definition using
-@code{defmacro}:
-
-@lisp
-(defmacro false-if-exception (expr)
- `(catch #t
- (lambda () ,expr)
- (lambda args #f)))
-@end lisp
-
-@noindent
-The effect of this definition is that expressions beginning with the
-identifier @code{false-if-exception} are automatically transformed into
-a @code{catch} expression following the macro definition specification.
-For example:
-
-@lisp
-(false-if-exception (open-input-file "may-not-exist"))
-@equiv{}
-(catch #t
- (lambda () (open-input-file "may-not-exist"))
- (lambda args #f))
-@end lisp
-
-
-@node Syntax Rules
-@section The R5RS @code{syntax-rules} System
-@cindex R5RS syntax-rules system
-
-R5RS defines an alternative system for macro and syntax transformations
-using the keywords @code{define-syntax}, @code{let-syntax},
-@code{letrec-syntax} and @code{syntax-rules}.
-
-The main difference between the R5RS system and the traditional macros
-of the previous section is how the transformation is specified. In
-R5RS, rather than permitting a macro definition to return an arbitrary
-expression, the transformation is specified in a pattern language that
-
-@itemize @bullet
-@item
-does not require complicated quoting and extraction of components of the
-source expression using @code{caddr} etc.
-
-@item
-is designed such that the bindings associated with identifiers in the
-transformed expression are well defined, and such that it is impossible
-for the transformed expression to construct new identifiers.
-@end itemize
-
-@noindent
-The last point is commonly referred to as being @dfn{hygienic}: the R5RS
-@code{syntax-case} system provides @dfn{hygienic macros}.
-
-For example, the R5RS pattern language for the @code{false-if-exception}
-example of the previous section looks like this:
-
-@lisp
-(syntax-rules ()
- ((_ expr)
- (catch #t
- (lambda () expr)
- (lambda args #f))))
-@end lisp
-
-In Guile, the @code{syntax-rules} system is provided by the @code{(ice-9
-syncase)} module. To make these facilities available in your code,
-include the expression @code{(use-syntax (ice-9 syncase))} (@pxref{Using
-Guile Modules}) before the first usage of @code{define-syntax} etc. If
-you are writing a Scheme module, you can alternatively include the form
-@code{#:use-syntax (ice-9 syncase)} in your @code{define-module}
-declaration (@pxref{Creating Guile Modules}).
-
-@menu
-* Pattern Language:: The @code{syntax-rules} pattern language.
-* Define-Syntax:: Top level syntax definitions.
-* Let-Syntax:: Local syntax definitions.
-@end menu
-
-
-@node Pattern Language
-@subsection The @code{syntax-rules} Pattern Language
-
-
-@node Define-Syntax
-@subsection Top Level Syntax Definitions
-
-define-syntax: The gist is
-
- (define-syntax <keyword> <transformer-spec>)
-
-makes the <keyword> into a macro so that
-
- (<keyword> ...)
-
-expands at _compile_ or _read_ time (i.e. before any
-evaluation begins) into some expression that is
-given by the <transformer-spec>.
-
-
-@node Let-Syntax
-@subsection Local Syntax Definitions
-
-
-@node Syntax Case
-@section Support for the @code{syntax-case} System
-
-
-
-@node Internal Macros
-@section Internal Representation of Macros and Syntax
-
-Internally, Guile uses three different flavors of macros. The three
-flavors are called @dfn{acro} (or @dfn{syntax}), @dfn{macro} and
-@dfn{mmacro}.
-
-Given the expression
-
-@lisp
-(foo @dots{})
-@end lisp
-
-@noindent
-with @code{foo} being some flavor of macro, one of the following things
-will happen when the expression is evaluated.
-
-@itemize @bullet
-@item
-When @code{foo} has been defined to be an @dfn{acro}, the procedure used
-in the acro definition of @code{foo} is passed the whole expression and
-the current lexical environment, and whatever that procedure returns is
-the value of evaluating the expression. You can think of this a
-procedure that receives its argument as an unevaluated expression.
-
-@item
-When @code{foo} has been defined to be a @dfn{macro}, the procedure used
-in the macro definition of @code{foo} is passed the whole expression and
-the current lexical environment, and whatever that procedure returns is
-evaluated again. That is, the procedure should return a valid Scheme
-expression.
-
-@item
-When @code{foo} has been defined to be a @dfn{mmacro}, the procedure
-used in the mmacro definition of `foo' is passed the whole expression
-and the current lexical environment, and whatever that procedure returns
-replaces the original expression. Evaluation then starts over from the
-new expression that has just been returned.
-@end itemize
-
-The key difference between a @dfn{macro} and a @dfn{mmacro} is that the
-expression returned by a @dfn{mmacro} procedure is remembered (or
-@dfn{memoized}) so that the expansion does not need to be done again
-next time the containing code is evaluated.
-
-The primitives @code{procedure->syntax}, @code{procedure->macro} and
-@code{procedure->memoizing-macro} are used to construct acros, macros
-and mmacros respectively. However, if you do not have a very special
-reason to use one of these primitives, you should avoid them: they are
-very specific to Guile's current implementation and therefore likely to
-change. Use @code{defmacro}, @code{define-macro} (@pxref{Macros}) or
-@code{define-syntax} (@pxref{Syntax Rules}) instead. (In low level
-terms, @code{defmacro}, @code{define-macro} and @code{define-syntax} are
-all implemented as mmacros.)
-
-@deffn {Scheme Procedure} procedure->syntax code
-@deffnx {C Function} scm_makacro (code)
-Return a macro which, when a symbol defined to this value appears as the
-first symbol in an expression, returns the result of applying @var{code}
-to the expression and the environment.
-@end deffn
-
-@deffn {Scheme Procedure} procedure->macro code
-@deffnx {C Function} scm_makmacro (code)
-Return a macro which, when a symbol defined to this value appears as the
-first symbol in an expression, evaluates the result of applying
-@var{code} to the expression and the environment. For example:
-
-@lisp
-(define trace
- (procedure->macro
- (lambda (x env)
- `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
-
-(trace @i{foo})
-@equiv{}
-(set! @i{foo} (tracef @i{foo} '@i{foo})).
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} procedure->memoizing-macro code
-@deffnx {C Function} scm_makmmacro (code)
-Return a macro which, when a symbol defined to this value appears as the
-first symbol in an expression, evaluates the result of applying
-@var{code} to the expression and the environment.
-@code{procedure->memoizing-macro} is the same as
-@code{procedure->macro}, except that the expression returned by
-@var{code} replaces the original macro expression in the memoized form
-of the containing code.
-@end deffn
-
-In the following primitives, @dfn{acro} flavor macros are referred to
-as @dfn{syntax transformers}.
-
-@deffn {Scheme Procedure} macro? obj
-@deffnx {C Function} scm_macro_p (obj)
-Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a
-syntax transformer.
-@end deffn
-
-@deffn {Scheme Procedure} macro-type m
-@deffnx {C Function} scm_macro_type (m)
-Return one of the symbols @code{syntax}, @code{macro} or
-@code{macro!}, depending on whether @var{m} is a syntax
-transformer, a regular macro, or a memoizing macro,
-respectively. If @var{m} is not a macro, @code{#f} is
-returned.
-@end deffn
-
-@deffn {Scheme Procedure} macro-name m
-@deffnx {C Function} scm_macro_name (m)
-Return the name of the macro @var{m}.
-@end deffn
-
-@deffn {Scheme Procedure} macro-transformer m
-@deffnx {C Function} scm_macro_transformer (m)
-Return the transformer of the macro @var{m}.
-@end deffn
-
-@deffn {Scheme Procedure} cons-source xorig x y
-@deffnx {C Function} scm_cons_source (xorig, x, y)
-Create and return a new pair whose car and cdr are @var{x} and @var{y}.
-Any source properties associated with @var{xorig} are also associated
-with the new pair.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-reading.texi b/doc/ref/scheme-reading.texi
deleted file mode 100644
index eea049d2d..000000000
--- a/doc/ref/scheme-reading.texi
+++ /dev/null
@@ -1,27 +0,0 @@
-@page
-@node Further Reading
-@chapter Further Reading
-
-@itemize @bullet
-@item
-Dorai Sitaram's online Scheme tutorial, @dfn{Teach Yourself Scheme in
-Fixnum Days}, at
-@url{http://www.cs.rice.edu/~dorai/t-y-scheme/t-y-scheme.html}.
-Includes a nice explanation of continuations.
-
-@item
-@url{http://wombat.doc.ic.ac.uk/foldoc/}.
-
-@item
-The complete text of @dfn{Structure and Interpretation of Computer
-Programs}, the classic introduction to computer science and Scheme by
-Hal Abelson, Jerry Sussman and Julie Sussman, is now available online at
-@url{http://mitpress.mit.edu/sicp/sicp.html}. This site also provides
-teaching materials related to the book, and all the source code used in
-the book, in a form suitable for loading and running.
-@end itemize
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-scheduling.texi b/doc/ref/scheme-scheduling.texi
deleted file mode 100644
index 920a73029..000000000
--- a/doc/ref/scheme-scheduling.texi
+++ /dev/null
@@ -1,453 +0,0 @@
-@page
-@node Scheduling
-@chapter Threads, Mutexes, Asyncs and Dynamic Roots
-
-[FIXME: This is pasted in from Tom Lord's original guile.texi chapter
-plus the Cygnus programmer's manual; it should be *very* carefully
-reviewed and largely reorganized.]
-
-@menu
-* Arbiters:: Synchronization primitives.
-* Asyncs:: Asynchronous procedure invocation.
-* Dynamic Roots:: Root frames of execution.
-* Threads:: Multiple threads of execution.
-* Fluids:: Dynamically scoped variables.
-@end menu
-
-
-@node Arbiters
-@section Arbiters
-
-@cindex arbiters
-
-@c FIXME::martin: Review me!
-
-Arbiters are synchronization objects. They are created with
-@code{make-arbiter}. Two or more threads can synchronize on an arbiter
-by trying to lock it using @code{try-arbiter}. This call will succeed
-if no other thread has called @code{try-arbiter} on the arbiter yet,
-otherwise it will fail and return @code{#f}. Once an arbiter is
-successfully locked, it cannot be locked by another thread until the
-thread holding the arbiter calls @code{release-arbiter} to unlock it.
-
-@deffn {Scheme Procedure} make-arbiter name
-@deffnx {C Function} scm_make_arbiter (name)
-Return an object of type arbiter and name @var{name}. Its
-state is initially unlocked. Arbiters are a way to achieve
-process synchronization.
-@end deffn
-
-@deffn {Scheme Procedure} try-arbiter arb
-@deffnx {C Function} scm_try_arbiter (arb)
-Return @code{#t} and lock the arbiter @var{arb} if the arbiter
-was unlocked. Otherwise, return @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} release-arbiter arb
-@deffnx {C Function} scm_release_arbiter (arb)
-Return @code{#t} and unlock the arbiter @var{arb} if the
-arbiter was locked. Otherwise, return @code{#f}.
-@end deffn
-
-
-@node Asyncs
-@section Asyncs
-
-@cindex asyncs
-@cindex system asyncs
-
-@c FIXME::martin: Review me!
-
-An async is a pair of one thunk (a parameterless procedure) and a mark.
-Setting the mark on an async guarantees that the thunk will be executed
-somewhen in the future (@dfn{asynchronously}). Setting the mark more
-than once is satisfied by one execution of the thunk.
-
-Guile supports two types of asyncs: Normal asyncs and system asyncs.
-They differ in that marked system asyncs are executed implicitly as soon
-as possible, whereas normal asyncs have to be invoked explicitly.
-System asyncs are held in an internal data structure and are maintained
-by Guile.
-
-Normal asyncs are created with @code{async}, system asyncs with
-@code{system-async}. They are marked with @code{async-mark} or
-@code{system-async-mark}, respectively.
-
-@deffn {Scheme Procedure} async thunk
-@deffnx {C Function} scm_async (thunk)
-Create a new async for the procedure @var{thunk}.
-@end deffn
-
-@deffn {Scheme Procedure} system-async thunk
-@deffnx {C Function} scm_system_async (thunk)
-Create a new async for the procedure @var{thunk}. Also
-add it to the system's list of active async objects.
-@end deffn
-
-@deffn {Scheme Procedure} async-mark a
-@deffnx {C Function} scm_async_mark (a)
-Mark the async @var{a} for future execution.
-@end deffn
-
-@deffn {Scheme Procedure} system-async-mark a
-@deffnx {C Function} scm_system_async_mark (a)
-Mark the async @var{a} for future execution.
-@end deffn
-
-As already mentioned above, system asyncs are executed automatically.
-Normal asyncs have to be explicitly invoked by storing one or more of
-them into a list and passing them to @code{run-asyncs}.
-
-@deffn {Scheme Procedure} run-asyncs list_of_a
-@deffnx {C Function} scm_run_asyncs (list_of_a)
-Execute all thunks from the asyncs of the list @var{list_of_a}.
-@end deffn
-
-Automatic invocation of system asyncs can be temporarily disabled by
-calling @code{mask-signals} and @code{unmask-signals}. Setting the mark
-while async execution is disabled will nevertheless cause the async to
-run once execution is enabled again. Please note that calls to these
-procedures should always be paired, and they must not be nested, e.g. no
-@code{mask-signals} is allowed if another one is still active.
-
-@deffn {Scheme Procedure} mask-signals
-@deffnx {C Function} scm_mask_signals ()
-Mask signals. The returned value is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} unmask-signals
-@deffnx {C Function} scm_unmask_signals ()
-Unmask signals. The returned value is not specified.
-@end deffn
-
-@c FIXME::martin: Find an example for usage of `noop'. What is that
-@c procedure for anyway?
-
-@deffn {Scheme Procedure} noop . args
-@deffnx {C Function} scm_noop (args)
-Do nothing. When called without arguments, return @code{#f},
-otherwise return the first argument.
-@end deffn
-
-
-@node Dynamic Roots
-@section Dynamic Roots
-@cindex dynamic roots
-
-A @dfn{dynamic root} is a root frame of Scheme evaluation.
-The top-level repl, for example, is an instance of a dynamic root.
-
-Each dynamic root has its own chain of dynamic-wind information. Each
-has its own set of continuations, jump-buffers, and pending CATCH
-statements which are inaccessible from the dynamic scope of any
-other dynamic root.
-
-In a thread-based system, each thread has its own dynamic root. Therefore,
-continuations created by one thread may not be invoked by another.
-
-Even in a single-threaded system, it is sometimes useful to create a new
-dynamic root. For example, if you want to apply a procedure, but to
-not allow that procedure to capture the current continuation, calling
-the procedure under a new dynamic root will do the job.
-
-@deffn {Scheme Procedure} call-with-dynamic-root thunk handler
-@deffnx {C Function} scm_call_with_dynamic_root (thunk, handler)
-Evaluate @code{(thunk)} in a new dynamic context, returning its value.
-
-If an error occurs during evaluation, apply @var{handler} to the
-arguments to the throw, just as @code{throw} would. If this happens,
-@var{handler} is called outside the scope of the new root -- it is
-called in the same dynamic context in which
-@code{call-with-dynamic-root} was evaluated.
-
-If @var{thunk} captures a continuation, the continuation is rooted at
-the call to @var{thunk}. In particular, the call to
-@code{call-with-dynamic-root} is not captured. Therefore,
-@code{call-with-dynamic-root} always returns at most one time.
-
-Before calling @var{thunk}, the dynamic-wind chain is un-wound back to
-the root and a new chain started for @var{thunk}. Therefore, this call
-may not do what you expect:
-
-@lisp
-;; Almost certainly a bug:
-(with-output-to-port
- some-port
-
- (lambda ()
- (call-with-dynamic-root
- (lambda ()
- (display 'fnord)
- (newline))
- (lambda (errcode) errcode))))
-@end lisp
-
-The problem is, on what port will @samp{fnord} be displayed? You
-might expect that because of the @code{with-output-to-port} that
-it will be displayed on the port bound to @code{some-port}. But it
-probably won't -- before evaluating the thunk, dynamic winds are
-unwound, including those created by @code{with-output-to-port}.
-So, the standard output port will have been re-set to its default value
-before @code{display} is evaluated.
-
-(This function was added to Guile mostly to help calls to functions in C
-libraries that can not tolerate non-local exits or calls that return
-multiple times. If such functions call back to the interpreter, it should
-be under a new dynamic root.)
-@end deffn
-
-
-@deffn {Scheme Procedure} dynamic-root
-@deffnx {C Function} scm_dynamic_root ()
-Return an object representing the current dynamic root.
-
-These objects are only useful for comparison using @code{eq?}.
-They are currently represented as numbers, but your code should
-in no way depend on this.
-@end deffn
-
-@c begin (scm-doc-string "boot-9.scm" "quit")
-@deffn {Scheme Procedure} quit [exit_val]
-Throw back to the error handler of the current dynamic root.
-
-If integer @var{exit_val} is specified and if Guile is being used
-stand-alone and if quit is called from the initial dynamic-root,
-@var{exit_val} becomes the exit status of the Guile process and the
-process exits.
-@end deffn
-
-When Guile is run interactively, errors are caught from within the
-read-eval-print loop. An error message will be printed and @code{abort}
-called. A default set of signal handlers is installed, e.g., to allow
-user interrupt of the interpreter.
-
-It is possible to switch to a "batch mode", in which the interpreter
-will terminate after an error and in which all signals cause their
-default actions. Switching to batch mode causes any handlers installed
-from Scheme code to be removed. An example of where this is useful is
-after forking a new process intended to run non-interactively.
-
-@c begin (scm-doc-string "boot-9.scm" "batch-mode?")
-@deffn {Scheme Procedure} batch-mode?
-Returns a boolean indicating whether the interpreter is in batch mode.
-@end deffn
-
-@c begin (scm-doc-string "boot-9.scm" "set-batch-mode?!")
-@deffn {Scheme Procedure} set-batch-mode?! arg
-If @var{arg} is true, switches the interpreter to batch mode.
-The @code{#f} case has not been implemented.
-@end deffn
-
-@node Threads
-@section Threads
-@cindex threads
-@cindex Guile threads
-
-@strong{[NOTE: this chapter was written for Cygnus Guile and has not yet
-been updated for the Guile 1.x release.]}
-
-Here is a the reference for Guile's threads. In this chapter I simply
-quote verbatim Tom Lord's description of the low-level primitives
-written in C (basically an interface to the POSIX threads library) and
-Anthony Green's description of the higher-level thread procedures
-written in scheme.
-@cindex posix threads
-@cindex Lord, Tom
-@cindex Green, Anthony
-
-When using Guile threads, keep in mind that each guile thread is
-executed in a new dynamic root.
-
-@menu
-* Low level thread primitives::
-* Higher level thread procedures::
-@end menu
-
-
-@node Low level thread primitives
-@subsection Low level thread primitives
-
-@c NJFIXME no current mechanism for making sure that these docstrings
-@c are in sync.
-
-@c begin (texi-doc-string "guile" "call-with-new-thread")
-@deffn {Scheme Procedure} call-with-new-thread thunk error-handler
-Evaluate @code{(thunk)} in a new thread, and new dynamic context,
-returning a new thread object representing the thread.
-
-If an error occurs during evaluation, call error-handler, passing it an
-error code describing the condition. [Error codes are currently
-meaningless integers. In the future, real values will be specified.]
-If this happens, the error-handler is called outside the scope of the new
-root -- it is called in the same dynamic context in which
-with-new-thread was evaluated, but not in the caller's thread.
-
-All the evaluation rules for dynamic roots apply to threads.
-@end deffn
-
-@c begin (texi-doc-string "guile" "join-thread")
-@deffn {Scheme Procedure} join-thread thread
-Suspend execution of the calling thread until the target @var{thread}
-terminates, unless the target @var{thread} has already terminated.
-@end deffn
-
-@c begin (texi-doc-string "guile" "yield")
-@deffn {Scheme Procedure} yield
-If one or more threads are waiting to execute, calling yield forces an
-immediate context switch to one of them. Otherwise, yield has no effect.
-@end deffn
-
-@c begin (texi-doc-string "guile" "make-mutex")
-@deffn {Scheme Procedure} make-mutex
-Create a new mutex object.
-@end deffn
-
-@c begin (texi-doc-string "guile" "lock-mutex")
-@deffn {Scheme Procedure} lock-mutex mutex
-Lock @var{mutex}. If the mutex is already locked, the calling thread
-blocks until the mutex becomes available. The function returns when
-the calling thread owns the lock on @var{mutex}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "unlock-mutex")
-@deffn {Scheme Procedure} unlock-mutex mutex
-Unlocks @var{mutex} if the calling thread owns the lock on @var{mutex}.
-Calling unlock-mutex on a mutex not owned by the current thread results
-in undefined behaviour. Once a mutex has been unlocked, one thread
-blocked on @var{mutex} is awakened and grabs the mutex lock.
-@end deffn
-
-@c begin (texi-doc-string "guile" "make-condition-variable")
-@deffn {Scheme Procedure} make-condition-variable
-@end deffn
-
-@c begin (texi-doc-string "guile" "wait-condition-variable")
-@deffn {Scheme Procedure} wait-condition-variable cond-var mutex
-@end deffn
-
-@c begin (texi-doc-string "guile" "signal-condition-variable")
-@deffn {Scheme Procedure} signal-condition-variable cond-var
-@end deffn
-
-
-@node Higher level thread procedures
-@subsection Higher level thread procedures
-
-@c new by ttn, needs review
-
-Higher level thread procedures are available by loading the
-@code{(ice-9 threads)} module. These provide standardized
-thread creation and mutex interaction.
-
-@deffn {Scheme Procedure} %thread-handler tag args@dots{}
-
-This procedure is specified as the standard error-handler for
-@code{make-thread} and @code{begin-thread}. If the number of @var{args}
-is three or more, use @code{display-error}, otherwise display a message
-"uncaught throw to @var{tag}". All output is sent to the port specified
-by @code{current-error-port}.
-
-Before display, global var @code{the-last-stack} is set to @code{#f}
-and signals are unmasked with @code{unmask-signals}.
-
-[FIXME: Why distinguish based on number of args?! Cue voodoo music here.]
-@end deffn
-
-@deffn macro make-thread proc [args@dots{}]
-Apply @var{proc} to @var{args} in a new thread formed by
-@code{call-with-new-thread} using @code{%thread-handler} as the error
-handler.
-@end deffn
-
-@deffn macro begin-thread first [rest@dots{}]
-Evaluate forms @var{first} and @var{rest} in a new thread formed by
-@code{call-with-new-thread} using @code{%thread-handler} as the error
-handler.
-@end deffn
-
-@deffn macro with-mutex m [body@dots{}]
-Lock mutex @var{m}, evaluate @var{body}, and then unlock @var{m}.
-These sub-operations form the branches of a @code{dynamic-wind}.
-@end deffn
-
-@deffn macro monitor first [rest@dots{}]
-Evaluate forms @var{first} and @var{rest} under a newly created
-anonymous mutex, using @code{with-mutex}.
-
-[FIXME: Is there any way to access the mutex?]
-@end deffn
-
-
-@node Fluids
-@section Fluids
-
-@cindex fluids
-
-@c FIXME::martin: Review me!
-
-Fluids are objects to store values in. They have a few properties which
-make them useful in certain situations: Fluids can have one value per
-dynamic root (@pxref{Dynamic Roots}), so that changes to the value in a
-fluid are only visible in the same dynamic root. Since threads are
-executed in separate dynamic roots, fluids can be used for thread local
-storage (@pxref{Threads}).
-
-Fluids can be used to simulate dynamically scoped variables. These are
-used in several (especially in older) dialects of lisp, such as in Emacs
-Lisp, and they work a bit like global variables in that they can be
-modified by the caller of a procedure, and the called procedure will see
-the changes. With lexically scoped variables---which are normally used
-in Scheme---this cannot happen. See the description of
-@code{with-fluids*} below for details.
-
-New fluids are created with @code{make-fluid} and @code{fluid?} is used
-for testing whether an object is actually a fluid.
-
-@deffn {Scheme Procedure} make-fluid
-@deffnx {C Function} scm_make_fluid ()
-Return a newly created fluid.
-Fluids are objects of a certain type (a smob) that can hold one SCM
-value per dynamic root. That is, modifications to this value are
-only visible to code that executes within the same dynamic root as
-the modifying code. When a new dynamic root is constructed, it
-inherits the values from its parent. Because each thread executes
-in its own dynamic root, you can use fluids for thread local storage.
-@end deffn
-
-@deffn {Scheme Procedure} fluid? obj
-@deffnx {C Function} scm_fluid_p (obj)
-Return @code{#t} iff @var{obj} is a fluid; otherwise, return
-@code{#f}.
-@end deffn
-
-The values stored in a fluid can be accessed with @code{fluid-ref} and
-@code{fluid-set!}.
-
-@deffn {Scheme Procedure} fluid-ref fluid
-@deffnx {C Function} scm_fluid_ref (fluid)
-Return the value associated with @var{fluid} in the current
-dynamic root. If @var{fluid} has not been set, then return
-@code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} fluid-set! fluid value
-@deffnx {C Function} scm_fluid_set_x (fluid, value)
-Set the value associated with @var{fluid} in the current dynamic root.
-@end deffn
-
-@code{with-fluids*} temporarily changes the values of one or more fluids,
-so that the given procedure and each procedure called by it access the
-given values. After the procedure returns, the old values are restored.
-
-@deffn {Scheme Procedure} with-fluids* fluids values thunk
-@deffnx {C Function} scm_with_fluids (fluids, values, thunk)
-Set @var{fluids} to @var{values} temporary, and call @var{thunk}.
-@var{fluids} must be a list of fluids and @var{values} must be the same
-number of their values to be applied. Each substitution is done
-one after another. @var{thunk} must be a procedure with no argument.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-translation.texi b/doc/ref/scheme-translation.texi
deleted file mode 100644
index 4d398c60f..000000000
--- a/doc/ref/scheme-translation.texi
+++ /dev/null
@@ -1,48 +0,0 @@
-@page
-@node Translation
-@chapter Support for Translating Other Languages
-
-[Describe translation framework.]
-
-@menu
-* Emacs Lisp Support:: Helper primitives for Emacs Lisp.
-@end menu
-
-
-@node Emacs Lisp Support
-@section Emacs Lisp Support
-
-@deffn {Scheme Procedure} nil-car x
-@deffnx {C Function} scm_nil_car (x)
-Return the car of @var{x}, but convert it to LISP nil if it
-is Scheme's end-of-list.
-@end deffn
-
-@deffn {Scheme Procedure} nil-cdr x
-@deffnx {C Function} scm_nil_cdr (x)
-Return the cdr of @var{x}, but convert it to LISP nil if it
-is Scheme's end-of-list.
-@end deffn
-
-@deffn {Scheme Procedure} nil-cons x y
-@deffnx {C Function} scm_nil_cons (x, y)
-Create a new cons cell with @var{x} as the car and @var{y} as
-the cdr, but convert @var{y} to Scheme's end-of-list if it is
-a Lisp nil.
-@end deffn
-
-@deffn {Scheme Procedure} nil-eq x y
-Compare @var{x} and @var{y} and return Lisp's t if they are
-@code{eq?}, return Lisp's nil otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} null x
-@deffnx {C Function} scm_null (x)
-Return Lisp's @code{t} if @var{x} is nil in the LISP sense,
-return Lisp's nil otherwise.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-utility.texi b/doc/ref/scheme-utility.texi
deleted file mode 100644
index f544ac0da..000000000
--- a/doc/ref/scheme-utility.texi
+++ /dev/null
@@ -1,731 +0,0 @@
-@page
-@node Utility Functions
-@chapter General Utility Functions
-
-@c FIXME::martin: Review me!
-
-This chapter contains information about procedures which are not cleanly
-tied to a specific data type. Because of their wide range of
-applications, they are collected in a @dfn{utility} chapter.
-
-@menu
-* Equality:: When are two values `the same'?
-* Object Properties:: A modern interface to object properties.
-* Sorting:: Sort utility procedures.
-* Copying:: Copying deep structures.
-* General Conversion:: Converting objects to strings.
-* Hooks:: User-customizable event lists.
-@end menu
-
-
-@node Equality
-@section Equality
-
-@c FIXME::martin: Review me!
-
-@cindex sameness
-@cindex equality
-
-Three different kinds of @dfn{sameness} are defined in Scheme.
-
-@itemize @bullet
-@item
-Two values can refer to exactly the same object.
-
-@item
-Two objects can have the same @dfn{value}.
-
-@item
-Two objects can be structurally equivalent.
-@end itemize
-
-The differentiation between these three kinds is important, because
-determining whether two values are the same objects is very efficient,
-while determining structural equivalence can be quite expensive
-(consider comparing two very long lists). Therefore, three different
-procedures for testing for equality are provided, which correspond to
-the three kinds of @dfn{sameness} defined above.
-
-@rnindex eq?
-@deffn {Scheme Procedure} eq? x y
-Return @code{#t} iff @var{x} references the same object as @var{y}.
-@code{eq?} is similar to @code{eqv?} except that in some cases it is
-capable of discerning distinctions finer than those detectable by
-@code{eqv?}.
-@end deffn
-
-@rnindex eqv?
-@deffn {Scheme Procedure} eqv? x y
-The @code{eqv?} procedure defines a useful equivalence relation on objects.
-Briefly, it returns @code{#t} if @var{x} and @var{y} should normally be
-regarded as the same object. This relation is left slightly open to
-interpretation, but works for comparing immediate integers, characters,
-and inexact numbers.
-@end deffn
-
-@rnindex equal?
-@deffn {Scheme Procedure} equal? x y
-Return @code{#t} iff @var{x} and @var{y} are recursively @code{eqv?} equivalent.
-@code{equal?} recursively compares the contents of pairs,
-vectors, and strings, applying @code{eqv?} on other objects such as
-numbers and symbols. A rule of thumb is that objects are generally
-@code{equal?} if they print the same. @code{equal?} may fail to
-terminate if its arguments are circular data structures.
-@end deffn
-
-
-@node Object Properties
-@section Object Properties
-
-It's often useful to associate a piece of additional information with a
-Scheme object even though that object does not have a dedicated slot
-available in which the additional information could be stored. Object
-properties allow you to do just that.
-
-An object property is most commonly used to associate one kind of
-additional information with each instance of a class of similar Scheme
-objects. For example, all procedures have a `name' property, which
-stores the name of the variable in which the procedure was stored by a
-@code{define} expression, or @code{#f} if the procedure wasn't created
-by that kind of expression.
-
-Guile's representation of an object property is a procedure-with-setter
-(@pxref{Procedures with Setters}) that can be used with the generalized
-form of @code{set!} (REFFIXME) to set and retrieve that property for any
-Scheme object. So, setting a property looks like this:
-
-@lisp
-(set! (my-property obj1) value-for-obj1)
-(set! (my-property obj2) value-for-obj2)
-@end lisp
-
-@noindent
-And retrieving values of the same property looks like this:
-
-@lisp
-(my-property obj1)
-@result{}
-value-for-obj1
-
-(my-property obj2)
-@result{}
-value-for-obj2
-@end lisp
-
-To create an object property in the first place, use the
-@code{make-object-property} procedure:
-
-@lisp
-(define my-property (make-object-property))
-@end lisp
-
-@deffn {Scheme Procedure} make-object-property
-Create and return an object property. An object property is a
-procedure-with-setter that can be called in two ways. @code{(set!
-(@var{property} @var{obj}) @var{val})} sets @var{obj}'s @var{property}
-to @var{val}. @code{(@var{property} @var{obj})} returns the current
-setting of @var{obj}'s @var{property}.
-@end deffn
-
-A single object property created by @code{make-object-property} can
-associate distinct property values with all Scheme values that are
-distinguishable by @code{eq?} (including, for example, integers).
-
-Internally, object properties are implemented using a weak key hash
-table. This means that, as long as a Scheme value with property values
-is protected from garbage collection, its property values are also
-protected. When the Scheme value is collected, its entry in the
-property table is removed and so the (ex-) property values are no longer
-protected by the table.
-
-@menu
-* Property Primitives:: Low level property implementation.
-* Old-fashioned Properties:: An older approach to properties.
-@end menu
-
-
-@node Property Primitives
-@subsection Low Level Property Implementation.
-
-@deffn {Scheme Procedure} primitive-make-property not_found_proc
-@deffnx {C Function} scm_primitive_make_property (not_found_proc)
-Create a @dfn{property token} that can be used with
-@code{primitive-property-ref} and @code{primitive-property-set!}.
-See @code{primitive-property-ref} for the significance of
-@var{not_found_proc}.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-property-ref prop obj
-@deffnx {C Function} scm_primitive_property_ref (prop, obj)
-Return the property @var{prop} of @var{obj}. When no value
-has yet been associated with @var{prop} and @var{obj}, call
-@var{not-found-proc} instead (see @code{primitive-make-property})
-and use its return value. That value is also associated with
-@var{obj} via @code{primitive-property-set!}. When
-@var{not-found-proc} is @code{#f}, use @code{#f} as the
-default value of @var{prop}.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-property-set! prop obj val
-@deffnx {C Function} scm_primitive_property_set_x (prop, obj, val)
-Associate @var{code} with @var{prop} and @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-property-del! prop obj
-@deffnx {C Function} scm_primitive_property_del_x (prop, obj)
-Remove any value associated with @var{prop} and @var{obj}.
-@end deffn
-
-
-@node Old-fashioned Properties
-@subsection An Older Approach to Properties
-
-Traditionally, Lisp systems provide a different object property
-interface to that provided by @code{make-object-property}, in which the
-object property that is being set or retrieved is indicated by a symbol.
-
-Guile includes this older kind of interface as well, but it may well be
-removed in a future release, as it is less powerful than
-@code{make-object-property} and so increases the size of the Guile
-library for no benefit. (And it is trivial to write a compatibility
-layer in Scheme.)
-
-@deffn {Scheme Procedure} object-properties obj
-@deffnx {C Function} scm_object_properties (obj)
-Return @var{obj}'s property list.
-@end deffn
-
-@deffn {Scheme Procedure} set-object-properties! obj alist
-@deffnx {C Function} scm_set_object_properties_x (obj, alist)
-Set @var{obj}'s property list to @var{alist}.
-@end deffn
-
-@deffn {Scheme Procedure} object-property obj key
-@deffnx {C Function} scm_object_property (obj, key)
-Return the property of @var{obj} with name @var{key}.
-@end deffn
-
-@deffn {Scheme Procedure} set-object-property! obj key value
-@deffnx {C Function} scm_set_object_property_x (obj, key, value)
-In @var{obj}'s property list, set the property named @var{key}
-to @var{value}.
-@end deffn
-
-
-@node Sorting
-@section Sorting
-
-@c FIXME::martin: Review me!
-
-@cindex sorting
-@cindex sorting lists
-@cindex sorting vectors
-
-Sorting is very important in computer programs. Therefore, Guile comes
-with several sorting procedures built-in. As always, procedures with
-names ending in @code{!} are side-effecting, that means that they may
-modify their parameters in order to produce their results.
-
-The first group of procedures can be used to merge two lists (which must
-be already sorted on their own) and produce sorted lists containing
-all elements of the input lists.
-
-@deffn {Scheme Procedure} merge alist blist less
-@deffnx {C Function} scm_merge (alist, blist, less)
-Merge two already sorted lists into one.
-Given two lists @var{alist} and @var{blist}, such that
-@code{(sorted? alist less?)} and @code{(sorted? blist less?)},
-return a new list in which the elements of @var{alist} and
-@var{blist} have been stably interleaved so that
-@code{(sorted? (merge alist blist less?) less?)}.
-Note: this does _not_ accept vectors.
-@end deffn
-
-@deffn {Scheme Procedure} merge! alist blist less
-@deffnx {C Function} scm_merge_x (alist, blist, less)
-Takes two lists @var{alist} and @var{blist} such that
-@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
-returns a new list in which the elements of @var{alist} and
-@var{blist} have been stably interleaved so that
- @code{(sorted? (merge alist blist less?) less?)}.
-This is the destructive variant of @code{merge}
-Note: this does _not_ accept vectors.
-@end deffn
-
-The following procedures can operate on sequences which are either
-vectors or list. According to the given arguments, they return sorted
-vectors or lists, respectively. The first of the following procedures
-determines whether a sequence is already sorted, the other sort a given
-sequence. The variants with names starting with @code{stable-} are
-special in that they maintain a special property of the input sequences:
-If two or more elements are the same according to the comparison
-predicate, they are left in the same order as they appeared in the
-input.
-
-@deffn {Scheme Procedure} sorted? items less
-@deffnx {C Function} scm_sorted_p (items, less)
-Return @code{#t} iff @var{items} is a list or a vector such that
-for all 1 <= i <= m, the predicate @var{less} returns true when
-applied to all elements i - 1 and i
-@end deffn
-
-@deffn {Scheme Procedure} sort items less
-@deffnx {C Function} scm_sort (items, less)
-Sort the sequence @var{items}, which may be a list or a
-vector. @var{less} is used for comparing the sequence
-elements. This is not a stable sort.
-@end deffn
-
-@deffn {Scheme Procedure} sort! items less
-@deffnx {C Function} scm_sort_x (items, less)
-Sort the sequence @var{items}, which may be a list or a
-vector. @var{less} is used for comparing the sequence
-elements. The sorting is destructive, that means that the
-input sequence is modified to produce the sorted result.
-This is not a stable sort.
-@end deffn
-
-@deffn {Scheme Procedure} stable-sort items less
-@deffnx {C Function} scm_stable_sort (items, less)
-Sort the sequence @var{items}, which may be a list or a
-vector. @var{less} is used for comparing the sequence elements.
-This is a stable sort.
-@end deffn
-
-@deffn {Scheme Procedure} stable-sort! items less
-@deffnx {C Function} scm_stable_sort_x (items, less)
-Sort the sequence @var{items}, which may be a list or a
-vector. @var{less} is used for comparing the sequence elements.
-The sorting is destructive, that means that the input sequence
-is modified to produce the sorted result.
-This is a stable sort.
-@end deffn
-
-The procedures in the last group only accept lists or vectors as input,
-as their names indicate.
-
-@deffn {Scheme Procedure} sort-list items less
-@deffnx {C Function} scm_sort_list (items, less)
-Sort the list @var{items}, using @var{less} for comparing the
-list elements. This is a stable sort.
-@end deffn
-
-@deffn {Scheme Procedure} sort-list! items less
-@deffnx {C Function} scm_sort_list_x (items, less)
-Sort the list @var{items}, using @var{less} for comparing the
-list elements. The sorting is destructive, that means that the
-input list is modified to produce the sorted result.
-This is a stable sort.
-@end deffn
-
-@deffn {Scheme Procedure} restricted-vector-sort! vec less startpos endpos
-@deffnx {C Function} scm_restricted_vector_sort_x (vec, less, startpos, endpos)
-Sort the vector @var{vec}, using @var{less} for comparing
-the vector elements. @var{startpos} and @var{endpos} delimit
-the range of the vector which gets sorted. The return value
-is not specified.
-@end deffn
-
-
-@node Copying
-@section Copying Deep Structures
-
-@c FIXME::martin: Review me!
-
-The procedures for copying lists (@pxref{Lists}) only produce a flat
-copy of the input list, and currently Guile does not even contain
-procedures for copying vectors. @code{copy-tree} can be used for these
-application, as it does not only copy the spine of a list, but also
-copies any pairs in the cars of the input lists.
-
-@deffn {Scheme Procedure} copy-tree obj
-@deffnx {C Function} scm_copy_tree (obj)
-Recursively copy the data tree that is bound to @var{obj}, and return a
-pointer to the new data structure. @code{copy-tree} recurses down the
-contents of both pairs and vectors (since both cons cells and vector
-cells may point to arbitrary objects), and stops recursing when it hits
-any other object.
-@end deffn
-
-
-@node General Conversion
-@section General String Conversion
-
-@c FIXME::martin: Review me!
-
-When debugging Scheme programs, but also for providing a human-friendly
-interface, a procedure for converting any Scheme object into string
-format is very useful. Conversion from/to strings can of course be done
-with specialized procedures when the data type of the object to convert
-is known, but with this procedure, it is often more comfortable.
-
-@code{object->string} converts an object by using a print procedure for
-writing to a string port, and then returning the resulting string.
-Converting an object back from the string is only possible if the object
-type has a read syntax and the read syntax is preserved by the printing
-procedure.
-
-@deffn {Scheme Procedure} object->string obj [printer]
-@deffnx {C Function} scm_object_to_string (obj, printer)
-Return a Scheme string obtained by printing @var{obj}.
-Printing function can be specified by the optional second
-argument @var{printer} (default: @code{write}).
-@end deffn
-
-
-@node Hooks
-@section Hooks
-@tpindex Hooks
-
-A hook is a list of procedures to be called at well defined points in
-time. Typically, an application provides a hook @var{h} and promises
-its users that it will call all of the procedures in @var{h} at a
-defined point in the application's processing. By adding its own
-procedure to @var{h}, an application user can tap into or even influence
-the progress of the application.
-
-Guile itself provides several such hooks for debugging and customization
-purposes: these are listed in a subsection below.
-
-When an application first creates a hook, it needs to know how many
-arguments will be passed to the hook's procedures when the hook is run.
-The chosen number of arguments (which may be none) is declared when the
-hook is created, and all the procedures that are added to that hook must
-be capable of accepting that number of arguments.
-
-A hook is created using @code{make-hook}. A procedure can be added to
-or removed from a hook using @code{add-hook!} or @code{remove-hook!},
-and all of a hook's procedures can be removed together using
-@code{reset-hook!}. When an application wants to run a hook, it does so
-using @code{run-hook}.
-
-@menu
-* Hook Example:: Hook usage by example.
-* Hook Reference:: Reference of all hook procedures.
-* C Hooks:: Hooks for use from C code.
-* Guile Hooks:: Hooks provided by Guile.
-@end menu
-
-
-@node Hook Example
-@subsection Hook Usage by Example
-
-Hook usage is shown by some examples in this section. First, we will
-define a hook of arity 2 --- that is, the procedures stored in the hook
-will have to accept two arguments.
-
-@lisp
-(define hook (make-hook 2))
-hook
-@result{} #<hook 2 40286c90>
-@end lisp
-
-Now we are ready to add some procedures to the newly created hook with
-@code{add-hook!}. In the following example, two procedures are added,
-which print different messages and do different things with their
-arguments.
-
-@lisp
-(add-hook! hook (lambda (x y)
- (display "Foo: ")
- (display (+ x y))
- (newline)))
-(add-hook! hook (lambda (x y)
- (display "Bar: ")
- (display (* x y))
- (newline)))
-@end lisp
-
-Once the procedures have been added, we can invoke the hook using
-@code{run-hook}.
-
-@lisp
-(run-hook hook 3 4)
-@print{} Bar: 12
-@print{} Foo: 7
-@end lisp
-
-Note that the procedures are called in the reverse of the order with
-which they were added. This is because the default behaviour of
-@code{add-hook!} is to add its procedure to the @emph{front} of the
-hook's procedure list. You can force @code{add-hook!} to add its
-procedure to the @emph{end} of the list instead by providing a third
-@code{#t} argument on the second call to @code{add-hook!}.
-
-@lisp
-(add-hook! hook (lambda (x y)
- (display "Foo: ")
- (display (+ x y))
- (newline)))
-(add-hook! hook (lambda (x y)
- (display "Bar: ")
- (display (* x y))
- (newline))
- #t) ; @r{<- Change here!}
-
-(run-hook hook 3 4)
-@print{} Foo: 7
-@print{} Bar: 12
-@end lisp
-
-
-@node Hook Reference
-@subsection Hook Reference
-
-When you create a hook with @code{make-hook}, you must specify the arity
-of the procedures which can be added to the hook. If the arity is not
-given explicitly as an argument to @code{make-hook}, it defaults to
-zero. All procedures of a given hook must have the same arity, and when
-the procedures are invoked using @code{run-hook}, the number of
-arguments passed must match the arity specified at hook creation time.
-
-The order in which procedures are added to a hook matters. If the third
-parameter to @code{add-hook!} is omitted or is equal to @code{#f}, the
-procedure is added in front of the procedures which might already be on
-that hook, otherwise the procedure is added at the end. The procedures
-are always called from the front to the end of the list when they are
-invoked via @code{run-hook}.
-
-The ordering of the list of procedures returned by @code{hook->list}
-matches the order in which those procedures would be called if the hook
-was run using @code{run-hook}.
-
-@deffn {Scheme Procedure} make-hook [n_args]
-@deffnx {C Function} scm_make_hook (n_args)
-Create a hook for storing procedure of arity @var{n_args}.
-@var{n_args} defaults to zero. The returned value is a hook
-object to be used with the other hook procedures.
-@end deffn
-
-@deffn {Scheme Procedure} hook? x
-@deffnx {C Function} scm_hook_p (x)
-Return @code{#t} if @var{x} is a hook, @code{#f} otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} hook-empty? hook
-@deffnx {C Function} scm_hook_empty_p (hook)
-Return @code{#t} if @var{hook} is an empty hook, @code{#f}
-otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} add-hook! hook proc [append_p]
-@deffnx {C Function} scm_add_hook_x (hook, proc, append_p)
-Add the procedure @var{proc} to the hook @var{hook}. The
-procedure is added to the end if @var{append_p} is true,
-otherwise it is added to the front. The return value of this
-procedure is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} remove-hook! hook proc
-@deffnx {C Function} scm_remove_hook_x (hook, proc)
-Remove the procedure @var{proc} from the hook @var{hook}. The
-return value of this procedure is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} reset-hook! hook
-@deffnx {C Function} scm_reset_hook_x (hook)
-Remove all procedures from the hook @var{hook}. The return
-value of this procedure is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} hook->list hook
-@deffnx {C Function} scm_hook_to_list (hook)
-Convert the procedure list of @var{hook} to a list.
-@end deffn
-
-@deffn {Scheme Procedure} run-hook hook . args
-@deffnx {C Function} scm_run_hook (hook, args)
-Apply all procedures from the hook @var{hook} to the arguments
-@var{args}. The order of the procedure application is first to
-last. The return value of this procedure is not specified.
-@end deffn
-
-If, in C code, you are certain that you have a hook object and well
-formed argument list for that hook, you can also use
-@code{scm_c_run_hook}, which is identical to @code{scm_run_hook} but
-does no type checking.
-
-@deftypefn {C Function} void scm_c_run_hook (SCM hook, SCM args)
-The same as @code{scm_run_hook} but without any type checking to confirm
-that @var{hook} is actually a hook object and that @var{args} is a
-well-formed list matching the arity of the hook.
-@end deftypefn
-
-
-@node C Hooks
-@subsection Hooks For C Code.
-
-The hooks already described are intended to be populated by Scheme-level
-procedures. In addition to this, the Guile library provides an
-independent set of interfaces for the creation and manipulation of hooks
-that are designed to be populated by functions implemented in C.
-
-The original motivation here was to provide a kind of hook that could
-safely be invoked at various points during garbage collection.
-Scheme-level hooks are unsuitable for this purpose as running them could
-itself require memory allocation, which would then invoke garbage
-collection recursively @dots{} However, it is also the case that these
-hooks are easier to work with than the Scheme-level ones if you only
-want to register C functions with them. So if that is mainly what your
-code needs to do, you may prefer to use this interface.
-
-To create a C hook, you should allocate storage for a structure of type
-@code{scm_t_c_hook} and then initialize it using @code{scm_c_hook_init}.
-
-@deftp {C Type} scm_t_c_hook
-Data type for a C hook. The internals of this type should be treated as
-opaque.
-@end deftp
-
-@deftp {C Enum} scm_t_c_hook_type
-Enumeration of possible hook types, which are:
-
-@table @code
-@item SCM_C_HOOK_NORMAL
-@vindex SCM_C_HOOK_NORMAL
-Type of hook for which all the registered functions will always be called.
-@item SCM_C_HOOK_OR
-@vindex SCM_C_HOOK_OR
-Type of hook for which the sequence of registered functions will be
-called only until one of them returns C true (a non-NULL pointer).
-@item SCM_C_HOOK_AND
-@vindex SCM_C_HOOK_AND
-Type of hook for which the sequence of registered functions will be
-called only until one of them returns C false (a NULL pointer).
-@end table
-@end deftp
-
-@deftypefn {C Function} void scm_c_hook_init (scm_t_c_hook *hook, void *hook_data, scm_t_c_hook_type type)
-Initialize the C hook at memory pointed to by @var{hook}. @var{type}
-should be one of the values of the @code{scm_t_c_hook_type} enumeration,
-and controls how the hook functions will be called. @var{hook_data} is
-a closure parameter that will be passed to all registered hook functions
-when they are called.
-@end deftypefn
-
-To add or remove a C function from a C hook, use @code{scm_c_hook_add}
-or @code{scm_c_hook_remove}. A hook function must expect three
-@code{void *} parameters which are, respectively:
-
-@table @var
-@item hook_data
-The hook closure data that was specified at the time the hook was
-initialized by @code{scm_c_hook_init}.
-
-@item func_data
-The function closure data that was specified at the time that that
-function was registered with the hook by @code{scm_c_hook_add}.
-
-@item data
-The call closure data specified by the @code{scm_c_hook_run} call that
-runs the hook.
-@end table
-
-@deftp {C Type} scm_t_c_hook_function
-Function type for a C hook function: takes three @code{void *}
-parameters and returns a @code{void *} result.
-@end deftp
-
-@deftypefn {C Function} void scm_c_hook_add (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data, int appendp)
-Add function @var{func}, with function closure data @var{func_data}, to
-the C hook @var{hook}. The new function is appended to the hook's list
-of functions if @var{appendp} is non-zero, otherwise prepended.
-@end deftypefn
-
-@deftypefn {C Function} void scm_c_hook_remove (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data)
-Remove function @var{func}, with function closure data @var{func_data},
-from the C hook @var{hook}. @code{scm_c_hook_remove} checks both
-@var{func} and @var{func_data} so as to allow for the same @var{func}
-being registered multiple times with different closure data.
-@end deftypefn
-
-Finally, to invoke a C hook, call the @code{scm_c_hook_run} function
-specifying the hook and the call closure data for this run:
-
-@deftypefn {C Function} void * scm_c_hook_run (scm_t_c_hook *hook, void *data)
-Run the C hook @var{hook} will call closure data @var{data}. Subject to
-the variations for hook types @code{SCM_C_HOOK_OR} and
-@code{SCM_C_HOOK_AND}, @code{scm_c_hook_run} calls @var{hook}'s
-registered functions in turn, passing them the hook's closure data, each
-function's closure data, and the call closure data.
-
-@code{scm_c_hook_run}'s return value is the return value of the last
-function to be called.
-@end deftypefn
-
-
-@node Guile Hooks
-@subsection Hooks Provided by Guile
-
-@menu
-* GC Hooks:: Garbage collection hooks.
-* REPL Hooks:: Hooks into the Guile REPL.
-@end menu
-
-
-@node GC Hooks
-@subsubsection Hooks for Garbage Collection
-
-Whenever Guile performs a garbage collection, it calls the following
-hooks in the order shown.
-
-@defvr {C Hook} scm_before_gc_c_hook
-C hook called at the very start of a garbage collection, after setting
-@code{scm_gc_running_p} to 1, but before entering the GC critical
-section.
-
-If garbage collection is blocked because @code{scm_block_gc} is
-non-zero, GC exits early soon after calling this hook, and no further
-hooks will be called.
-@end defvr
-
-@defvr {C Hook} scm_before_mark_c_hook
-C hook called before beginning the mark phase of garbage collection,
-after the GC thread has entered a critical section.
-@end defvr
-
-@defvr {C Hook} scm_before_sweep_c_hook
-C hook called before beginning the sweep phase of garbage collection.
-This is the same as at the end of the mark phase, since nothing else
-happens between marking and sweeping.
-@end defvr
-
-@defvr {C Hook} scm_after_sweep_c_hook
-C hook called after the end of the sweep phase of garbage collection,
-but while the GC thread is still inside its critical section.
-@end defvr
-
-@defvr {C Hook} scm_after_gc_c_hook
-C hook called at the very end of a garbage collection, after the GC
-thread has left its critical section.
-@end defvr
-
-@defvr {Scheme Hook} after-gc-hook
-@vindex scm_after_gc_hook
-Scheme hook with arity 0. This hook is run asynchronously
-(@pxref{Asyncs}) soon after the GC has completed and any other events
-that were deferred during garbage collection have been processed. (Also
-accessible from C with the name @code{scm_after_gc_hook}.)
-@end defvr
-
-All the C hooks listed here have type @code{SCM_C_HOOK_NORMAL}, are
-initialized with hook closure data NULL, are are invoked by
-@code{scm_c_hook_run} with call closure data NULL.
-
-@cindex guardians, testing for GC'd objects
-The Scheme hook @code{after-gc-hook} is particularly useful in
-conjunction with guardians (@pxref{Guardians}). Typically, if you are
-using a guardian, you want to call the guardian after garbage collection
-to see if any of the objects added to the guardian have been collected.
-By adding a thunk that performs this call to @code{after-gc-hook}, you
-can ensure that your guardian is tested after every garbage collection
-cycle.
-
-
-@node REPL Hooks
-@subsubsection Hooks into the Guile REPL
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scm.texi b/doc/ref/scm.texi
deleted file mode 100644
index d4a634eb9..000000000
--- a/doc/ref/scm.texi
+++ /dev/null
@@ -1,181 +0,0 @@
-@page
-@node API Overview
-@chapter Overview of the Guile API
-
-Guile's application programming interface (@dfn{API}) makes
-functionality available that an application developer can use in either
-C or Scheme programming. The interface consists of @dfn{elements} that
-may be macros, functions or variables in C, and procedures, variables,
-syntax or other types of object in Scheme. Broadly speaking, the
-interface as a whole can be divided into three groups.
-
-@enumerate
-@item
-Elements that are available equivalently as C functions or Scheme
-procedures.
-
-@item
-Elements that are only available as macros, functions or variables for C
-programming.
-
-@item
-Elements that are only available as procedures or other objects in
-Scheme.
-@end enumerate
-
-Functions/procedures in the first group are often known as
-@dfn{primitives}, @dfn{subrs} or @dfn{builtins}. An example is the
-@code{assq} Scheme procedure, which is also available as @code{scm_assq}
-in C.
-
-Elements in the second and third groups exist because they provide
-additional language-specific benefits in either Scheme or C. Examples
-are the C macro @code{SCM_CONSP}, which is faster and more convenient in
-C programming than the primitive @code{scm_pair_p}, and the
-procedure-with-setter @code{make-object-property}, which provides a
-more convenient property handling interface in Scheme than the
-primitives on which it is based.
-
-@menu
-* Primitives:: Identical function for Scheme and C.
-* C Only:: Elements only available in C.
-* Scheme Only:: Elements only available in Scheme.
-* Reference Layout:: The layout of this part of the manual.
-@end menu
-
-
-@node Primitives
-@section Identical Function in both Scheme and C
-
-They form the majority of the API, and allow both C and Scheme
-programmers to perform identical operations.
-
-@c @node Scheme Primitives
-@c @chapter Writing Scheme primitives in C
-@c - according to the menu in guile.texi - NJ 2001/1/26
-@c @chapter Relationship between Scheme and C functions
-
-@c Chapter contents contributed by Thien-Thi Nguyen <ttn@gnu.org>.
-
-Scheme procedures marked "primitive functions" have a regular interface
-when calling from C, reflected in two areas: the name of a C function, and
-the convention for passing non-required arguments to this function.
-
-@c Although the vast majority of functions support these relationships,
-@c there are some exceptions.
-
-@menu
-* Transforming Scheme name to C name::
-* Structuring argument lists for C functions::
-@c * Exceptions to the regularity::
-@end menu
-
-
-@node Transforming Scheme name to C name
-@subsection Transforming Scheme name to C name
-
-Normally, the name of a C function can be derived given its Scheme name,
-using some simple textual transformations:
-
-@itemize @bullet
-
-@item
-Replace @code{-} (hyphen) with @code{_} (underscore).
-
-@item
-Replace @code{?} (question mark) with "_p".
-
-@item
-Replace @code{!} (exclamation point) with "_x".
-
-@item
-Replace internal @code{->} with "_to_".
-
-@item
-Replace @code{<=} (less than or equal) with "_leq".
-
-@item
-Replace @code{>=} (greater than or equal) with "_geq".
-
-@item
-Replace @code{<} (less than) with "_less".
-
-@item
-Replace @code{>} (greater than) with "_gr".
-
-@item
-Replace @code{@@} with "at". [Omit?]
-
-@item
-Prefix with "gh_" (or "scm_" if you are ignoring the gh interface).
-
-@item
-[Anything else? --ttn, 2000/01/16 15:17:28]
-
-@end itemize
-
-Here is an Emacs Lisp command that prompts for a Scheme function name and
-inserts the corresponding C function name into the buffer.
-
-@example
-(defun insert-scheme-to-C (name &optional use-gh)
- "Transforms Scheme NAME, a string, to its C counterpart, and inserts it.
-Prefix arg non-nil means use \"gh_\" prefix, otherwise use \"scm_\" prefix."
- (interactive "sScheme name: \nP")
- (let ((transforms '(("-" . "_")
- ("?" . "_p")
- ("!" . "_x")
- ("->" . "_to_")
- ("<=" . "_leq")
- (">=" . "_geq")
- ("<" . "_less")
- (">" . "_gr")
- ("@@" . "at"))))
- (while transforms
- (let ((trigger (concat "\\(.*\\)"
- (regexp-quote (caar transforms))
- "\\(.*\\)"))
- (sub (cdar transforms))
- (m nil))
- (while (setq m (string-match trigger name))
- (setq name (concat (match-string 1 name)
- sub
- (match-string 2 name)))))
- (setq transforms (cdr transforms))))
- (insert (if use-gh "gh_" "scm_") name))
-@end example
-
-
-@node Structuring argument lists for C functions
-@subsection Structuring argument lists for C functions
-
-The C function's arguments will be all of the Scheme procedure's
-arguments, both required and optional; if the Scheme procedure takes a
-``rest'' argument, that will be a final argument to the C function. The
-C function's arguments, as well as its return type, will be @code{SCM}.
-
-
-@node C Only
-@section Elements Available Only in C
-
-For C this is usually a matter of better performance (e.g. the
-@code{SCM_CONSP} macro) or of accepting C language types rather than the
-generic @code{SCM}.
-
-
-@node Scheme Only
-@section Elements Available Only in Scheme
-
-
-@node Reference Layout
-@section Reference Material Layout
-
-This part of the reference manual documents all of Guile's core
-Scheme-level language and features in functionally-related groups.
-Where a particular section of the manual includes both R5RS-compliant
-parts and Guile-specific extensions, the text indicates which parts of
-the documentation describe R5RS behaviour and which parts describe Guile
-extensions.
-
-For a quick way of identifying the parts of Guile that implement
-R5RS-compliant features, see the R5RS index: @ref{R5RS Index}.
diff --git a/doc/ref/script-getopt.texi b/doc/ref/script-getopt.texi
deleted file mode 100644
index c71dbd205..000000000
--- a/doc/ref/script-getopt.texi
+++ /dev/null
@@ -1,435 +0,0 @@
-@page
-@node Command Line Handling
-@chapter Handling Command Line Options and Arguments
-
-@c This chapter was written and contributed by Martin Grabmueller.
-
-The ability to accept and handle command line arguments is very
-important when writing Guile scripts to solve particular problems, such
-as extracting information from text files or interfacing with existing
-command line applications. This chapter describes how Guile makes
-command line arguments available to a Guile script, and the utilities
-that Guile provides to help with the processing of command line
-arguments.
-
-@menu
-* Command Line Args:: Using command line arguments.
-* getopt-long:: The (ice-9 getopt-long) module.
-@end menu
-
-
-@node Command Line Args
-@section Using Command Line Arguments
-
-When a Guile script is invoked, Guile makes the command line arguments
-accessible via the procedure @code{command-line}, which returns the
-arguments as a list of strings.
-
-For example, if the script
-
-@example
-#! /usr/local/bin/guile -s
-!#
-(write (command-line))
-(newline)
-@end example
-
-@noindent
-is saved in a file @file{cmdline-test.scm} and invoked using the command
-line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}, the output
-is
-
-@example
-("./cmdline-test.scm" "bar.txt" "-o" "foo" "-frumple" "grob")
-@end example
-
-If the script invocation includes a @code{-e} option, specifying a
-procedure to call after loading the script, Guile will call that
-procedure with @code{(command-line)} as its argument. So a script that
-uses @code{-e} doesn't need to refer explicitly to @code{command-line}
-in its code. For example, the script above would have identical
-behaviour if it was written instead like this:
-
-@example
-#! /usr/local/bin/guile \
--e main -s
-!#
-(define (main args)
- (write args)
- (newline))
-@end example
-
-(Note the use of the meta switch @code{\} so that the script invocation
-can include more than one Guile option: @xref{The Meta Switch}.)
-
-These scripts use the @code{#!} POSIX convention so that they can be
-executed using their own file names directly, as in the example command
-line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}. But they
-can also be executed by typing out the implied Guile command line in
-full, as in:
-
-@example
-$ guile -s ./cmdline-test.scm bar.txt -o foo -frumple grob
-@end example
-
-@noindent
-or
-
-@example
-$ guile -e main -s ./cmdline-test2.scm bar.txt -o foo -frumple grob
-@end example
-
-Even when a script is invoked using this longer form, the arguments that
-the script receives are the same as if it had been invoked using the
-short form. Guile ensures that the @code{(command-line)} or @code{-e}
-arguments are independent of how the script is invoked, by stripping off
-the arguments that Guile itself processes.
-
-
-@node getopt-long
-@section The (ice-9 getopt-long) Module
-
-A script is free to parse and handle its command line arguments in any
-way that it chooses. Where the set of possible options and arguments is
-complex, however, it can get tricky to extract all the options, check
-the validity of given arguments, and so on. This task can be greatly
-simplified by taking advantage of the module @code{(ice-9 getopt-long)},
-which is distributed with Guile.
-
-The @code{(ice-9 getopt-long)} module exports two procedures:
-@code{getopt-long} and @code{option-ref}.
-
-@itemize @bullet
-@item
-@code{getopt-long} takes a list of strings --- the command line
-arguments --- and an @dfn{option specification}. It parses the command
-line arguments according to the option specification and returns a data
-structure that encapsulates the results of the parsing.
-
-@item
-@code{option-ref} then takes the parsed data structure and a specific
-option's name, and returns information about that option in particular.
-@end itemize
-
-To make these procedures available to your Guile script, include the
-expression @code{(use-modules (ice-9 getopt-long))} somewhere near the
-top, before the first usage of @code{getopt-long} or @code{option-ref}.
-
-@menu
-* getopt-long Example:: A short getopt-long example.
-* Option Specification:: How to write an option specification.
-* Command Line Format:: The expected command line format.
-* getopt-long Reference:: Full documentation for @code{getopt-long}.
-* option-ref Reference:: Full documentation for @code{option-ref}.
-@end menu
-
-
-@node getopt-long Example
-@subsection A Short getopt-long Example
-
-This subsection illustrates how @code{getopt-long} is used by presenting
-and dissecting a simple example. The first thing that we need is an
-@dfn{option specification} that tells @code{getopt-long} how to parse
-the command line. This specification is an association list with the
-long option name as the key. Here is how such a specification might
-look:
-
-@lisp
-(define option-spec
- '((version (single-char #\v) (value #f))
- (help (single-char #\h) (value #f))))
-@end lisp
-
-This alist tells @code{getopt-long} that it should accept two long
-options, called @emph{version} and @emph{help}, and that these options
-can also be selected by the single-letter abbreviations @emph{v} and
-@emph{h}, respectively. The @code{(value #f)} clauses indicate that
-neither of the options accepts a value.
-
-With this specification we can use @code{getopt-long} to parse a given
-command line:
-
-@lisp
-(define options (getopt-long (command-line) option-spec))
-@end lisp
-
-After this call, @code{options} contains the parsed command line and is
-ready to be examined by @code{option-ref}. @code{option-ref} is called
-like this:
-
-@lisp
-(option-ref options 'help #f)
-@end lisp
-
-@noindent
-It expects the parsed command line, a symbol indicating the option to
-examine, and a default value. The default value is returned if the
-option was not present in the command line, or if the option was present
-but without a value; otherwise the value from the command line is
-returned. Usually @code{option-ref} is called once for each possible
-option that a script supports.
-
-The following example shows a main program which puts all this together
-to parse its command line and figure out what the user wanted.
-
-@lisp
-(define (main args)
- (let* ((option-spec '((version (single-char #\v) (value #f))
- (help (single-char #\h) (value #f))))
- (options (getopt-long args option-spec))
- (help-wanted (option-ref options 'help #f))
- (version-wanted (option-ref options 'version #f)))
- (if (or version-wanted help-wanted)
- (begin
- (if version-wanted
- (display "getopt-long-example version 0.3\n"))
- (if help-wanted
- (display "\
-getopt-long-example [options]
- -v, --version Display version
- -h, --help Display this help
-")))
- (begin
- (display "Hello, World!") (newline)))))
-@end lisp
-
-
-@node Option Specification
-@subsection How to Write an Option Specification
-
-An option specification is an association list (@pxref{Association
-Lists}) with one list element for each supported option. The key of each
-list element is a symbol that names the option, while the value is a
-list of option properties:
-
-@lisp
-OPTION-SPEC ::= '( (OPT-NAME1 (PROP-NAME PROP-VALUE) @dots{})
- (OPT-NAME2 (PROP-NAME PROP-VALUE) @dots{})
- (OPT-NAME3 (PROP-NAME PROP-VALUE) @dots{})
- @dots{}
- )
-@end lisp
-
-Each @var{opt-name} specifies the long option name for that option. For
-example, a list element with @var{opt-name} @code{background} specifies
-an option that can be specified on the command line using the long
-option @code{--background}. Further information about the option ---
-whether it takes a value, whether it is required to be present in the
-command line, and so on --- is specified by the option properties.
-
-In the example of the preceding subsection, we already saw that a long
-option name can have a equivalent @dfn{short option} character. The
-equivalent short option character can be set for an option by specifying
-a @code{single-char} property in that option's property list. For
-example, a list element like @code{'(output (single-char #\o) @dots{})}
-specifies an option with long name @code{--output} that can also be
-specified by the equivalent short name @code{-o}.
-
-The @code{value} property specifies whether an option requires or
-accepts a value. If the @code{value} property is set to @code{#t}, the
-option requires a value: @code{getopt-long} will signal an error if the
-option name is present without a corresponding value. If set to
-@code{#f}, the option does not take a value; in this case, a non-option
-word that follows the option name in the command line will be treated as
-a non-option argument. If set to the symbol @code{optional}, the option
-accepts a value but does not require one: a non-option word that follows
-the option name in the command line will be interpreted as that option's
-value. If the option name for an option with @code{'(value optional)}
-is immediately followed in the command line by @emph{another} option
-name, the value for the first option is implicitly @code{#t}.
-
-The @code{required?} property indicates whether an option is required to
-be present in the command line. If the @code{required?} property is
-set to @code{#t}, @code{getopt-long} will signal an error if the option
-is not specified.
-
-Finally, the @code{predicate} property can be used to constrain the
-possible values of an option. If used, the @code{predicate} property
-should be set to a procedure that takes one argument --- the proposed
-option value as a string --- and returns either @code{#t} or @code{#f}
-according as the proposed value is or is not acceptable. If the
-predicate procedure returns @code{#f}, @code{getopt-long} will signal an
-error.
-
-By default, options do not have single-character equivalents, are not
-required, and do not take values. Where the list element for an option
-includes a @code{value} property but no @code{predicate} property, the
-option values are unconstrained.
-
-
-@node Command Line Format
-@subsection Expected Command Line Format
-
-In order for @code{getopt-long} to correctly parse a command line, that
-command line must conform to a standard set of rules for how command
-line options are specified. This subsection explains what those rules
-are.
-
-@code{getopt-long} splits a given command line into several pieces. All
-elements of the argument list are classified to be either options or
-normal arguments. Options consist of two dashes and an option name
-(so-called @dfn{long} options), or of one dash followed by a single
-letter (@dfn{short} options).
-
-Options can behave as switches, when they are given without a value, or
-they can be used to pass a value to the program. The value for an
-option may be specified using an equals sign, or else is simply the next
-word in the command line, so the following two invocations are
-equivalent:
-
-@example
-$ ./foo.scm --output=bar.txt
-$ ./foo.scm --output bar.txt
-@end example
-
-Short options can be used instead of their long equivalents and can be
-grouped together after a single dash. For example, the following
-commands are equivalent.
-
-@example
-$ ./foo.scm --version --help
-$ ./foo.scm -v --help
-$ ./foo.scm -vh
-@end example
-
-If an option requires a value, it can only be grouped together with other
-short options if it is the last option in the group; the value is the
-next argument. So, for example, with the following option
-specification ---
-
-@lisp
-((apples (single-char #\a))
- (blimps (single-char #\b) (value #t))
- (catalexis (single-char #\c) (value #t)))
-@end lisp
-
-@noindent
---- the following command lines would all be acceptable:
-
-@example
-$ ./foo.scm -a -b bang -c couth
-$ ./foo.scm -ab bang -c couth
-$ ./foo.scm -ac couth -b bang
-@end example
-
-But the next command line is an error, because @code{-b} is not the last
-option in its combination, and because a group of short options cannot
-include two options that both require values:
-
-@example
-$ ./foo.scm -abc couth bang
-@end example
-
-If an option's value is optional, @code{getopt-long} decides whether the
-option has a value by looking at what follows it in the argument list.
-If the next element is a string, and it does not appear to be an option
-itself, then that string is the option's value.
-
-If the option @code{--} appears in the argument list, argument parsing
-stops there and subsequent arguments are returned as ordinary arguments,
-even if they resemble options. So, with the command line
-
-@example
-$ ./foo.scm --apples "Granny Smith" -- --blimp Goodyear
-@end example
-
-@noindent
-@code{getopt-long} will recognize the @code{--apples} option as having
-the value "Granny Smith", but will not treat @code{--blimp} as an
-option. The strings @code{--blimp} and @code{Goodyear} will be returned
-as ordinary argument strings.
-
-
-@node getopt-long Reference
-@subsection Reference Documentation for @code{getopt-long}
-
-@deffn {Scheme Procedure} getopt-long args grammar
-Parse the command line given in @var{args} (which must be a list of
-strings) according to the option specification @var{grammar}.
-
-The @var{grammar} argument is expected to be a list of this form:
-
-@code{((@var{option} (@var{property} @var{value}) @dots{}) @dots{})}
-
-where each @var{option} is a symbol denoting the long option, but
-without the two leading dashes (e.g. @code{version} if the option is
-called @code{--version}).
-
-For each option, there may be list of arbitrarily many property/value
-pairs. The order of the pairs is not important, but every property may
-only appear once in the property list. The following table lists the
-possible properties:
-
-@table @asis
-@item @code{(single-char @var{char})}
-Accept @code{-@var{char}} as a single-character equivalent to
-@code{--@var{option}}. This is how to specify traditional Unix-style
-flags.
-@item @code{(required? @var{bool})}
-If @var{bool} is true, the option is required. @code{getopt-long} will
-raise an error if it is not found in @var{args}.
-@item @code{(value @var{bool})}
-If @var{bool} is @code{#t}, the option accepts a value; if it is
-@code{#f}, it does not; and if it is the symbol @code{optional}, the
-option may appear in @var{args} with or without a value.
-@item @code{(predicate @var{func})}
-If the option accepts a value (i.e. you specified @code{(value #t)} for
-this option), then @code{getopt-long} will apply @var{func} to the
-value, and throw an exception if it returns @code{#f}. @var{func}
-should be a procedure which accepts a string and returns a boolean
-value; you may need to use quasiquotes to get it into @var{grammar}.
-@end table
-@end deffn
-
-@code{getopt-long}'s @var{args} parameter is expected to be a list of
-strings like the one returned by @code{command-line}, with the first
-element being the name of the command. Therefore @code{getopt-long}
-ignores the first element in @var{args} and starts argument
-interpretation with the second element.
-
-@code{getopt-long} signals an error if any of the following conditions
-hold.
-
-@itemize @bullet
-@item
-The option grammar has an invalid syntax.
-
-@item
-One of the options in the argument list was not specified by the
-grammar.
-
-@item
-A required option is omitted.
-
-@item
-An option which requires an argument did not get one.
-
-@item
-An option that doesn't accept an argument does get one (this can only
-happen using the long option @code{--opt=@var{value}} syntax).
-
-@item
-An option predicate fails.
-@end itemize
-
-
-@node option-ref Reference
-@subsection Reference Documentation for @code{option-ref}
-
-@deffn {Scheme Procedure} option-ref options key default
-Search @var{options} for a command line option named @var{key} and
-return its value, if found. If the option has no value, but was given,
-return @code{#t}. If the option was not given, return @var{default}.
-@var{options} must be the result of a call to @code{getopt-long}.
-@end deffn
-
-@code{option-ref} always succeeds, either by returning the requested
-option value from the command line, or the default value.
-
-The special key @code{'()} can be used to get a list of all
-non-option arguments.
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scripts.texi b/doc/ref/scripts.texi
deleted file mode 100644
index 10549dc12..000000000
--- a/doc/ref/scripts.texi
+++ /dev/null
@@ -1,225 +0,0 @@
-@page
-@node Guile Scripting
-@chapter Guile Scripting
-
-Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
-script is simply a file of Scheme code with some extra information at
-the beginning which tells the operating system how to invoke Guile, and
-then tells Guile how to handle the Scheme code.
-
-@menu
-* Invoking Guile:: How to start a Guile script.
-* The Meta Switch:: Passing complex argument lists to Guile
- from shell scripts.
-@end menu
-
-@node Invoking Guile
-@section Invoking Guile
-
-Here we describe Guile's command-line processing in detail. Guile
-processes its arguments from left to right, recognizing the switches
-described below. For examples, see @ref{Scripting Examples}.
-
-@table @code
-
-@item -s @var{script} @var{arg...}
-Read and evaluate Scheme source code from the file @var{script}, as the
-@code{load} function would. After loading @var{script}, exit. Any
-command-line arguments @var{arg...} following @var{script} become the
-script's arguments; the @code{command-line} function returns a list of
-strings of the form @code{(@var{script} @var{arg...})}.
-
-@item -c @var{expr} @var{arg...}
-Evaluate @var{expr} as Scheme code, and then exit. Any command-line
-arguments @var{arg...} following @var{expr} become command-line arguments; the
-@code{command-line} function returns a list of strings of the form
-@code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
-Guile executable.
-
-@item -- @var{arg...}
-Run interactively, prompting the user for expressions and evaluating
-them. Any command-line arguments @var{arg...} following the @code{--}
-become command-line arguments for the interactive session; the
-@code{command-line} function returns a list of strings of the form
-@code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
-Guile executable.
-
-@item -l @var{file}
-Load Scheme source code from @var{file}, and continue processing the
-command line.
-
-@item -e @var{function}
-Make @var{function} the @dfn{entry point} of the script. After loading
-the script file (with @code{-s}) or evaluating the expression (with
-@code{-c}), apply @var{function} to a list containing the program name
-and the command-line arguments --- the list provided by the
-@code{command-line} function.
-
-A @code{-e} switch can appear anywhere in the argument list, but Guile
-always invokes the @var{function} as the @emph{last} action it performs.
-This is weird, but because of the way script invocation works under
-POSIX, the @code{-s} option must always come last in the list.
-
-@xref{Scripting Examples}.
-
-@item -ds
-Treat a final @code{-s} option as if it occurred at this point in the
-command line; load the script here.
-
-This switch is necessary because, although the POSIX script invocation
-mechanism effectively requires the @code{-s} option to appear last, the
-programmer may well want to run the script before other actions
-requested on the command line. For examples, see @ref{Scripting
-Examples}.
-
-@item \
-Read more command-line arguments, starting from the second line of the
-script file. @xref{The Meta Switch}.
-
-@item --emacs
-Assume Guile is running as an inferior process of Emacs, and use a
-special protocol to communicate with Emacs's Guile interaction mode.
-This switch sets the global variable use-emacs-interface to @code{#t}.
-
-This switch is still experimental.
-
-@item --use-srfi=@var{list}
-The option @code{--use-srfi} expects a comma-separated list of numbers,
-each representing a SRFI number to be loaded into the interpreter
-before starting evaluating a script file or the REPL. Additionally,
-the feature identifier for the loaded SRFIs is recognized by
-`cond-expand' when using this option.
-
-@example
-guile --use-srfi=8,13
-@end example
-
-@item --debug
-Start with the debugging evaluator and enable backtraces. Using the
-debugging evaluator will give you better error messages but it will
-slow down execution. By default, the debugging evaluator is only used
-when entering an interactive session. When executing a script with
-@code{-s} or @code{-c}, the normal, faster evaluator is used by default.
-
-@vnew{1.8}
-@item --no-debug
-Do not use the debugging evaluator, even when entering an interactive
-session.
-
-@item -h@r{, }--help
-Display help on invoking Guile, and then exit.
-
-@item -v@r{, }--version
-Display the current version of Guile, and then exit.
-
-@end table
-
-
-@node The Meta Switch
-@section The Meta Switch
-
-Guile's command-line switches allow the programmer to describe
-reasonably complicated actions in scripts. Unfortunately, the POSIX
-script invocation mechanism only allows one argument to appear on the
-@samp{#!} line after the path to the Guile executable, and imposes
-arbitrary limits on that argument's length. Suppose you wrote a script
-starting like this:
-@example
-#!/usr/local/bin/guile -e main -s
-!#
-(define (main args)
- (map (lambda (arg) (display arg) (display " "))
- (cdr args))
- (newline))
-@end example
-The intended meaning is clear: load the file, and then call @code{main}
-on the command-line arguments. However, the system will treat
-everything after the Guile path as a single argument --- the string
-@code{"-e main -s"} --- which is not what we want.
-
-As a workaround, the meta switch @code{\} allows the Guile programmer to
-specify an arbitrary number of options without patching the kernel. If
-the first argument to Guile is @code{\}, Guile will open the script file
-whose name follows the @code{\}, parse arguments starting from the
-file's second line (according to rules described below), and substitute
-them for the @code{\} switch.
-
-Working in concert with the meta switch, Guile treats the characters
-@samp{#!} as the beginning of a comment which extends through the next
-line containing only the characters @samp{!#}. This sort of comment may
-appear anywhere in a Guile program, but it is most useful at the top of
-a file, meshing magically with the POSIX script invocation mechanism.
-
-Thus, consider a script named @file{/u/jimb/ekko} which starts like this:
-@example
-#!/usr/local/bin/guile \
--e main -s
-!#
-(define (main args)
- (map (lambda (arg) (display arg) (display " "))
- (cdr args))
- (newline))
-@end example
-
-Suppose a user invokes this script as follows:
-@example
-$ /u/jimb/ekko a b c
-@end example
-
-Here's what happens:
-@itemize @bullet
-
-@item
-the operating system recognizes the @samp{#!} token at the top of the
-file, and rewrites the command line to:
-@example
-/usr/local/bin/guile \ /u/jimb/ekko a b c
-@end example
-This is the usual behavior, prescribed by POSIX.
-
-@item
-When Guile sees the first two arguments, @code{\ /u/jimb/ekko}, it opens
-@file{/u/jimb/ekko}, parses the three arguments @code{-e}, @code{main},
-and @code{-s} from it, and substitutes them for the @code{\} switch.
-Thus, Guile's command line now reads:
-@example
-/usr/local/bin/guile -e main -s /u/jimb/ekko a b c
-@end example
-
-@item
-Guile then processes these switches: it loads @file{/u/jimb/ekko} as a
-file of Scheme code (treating the first three lines as a comment), and
-then performs the application @code{(main "/u/jimb/ekko" "a" "b" "c")}.
-
-@end itemize
-
-
-When Guile sees the meta switch @code{\}, it parses command-line
-argument from the script file according to the following rules:
-@itemize @bullet
-
-@item
-Each space character terminates an argument. This means that two
-spaces in a row introduce an argument @code{""}.
-
-@item
-The tab character is not permitted (unless you quote it with the
-backslash character, as described below), to avoid confusion.
-
-@item
-The newline character terminates the sequence of arguments, and will
-also terminate a final non-empty argument. (However, a newline
-following a space will not introduce a final empty-string argument;
-it only terminates the argument list.)
-
-@item
-The backslash character is the escape character. It escapes backslash,
-space, tab, and newline. The ANSI C escape sequences like @code{\n} and
-@code{\t} are also supported. These produce argument constituents; the
-two-character combination @code{\n} doesn't act like a terminating
-newline. The escape sequence @code{\@var{NNN}} for exactly three octal
-digits reads as the character whose ASCII code is @var{NNN}. As above,
-characters produced this way are argument constituents. Backslash
-followed by other characters is not allowed.
-
-@end itemize
diff --git a/doc/ref/scsh.texi b/doc/ref/scsh.texi
deleted file mode 100644
index 56177e78f..000000000
--- a/doc/ref/scsh.texi
+++ /dev/null
@@ -1,18 +0,0 @@
-@page
-@node The Scheme shell (scsh)
-@chapter The Scheme shell (scsh)
-
-An incomplete port of the Scheme shell (scsh) is available for Guile
-as a separate package. The current status of guile-scsh can be found at
-@url{http://arglist.com/guile/}.
-
-For information about scsh see
-@url{http://www-swiss.ai.mit.edu/ftpdir/scsh/}.
-
-The closest emulation of scsh can be obtained by running:
-
-@smalllisp
-(load-from-path "scsh/init")
-@end smalllisp
-
-See the USAGE file supplied with guile-scsh for more details.
diff --git a/doc/ref/slib.texi b/doc/ref/slib.texi
deleted file mode 100644
index 4d9e8c14c..000000000
--- a/doc/ref/slib.texi
+++ /dev/null
@@ -1,105 +0,0 @@
-@page
-@node SLIB
-@chapter SLIB
-
-Before the the SLIB facilities can be used, the following Scheme
-expression must be executed:
-
-@smalllisp
-(use-modules (ice-9 slib))
-@end smalllisp
-
-@code{require} can then be used as described in
-@ref{Top, , SLIB, slib, The SLIB Manual}.
-
-For example:
-
-@smalllisp
-guile> (use-modules (ice-9 slib))
-guile> (require 'primes)
-guile> (probably-prime? 13)
-@end smalllisp
-
-@menu
-* SLIB installation::
-* JACAL::
-@end menu
-
-@node SLIB installation
-@section SLIB installation
-
-The following seems to work (e.g., with slib versions 2c7 and 2d2):
-
-@enumerate
-@item
-Unpack slib somewhere, e.g., /usr/local/share/slib.
-
-@item
-Create a symlink in the Guile site directory to slib, e.g.,:
-
-@example
-ln -s /usr/local/share/slib /usr/local/share/guile/site/slib
-@end example
-
-@item
-Use Guile to create the catalog file, e.g.,:
-
-@example
-# guile
-guile> (use-modules (ice-9 slib))
-guile> (load "/usr/local/share/slib/mklibcat.scm")
-guile> (quit)
-@end example
-
-The catalog data should now be in
-@code{/usr/local/share/guile/site/slibcat}.
-
-If instead you get an error such as:
-
-@example
-Unbound variable: scheme-implementation-type
-@end example
-
-then a solution is to get a newer version of Guile,
-or to modify ice-9/slib.scm to use define-public for the
-offending variables.
-
-@item
-Install the documentation:
-
-@example
-cd /usr/local/share/slib
-rm /usr/local/info/slib.info*
-cp slib.info /usr/local/info
-install-info slib.info /usr/local/info/dir
-@end example
-@end enumerate
-
-@node JACAL
-@section JACAL
-
-@cindex Jaffer, Aubrey
-@cindex symbolic math
-@cindex math -- symbolic
-Jacal is a symbolic math package written in Scheme by Aubrey Jaffer. It
-is usually installed as an extra package in SLIB (@pxref{Packages not
-shipped with Guile}).
-
-You can use Guile's interface to SLIB to invoke Jacal:
-
-@smalllisp
-(use-modules (ice-9 slib))
-(slib:load "math")
-(math)
-@end smalllisp
-
-@noindent
-For complete documentation on Jacal, please read the Jacal manual. If
-it has been installed on line, you can look at @ref{Top, , Jacal, jacal,
-The SLIB Manual}. Otherwise you can find it on the web at
-@url{http://www-swiss.ai.mit.edu/~jaffer/JACAL.html}
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi
deleted file mode 100644
index 32de27a4b..000000000
--- a/doc/ref/srfi-modules.texi
+++ /dev/null
@@ -1,2399 +0,0 @@
-@page
-@node SRFI Support
-@chapter SRFI Support Modules
-
-SRFI is an acronym for Scheme Request For Implementation. The SRFI
-documents define a lot of syntactic and procedure extensions to standard
-Scheme as defined in R5RS.
-
-Guile has support for a number of SRFIs. This chapter gives an overview
-over the available SRFIs and some usage hints. For complete
-documentation, design rationales and further examples, we advise you to
-get the relevant SRFI documents from the SRFI home page
-@url{http://srfi.schemers.org}.
-
-@menu
-* About SRFI Usage:: What to know about Guile's SRFI support.
-* SRFI-0:: cond-expand
-* SRFI-1:: List library.
-* SRFI-2:: and-let*.
-* SRFI-4:: Homogeneous numeric vector datatypes.
-* SRFI-6:: Basic String Ports.
-* SRFI-8:: receive.
-* SRFI-9:: define-record-type.
-* SRFI-10:: Hash-Comma Reader Extension.
-* SRFI-11:: let-values and let-values*.
-* SRFI-13:: String library.
-* SRFI-14:: Character-set library.
-* SRFI-16:: case-lambda
-* SRFI-17:: Generalized set!
-* SRFI-19:: Time/Date library.
-@end menu
-
-
-@node About SRFI Usage
-@section About SRFI Usage
-
-@c FIXME::martin: Review me!
-
-SRFI support in Guile is currently implemented partly in the core
-library, and partly as add-on modules. That means that some SRFIs are
-automatically available when the interpreter is started, whereas the
-other SRFIs require you to use the appropriate support module
-explicitly.
-
-There are several reasons for this inconsistency. First, the feature
-checking syntactic form @code{cond-expand} (@pxref{SRFI-0}) must be
-available immediately, because it must be there when the user wants to
-check for the Scheme implementation, that is, before she can know that
-it is safe to use @code{use-modules} to load SRFI support modules. The
-second reason is that some features defined in SRFIs had been
-implemented in Guile before the developers started to add SRFI
-implementations as modules (for example SRFI-6 (@pxref{SRFI-6})). In
-the future, it is possible that SRFIs in the core library might be
-factored out into separate modules, requiring explicit module loading
-when they are needed. So you should be prepared to have to use
-@code{use-modules} someday in the future to access SRFI-6 bindings. If
-you want, you can do that already. We have included the module
-@code{(srfi srfi-6)} in the distribution, which currently does nothing,
-but ensures that you can write future-safe code.
-
-Generally, support for a specific SRFI is made available by using
-modules named @code{(srfi srfi-@var{number})}, where @var{number} is the
-number of the SRFI needed. Another possibility is to use the command
-line option @code{--use-srfi}, which will load the necessary modules
-automatically (@pxref{Invoking Guile}).
-
-
-@node SRFI-0
-@section SRFI-0 - cond-expand
-
-@c FIXME::martin: Review me!
-
-SRFI-0 defines a means for checking whether a Scheme implementation has
-support for a specified feature. The syntactic form @code{cond-expand},
-which implements this means, has the following syntax.
-
-@example
-@group
-<cond-expand>
- --> (cond-expand <cond-expand-clause>+)
- | (cond-expand <cond-expand-clause>* (else <command-or-definition>))
-<cond-expand-clause>
- --> (<feature-requirement> <command-or-definition>*)
-<feature-requirement>
- --> <feature-identifier>
- | (and <feature-requirement>*)
- | (or <feature-requirement>*)
- | (not <feature-requirement>)
-<feature-identifier>
- --> <a symbol which is the name or alias of a SRFI>
-@end group
-@end example
-
-When evaluated, this form checks all clauses in order, until it finds
-one whose feature requirement is satisfied. Then the form expands into
-the commands or definitions in the clause. A requirement is tested as
-follows:
-
-@itemize @bullet
-@item
-If it is a symbol, it is satisfied if the feature identifier is
-supported.
-
-@item
-If it is an @code{and} form, all requirements must be satisfied. If no
-requirements are given, it is satisfied, too.
-
-@item
-If it is an @code{or} form, at least one of the requirements must be
-satisfied. If no requirements are given, it is not satisfied.
-
-@item
-If it is a @code{not} form, the feature requirement must @emph{not} be
-satisfied.
-
-@item
-If the feature requirement is the keyword @code{else} and it is the last
-clause, it is satisfied if no prior clause matched.
-@end itemize
-
-If no clause is satisfied, an error is signalled.
-
-Since @code{cond-expand} is needed to tell what a Scheme implementation
-provides, it must be accessible without using any
-implementation-dependent operations, such as @code{use-modules} in
-Guile. Thus, it is not necessary to use any module to get access to
-this form.
-
-Currently, the feature identifiers @code{guile}, @code{r5rs} and
-@code{srfi-0} are supported. The other SRFIs are not in that list by
-default, because the SRFI modules must be explicitly used before their
-exported bindings can be used.
-
-So if a Scheme program wishes to use SRFI-8, it has two possibilities:
-First, it can check whether the running Scheme implementation is Guile,
-and if it is, it can use the appropriate module:
-
-@lisp
-(cond-expand
- (guile
- (use-modules (srfi srfi-8)))
- (srfi-8
- #t))
- ;; otherwise fail.
-@end lisp
-
-The other possibility is to use the @code{--use-srfi} command line
-option when invoking Guile (@pxref{Invoking Guile}). When you do that,
-the specified SRFI support modules will be loaded and add their feature
-identifier to the list of symbols checked by @code{cond-expand}.
-
-So, if you invoke Guile like this:
-
-@example
-$ guile --use-srfi=8
-@end example
-
-the following snippet will expand to @code{'hooray}.
-
-@lisp
-(cond-expand (srfi-8 'hooray))
-@end lisp
-
-
-@node SRFI-1
-@section SRFI-1 - List library
-
-@c FIXME::martin: Review me!
-
-The list library defined in SRFI-1 contains a lot of useful list
-processing procedures for construction, examining, destructuring and
-manipulating lists and pairs.
-
-Since SRFI-1 also defines some procedures which are already contained
-in R5RS and thus are supported by the Guile core library, some list
-and pair procedures which appear in the SRFI-1 document may not appear
-in this section. So when looking for a particular list/pair
-processing procedure, you should also have a look at the sections
-@ref{Lists} and @ref{Pairs}.
-
-@menu
-* SRFI-1 Constructors:: Constructing new lists.
-* SRFI-1 Predicates:: Testing list for specific properties.
-* SRFI-1 Selectors:: Selecting elements from lists.
-* SRFI-1 Length Append etc:: Length calculation and list appending.
-* SRFI-1 Fold and Map:: Higher-order list processing.
-* SRFI-1 Filtering and Partitioning:: Filter lists based on predicates.
-* SRFI-1 Searching:: Search for elements.
-* SRFI-1 Deleting:: Delete elements from lists.
-* SRFI-1 Association Lists:: Handle association lists.
-* SRFI-1 Set Operations:: Use lists for representing sets.
-@end menu
-
-@node SRFI-1 Constructors
-@subsection Constructors
-
-@c FIXME::martin: Review me!
-
-New lists can be constructed by calling one of the following
-procedures.
-
-@deffn {Scheme Procedure} xcons d a
-Like @code{cons}, but with interchanged arguments. Useful mostly when
-passed to higher-order procedures.
-@end deffn
-
-@deffn {Scheme Procedure} list-tabulate n init-proc
-Return an @var{n}-element list, where each list element is produced by
-applying the procedure @var{init-proc} to the corresponding list
-index. The order in which @var{init-proc} is applied to the indices
-is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} circular-list elt1 elt2 @dots{}
-Return a circular list containing the given arguments @var{elt1}
-@var{elt2} @dots{}.
-@end deffn
-
-@deffn {Scheme Procedure} iota count [start step]
-Return a list containing @var{count} elements, where each element is
-calculated as follows:
-
-@var{start} + (@var{count} - 1) * @var{step}
-
-@var{start} defaults to 0 and @var{step} defaults to 1.
-@end deffn
-
-
-@node SRFI-1 Predicates
-@subsection Predicates
-
-@c FIXME::martin: Review me!
-
-The procedures in this section test specific properties of lists.
-
-@deffn {Scheme Procedure} proper-list? obj
-Return @code{#t} if @var{obj} is a proper list, that is a finite list,
-terminated with the empty list. Otherwise, return @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} circular-list? obj
-Return @code{#t} if @var{obj} is a circular list, otherwise return
-@code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} dotted-list? obj
-Return @code{#t} if @var{obj} is a dotted list, return @code{#f}
-otherwise. A dotted list is a finite list which is not terminated by
-the empty list, but some other value.
-@end deffn
-
-@deffn {Scheme Procedure} null-list? lst
-Return @code{#t} if @var{lst} is the empty list @code{()}, @code{#f}
-otherwise. If something else than a proper or circular list is passed
-as @var{lst}, an error is signalled. This procedure is recommended
-for checking for the end of a list in contexts where dotted lists are
-not allowed.
-@end deffn
-
-@deffn {Scheme Procedure} not-pair? obj
-Return @code{#t} is @var{obj} is not a pair, @code{#f} otherwise.
-This is shorthand notation @code{(not (pair? @var{obj}))} and is
-supposed to be used for end-of-list checking in contexts where dotted
-lists are allowed.
-@end deffn
-
-@deffn {Scheme Procedure} list= elt= list1 @dots{}
-Return @code{#t} if all argument lists are equal, @code{#f} otherwise.
-List equality is determined by testing whether all lists have the same
-length and the corresponding elements are equal in the sense of the
-equality predicate @var{elt=}. If no or only one list is given,
-@code{#t} is returned.
-@end deffn
-
-
-@node SRFI-1 Selectors
-@subsection Selectors
-
-@c FIXME::martin: Review me!
-
-@deffn {Scheme Procedure} first pair
-@deffnx {Scheme Procedure} second pair
-@deffnx {Scheme Procedure} third pair
-@deffnx {Scheme Procedure} fourth pair
-@deffnx {Scheme Procedure} fifth pair
-@deffnx {Scheme Procedure} sixth pair
-@deffnx {Scheme Procedure} seventh pair
-@deffnx {Scheme Procedure} eighth pair
-@deffnx {Scheme Procedure} ninth pair
-@deffnx {Scheme Procedure} tenth pair
-These are synonyms for @code{car}, @code{cadr}, @code{caddr}, @dots{}.
-@end deffn
-
-@deffn {Scheme Procedure} car+cdr pair
-Return two values, the @sc{car} and the @sc{cdr} of @var{pair}.
-@end deffn
-
-@deffn {Scheme Procedure} take lst i
-@deffnx {Scheme Procedure} take! lst i
-Return a list containing the first @var{i} elements of @var{lst}.
-
-@code{take!} may modify the structure of the argument list @var{lst}
-in order to produce the result.
-@end deffn
-
-@deffn {Scheme Procedure} drop lst i
-Return a list containing all but the first @var{i} elements of
-@var{lst}.
-@end deffn
-
-@deffn {Scheme Procedure} take-right lst i
-Return the a list containing the @var{i} last elements of @var{lst}.
-@end deffn
-
-@deffn {Scheme Procedure} drop-right lst i
-@deffnx {Scheme Procedure} drop-right! lst i
-Return the a list containing all but the @var{i} last elements of
-@var{lst}.
-
-@code{drop-right!} may modify the structure of the argument list
-@var{lst} in order to produce the result.
-@end deffn
-
-@deffn {Scheme Procedure} split-at lst i
-@deffnx {Scheme Procedure} split-at! lst i
-Return two values, a list containing the first @var{i} elements of the
-list @var{lst} and a list containing the remaining elements.
-
-@code{split-at!} may modify the structure of the argument list
-@var{lst} in order to produce the result.
-@end deffn
-
-@deffn {Scheme Procedure} last lst
-Return the last element of the non-empty, finite list @var{lst}.
-@end deffn
-
-
-@node SRFI-1 Length Append etc
-@subsection Length, Append, Concatenate, etc.
-
-@c FIXME::martin: Review me!
-
-@deffn {Scheme Procedure} length+ lst
-Return the length of the argument list @var{lst}. When @var{lst} is a
-circular list, @code{#f} is returned.
-@end deffn
-
-@deffn {Scheme Procedure} concatenate list-of-lists
-@deffnx {Scheme Procedure} concatenate! list-of-lists
-Construct a list by appending all lists in @var{list-of-lists}.
-
-@code{concatenate!} may modify the structure of the given lists in
-order to produce the result.
-@end deffn
-
-@deffn {Scheme Procedure} append-reverse rev-head tail
-@deffnx {Scheme Procedure} append-reverse! rev-head tail
-Reverse @var{rev-head}, append @var{tail} and return the result. This
-is equivalent to @code{(append (reverse @var{rev-head}) @var{tail})},
-but more efficient.
-
-@code{append-reverse!} may modify @var{rev-head} in order to produce
-the result.
-@end deffn
-
-@deffn {Scheme Procedure} zip lst1 lst2 @dots{}
-Return a list as long as the shortest of the argument lists, where
-each element is a list. The first list contains the first elements of
-the argument lists, the second list contains the second elements, and
-so on.
-@end deffn
-
-@deffn {Scheme Procedure} unzip1 lst
-@deffnx {Scheme Procedure} unzip2 lst
-@deffnx {Scheme Procedure} unzip3 lst
-@deffnx {Scheme Procedure} unzip4 lst
-@deffnx {Scheme Procedure} unzip5 lst
-@code{unzip1} takes a list of lists, and returns a list containing the
-first elements of each list, @code{unzip2} returns two lists, the
-first containing the first elements of each lists and the second
-containing the second elements of each lists, and so on.
-@end deffn
-
-
-@node SRFI-1 Fold and Map
-@subsection Fold, Unfold & Map
-
-@c FIXME::martin: Review me!
-
-@deffn {Scheme Procedure} fold kons knil lst1 lst2 @dots{}
-Fold the procedure @var{kons} across all elements of @var{lst1},
-@var{lst2}, @dots{}. Produce the result of
-
-@code{(@var{kons} @var{en1} @var{en2} @dots{} (@var{kons} @var{e21}
-@var{e22} (@var{kons} @var{e11} @var{e12} @var{knil})))},
-
-if @var{enm} are the elements of the lists @var{lst1}, @var{lst2},
-@dots{}.
-@end deffn
-
-@deffn {Scheme Procedure} fold-right kons knil lst1 lst2 @dots{}
-Similar to @code{fold}, but applies @var{kons} in right-to-left order
-to the list elements, that is:
-
-@code{(@var{kons} @var{e11} @var{e12}(@var{kons} @var{e21}
-@var{e22} @dots{} (@var{kons} @var{en1} @var{en2} @var{knil})))},
-@end deffn
-
-@deffn {Scheme Procedure} pair-fold kons knil lst1 lst2 @dots{}
-Like @code{fold}, but apply @var{kons} to the pairs of the list
-instead of the list elements.
-@end deffn
-
-@deffn {Scheme Procedure} pair-fold-right kons knil lst1 lst2 @dots{}
-Like @code{fold-right}, but apply @var{kons} to the pairs of the list
-instead of the list elements.
-@end deffn
-
-@deffn {Scheme Procedure} reduce f ridentity lst
-@code{reduce} is a variant of @code{reduce}. If @var{lst} is
-@code{()}, @var{ridentity} is returned. Otherwise, @code{(fold (car
-@var{lst}) (cdr @var{lst}))} is returned.
-@end deffn
-
-@deffn {Scheme Procedure} reduce-right f ridentity lst
-This is the @code{fold-right} variant of @var{reduce}.
-@end deffn
-
-@deffn {Scheme Procedure} unfold p f g seed [tail-gen]
-@code{unfold} is defined as follows:
-
-@lisp
-(unfold p f g seed) =
- (if (p seed) (tail-gen seed)
- (cons (f seed)
- (unfold p f g (g seed))))
-@end lisp
-
-@table @var
-@item p
-Determines when to stop unfolding.
-
-@item f
-Maps each seed value to the corresponding list element.
-
-@item g
-Maps each seed value to next seed valu.
-
-@item seed
-The state value for the unfold.
-
-@item tail-gen
-Creates the tail of the list; defaults to @code{(lambda (x) '())}.
-@end table
-
-@var{g} produces a series of seed values, which are mapped to list
-elements by @var{f}. These elements are put into a list in
-left-to-right order, and @var{p} tells when to stop unfolding.
-@end deffn
-
-@deffn {Scheme Procedure} unfold-right p f g seed [tail]
-Construct a list with the following loop.
-
-@lisp
-(let lp ((seed seed) (lis tail))
- (if (p seed) lis
- (lp (g seed)
- (cons (f seed) lis))))
-@end lisp
-
-@table @var
-@item p
-Determines when to stop unfolding.
-
-@item f
-Maps each seed value to the corresponding list element.
-
-@item g
-Maps each seed value to next seed valu.
-
-@item seed
-The state value for the unfold.
-
-@item tail-gen
-Creates the tail of the list; defaults to @code{(lambda (x) '())}.
-@end table
-
-@end deffn
-
-@deffn {Scheme Procedure} map f lst1 lst2 @dots{}
-Map the procedure over the list(s) @var{lst1}, @var{lst2}, @dots{} and
-return a list containing the results of the procedure applications.
-This procedure is extended with respect to R5RS, because the argument
-lists may have different lengths. The result list will have the same
-length as the shortest argument lists. The order in which @var{f}
-will be applied to the list element(s) is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} for-each f lst1 lst2 @dots{}
-Apply the procedure @var{f} to each pair of corresponding elements of
-the list(s) @var{lst1}, @var{lst2}, @dots{}. The return value is not
-specified. This procedure is extended with respect to R5RS, because
-the argument lists may have different lengths. The shortest argument
-list determines the number of times @var{f} is called. @var{f} will
-be applied to the list elements in left-to-right order.
-
-@end deffn
-
-@deffn {Scheme Procedure} append-map f lst1 lst2 @dots{}
-@deffnx {Scheme Procedure} append-map! f lst1 lst2 @dots{}
-Equivalent to
-
-@lisp
-(apply append (map f clist1 clist2 ...))
-@end lisp
-
-and
-
-@lisp
-(apply append! (map f clist1 clist2 ...))
-@end lisp
-
-Map @var{f} over the elements of the lists, just as in the @code{map}
-function. However, the results of the applications are appended
-together to make the final result. @code{append-map} uses
-@code{append} to append the results together; @code{append-map!} uses
-@code{append!}.
-
-The dynamic order in which the various applications of @var{f} are
-made is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} map! f lst1 lst2 @dots{}
-Linear-update variant of @code{map} -- @code{map!} is allowed, but not
-required, to alter the cons cells of @var{lst1} to construct the
-result list.
-
-The dynamic order in which the various applications of @var{f} are
-made is not specified. In the n-ary case, @var{lst2}, @var{lst3},
-@dots{} must have at least as many elements as @var{lst1}.
-@end deffn
-
-@deffn {Scheme Procedure} pair-for-each f lst1 lst2 @dots{}
-Like @code{for-each}, but applies the procedure @var{f} to the pairs
-from which the argument lists are constructed, instead of the list
-elements. The return value is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} filter-map f lst1 lst2 @dots{}
-Like @code{map}, but only results from the applications of @var{f}
-which are true are saved in the result list.
-@end deffn
-
-
-@node SRFI-1 Filtering and Partitioning
-@subsection Filtering and Partitioning
-
-@c FIXME::martin: Review me!
-
-Filtering means to collect all elements from a list which satisfy a
-specific condition. Partitioning a list means to make two groups of
-list elements, one which contains the elements satisfying a condition,
-and the other for the elements which don't.
-
-@deffn {Scheme Procedure} filter pred lst
-@deffnx {Scheme Procedure} filter! pred lst
-Return a list containing all elements from @var{lst} which satisfy the
-predicate @var{pred}. The elements in the result list have the same
-order as in @var{lst}. The order in which @var{pred} is applied to
-the list elements is not specified.
-
-@code{filter!} is allowed, but not required to modify the structure of
-@end deffn
-
-@deffn {Scheme Procedure} partition pred lst
-@deffnx {Scheme Procedure} partition! pred lst
-Return two lists, one containing all elements from @var{lst} which
-satisfy the predicate @var{pred}, and one list containing the elements
-which do not satisfy the predicated. The elements in the result lists
-have the same order as in @var{lst}. The order in which @var{pred} is
-applied to the list elements is not specified.
-
-@code{partition!} is allowed, but not required to modify the structure of
-the input list.
-@end deffn
-
-@deffn {Scheme Procedure} remove pred lst
-@deffnx {Scheme Procedure} remove! pred lst
-Return a list containing all elements from @var{lst} which do not
-satisfy the predicate @var{pred}. The elements in the result list
-have the same order as in @var{lst}. The order in which @var{pred} is
-applied to the list elements is not specified.
-
-@code{remove!} is allowed, but not required to modify the structure of
-the input list.
-@end deffn
-
-
-@node SRFI-1 Searching
-@subsection Searching
-
-@c FIXME::martin: Review me!
-
-The procedures for searching elements in lists either accept a
-predicate or a comparison object for determining which elements are to
-be searched.
-
-@deffn {Scheme Procedure} find pred lst
-Return the first element of @var{lst} which satisfies the predicate
-@var{pred} and @code{#f} if no such element is found.
-@end deffn
-
-@deffn {Scheme Procedure} find-tail pred lst
-Return the first pair of @var{lst} whose @sc{car} satisfies the
-predicate @var{pred} and @code{#f} if no such element is found.
-@end deffn
-
-@deffn {Scheme Procedure} take-while pred lst
-@deffnx {Scheme Procedure} take-while! pred lst
-Return the longest initial prefix of @var{lst} whose elements all
-satisfy the predicate @var{pred}.
-
-@code{take-while!} is allowed, but not required to modify the input
-list while producing the result.
-@end deffn
-
-@deffn {Scheme Procedure} drop-while pred lst
-Drop the longest initial prefix of @var{lst} whose elements all
-satisfy the predicate @var{pred}.
-@end deffn
-
-@deffn {Scheme Procedure} span pred lst
-@deffnx {Scheme Procedure} span! pred lst
-@deffnx {Scheme Procedure} break pred lst
-@deffnx {Scheme Procedure} break! pred lst
-@code{span} splits the list @var{lst} into the longest initial prefix
-whose elements all satisfy the predicate @var{pred}, and the remaining
-tail. @code{break} inverts the sense of the predicate.
-
-@code{span!} and @code{break!} are allowed, but not required to modify
-the structure of the input list @var{lst} in order to produce the
-result.
-@end deffn
-
-@deffn {Scheme Procedure} any pred lst1 lst2 @dots{}
-Apply @var{pred} across the lists and return a true value if the
-predicate returns true for any of the list elements(s); return
-@code{#f} otherwise. The true value returned is always the result of
-the first successful application of @var{pred}.
-@end deffn
-
-@deffn {Scheme Procedure} every pred lst1 lst2 @dots{}
-Apply @var{pred} across the lists and return a true value if the
-predicate returns true for every of the list elements(s); return
-@code{#f} otherwise. The true value returned is always the result of
-the final successful application of @var{pred}.
-@end deffn
-
-@deffn {Scheme Procedure} list-index pred lst1 lst2 @dots{}
-Return the index of the leftmost element that satisfies @var{pred}.
-@end deffn
-
-@deffn {Scheme Procedure} member x lst [=]
-Return the first sublist of @var{lst} whose @sc{car} is equal to
-@var{x}. If @var{x} does no appear in @var{lst}, return @code{#f}.
-Equality is determined by the equality predicate @var{=}, or
-@code{equal?} if @var{=} is not given.
-@end deffn
-
-
-@node SRFI-1 Deleting
-@subsection Deleting
-
-@c FIXME::martin: Review me!
-
-The procedures for deleting elements from a list either accept a
-predicate or a comparison object for determining which elements are to
-be removed.
-
-@deffn {Scheme Procedure} delete x lst [=]
-@deffnx {Scheme Procedure} delete! x lst [=]
-Return a list containing all elements from @var{lst}, but without the
-elements equal to @var{x}. Equality is determined by the equality
-predicate @var{=}, which defaults to @code{equal?} if not given.
-
-@code{delete!} is allowed, but not required to modify the structure of
-the argument list in order to produce the result.
-@end deffn
-
-@deffn {Scheme Procedure} delete-duplicates lst [=]
-@deffnx {Scheme Procedure} delete-duplicates! lst [=]
-Return a list containing all elements from @var{lst}, but without
-duplicate elements. Equality of elements is determined by the
-equality predicate @var{=}, which defaults to @code{equal?} if not
-given.
-
-@code{delete-duplicates!} is allowed, but not required to modify the
-structure of the argument list in order to produce the result.
-@end deffn
-
-
-@node SRFI-1 Association Lists
-@subsection Association Lists
-
-@c FIXME::martin: Review me!
-
-Association lists are described in detail in section @ref{Association
-Lists}. The present section only documents the additional procedures
-for dealing with association lists defined by SRFI-1.
-
-@deffn {Scheme Procedure} assoc key alist [=]
-Return the pair from @var{alist} which matches @var{key}. Equality is
-determined by @var{=}, which defaults to @code{equal?} if not given.
-@var{alist} must be an association lists---a list of pairs.
-@end deffn
-
-@deffn {Scheme Procedure} alist-cons key datum alist
-Equivalent to
-
-@lisp
-(cons (cons @var{key} @var{datum}) @var{alist})
-@end lisp
-
-This procedure is used to coons a new pair onto an existing
-association list.
-@end deffn
-
-@deffn {Scheme Procedure} alist-copy alist
-Return a newly allocated copy of @var{alist}, that means that the
-spine of the list as well as the pairs are copied.
-@end deffn
-
-@deffn {Scheme Procedure} alist-delete key alist [=]
-@deffnx {Scheme Procedure} alist-delete! key alist [=]
-Return a list containing the pairs of @var{alist}, but without the
-pairs whose @sc{cars} are equal to @var{key}. Equality is determined
-by @var{=}, which defaults to @code{equal?} if not given.
-
-@code{alist-delete!} is allowed, but not required to modify the
-structure of the list @var{alist} in order to produce the result.
-@end deffn
-
-
-@node SRFI-1 Set Operations
-@subsection Set Operations on Lists
-
-@c FIXME::martin: Review me!
-
-Lists can be used for representing sets of objects. The procedures
-documented in this section can be used for such set representations.
-Man combining several sets or adding elements, they make sure that no
-object is contained more than once in a given list. Please note that
-lists are not a too efficient implementation method for sets, so if
-you need high performance, you should think about implementing a
-custom data structure for representing sets, such as trees, bitsets,
-hash tables or something similar.
-
-All these procedures accept an equality predicate as the first
-argument. This predicate is used for testing the objects in the list
-sets for sameness.
-
-@deffn {Scheme Procedure} lset<= = list1 @dots{}
-Return @code{#t} if every @var{listi} is a subset of @var{listi+1},
-otherwise return @code{#f}. Returns @code{#t} if called with less
-than two arguments. @var{=} is used for testing element equality.
-@end deffn
-
-@deffn {Scheme Procedure} lset= = list1 list2 @dots{}
-Return @code{#t} if all argument lists are equal. @var{=} is used for
-testing element equality.
-@end deffn
-
-@deffn {Scheme Procedure} lset-adjoin = list elt1 @dots{}
-@deffnx {Scheme Procedure} lset-adjoin! = list elt1 @dots{}
-Add all @var{elts} to the list @var{list}, suppressing duplicates and
-return the resulting list. @code{lset-adjoin!} is allowed, but not
-required to modify its first argument. @var{=} is used for testing
-element equality.
-@end deffn
-
-@deffn {Scheme Procedure} lset-union = list1 @dots{}
-@deffnx {Scheme Procedure} lset-union! = list1 @dots{}
-Return the union of all argument list sets. The union is the set of
-all elements which appear in any of the argument sets.
-@code{lset-union!} is allowed, but not required to modify its first
-argument. @var{=} is used for testing element equality.
-@end deffn
-
-@deffn {Scheme Procedure} lset-intersection = list1 list2 @dots{}
-@deffnx {Scheme Procedure} lset-intersection! = list1 list2 @dots{}
-Return the intersection of all argument list sets. The intersection
-is the set containing all elements which appear in all argument sets.
-@code{lset-intersection!} is allowed, but not required to modify its
-first argument. @var{=} is used for testing element equality.
-@end deffn
-
-@deffn {Scheme Procedure} lset-difference = list1 list2 @dots{}
-@deffnx {Scheme Procedure} lset-difference! = list1 list2 @dots{}
-Return the difference of all argument list sets. The difference is
-the the set containing all elements of the first list which do not
-appear in the other lists. @code{lset-difference!} is allowed, but
-not required to modify its first argument. @var{=} is used for testing
-element equality.
-@end deffn
-
-@deffn {Scheme Procedure} lset-xor = list1 @dots{}
-@deffnx {Scheme Procedure} lset-xor! = list1 @dots{}
-Return the set containing all elements which appear in the first
-argument list set, but not in the second; or, more generally: which
-appear in an odd number of sets. @code{lset-xor!} is allowed, but
-not required to modify its first argument. @var{=} is used for testing
-element equality.
-@end deffn
-
-@deffn {Scheme Procedure} lset-diff+intersection = list1 list2 @dots{}
-@deffnx {Scheme Procedure} lset-diff+intersection! = list1 list2 @dots{}
-Return two values, the difference and the intersection of the argument
-list sets. This works like a combination of @code{lset-difference} and
-@code{lset-intersection}, but is more efficient.
-@code{lset-diff+intersection!} is allowed, but not required to modify
-its first argument. @var{=} is used for testing element equality. You
-have to use some means to deal with the multiple values these
-procedures return (@pxref{Multiple Values}).
-@end deffn
-
-
-@node SRFI-2
-@section SRFI-2 - and-let*
-
-@c FIXME::martin: Review me!
-
-The syntactic form @code{and-let*} combines the conditional evaluation
-form @code{and} with the binding form @var{let*}. Each argument
-expression will be evaluated sequentially, bound to a variable (if a
-variable name is given), but only as long as no expression returns
-the false value @code{#f}.
-
-Use @code{(use-modules (srfi srfi-2)} to access this syntax form.
-
-A short example will demonstrate how it works. In the first expression,
-@var{x} will get bound to 1, but the next expression (@code{#f}) is
-false, so evaluation of the form is stopped, and @code{#f} is returned.
-In the next expression, @var{x} is bound to 1, @var{y} is bound to
-@code{#t} and since no expression in the binding section was false, the
-body of the @code{and-let*} expression is evaluated, which in this case
-returns the value of @var{x}.
-
-@lisp
-(and-let* ((x 1) (y #f)) 42)
-@result{}
-#f
-(and-let* ((x 1) (y #t)) x)
-@result{}
-1
-@end lisp
-
-
-@node SRFI-4
-@section SRFI-4 - Homogeneous numeric vector datatypes.
-
-@c FIXME::martin: Review me!
-
-SRFI-4 defines a set of datatypes for vectors whose elements are all
-of the same numeric type. Vectors for signed and unsigned exact
-integer or inexact real numbers in several precisions are available.
-
-Procedures similar to the vector procedures (@pxref{Vectors}) are
-provided for handling these homogeneous vectors, but they are distinct
-datatypes.
-
-The reason for providing this set of datatypes is that with the
-limitation (all elements must have the same type), it is possible to
-implement them much more memory-efficient than normal, heterogenous
-vectors.
-
-If you want to use these datatypes and the corresponding procedures,
-you have to use the module @code{(srfi srfi-4)}.
-
-Ten vector data types are provided: Unsigned and signed integer values
-with 8, 16, 32 and 64 bits and floating point values with 32 and 64
-bits. In the following descriptions, the tags @code{u8}, @code{s8},
-@code{u16}, @code{s16}, @code{u32}, @code{s32}, @code{u64},
-@code{s64}, @code{f32}, @code{f64}, respectively, are used for
-denoting the various types.
-
-@menu
-* SRFI-4 - Read Syntax:: How to write homogeneous vector literals.
-* SRFI-4 - Procedures:: Available homogeneous vector procedures.
-@end menu
-
-
-@node SRFI-4 - Read Syntax
-@subsection SRFI-4 - Read Syntax
-
-Homogeneous numeric vectors have an external representation (read
-syntax) similar to normal Scheme vectors, but with an additional tag
-telling the vector's type.
-
-@lisp
-#u16(1 2 3)
-@end lisp
-
-denotes a homogeneous numeric vector of three elements, which are the
-values 1, 2 and 3, represented as 16-bit unsigned integers.
-Correspondingly,
-
-@lisp
-#f64(3.1415 2.71)
-@end lisp
-
-denotes a vector of two elements, which are the values 3.1415 and
-2.71, represented as floating-point values of 64 bit precision.
-
-Please note that the read syntax for floating-point vectors conflicts
-with Standard Scheme, because there @code{#f} is defined to be the
-literal false value. That means, that with the loaded SRFI-4 module,
-it is not possible to enter some list like
-
-@lisp
-'(1 #f3)
-@end lisp
-
-and hope that it will be parsed as a three-element list with the
-elements 1, @code{#f} and 3. In normal use, this should be no
-problem, because people tend to terminate tokens sensibly when writing
-Scheme expressions.
-
-@node SRFI-4 - Procedures
-@subsection SRFI-4 Procedures
-
-The procedures listed in this section are provided for all homogeneous
-numeric vector datatypes. For brevity, they are not all documented,
-but a summary of the procedures is given. In the following
-descriptions, you can replace @code{TAG} by any of the datatype
-indicators @code{u8}, @code{s8}, @code{u16}, @code{s16}, @code{u32},
-@code{s32}, @code{u64}, @code{s64}, @code{f32} and @code{f64}.
-
-For example, you can use the procedures @code{u8vector?},
-@code{make-s8vector}, @code{u16vector}, @code{u32vector-length},
-@code{s64vector-ref}, @code{f32vector-set!} or @code{f64vector->list}.
-
-@deffn {Scheme Procedure} TAGvector? obj
-Return @code{#t} if @var{obj} is a homogeneous numeric vector of type
-@code{TAG}.
-@end deffn
-
-@deffn {Scheme Procedure} make-TAGvector n [value]
-Create a newly allocated homogeneous numeric vector of type
-@code{TAG}, which can hold @var{n} elements. If @var{value} is given,
-the vector is initialized with the value, otherwise, the contents of
-the returned vector is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} TAGvector value1 @dots{}
-Create a newly allocated homogeneous numeric vector of type
-@code{TAG}. The returned vector is as long as the number of arguments
-given, and is initialized with the argument values.
-@end deffn
-
-@deffn {Scheme Procedure} TAGvector-length TAGvec
-Return the number of elements in @var{TAGvec}.
-@end deffn
-
-@deffn {Scheme Procedure} TAGvector-ref TAGvec i
-Return the element at index @var{i} in @var{TAGvec}.
-@end deffn
-
-@deffn {Scheme Procedure} TAGvector-ref TAGvec i value
-Set the element at index @var{i} in @var{TAGvec} to @var{value}. The
-return value is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} TAGvector->list TAGvec
-Return a newly allocated list holding all elements of @var{TAGvec}.
-@end deffn
-
-@deffn {Scheme Procedure} list->TAGvector lst
-Return a newly allocated homogeneous numeric vector of type @code{TAG},
-initialized with the elements of the list @var{lst}.
-@end deffn
-
-
-@node SRFI-6
-@section SRFI-6 - Basic String Ports
-
-SRFI-6 defines the procedures @code{open-input-string},
-@code{open-output-string} and @code{get-output-string}. These
-procedures are included in the Guile core, so using this module does not
-make any difference at the moment. But it is possible that support for
-SRFI-6 will be factored out of the core library in the future, so using
-this module does not hurt, after all.
-
-@node SRFI-8
-@section SRFI-8 - receive
-
-@code{receive} is a syntax for making the handling of multiple-value
-procedures easier. It is documented in @xref{Multiple Values}.
-
-
-@node SRFI-9
-@section SRFI-9 - define-record-type
-
-This is the SRFI way for defining record types. The Guile
-implementation is a layer above Guile's normal record construction
-procedures (@pxref{Records}). The nice thing about this kind of record
-definition method is that no new names are implicitly created, all
-constructor, accessor and predicates are explicitly given. This reduces
-the risk of variable capture.
-
-The syntax of a record type definition is:
-
-@example
-@group
-<record type definition>
- -> (define-record-type <type name>
- (<constructor name> <field tag> ...)
- <predicate name>
- <field spec> ...)
-<field spec> -> (<field tag> <accessor name>)
- -> (<field tag> <accessor name> <modifier name>)
-<field tag> -> <identifier>
-<... name> -> <identifier>
-@end group
-@end example
-
-Usage example:
-
-@example
-guile> (use-modules (srfi srfi-9))
-guile> (define-record-type :foo (make-foo x) foo?
- (x get-x) (y get-y set-y!))
-guile> (define f (make-foo 1))
-guile> f
-#<:foo x: 1 y: #f>
-guile> (get-x f)
-1
-guile> (set-y! f 2)
-2
-guile> (get-y f)
-2
-guile> f
-#<:foo x: 1 y: 2>
-guile> (foo? f)
-#t
-guile> (foo? 1)
-#f
-@end example
-
-
-@node SRFI-10
-@section SRFI-10 - Hash-Comma Reader Extension
-
-@cindex hash-comma
-@cindex #,()
-The module @code{(srfi srfi-10)} implements the syntax extension
-@code{#,()}, also called hash-comma, which is defined in SRFI-10.
-
-The support for SRFI-10 consists of the procedure
-@code{define-reader-ctor} for defining new reader constructors and the
-read syntax form
-
-@example
-#,(@var{ctor} @var{datum} ...)
-@end example
-
-where @var{ctor} must be a symbol for which a read constructor was
-defined previously, using @code{define-reader-ctor}.
-
-Example:
-
-@lisp
-(define-reader-ctor 'file open-input-file)
-(define f '#,(file "/etc/passwd"))
-(read-line f)
-@result{}
-"root:x:0:0:root:/root:/bin/bash"
-@end lisp
-
-Please note the quote before the @code{#,(file ...)} expression. This
-is necessary because ports are not self-evaluating in Guile.
-
-@deffn {Scheme Procedure} define-reader-ctor symbol proc
-Define @var{proc} as the reader constructor for hash-comma forms with a
-tag @var{symbol}. @var{proc} will be applied to the datum(s) following
-the tag in the hash-comma expression after the complete form has been
-read in. The result of @var{proc} is returned by the Scheme reader.
-@end deffn
-
-
-@node SRFI-11
-@section SRFI-11 - let-values
-
-This module implements the binding forms for multiple values
-@code{let-values} and @code{let-values*}. These forms are similar to
-@code{let} and @code{let*} (@pxref{Local Bindings}), but they support
-binding of the values returned by multiple-valued expressions.
-
-Write @code{(use-modules (srfi srfi-11))} to make the bindings
-available.
-
-@lisp
-(let-values (((x y) (values 1 2))
- ((z f) (values 3 4)))
- (+ x y z f))
-@result{}
-10
-@end lisp
-
-@code{let-values} performs all bindings simultaneously, which means that
-no expression in the binding clauses may refer to variables bound in the
-same clause list. @code{let-values*}, on the other hand, performs the
-bindings sequentially, just like @code{let*} does for single-valued
-expressions.
-
-
-@node SRFI-13
-@section SRFI-13 - String Library
-
-In this section, we will describe all procedures defined in SRFI-13
-(string library) and implemented by the module @code{(srfi srfi-13)}.
-
-Note that only the procedures from SRFI-13 are documented here which are
-not already contained in Guile. For procedures not documented here
-please refer to the relevant chapters in the Guile Reference Manual, for
-example the documentation of strings and string procedures
-(@pxref{Strings}).
-
-All of the procedures defined in SRFI-13, which are not already
-included in the Guile core library, are implemented in the module
-@code{(srfi srfi-13)}. The procedures which are both in Guile and in
-SRFI-13 are slightly extended in this module. Their bindings
-overwrite those in the Guile core.
-
-The procedures which are defined in the section @emph{Low-level
-procedures} of SRFI-13 for parsing optional string indices, substring
-specification checking and Knuth-Morris-Pratt-Searching are not
-implemented.
-
-The procedures @code{string-contains} and @code{string-contains-ci} are
-not implemented very efficiently at the moment. This will be changed as
-soon as possible.
-
-@menu
-* Loading SRFI-13:: How to load SRFI-13 support.
-* SRFI-13 Predicates:: String predicates.
-* SRFI-13 Constructors:: String constructing procedures.
-* SRFI-13 List/String Conversion:: Conversion from/to lists.
-* SRFI-13 Selection:: Selection portions of strings.
-* SRFI-13 Modification:: Modify strings in-place.
-* SRFI-13 Comparison:: Compare strings.
-* SRFI-13 Prefixes/Suffixes:: Detect common pre-/suffixes.
-* SRFI-13 Searching:: Searching for substrings.
-* SRFI-13 Case Mapping:: Mapping to lower-/upper-case.
-* SRFI-13 Reverse/Append:: Reverse and append strings.
-* SRFI-13 Fold/Unfold/Map:: Construct/deconstruct strings.
-* SRFI-13 Replicate/Rotate:: Replicate and rotate portions of strings.
-* SRFI-13 Miscellaneous:: Left-over string procedures.
-* SRFI-13 Filtering/Deleting:: Filter and delete characters from strings.
-@end menu
-
-
-@node Loading SRFI-13
-@subsection Loading SRFI-13
-
-When Guile is properly installed, SRFI-13 support can be loaded into a
-running Guile by using the @code{(srfi srfi-13)} module.
-
-@example
-$ guile
-guile> (use-modules (srfi srfi-13))
-guile>
-@end example
-
-When this step causes any errors, Guile is not properly installed.
-
-One possible reason is that Guile cannot find either the Scheme module
-file @file{srfi-13.scm}, or it cannot find the shared object file
-@file{libguile-srfi-srfi-13-14.so}. Make sure that the former is in the
-Guile load path and that the latter is either installed in some default
-location like @file{/usr/local/lib} or that the directory it was
-installed to is in your @code{LTDL_LIBRARY_PATH}. The same applies to
-@file{srfi-14.scm}.
-
-Now you can test whether the SRFI-13 procedures are working by calling
-the @code{string-concatenate} procedure.
-
-@example
-guile> (string-concatenate '("Hello" " " "World!"))
-"Hello World!"
-@end example
-
-@node SRFI-13 Predicates
-@subsection Predicates
-
-In addition to the primitives @code{string?} and @code{string-null?},
-which are already in the Guile core, the string predicates
-@code{string-any} and @code{string-every} are defined by SRFI-13.
-
-@deffn {Scheme Procedure} string-any pred s [start end]
-Check if the predicate @var{pred} is true for any character in
-the string @var{s}, proceeding from left (index @var{start}) to
-right (index @var{end}). If @code{string-any} returns true,
-the returned true value is the one produced by the first
-successful application of @var{pred}.
-@end deffn
-
-@deffn {Scheme Procedure} string-every pred s [start end]
-Check if the predicate @var{pred} is true for every character
-in the string @var{s}, proceeding from left (index @var{start})
-to right (index @var{end}). If @code{string-every} returns
-true, the returned true value is the one produced by the final
-application of @var{pred} to the last character of @var{s}.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Constructors
-@subsection Constructors
-
-SRFI-13 defines several procedures for constructing new strings. In
-addition to @code{make-string} and @code{string} (available in the Guile
-core library), the procedure @code{string-tabulate} does exist.
-
-@deffn {Scheme Procedure} string-tabulate proc len
-@var{proc} is an integer->char procedure. Construct a string
-of size @var{len} by applying @var{proc} to each index to
-produce the corresponding string element. The order in which
-@var{proc} is applied to the indices is not specified.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 List/String Conversion
-@subsection List/String Conversion
-
-The procedure @code{string->list} is extended by SRFI-13, that is why it
-is included in @code{(srfi srfi-13)}. The other procedures are new.
-The Guile core already contains the procedure @code{list->string} for
-converting a list of characters into a string (@pxref{List/String
-Conversion}).
-
-@deffn {Scheme Procedure} string->list str [start end]
-Convert the string @var{str} into a list of characters.
-@end deffn
-
-@deffn {Scheme Procedure} reverse-list->string chrs
-An efficient implementation of @code{(compose string->list
-reverse)}:
-
-@smalllisp
-(reverse-list->string '(#\a #\B #\c)) @result{} "cBa"
-@end smalllisp
-@end deffn
-
-@deffn {Scheme Procedure} string-join ls [delimiter grammar]
-Append the string in the string list @var{ls}, using the string
-@var{delim} as a delimiter between the elements of @var{ls}.
-@var{grammar} is a symbol which specifies how the delimiter is
-placed between the strings, and defaults to the symbol
-@code{infix}.
-
-@table @code
-@item infix
-Insert the separator between list elements. An empty string
-will produce an empty list.
-
-@item string-infix
-Like @code{infix}, but will raise an error if given the empty
-list.
-
-@item suffix
-Insert the separator after every list element.
-
-@item prefix
-Insert the separator before each list element.
-@end table
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Selection
-@subsection Selection
-
-These procedures are called @dfn{selectors}, because they access
-information about the string or select pieces of a given string.
-
-Additional selector procedures are documented in the Strings section
-(@pxref{String Selection}), like @code{string-length} or
-@code{string-ref}.
-
-@code{string-copy} is also available in core Guile, but this version
-accepts additional start/end indices.
-
-@deffn {Scheme Procedure} string-copy str [start end]
-Return a freshly allocated copy of the string @var{str}. If
-given, @var{start} and @var{end} delimit the portion of
-@var{str} which is copied.
-@end deffn
-
-@deffn {Scheme Procedure} substring/shared str start [end]
-Like @code{substring}, but the result may share memory with the
-argument @var{str}.
-@end deffn
-
-@deffn {Scheme Procedure} string-copy! target tstart s [start end]
-Copy the sequence of characters from index range [@var{start},
-@var{end}) in string @var{s} to string @var{target}, beginning
-at index @var{tstart}. The characters are copied left-to-right
-or right-to-left as needed - the copy is guaranteed to work,
-even if @var{target} and @var{s} are the same string. It is an
-error if the copy operation runs off the end of the target
-string.
-@end deffn
-
-@deffn {Scheme Procedure} string-take s n
-@deffnx {Scheme Procedure} string-take-right s n
-Return the @var{n} first/last characters of @var{s}.
-@end deffn
-
-@deffn {Scheme Procedure} string-drop s n
-@deffnx {Scheme Procedure} string-drop-right s n
-Return all but the first/last @var{n} characters of @var{s}.
-@end deffn
-
-@deffn {Scheme Procedure} string-pad s len [chr start end]
-@deffnx {Scheme Procedure} string-pad-right s len [chr start end]
-Take that characters from @var{start} to @var{end} from the
-string @var{s} and return a new string, right(left)-padded by the
-character @var{chr} to length @var{len}. If the resulting
-string is longer than @var{len}, it is truncated on the right (left).
-@end deffn
-
-@deffn {Scheme Procedure} string-trim s [char_pred start end]
-@deffnx {Scheme Procedure} string-trim-right s [char_pred start end]
-@deffnx {Scheme Procedure} string-trim-both s [char_pred start end]
-Trim @var{s} by skipping over all characters on the left/right/both
-sides of the string that satisfy the parameter @var{char_pred}:
-
-@itemize @bullet
-@item
-if it is the character @var{ch}, characters equal to
-@var{ch} are trimmed,
-
-@item
-if it is a procedure @var{pred} characters that
-satisfy @var{pred} are trimmed,
-
-@item
-if it is a character set, characters in that set are trimmed.
-@end itemize
-
-If called without a @var{char_pred} argument, all whitespace is
-trimmed.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Modification
-@subsection Modification
-
-The procedure @code{string-fill!} is extended from R5RS because it
-accepts optional start/end indices. This bindings shadows the procedure
-of the same name in the Guile core. The second modification procedure
-@code{string-set!} is documented in the Strings section (@pxref{String
-Modification}).
-
-@deffn {Scheme Procedure} string-fill! str chr [start end]
-Stores @var{chr} in every element of the given @var{str} and
-returns an unspecified value.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Comparison
-@subsection Comparison
-
-The procedures in this section are used for comparing strings in
-different ways. The comparison predicates differ from those in R5RS in
-that they do not only return @code{#t} or @code{#f}, but the mismatch
-index in the case of a true return value.
-
-@code{string-hash} and @code{string-hash-ci} are for calculating hash
-values for strings, useful for implementing fast lookup mechanisms.
-
-@deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2]
-Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
-mismatch index, depending upon whether @var{s1} is less than,
-equal to, or greater than @var{s2}. The mismatch index is the
-largest index @var{i} such that for every 0 <= @var{j} <
-@var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] - that is,
-@var{i} is the first position that does not match. The
-character comparison is done case-insensitively.
-@end deffn
-
-@deffn {Scheme Procedure} string= s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string<> s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string< s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string> s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string<= s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string>= s1 s2 [start1 end1 start2 end2]
-Compare @var{s1} and @var{s2} and return @code{#f} if the predicate
-fails. Otherwise, the mismatch index is returned (or @var{end1} in the
-case of @code{string=}.
-@end deffn
-
-@deffn {Scheme Procedure} string-ci= s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-ci<> s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-ci< s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-ci> s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-ci<= s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-ci>= s1 s2 [start1 end1 start2 end2]
-Compare @var{s1} and @var{s2} and return @code{#f} if the predicate
-fails. Otherwise, the mismatch index is returned (or @var{end1} in the
-case of @code{string=}. These are the case-insensitive variants.
-@end deffn
-
-@deffn {Scheme Procedure} string-hash s [bound start end]
-@deffnx {Scheme Procedure} string-hash-ci s [bound start end]
-Return a hash value of the string @var{s} in the range 0 @dots{}
-@var{bound} - 1. @code{string-hash-ci} is the case-insensitive variant.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Prefixes/Suffixes
-@subsection Prefixes/Suffixes
-
-Using these procedures you can determine whether a given string is a
-prefix or suffix of another string or how long a common prefix/suffix
-is.
-
-@deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-prefix-length-ci s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-suffix-length s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-suffix-length-ci s1 s2 [start1 end1 start2 end2]
-Return the length of the longest common prefix/suffix of the two
-strings. @code{string-prefix-length-ci} and
-@code{string-suffix-length-ci} are the case-insensitive variants.
-@end deffn
-
-@deffn {Scheme Procedure} string-prefix? s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-prefix-ci? s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-suffix? s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-suffix-ci? s1 s2 [start1 end1 start2 end2]
-Is @var{s1} a prefix/suffix of @var{s2}. @code{string-prefix-ci?} and
-@code{string-suffix-ci?} are the case-insensitive variants.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Searching
-@subsection Searching
-
-Use these procedures to find out whether a string contains a given
-character or a given substring, or a character from a set of characters.
-
-@deffn {Scheme Procedure} string-index s char_pred [start end]
-@deffnx {Scheme Procedure} string-index-right s char_pred [start end]
-Search through the string @var{s} from left to right (right to left),
-returning the index of the first (last) occurrence of a character which
-
-@itemize @bullet
-@item
-equals @var{char_pred}, if it is character,
-
-@item
-satisfies the predicate @var{char_pred}, if it is a
-procedure,
-
-@item
-is in the set @var{char_pred}, if it is a character set.
-@end itemize
-@end deffn
-
-@deffn {Scheme Procedure} string-skip s char_pred [start end]
-@deffnx {Scheme Procedure} string-skip-right s char_pred [start end]
-Search through the string @var{s} from left to right (right to left),
-returning the index of the first (last) occurrence of a character which
-
-@itemize @bullet
-@item
-does not equal @var{char_pred}, if it is character,
-
-@item
-does not satisfy the predicate @var{char_pred}, if it is
-a procedure.
-
-@item
-is not in the set if @var{char_pred} is a character set.
-@end itemize
-@end deffn
-
-@deffn {Scheme Procedure} string-count s char_pred [start end]
-Return the count of the number of characters in the string
-@var{s} which
-
-@itemize @bullet
-@item
-equals @var{char_pred}, if it is character,
-
-@item
-satisfies the predicate @var{char_pred}, if it is a procedure.
-
-@item
-is in the set @var{char_pred}, if it is a character set.
-@end itemize
-@end deffn
-
-@deffn {Scheme Procedure} string-contains s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-contains-ci s1 s2 [start1 end1 start2 end2]
-Does string @var{s1} contain string @var{s2}? Return the index
-in @var{s1} where @var{s2} occurs as a substring, or false.
-The optional start/end indices restrict the operation to the
-indicated substrings.
-
-@code{string-contains-ci} is the case-insensitive variant.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Case Mapping
-@subsection Alphabetic Case Mapping
-
-These procedures convert the alphabetic case of strings. They are
-similar to the procedures in the Guile core, but are extended to handle
-optional start/end indices.
-
-@deffn {Scheme Procedure} string-upcase s [start end]
-@deffnx {Scheme Procedure} string-upcase! s [start end]
-Upcase every character in @var{s}. @code{string-upcase!} is the
-side-effecting variant.
-@end deffn
-
-@deffn {Scheme Procedure} string-downcase s [start end]
-@deffnx {Scheme Procedure} string-downcase! s [start end]
-Downcase every character in @var{s}. @code{string-downcase!} is the
-side-effecting variant.
-@end deffn
-
-@deffn {Scheme Procedure} string-titlecase s [start end]
-@deffnx {Scheme Procedure} string-titlecase! s [start end]
-Upcase every first character in every word in @var{s}, downcase the
-other characters. @code{string-titlecase!} is the side-effecting
-variant.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Reverse/Append
-@subsection Reverse/Append
-
-One appending procedure, @code{string-append} is the same in R5RS and in
-SRFI-13, so it is not redefined.
-
-@deffn {Scheme Procedure} string-reverse str [start end]
-@deffnx {Scheme Procedure} string-reverse! str [start end]
-Reverse the string @var{str}. The optional arguments
-@var{start} and @var{end} delimit the region of @var{str} to
-operate on.
-
-@code{string-reverse!} modifies the argument string and returns an
-unspecified value.
-@end deffn
-
-@deffn {Scheme Procedure} string-append/shared ls @dots{}
-Like @code{string-append}, but the result may share memory
-with the argument strings.
-@end deffn
-
-@deffn {Scheme Procedure} string-concatenate ls
-Append the elements of @var{ls} (which must be strings)
-together into a single string. Guaranteed to return a freshly
-allocated string.
-@end deffn
-
-@deffn {Scheme Procedure} string-concatenate/shared ls
-Like @code{string-concatenate}, but the result may share memory
-with the strings in the list @var{ls}.
-@end deffn
-
-@deffn {Scheme Procedure} string-concatenate-reverse ls final_string end
-Without optional arguments, this procedure is equivalent to
-
-@smalllisp
-(string-concatenate (reverse ls))
-@end smalllisp
-
-If the optional argument @var{final_string} is specified, it is
-consed onto the beginning to @var{ls} before performing the
-list-reverse and string-concatenate operations. If @var{end}
-is given, only the characters of @var{final_string} up to index
-@var{end} are used.
-
-Guaranteed to return a freshly allocated string.
-@end deffn
-
-@deffn {Scheme Procedure} string-concatenate-reverse/shared ls final_string end
-Like @code{string-concatenate-reverse}, but the result may
-share memory with the the strings in the @var{ls} arguments.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Fold/Unfold/Map
-@subsection Fold/Unfold/Map
-
-@code{string-map}, @code{string-for-each} etc. are for iterating over
-the characters a string is composed of. The fold and unfold procedures
-are list iterators and constructors.
-
-@deffn {Scheme Procedure} string-map proc s [start end]
-@var{proc} is a char->char procedure, it is mapped over
-@var{s}. The order in which the procedure is applied to the
-string elements is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} string-map! proc s [start end]
-@var{proc} is a char->char procedure, it is mapped over
-@var{s}. The order in which the procedure is applied to the
-string elements is not specified. The string @var{s} is
-modified in-place, the return value is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} string-fold kons knil s [start end]
-@deffnx {Scheme Procedure} string-fold-right kons knil s [start end]
-Fold @var{kons} over the characters of @var{s}, with @var{knil} as the
-terminating element, from left to right (or right to left, for
-@code{string-fold-right}). @var{kons} must expect two arguments: The
-actual character and the last result of @var{kons}' application.
-@end deffn
-
-@deffn {Scheme Procedure} string-unfold p f g seed [base make_final]
-@deffnx {Scheme Procedure} string-unfold-right p f g seed [base make_final]
-These are the fundamental string constructors.
-@itemize @bullet
-@item @var{g} is used to generate a series of @emph{seed}
-values from the initial @var{seed}: @var{seed}, (@var{g}
-@var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
-@dots{}
-@item @var{p} tells us when to stop - when it returns true
-when applied to one of these seed values.
-@item @var{f} maps each seed value to the corresponding
-character in the result string. These chars are assembled into the
-string in a left-to-right (right-to-left) order.
-@item @var{base} is the optional initial/leftmost (rightmost)
- portion of the constructed string; it default to the empty string.
-@item @var{make_final} is applied to the terminal seed
-value (on which @var{p} returns true) to produce the final/rightmost
-(leftmost) portion of the constructed string. It defaults to
-@code{(lambda (x) "")}.
-@end itemize
-@end deffn
-
-@deffn {Scheme Procedure} string-for-each proc s [start end]
-@var{proc} is mapped over @var{s} in left-to-right order. The
-return value is not specified.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Replicate/Rotate
-@subsection Replicate/Rotate
-
-These procedures are special substring procedures, which can also be
-used for replicating strings. They are a bit tricky to use, but
-consider this code fragment, which replicates the input string
-@code{"foo"} so often that the resulting string has a length of six.
-
-@lisp
-(xsubstring "foo" 0 6)
-@result{}
-"foofoo"
-@end lisp
-
-@deffn {Scheme Procedure} xsubstring s from [to start end]
-This is the @emph{extended substring} procedure that implements
-replicated copying of a substring of some string.
-
-@var{s} is a string, @var{start} and @var{end} are optional
-arguments that demarcate a substring of @var{s}, defaulting to
-0 and the length of @var{s}. Replicate this substring up and
-down index space, in both the positive and negative directions.
-@code{xsubstring} returns the substring of this string
-beginning at index @var{from}, and ending at @var{to}, which
-defaults to @var{from} + (@var{end} - @var{start}).
-@end deffn
-
-@deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto start end]
-Exactly the same as @code{xsubstring}, but the extracted text
-is written into the string @var{target} starting at index
-@var{tstart}. The operation is not defined if @code{(eq?
-@var{target} @var{s})} or these arguments share storage - you
-cannot copy a string on top of itself.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Miscellaneous
-@subsection Miscellaneous
-
-@code{string-replace} is for replacing a portion of a string with
-another string and @code{string-tokenize} splits a string into a list of
-strings, breaking it up at a specified character.
-
-@deffn {Scheme Procedure} string-replace s1 s2 [start1 end1 start2 end2]
-Return the string @var{s1}, but with the characters
-@var{start1} @dots{} @var{end1} replaced by the characters
-@var{start2} @dots{} @var{end2} from @var{s2}.
-@end deffn
-
-@deffn {Scheme Procedure} string-tokenize s [token-set start end]
-Split the string @var{s} into a list of substrings, where each
-substring is a maximal non-empty contiguous sequence of characters
-from the character set @var{token_set}, which defaults to an
-equivalent of @code{char-set:graphic}. If @var{start} or @var{end}
-indices are provided, they restrict @code{string-tokenize} to
-operating on the indicated substring of @var{s}.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Filtering/Deleting
-@subsection Filtering/Deleting
-
-@dfn{Filtering} means to remove all characters from a string which do
-not match a given criteria, @dfn{deleting} means the opposite.
-
-@deffn {Scheme Procedure} string-filter s char_pred [start end]
-Filter the string @var{s}, retaining only those characters that
-satisfy the @var{char_pred} argument. If the argument is a
-procedure, it is applied to each character as a predicate, if
-it is a character, it is tested for equality and if it is a
-character set, it is tested for membership.
-@end deffn
-
-@deffn {Scheme Procedure} string-delete s char_pred [start end]
-Filter the string @var{s}, retaining only those characters that
-do not satisfy the @var{char_pred} argument. If the argument
-is a procedure, it is applied to each character as a predicate,
-if it is a character, it is tested for equality and if it is a
-character set, it is tested for membership.
-@end deffn
-
-
-@node SRFI-14
-@section SRFI-14 - Character-set Library
-
-SRFI-14 defines the data type @dfn{character set}, and also defines a
-lot of procedures for handling this character type, and a few standard
-character sets like whitespace, alphabetic characters and others.
-
-All procedures from SRFI-14 (character-set library) are implemented in
-the module @code{(srfi srfi-14)}, as well as the standard variables
-@code{char-set:letter}, @code{char-set:digit} etc.
-
-@menu
-* Loading SRFI-14:: How to make charsets available.
-* SRFI-14 Character Set Data Type:: Underlying data type for charsets.
-* SRFI-14 Predicates/Comparison:: Charset predicates.
-* SRFI-14 Iterating Over Character Sets:: Enumerate charset elements.
-* SRFI-14 Creating Character Sets:: Making new charsets.
-* SRFI-14 Querying Character Sets:: Test charsets for membership etc.
-* SRFI-14 Character-Set Algebra:: Calculating new charsets.
-* SRFI-14 Standard Character Sets:: Variables containing predefined charsets.
-@end menu
-
-
-@node Loading SRFI-14
-@subsection Loading SRFI-14
-
-When Guile is properly installed, SRFI-14 support can be loaded into a
-running Guile by using the @code{(srfi srfi-14)} module.
-
-@example
-$ guile
-guile> (use-modules (srfi srfi-14))
-guile> (char-set-union (char-set #\f #\o #\o) (string->char-set "bar"))
-#<charset @{#\a #\b #\f #\o #\r@}>
-guile>
-@end example
-
-
-@node SRFI-14 Character Set Data Type
-@subsection Character Set Data Type
-
-The data type @dfn{charset} implements sets of characters
-(@pxref{Characters}). Because the internal representation of character
-sets is not visible to the user, a lot of procedures for handling them
-are provided.
-
-Character sets can be created, extended, tested for the membership of a
-characters and be compared to other character sets.
-
-The Guile implementation of character sets deals with 8-bit characters.
-In the standard variables, only the ASCII part of the character range is
-really used, so that for example @dfn{Umlaute} and other accented
-characters are not considered to be letters. In the future, as Guile
-may get support for international character sets, this will change, so
-don't rely on these ``features''.
-
-
-@c ===================================================================
-
-@node SRFI-14 Predicates/Comparison
-@subsection Predicates/Comparison
-
-Use these procedures for testing whether an object is a character set,
-or whether several character sets are equal or subsets of each other.
-@code{char-set-hash} can be used for calculating a hash value, maybe for
-usage in fast lookup procedures.
-
-@deffn {Scheme Procedure} char-set? obj
-Return @code{#t} if @var{obj} is a character set, @code{#f}
-otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} char-set= cs1 @dots{}
-Return @code{#t} if all given character sets are equal.
-@end deffn
-
-@deffn {Scheme Procedure} char-set<= cs1 @dots{}
-Return @code{#t} if every character set @var{cs}i is a subset
-of character set @var{cs}i+1.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-hash cs [bound]
-Compute a hash value for the character set @var{cs}. If
-@var{bound} is given and not @code{#f}, it restricts the
-returned value to the range 0 @dots{} @var{bound - 1}.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-14 Iterating Over Character Sets
-@subsection Iterating Over Character Sets
-
-Character set cursors are a means for iterating over the members of a
-character sets. After creating a character set cursor with
-@code{char-set-cursor}, a cursor can be dereferenced with
-@code{char-set-ref}, advanced to the next member with
-@code{char-set-cursor-next}. Whether a cursor has passed past the last
-element of the set can be checked with @code{end-of-char-set?}.
-
-Additionally, mapping and (un-)folding procedures for character sets are
-provided.
-
-@deffn {Scheme Procedure} char-set-cursor cs
-Return a cursor into the character set @var{cs}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-ref cs cursor
-Return the character at the current cursor position
-@var{cursor} in the character set @var{cs}. It is an error to
-pass a cursor for which @code{end-of-char-set?} returns true.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-cursor-next cs cursor
-Advance the character set cursor @var{cursor} to the next
-character in the character set @var{cs}. It is an error if the
-cursor given satisfies @code{end-of-char-set?}.
-@end deffn
-
-@deffn {Scheme Procedure} end-of-char-set? cursor
-Return @code{#t} if @var{cursor} has reached the end of a
-character set, @code{#f} otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-fold kons knil cs
-Fold the procedure @var{kons} over the character set @var{cs},
-initializing it with @var{knil}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-unfold p f g seed [base_cs]
-@deffnx {Scheme Procedure} char-set-unfold! p f g seed base_cs
-This is a fundamental constructor for character sets.
-@itemize @bullet
-@item @var{g} is used to generate a series of ``seed'' values
-from the initial seed: @var{seed}, (@var{g} @var{seed}),
-(@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
-@item @var{p} tells us when to stop -- when it returns true
-when applied to one of the seed values.
-@item @var{f} maps each seed value to a character. These
-characters are added to the base character set @var{base_cs} to
-form the result; @var{base_cs} defaults to the empty set.
-@end itemize
-
-@code{char-set-unfold!} is the side-effecting variant.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-for-each proc cs
-Apply @var{proc} to every character in the character set
-@var{cs}. The return value is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-map proc cs
-Map the procedure @var{proc} over every character in @var{cs}.
-@var{proc} must be a character -> character procedure.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-14 Creating Character Sets
-@subsection Creating Character Sets
-
-New character sets are produced with these procedures.
-
-@deffn {Scheme Procedure} char-set-copy cs
-Return a newly allocated character set containing all
-characters in @var{cs}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set char1 @dots{}
-Return a character set containing all given characters.
-@end deffn
-
-@deffn {Scheme Procedure} list->char-set char_list [base_cs]
-@deffnx {Scheme Procedure} list->char-set! char_list base_cs
-Convert the character list @var{list} to a character set. If
-the character set @var{base_cs} is given, the character in this
-set are also included in the result.
-
-@code{list->char-set!} is the side-effecting variant.
-@end deffn
-
-@deffn {Scheme Procedure} string->char-set s [base_cs]
-@deffnx {Scheme Procedure} string->char-set! s base_cs
-Convert the string @var{str} to a character set. If the
-character set @var{base_cs} is given, the characters in this
-set are also included in the result.
-
-@code{string->char-set!} is the side-effecting variant.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-filter pred cs [base_cs]
-@deffnx {Scheme Procedure} char-set-filter! pred cs base_cs
-Return a character set containing every character from @var{cs}
-so that it satisfies @var{pred}. If provided, the characters
-from @var{base_cs} are added to the result.
-
-@code{char-set-filter!} is the side-effecting variant.
-@end deffn
-
-@deffn {Scheme Procedure} ucs-range->char-set lower upper [error? base_cs]
-@deffnx {Scheme Procedure} uce-range->char-set! lower upper error? base_cs
-Return a character set containing all characters whose
-character codes lie in the half-open range
-[@var{lower},@var{upper}).
-
-If @var{error} is a true value, an error is signalled if the
-specified range contains characters which are not contained in
-the implemented character range. If @var{error} is @code{#f},
-these characters are silently left out of the resulting
-character set.
-
-The characters in @var{base_cs} are added to the result, if
-given.
-
-@code{ucs-range->char-set!} is the side-effecting variant.
-@end deffn
-
-@deffn {Scheme Procedure} ->char-set x
-Coerce @var{x} into a character set. @var{x} may be a string, a
-character or a character set.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-14 Querying Character Sets
-@subsection Querying Character Sets
-
-Access the elements and other information of a character set with these
-procedures.
-
-@deffn {Scheme Procedure} char-set-size cs
-Return the number of elements in character set @var{cs}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-count pred cs
-Return the number of the elements int the character set
-@var{cs} which satisfy the predicate @var{pred}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set->list cs
-Return a list containing the elements of the character set
-@var{cs}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set->string cs
-Return a string containing the elements of the character set
-@var{cs}. The order in which the characters are placed in the
-string is not defined.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-contains? cs char
-Return @code{#t} iff the character @var{ch} is contained in the
-character set @var{cs}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-every pred cs
-Return a true value if every character in the character set
-@var{cs} satisfies the predicate @var{pred}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-any pred cs
-Return a true value if any character in the character set
-@var{cs} satisfies the predicate @var{pred}.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-14 Character-Set Algebra
-@subsection Character-Set Algebra
-
-Character sets can be manipulated with the common set algebra operation,
-such as union, complement, intersection etc. All of these procedures
-provide side-effecting variants, which modify their character set
-argument(s).
-
-@deffn {Scheme Procedure} char-set-adjoin cs char1 @dots{}
-@deffnx {Scheme Procedure} char-set-adjoin! cs char1 @dots{}
-Add all character arguments to the first argument, which must
-be a character set.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-delete cs char1 @dots{}
-@deffnx {Scheme Procedure} char-set-delete! cs char1 @dots{}
-Delete all character arguments from the first argument, which
-must be a character set.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-complement cs
-@deffnx {Scheme Procedure} char-set-complement! cs
-Return the complement of the character set @var{cs}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-union cs1 @dots{}
-@deffnx {Scheme Procedure} char-set-union! cs1 @dots{}
-Return the union of all argument character sets.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-intersection cs1 @dots{}
-@deffnx {Scheme Procedure} char-set-intersection! cs1 @dots{}
-Return the intersection of all argument character sets.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-difference cs1 @dots{}
-@deffnx {Scheme Procedure} char-set-difference! cs1 @dots{}
-Return the difference of all argument character sets.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-xor cs1 @dots{}
-@deffnx {Scheme Procedure} char-set-xor! cs1 @dots{}
-Return the exclusive-or of all argument character sets.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-diff+intersection cs1 @dots{}
-@deffnx {Scheme Procedure} char-set-diff+intersection! cs1 @dots{}
-Return the difference and the intersection of all argument
-character sets.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-14 Standard Character Sets
-@subsection Standard Character Sets
-
-In order to make the use of the character set data type and procedures
-useful, several predefined character set variables exist.
-
-@defvar char-set:lower-case
-All lower-case characters.
-@end defvar
-
-@defvar char-set:upper-case
-All upper-case characters.
-@end defvar
-
-@defvar char-set:title-case
-This is empty, because ASCII has no titlecase characters.
-@end defvar
-
-@defvar char-set:letter
-All letters, e.g. the union of @code{char-set:lower-case} and
-@code{char-set:upper-case}.
-@end defvar
-
-@defvar char-set:digit
-All digits.
-@end defvar
-
-@defvar char-set:letter+digit
-The union of @code{char-set:letter} and @code{char-set:digit}.
-@end defvar
-
-@defvar char-set:graphic
-All characters which would put ink on the paper.
-@end defvar
-
-@defvar char-set:printing
-The union of @code{char-set:graphic} and @code{char-set:whitespace}.
-@end defvar
-
-@defvar char-set:whitespace
-All whitespace characters.
-@end defvar
-
-@defvar char-set:blank
-All horizontal whitespace characters, that is @code{#\space} and
-@code{#\tab}.
-@end defvar
-
-@defvar char-set:iso-control
-The ISO control characters with the codes 0--31 and 127.
-@end defvar
-
-@defvar char-set:punctuation
-The characters @code{!"#%&'()*,-./:;?@@[\\]_@{@}}
-@end defvar
-
-@defvar char-set:symbol
-The characters @code{$+<=>^`|~}.
-@end defvar
-
-@defvar char-set:hex-digit
-The hexadecimal digits @code{0123456789abcdefABCDEF}.
-@end defvar
-
-@defvar char-set:ascii
-All ASCII characters.
-@end defvar
-
-@defvar char-set:empty
-The empty character set.
-@end defvar
-
-@defvar char-set:full
-This character set contains all possible characters.
-@end defvar
-
-@node SRFI-16
-@section SRFI-16 - case-lambda
-
-@c FIXME::martin: Review me!
-
-The syntactic form @code{case-lambda} creates procedures, just like
-@code{lambda}, but has syntactic extensions for writing procedures of
-varying arity easier.
-
-The syntax of the @code{case-lambda} form is defined in the following
-EBNF grammar.
-
-@example
-@group
-<case-lambda>
- --> (case-lambda <case-lambda-clause>)
-<case-lambda-clause>
- --> (<formals> <definition-or-command>*)
-<formals>
- --> (<identifier>*)
- | (<identifier>* . <identifier>)
- | <identifier>
-@end group
-@end example
-
-The value returned by a @code{case-lambda} form is a procedure which
-matches the number of actual arguments against the formals in the
-various clauses, in order. @dfn{Formals} means a formal argument list
-just like with @code{lambda} (@pxref{Lambda}). The first matching clause
-is selected, the corresponding values from the actual parameter list are
-bound to the variable names in the clauses and the body of the clause is
-evaluated. If no clause matches, an error is signalled.
-
-The following (silly) definition creates a procedure @var{foo} which
-acts differently, depending on the number of actual arguments. If one
-argument is given, the constant @code{#t} is returned, two arguments are
-added and if more arguments are passed, their product is calculated.
-
-@lisp
-(define foo (case-lambda
- ((x) #t)
- ((x y) (+ x y))
- (z
- (apply * z))))
-(foo 'bar)
-@result{}
-#t
-(foo 2 4)
-@result{}
-6
-(foo 3 3 3)
-@result{}
-27
-(foo)
-@result{}
-1
-@end lisp
-
-The last expression evaluates to 1 because the last clause is matched,
-@var{z} is bound to the empty list and the following multiplication,
-applied to zero arguments, yields 1.
-
-
-@node SRFI-17
-@section SRFI-17 - Generalized set!
-
-This is an implementation of SRFI-17: Generalized set!
-
-It exports the Guile procedure @code{make-procedure-with-setter} under
-the SRFI name @code{getter-with-setter} and exports the standard
-procedures @code{car}, @code{cdr}, @dots{}, @code{cdddr},
-@code{string-ref} and @code{vector-ref} as procedures with setters, as
-required by the SRFI.
-
-SRFI-17 was heavily criticized during its discussion period but it was
-finalized anyway. One issue was its concept of globally associating
-setter @dfn{properties} with (procedure) values, which is non-Schemy.
-For this reason, this implementation chooses not to provide a way to set
-the setter of a procedure. In fact, @code{(set! (setter @var{proc})
-@var{setter})} signals an error. The only way to attach a setter to a
-procedure is to create a new object (a @dfn{procedure with setter}) via
-the @code{getter-with-setter} procedure. This procedure is also
-specified in the SRFI. Using it avoids the described problems.
-
-
-@node SRFI-19
-@section SRFI-19 - Time/Date Library
-
-This is an implementation of SRFI-19: Time/Date Library
-
-It depends on SRFIs: 6 (@pxref{SRFI-6}), 8 (@pxref{SRFI-8}),
-9 (@pxref{SRFI-9}).
-
-This section documents constants and procedure signatures.
-
-@menu
-* SRFI-19 Constants::
-* SRFI-19 Current time and clock resolution::
-* SRFI-19 Time object and accessors::
-* SRFI-19 Time comparison procedures::
-* SRFI-19 Time arithmetic procedures::
-* SRFI-19 Date object and accessors::
-* SRFI-19 Time/Date/Julian Day/Modified Julian Day converters::
-* SRFI-19 Date to string/string to date converters::
-@end menu
-
-@node SRFI-19 Constants
-@subsection SRFI-19 Constants
-
-All these are bound to their symbol names:
-
-@example
- time-duration
- time-monotonic
- time-process
- time-tai
- time-thread
- time-utc
-@end example
-
-@node SRFI-19 Current time and clock resolution
-@subsection SRFI-19 Current time and clock resolution
-
-@example
- (current-date . tz-offset)
- (current-julian-day)
- (current-modified-julian-day)
- (current-time . clock-type)
- (time-resolution . clock-type)
-@end example
-
-@node SRFI-19 Time object and accessors
-@subsection SRFI-19 Time object and accessors
-
-@example
- (make-time type nanosecond second)
- (time? obj)
- (time-type time)
- (time-nanosecond time)
- (time-second time)
- (set-time-type! time type)
- (set-time-nanosecond! time nsec)
- (set-time-second! time sec)
- (copy-time time)
-@end example
-
-@node SRFI-19 Time comparison procedures
-@subsection SRFI-19 Time comparison procedures
-
-Args are all @code{time} values.
-
-@example
- (time<=? t1 t2)
- (time<? t1 t2)
- (time=? t1 t2)
- (time>=? t1 t2)
- (time>? t1 t2)
-@end example
-
-@node SRFI-19 Time arithmetic procedures
-@subsection SRFI-19 Time arithmetic procedures
-
-The @code{foo!} variants modify in place. Time difference
-is expressed in @code{time-duration} values.
-
-@example
- (time-difference t1 t2)
- (time-difference! t1 t2)
- (add-duration time duration)
- (add-duration! time duration)
- (subtract-duration time duration)
- (subtract-duration! time duration)
- @end example
-
-@node SRFI-19 Date object and accessors
-@subsection SRFI-19 Date object and accessors
-
-@example
- (make-date nsecs seconds minutes hours
- date month year offset)
- (date? obj)
- (date-nanosecond date)
- (date-second date)
- (date-minute date)
- (date-hour date)
- (date-day date)
- (date-month date)
- (date-year date)
- (date-zone-offset date)
- (date-year-day date)
- (date-week-day date)
- (date-week-number date day-of-week-starting-week)
-@end example
-
-@node SRFI-19 Time/Date/Julian Day/Modified Julian Day converters
-@subsection SRFI-19 Time/Date/Julian Day/Modified Julian Day converters
-
-@example
- (date->julian-day date)
- (date->modified-julian-day date)
- (date->time-monotonic date)
- (date->time-tai date)
- (date->time-utc date)
- (julian-day->date jdn . tz-offset)
- (julian-day->time-monotonic jdn)
- (julian-day->time-tai jdn)
- (julian-day->time-utc jdn)
- (modified-julian-day->date jdn . tz-offset)
- (modified-julian-day->time-monotonic jdn)
- (modified-julian-day->time-tai jdn)
- (modified-julian-day->time-utc jdn)
- (time-monotonic->date time . tz-offset)
- (time-monotonic->time-tai time-in)
- (time-monotonic->time-tai! time-in)
- (time-monotonic->time-utc time-in)
- (time-monotonic->time-utc! time-in)
- (time-tai->date time . tz-offset)
- (time-tai->julian-day time)
- (time-tai->modified-julian-day time)
- (time-tai->time-monotonic time-in)
- (time-tai->time-monotonic! time-in)
- (time-tai->time-utc time-in)
- (time-tai->time-utc! time-in)
- (time-utc->date time . tz-offset)
- (time-utc->julian-day time)
- (time-utc->modified-julian-day time)
- (time-utc->time-monotonic time-in)
- (time-utc->time-monotonic! time-in)
- (time-utc->time-tai time-in)
- (time-utc->time-tai! time-in)
-@end example
-
-@node SRFI-19 Date to string/string to date converters
-@subsection SRFI-19 Date to string/string to date converters
-
-@example
- (date->string date . format-string)
- (string->date input-string template-string)
-@end example
-
-@c srfi-modules.texi ends here
diff --git a/doc/ref/tcltk.texi b/doc/ref/tcltk.texi
deleted file mode 100644
index efc38ea9d..000000000
--- a/doc/ref/tcltk.texi
+++ /dev/null
@@ -1,3 +0,0 @@
-@page
-@node Tcl/Tk Interface
-@chapter Tcl/Tk Interface
diff --git a/doc/ref/tools.texi b/doc/ref/tools.texi
deleted file mode 100644
index 061e34477..000000000
--- a/doc/ref/tools.texi
+++ /dev/null
@@ -1,386 +0,0 @@
-@page
-@node Miscellaneous Tools
-@chapter Miscellaneous Tools
-
-Programming is more fun with a good tools. This chapter describes snarfing
-tools, and the @code{guile-tools} program which can be used to invoke the rest
-of the tools (which are self-documenting). Some of these are used in Guile
-development, too. Imagine that!
-
-@menu
-* Snarfing:: Grepping the source in various ways.
-* Executable Modules:: Modules callable via guile-tools.
-@end menu
-
-@c ---------------------------------------------------------------------------
-@node Snarfing
-@section Snarfing
-@cindex snarfing
-
-Because it's easier to maintain documentation, code, and other metainfo in one
-source file than in many files, there have evolved many methods for grepping
-source to lift and separate these kinds of info, in the process generating
-docs or fragments of source or what have you. This is known generally as
-@dfn{snarfing}, which comes from the verb ``to snarf'', here meaning ``to
-unceremoniously extract information from a somewhat unwilling source.''
-
-This section documents the installed program @code{guile-snarf} which does
-@dfn{init snarfing}, and also touches upon guile's doc snarfing process which
-is not yet finalized (i.e., doc snarfing programs are not installed at this
-time).
-
-@menu
-* Init Snarfing with guile-snarf:: Exposing C subrs and friends to Scheme.
-* Doc Snarfing:: Generating GDFv2 or texi from source.
-@end menu
-
-@c ---------------------------------------------------------------------------
-@node Init Snarfing with guile-snarf
-@subsection Init Snarfing with guile-snarf
-@c NOTE: This node and two subnodes are adapted from ../sources/snarf.texi.
-@cindex snarfing, init
-@cindex primitive functions
-@cindex subrs, defining
-
-When writing C code for use with Guile, you typically define a set of C
-functions, and then make some of them visible to the Scheme world by
-calling the @code{scm_c_define_gsubr} function; a C function published in
-this way is called a @dfn{subr}. If you have many subrs to publish, it
-can sometimes be annoying to keep the list of calls to
-@code{scm_c_define_gsubr} in sync with the list of function definitions.
-Frequently, a programmer will define a new subr in C, recompile the
-application, and then discover that the Scheme interpreter cannot see
-the subr, because of a missed call to @code{scm_c_define_gsubr}.
-
-Guile provides the @code{guile-snarf} command to manage this problem.
-Using this tool, you can keep all the information needed to define the
-subr alongside the function definition itself; @code{guile-snarf} will
-extract this information from your source code, and automatically
-generate a file of calls to @code{scm_c_define_gsubr} which you can
-@code{#include} into an initialization function.
-
-@menu
-* How guile-snarf works:: Using @code{guile-snarf}, with example.
-* Macros guile-snarf recognizes:: How to mark up code for @code{guile-snarf}.
-@end menu
-
-@c ---------------------------------------------------------------------------
-@node How guile-snarf works
-@subsubsection How guile-snarf works
-@cindex guile-snarf invocation
-@cindex guile-snarf example
-
-Usage: guile-snarf [-d | -D] [-o OUTFILE] INFILE [CPP-OPTIONS ...]
-
-What @code{guile-snarf} does:
-
-Process INFILE using the C pre-processor and some other programs.
-Write output to a file named OUTFILE or to the standard output when no
-OUTFILE has been specified or when OUTFILE is @code{-}. When writing
-to a file, ignore lines from the input matching the following grep(1)
-regular expression:
-
-@example
- ^#include ".*OUTFILE"
-@end example
-
-If there are errors during processing, delete OUTFILE and exit with
-non-zero status.
-
-Optional arg "-d" means grep INFILE for deprecated macros and
-issue a warning if any are found. Alternatively, "-D" means
-do the same thing but signal error and exit with non-zero status.
-
-If env var CPP is set, use its value instead of the C pre-processor
-determined at Guile configure-time.
-
-During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is
-defined.
-
-@xref{Macros guile-snarf recognizes}, for a list of the special (some would
-say magic) cpp macros you can use, including the list of deprecated macros.
-
-For example, here is how you might define a new subr called
-@code{clear-image}, implemented by the C function @code{clear_image}:
-
-@example
-@group
-#include <libguile.h>
-
-SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
- (SCM image_smob),
- "Clear the image.")
-#define FUNC_NAME s_clear_image
-@{
- /* C code to clear the image... */
-@}
-#undef FUNC_NAME
-
-void
-init_image_type ()
-@{
-#include "image-type.x"
-@}
-@end group
-@end example
-
-The @code{SCM_DEFINE} declaration says that the C function
-@code{clear_image} implements a Scheme subr called @code{clear-image},
-which takes one required argument (type @code{SCM} named
-@code{image_smob}), no optional arguments, and no tail argument.
-@xref{Doc Snarfing}, for info on the docstring.
-
-This works in concert with @code{FUNC_NAME} to also define a static
-array of characters named @code{s_clear_image}, initialized to the
-string "clear-image". The body of @code{clear_image} may use the array
-in error messages, instead of writing out the literal string; this may
-save string space on some systems.
-
-Assuming the text above lives in a file named @file{image-type.c}, you will
-need to execute the following command to prepare this file for compilation:
-
-@example
-guile-snarf image-type.c
-@end example
-
-This scans @file{image-type.c} for @code{SCM_DEFINE}
-declarations, and writes to @file{image-type.x} the output:
-
-@example
-scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);
-@end example
-
-When compiled normally, @code{SCM_DEFINE} is a macro which expands to a
-declaration of the @code{s_clear_image} string.
-
-Note that the output file name matches the @code{#include} from the
-input file. Also, you still need to provide all the same information
-you would if you were using @code{scm_c_define_gsubr} yourself, but you
-can place the information near the function definition itself, so it is
-less likely to become incorrect or out-of-date.
-
-If you have many files that @code{guile-snarf} must process, you should
-consider using a fragment like the following in your Makefile:
-
-@example
-snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
-.SUFFIXES: .x
-.c.x:
- guile-snarf -o $@ $< $(snarfcppopts)
-@end example
-
-This tells make to run @code{guile-snarf} to produce each needed
-@file{.x} file from the corresponding @file{.c} file.
-
-Aside from the required argument INFILE, @code{guile-snarf} passes its
-command-line arguments directly to the C preprocessor, which it uses to
-extract the information it needs from the source code. this means you can pass
-normal compilation flags to @code{guile-snarf} to define preprocessor symbols,
-add header file directories, and so on.
-
-@c ---------------------------------------------------------------------------
-@node Macros guile-snarf recognizes
-@subsubsection Macros guile-snarf recognizes
-@cindex guile-snarf recognized macros
-@cindex guile-snarf deprecated macros
-
-Here are the macros you can use in your source code from which
-@code{guile-snarf} can construct initialization code:
-
-@example
-/* procedures */
-SCM_DEFINE (FNAME, PRIMNAME, REQ, OPT, VAR, ARGLIST, DOCSTRING)
-
-SCM_PROC (RANAME, STR, REQ, OPT, VAR, CFN)
-SCM_REGISTER_PROC (RANAME, STR, REQ, OPT, VAR, CFN)
-
-SCM_GPROC (RANAME, STR, REQ, OPT, VAR, CFN, GF)
-
-/* everything else */
-SCM_SYMBOL (c_name, scheme_name)
-SCM_GLOBAL_SYMBOL (c_name, scheme_name)
-
-SCM_KEYWORD (c_name, scheme_name)
-SCM_GLOBAL_KEYWORD (c_name, scheme_name)
-
-SCM_VARIABLE (c_name, scheme_name)
-SCM_GLOBAL_VARIABLE (c_name, scheme_name)
-
-SCM_VARIABLE_INIT (c_name, scheme_name, init_val)
-SCM_GLOBAL_VARIABLE_INIT (c_name, scheme_name, init_val)
-@end example
-
-@c i like things dense, but maybe someone else will reformat this
-@c into an easier-to-read list. also, all-upcase to me is a form
-@c of quoting, so @var{} is not necessary there. --ttn
-REQ and OPT are numbers indicating required and optional argument
-counts, respectively; VAR is a number that, if non-zero, means the
-function will accept any remaining arguments as a list; DOCSTRING is a
-string (use @code{\n\} at eol for multi-line); FNAME is a C-language
-identifier, CFN and GF and @var{c_name} likewise; PRIMNAME is a string
-denoting the name available to Scheme code, STR and @var{scheme_name}
-likewise; RANAME is the name of the static string (must match that
-declared by the associated definition of cpp macro @var{FUNC_NAME});
-ARGLIST is an argument list (in parentheses); and lastly, @var{init_val}
-is a expression suitable for initializing a new variable.
-
-For procedures, you can use @code{SCM_DEFINE} for most purposes. Use
-@code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't want
-to be bothered with docstrings. Use @code{SCM_GPROC} for generic
-functions (@pxref{GOOPS,,,goops}). All procedures are declared
-@code{static} with return type @code{SCM}.
-
-For everything else, use the appropriate macro (@code{SCM_SYMBOL} for
-symbols, and so on). The "_GLOBAL_" variants omit @code{static}
-declaration.
-
-All these macros should be used at top-level, outside function bodies.
-Also, it's a good idea to define @var{FUNC_NAME} immediately after using
-@code{SCM_DEFINE} (and similar), and then the function body, and then
-@code{#undef FUNC_NAME}.
-
-Here is the list of deprecated macros:
-
-@c reminder: sync w/ libguile/guile-snarf.in var `deprecated_list'
-@example
- SCM_CONST_LONG
- SCM_VCELL
- SCM_VCELL_INIT
- SCM_GLOBAL_VCELL
- SCM_GLOBAL_VCELL_INIT
-@end example
-
-Some versions of guile (and guile-snarf) will continue to recognize them but
-at some point they will no longer work. You can pass either @code{-d} or
-@code{-D} option to have guile-snarf warn or signal error, respectively, if
-any of these are found in the input file.
-
-@xref{How guile-snarf works}, and also libguile source, for examples.
-@xref{Subrs}, for details on argument passing and how to write C
-functions.
-
-@c ---------------------------------------------------------------------------
-@node Doc Snarfing
-@subsection Doc Snarfing
-
-In addition to init snarfing (@pxref{Init Snarfing with guile-snarf}),
-the libguile sources are also subject to doc snarfing, by programs that
-are included in the distribution (but not installed at this time). The
-output is the file @file{guile-procedures.txt} which is installed, and
-subsequently used by module @code{(ice-9 documentation)}.
-
-Here is a list of what does what according to @file{libguile/Makefile.am}:
-
-@itemize
-@item guile-snarf-docs runs cpp defining SCM_MAGIC_SNARF_DOCS
-@item guile_filter_doc_snarfage parses guile-snarf-docs output to produce .doc
-@item ../scripts/snarf-check-and-output-texi makes guile.texi
-@item ../scripts/snarf-check-and-output-texi makes guile-procedures.txt
-@item guile-func-name-check checks source snarf-syntax integrity (optional?)
-@item guile-doc-snarf calls guile-snarf-docs (to make .doc) and guile-snarf
-@end itemize
-
-Note that for guile-1.4, a completely different approach was used! All this
-is rather byzantine, so for now @emph{NO} doc snarfing programs are installed.
-
-[fixme: Document further once doc snarfing is tamed somewhat. --ttn]
-
-@c ---------------------------------------------------------------------------
-@node Executable Modules
-@section Executable Modules
-@cindex guile-tools
-@cindex modules, executable
-@cindex executable modules
-@cindex scripts
-
-When Guile is installed, in addition to the @code{(ice-9 FOO)} modules,
-a set of @dfn{executable modules} @code{(scripts BAR)} is also installed.
-Each is a regular Scheme module that has some additional packaging so
-that it can be called as a program in its own right, from the shell. For this
-reason, we sometimes use the term @dfn{script} in this context to mean the
-same thing.
-
-@c wow look at this hole^! variable-width font users eat your heart out.
-
-As a convenience, the @code{guile-tools} wrapper program is installed along w/
-@code{guile}; it knows where a particular module is installed and calls it
-passing its args to the program. The result is that you need not augment your
-PATH. Usage is straightforward:
-
-@example
-guile-tools --help
-guile-tools --version
-guile-tools [OPTION] PROGRAM [ARGS ...]
-
-If PROGRAM is "list" or omitted, display contents of scripts dir, otherwise
-PROGRAM is run w/ ARGS. Options (only one of which may be used at a time):
- --scriptsdir DIR -- Look in DIR for scripts
- --guileversion VERS -- Look in $pkgdatadir/VERS/scripts for scripts
- --source -- Display PROGRAM source (ignore ARGS) to stdout
-@end example
-
-The modules are self-documenting. For example, to see the documentation for
-@code{lint}, use one (or both) of the shell commands:
-
-@example
-guile-tools display-commentary '(scripts lint)'
-guile-tools --source lint
-@end example
-
-The rest of this section describes the packaging that goes into creating an
-executable module. Feel free to skip to the next chapter.
-
-@subsection Writing Executable Modules
-
-@c adapted from scripts/README
-
-See template file @code{PROGRAM} for a quick start.
-
-Programs must follow the @dfn{executable module} convention, documented here:
-
-@itemize
-
-@item
-The file name must not end in ".scm".
-
-@item
-The file must be executable (chmod +x).
-
-@item
-The module name must be "(scripts PROGRAM)". A procedure named PROGRAM w/
-signature "(PROGRAM . args)" must be exported. Basically, use some variant
-of the form:
-
-@example
-(define-module (scripts PROGRAM)
- :export (PROGRAM))
-@end example
-
-Feel free to export other definitions useful in the module context.
-
-@item
-There must be the alias:
-
-@example
-(define main PROGRAM)
-@end example
-
-However, `main' must NOT be exported.
-
-@item
-The beginning of the file must use the following invocation sequence:
-
-@example
-#!/bin/sh
-main='(module-ref (resolve-module '\''(scripts PROGRAM)) '\'main')'
-exec $@{GUILE-guile@} -l $0 -c "(apply $main (cdr (command-line)))" "$@@"
-!#
-@end example
-
-@end itemize
-
-Following these conventions allows the program file to be used as module
-@code{(scripts PROGRAM)} in addition to as a standalone executable. Please
-also include a helpful Commentary section w/ some usage info.
-
-@c tools.texi ends here
diff --git a/doc/sources/.cvsignore b/doc/sources/.cvsignore
deleted file mode 100644
index 1b583920e..000000000
--- a/doc/sources/.cvsignore
+++ /dev/null
@@ -1,20 +0,0 @@
-Makefile
-Makefile.in
-stamp-vti
-*.log
-*.dvi
-*.aux
-*.toc
-*.cp
-*.fn
-*.vr
-*.tp
-*.ky
-*.pg
-*.cps
-*.fns
-*.tps
-*.vrs
-*.ps
-*.info*
-version.texi
diff --git a/doc/sources/ChangeLog b/doc/sources/ChangeLog
deleted file mode 100644
index 1df00138b..000000000
--- a/doc/sources/ChangeLog
+++ /dev/null
@@ -1,5 +0,0 @@
-2001-08-27 Neil Jerram <neil@ossau.uklinux.net>
-
- The change log for files in this directory continues backwards
- from 2001-08-27 in ../ChangeLog, as all the Guile documentation
- prior to this date was contained in a single directory.
diff --git a/doc/sources/Makefile.am b/doc/sources/Makefile.am
deleted file mode 100644
index d201637e4..000000000
--- a/doc/sources/Makefile.am
+++ /dev/null
@@ -1,7 +0,0 @@
-# -*- Makefile -*-
-
-EXTRA_DIST = libguile-overview.texi snarf.texi contributors.texi \
- libguile-tools.texi strings.texi data-rep.texi new-types.texi tk.texi \
- debug-c.texi old-intro.texi unix-other.texi debug-scheme.texi \
- sample-APIs.texi unix.texi guile-slib.texi scheme-concepts.texi \
- jimb-org.texi scm-ref.texi
diff --git a/doc/sources/contributors.texi b/doc/sources/contributors.texi
deleted file mode 100644
index 578c358f7..000000000
--- a/doc/sources/contributors.texi
+++ /dev/null
@@ -1,80 +0,0 @@
-@node Contributors to Guile
-@appendix Contributors to Guile
-
-This Guile Manual was written by Mark Galassi, Jim Blandy and Gary
-Houston.
-
-Guile was developed over many years by the following people:
-
-@table @strong
-@item George Carrette
-Wrote files present in Siod version 2.3, released in December of 1989.
-
-@item Aubrey Jaffer
-Wrote substantial portions of guile.texi, and surely others.
-Changes to: eval.c, ioext.c, posix.c, gscm.c, scm.h, socket.c,
-gsubr.c, sys.c, test.scm, stime.c, and unif.c.
-
-@item Gary Houston
-changes to many files in libguile.
-
-wrote: libguile/socket.c, ice-9/expect.scm
-
-@item Tom Lord
-Many changes throughout.
-In the subdirectory ctax, wrote:
- Makefile.in configure.in hashtabs.scm macros.scm scm-ops.scm
- c-ops.scm grammar.scm lexer.scm reader.scm
-In the subdirectory gtcltk-lib, wrote:
- Makefile.in guile-tcl.c guile-tk.c
- configure.in guile-tcl.h guile-tk.h
-In the subdirectory guile, wrote:
- Makefile.in getopt.c getopt1.c
- configure.in getopt.h guile.c
-In the subdirectory ice-9, wrote:
- Makefile.in configure.in lineio.scm poe.scm
- boot-9.scm hcons.scm mapping.scm
-In the subdirectory lang, wrote:
- Makefile.in grammar.scm lr0.scm pp.scm
- configure.in lex.scm lr1.scm
-In the subdirectory rx, wrote:
- Makefile.in runtests.c rxbitset.h rxnfa.c rxspencer.c
- TESTS rx.c rxcontext.h rxnfa.h rxspencer.h
- TESTS2C.sed rx.h rxcset.c rxnode.c rxstr.c
- _rx.h rxall.h rxcset.h rxnode.h rxstr.h
- configure.in rxanal.c rxdbug.c rxposix.c rxsuper.c
- hashrexp.c rxanal.h rxgnucomp.c rxposix.h rxsuper.h
- inst-rxposix.h rxbasic.c rxgnucomp.h rxproto.h rxunfa.c
- rgx.c rxbasic.h rxhash.c rxsimp.c rxunfa.h
- rgx.h rxbitset.c rxhash.h rxsimp.h testcases.h
-In the subdirectory doc, wrote:
- ctax.texi gtcltk.texi in.texi lang.texi
-and portions of guile.texi.
-
-@item Anthony Green
-wrote the original code in the 'threads' directory, and
-ice-9/threads.scm.
-
-@item Mikael Djurfeldt
-@example
-In the subdirectory libguile, wrote:
- backtrace.c debug.c options.c root.c srcprop.c stacks.c
- backtrace.h debug.h options.h root.h srcprop.h stacks.h
-In the subdirectory threads, rewrote:
- coop-threads.c coop.c mit-pthreads.c threads.c
- coop-threads.h fsu-pthreads.h mit-pthreads.h threads.h
-Many other changes throughout.
-@end example
-
-@item Mark Galassi
-@example
-Designed and implemented the high-level libguile API (the @code{gh_}
-interface), based largely on the defunct @code{gscm_} interface. In the
-subdirectory gh, wrote:
-gh.c gh_eval.c gh_io.c gh_test_c.c
-gh.h gh_funcs.c gh_list.c gh_test_repl.c
-gh_data.c gh_init.c gh_predicates.c
-@end example
-
-
-@end table
diff --git a/doc/sources/debug-c.texi b/doc/sources/debug-c.texi
deleted file mode 100644
index 77d02f440..000000000
--- a/doc/sources/debug-c.texi
+++ /dev/null
@@ -1,2 +0,0 @@
-@node Debugging libguile
-@chapter Debugging libguile
diff --git a/doc/sources/debug-scheme.texi b/doc/sources/debug-scheme.texi
deleted file mode 100644
index 35340f943..000000000
--- a/doc/sources/debug-scheme.texi
+++ /dev/null
@@ -1,2 +0,0 @@
-@node Debugging Scheme programs
-@chapter Debugging Scheme programs
diff --git a/doc/sources/env.texi b/doc/sources/env.texi
deleted file mode 100644
index dc6bf9a40..000000000
--- a/doc/sources/env.texi
+++ /dev/null
@@ -1,1165 +0,0 @@
-\input texinfo @c -*-texinfo-*-
-@c %**start of header
-@setfilename env.info
-@settitle Top-level Environments in Guile
-@c %**end of header
-
-@setchapternewpage odd
-
-@c Changes since Jost's implementation:
-@c "finite environments" -> "leaf environments"
-@c "scm_foo_internal" -> "scm_c_foo"
-
-@c To do:
-@c add spec for soft environments
-
-@c When merged into the main manual, add cross-references for:
-@c weak references
-@c smobs (esp. module's mark and free functions)
-
-
-[[add refs for all conditions signalled]]
-
-@ifinfo
-Copyright 1999 Free Software Foundation, Inc.
-@end ifinfo
-
-@titlepage
-@sp 10
-@comment The title is printed in a large font.
-@center @titlefont{Top-level Environments in Guile}
-
-@c The following two commands start the copyright page.
-@page
-@vskip 0pt plus 1filll
-Copyright @copyright{} 1999 Free Software Foundation, Inc.
-@end titlepage
-
-@node Top, Motivation, (dir), (dir)
-
-@menu
-* Motivation::
-* Top-Level Environments in Guile::
-* Modules::
-@end menu
-
-@node Motivation, Top-Level Environments in Guile, Top, Top
-@chapter Motivation
-
-@example
-$Id: env.texi,v 1.1 2001-08-24 09:40:29 ossau Exp $
-@end example
-
-This is a draft proposal for a new datatype for representing top-level
-environments in Guile. Upon completion, this proposal will be posted to
-the mailing list @samp{guile@@cygnus.com} for discussion, revised in
-light of whatever insights that may produce, and eventually implemented.
-
-Note that this is @emph{not} a proposal for a module system; rather, it
-is a proposal for a data structure which encapsulates the ideas one
-needs when writing a module system, and, most importantly, a fixed
-interface which insulates the interpreter from the details of the module
-system. Using these environments, one could implement any module system
-one pleased, without changing the interpreter.
-
-I hope this text will eventually become a chapter of the Guile manual;
-thus, the description of environments in written in the present tense,
-as if it were already implemented, not in the future tense. However,
-this text does not actually describe the present state of Guile.
-
-I'm especially interested in improving the vague, rambling presentation
-of environments in the section "Modules and Environments". I'm trying
-to orient the user for the discussion that follows, but I wonder if I'm
-just confusing the issue. I would appreciate suggestions if they are
-concrete --- please provide new wording.
-
-Note also: I'm trying out a convention I'm considering for use in the
-manual. When a Scheme procedure which is directly implemented by a C
-procedure, and both are useful to call from their respective languages,
-we document the Scheme procedure only, and call it a "Primitive". If a
-Scheme function is marked as a primitive, you can derive the name of the
-corresponding C function by changing @code{-} to @code{_}, @code{!} to
-@code{_x}, @code{?} to @code{_p}, and prepending @code{scm_}. The C
-function's arguments will be all of the Scheme procedure's argumements,
-both required and optional; if the Scheme procedure takes a ``rest''
-argument, that will be a final argument to the C function. The C
-function's arguments, as well as its return type, will be @code{SCM}.
-Thus, a procedure documented like this:
-@deffn Primitive set-car! pair value
-@end deffn
-
-has a corresponding C function which would be documented like this:
-@deftypefn {Libguile function} SCM scm_set_car_x (SCM @var{pair}, SCM @var{value})
-@end deftypefn
-
-The hope is that this will be an uncluttered way to document both the C
-and Scheme interfaces, without unduly confusing users interested only in
-the Scheme level.
-
-When there is a C function which provides the same functionality as a
-primitive, but with a different interface tailored for C's needs, it
-usually has the same name as the primitive's C function, but with the
-prefix @code{scm_c_} instead of simply @code{scm_}. Thus,
-@code{scm_c_environment_ref} is almost identical to
-@code{scm_environment_ref}, except that it indicates an unbound variable
-in a manner friendlier to C code.
-
-
-
-@node Top-Level Environments in Guile, Modules, Motivation, Top
-@chapter Top-Level Environments in Guile
-
-In Guile, an environment is a mapping from symbols onto variables, and
-a variable is a location containing a value. Guile uses the datatype
-described here to represent its top-level environments.
-
-
-@menu
-* Modules and Environments:: Modules are environments, with bookkeeping.
-* Common Environment Operations:: Looking up bindings, creating bindings, etc.
-* Standard Environment Types:: Guile has some fundamental environment types.
-* Implementing Environments:: You can extend Guile with new kinds of
- environments.
-* Switching to Environments:: Changes needed to today's Guile to
- implement the features described here.
-@end menu
-
-@node Modules and Environments, Common Environment Operations, Top-Level Environments in Guile, Top-Level Environments in Guile
-@section Modules and Environments
-
-Guile distinguishes between environments and modules. A module is a
-unit of code sharing; it has a name, like @code{(math random)}, an
-implementation (e.g., Scheme source code, a dynamically linked library,
-or a set of primitives built into Guile), and finally, an environment
-containing the definitions which the module exports for its users.
-
-An environment, by contrast, is simply an abstract data type
-representing a mapping from symbols onto variables which the Guile
-interpreter uses to look up top-level definitions. The @code{eval}
-procedure interprets its first argument, an expression, in the context
-of its second argument, an environment.
-
-Guile uses environments to implement its module system. A module
-created by loading Scheme code might be built from several environments.
-In addition to the environment of exported definitions, such a module
-might have an internal top-level environment, containing both exported
-and private definitions, and perhaps environments for imported
-definitions alone and local definitions alone.
-
-The interface described here includes a full set of functions for
-mutating environments, and the system goes to some length to maintain
-its consistency as environments' bindings change. This is necessary
-because Guile is an interactive system. The user may create new
-definitions or modify and reload modules while Guile is running; the
-system should handle these changes in a consistent and predictable way.
-
-A typical Guile system will have several distinct top-level
-environments. (This is why we call them ``top-level'', and not
-``global''.) For example, consider the following fragment of an
-interactive Guile session:
-
-@example
-guile> (use-modules (ice-9 regex))
-guile> (define pattern "^(..+)\\1+$")
-guile> (string-match pattern "xxxx")
-#("xxxx" (0 . 4) (0 . 2))
-guile> (string-match pattern "xxxxx")
-#f
-guile>
-@end example
-@noindent
-Guile evaluates the expressions the user types in a top-level
-environment reserved for that purpose; the definition of @code{pattern}
-goes there. That environment is distinct from the one holding the
-private definitions of the @code{(ice-9 regex)} module. At the Guile
-prompt, the user does not see the module's private definitions, and the
-module is unaffected by definitions the user makes at the prompt. The
-@code{use-modules} form copies the module's public bindings into the
-user's environment.
-
-All Scheme evaluation takes place with respect to some top-level
-environment. Just as the procedure created by a @code{lambda} form
-closes over any local scopes surrounding that form, it also closes over
-the surrounding top-level environment. Thus, since the
-@code{string-match} procedure is defined in the @code{(ice-9 regex)}
-module, it closes over that module's top-level environment. Thus, when
-the user calls @code{string-match} from the Guile prompt, any free
-variables in @code{string-match}'s definition are resolved with respect
-to the module's top-level environment, not the user's.
-
-Although the Guile interaction loop maintains a ``current'' top-level
-environment in which it evaluates the user's input, it would be
-misleading to extend the concept of a ``current top-level environment''
-to the system as a whole. Each procedure closes over its own top-level
-environment, in which that procedure will find bindings for its free
-variables. Thus, the top-level environment in force at any given time
-depends on the procedure Guile happens to be executing. The global
-``current'' environment is a figment of the interaction loop's
-imagination.
-
-Since environments provide all the operations the Guile interpreter
-needs to evaluate code, they effectively insulate the interpreter from
-the details of the module system. Without changing the interpreter, you
-can implement any module system you like, as long as its efforts produce
-an environment object the interpreter can consult.
-
-Finally, environments may prove a convenient way for Guile to access the
-features of other systems. For example, one might export the The GIMP's
-Procedural Database to Guile as a custom environment type; this
-environment could create Scheme procedure objects corresponding to GIMP
-procedures, as the user referenced them.
-
-
-@node Common Environment Operations, Standard Environment Types, Modules and Environments, Top-Level Environments in Guile
-@section Common Environment Operations
-
-This section describes the common set of operations that all environment
-objects support. To create an environment object, or to perform an
-operation specific to a particular kind of environment, see
-@ref{Standard Environment Types}.
-
-In this section, the following names for formal parameters imply that
-the actual parameters must have a certain type:
-
-@table @var
-
-@item env
-an environment
-
-@item symbol
-a symbol
-
-@item proc
-a procedure
-
-@item value
-@itemx object
-an arbitrary Scheme value
-
-@end table
-
-
-@menu
-* Examining Environments::
-* Changing Environments::
-* Caching Environment Lookups::
-* Observing Changes to Environments ::
-* Environment Errors::
-@end menu
-
-@node Examining Environments, Changing Environments, Common Environment Operations, Common Environment Operations
-@subsection Examining Environments
-
-@deffn Primitive environment? object
-Return @code{#t} if @var{object} is an environment, or @code{#f} otherwise.
-@end deffn
-
-@deffn Primitive environment-ref env symbol
-Return the value of the location bound to @var{symbol} in @var{env}.
-If @var{symbol} is unbound in @var{env}, signal an @code{environment:unbound}
-error (@pxref{Environment Errors}).
-@end deffn
-
-@deffn Primitive environment-bound? env symbol
-Return @code{#t} if @var{symbol} is bound in @var{env}, or @code{#f}
-otherwise.
-@end deffn
-
-@deffn Primitive environment-fold env proc init
-Iterate over all the bindings in an environment, accumulating some value.
-
-For each binding in @var{env}, apply @var{proc} to the symbol bound, its
-value, and the result from the previous application of @var{proc}. Use
-@var{init} as @var{proc}'s third argument the first time @var{proc} is
-applied.
-
-If @var{env} contains no bindings, this function simply returns @var{init}.
-
-If @var{env} binds the symbol @var{sym1} to the value @var{val1},
-@var{sym2} to @var{val2}, and so on, then this procedure computes:
-@example
-(@var{proc} @var{sym1} @var{val1}
- (@var{proc} @var{sym2} @var{val2}
- ...
- (@var{proc} @var{symn} @var{valn}
- @var{init})))
-@end example
-
-Each binding in @var{env} is processed at most once.
-@code{environment-fold} makes no guarantees about the order in which the
-bindings are processed.
-
-If @var{env} is not modified while the iteration is taking place,
-@code{environment-fold} will apply @var{proc} to each binding in
-@var{env} exactly once.
-
-If @var{env} is modified while the iteration is taking place, we need to
-be more subtle in describing @code{environment-fold}'s behavior.
-@code{environment-fold} repeatedly applies @var{proc} to a binding which
-was present in @var{env} when @code{environment-fold} was invoked and is
-still present in @var{env}, until there are no such bindings remaining.
-(If no mutations take place, this definition is equivalent to the
-simpler one given above.) By this definition, bindings added during the
-iteration will not be passed to @var{proc}.
-
-Here is a function which, given an environment, constructs an
-association list representing that environment's bindings, using
-@code{environment-fold}:
-@example
-(define (environment->alist env)
- (environment-fold env
- (lambda (sym val tail)
- (cons (cons sym val) tail))
- '()))
-@end example
-@end deffn
-
-@deftypefn {Libguile macro} int SCM_ENVP (@var{object})
-Return non-zero if @var{object} is an environment.
-@end deftypefn
-
-@deftypefn {Libguile function} SCM scm_c_environment_ref (SCM @var{env}, SCM @var{symbol})
-This C function is identical to @code{environment-ref}, except that if
-@var{symbol} is unbound in @var{env}, it returns the value
-@code{SCM_UNDEFINED}, instead of signalling an error.
-@end deftypefn
-
-@deftypefn {Libguile function} SCM scm_c_environment_fold (SCM @var{env}, scm_environment_folder *@var{proc}, SCM @var{data}, SCM @var{init})
-This is the C-level analog of @code{environment-fold}. For each binding in
-@var{env}, make the call:
-@example
-(*@var{proc}) (@var{data}, @var{symbol}, @var{value}, @var{previous})
-@end example
-@noindent
-where @var{previous} is the value returned from the last call to
-@code{*@var{proc}}, or @var{init} for the first call. If @var{env}
-contains no bindings, return @var{init}.
-@end deftypefn
-
-@deftp {Libguile data type} scm_environment_folder SCM (SCM @var{data}, SCM @var{symbol}, SCM @var{value}, SCM @var{tail})
-The type of a folding function to pass to @code{scm_c_environment_fold}.
-@end deftp
-
-
-@node Changing Environments, Caching Environment Lookups, Examining Environments, Common Environment Operations
-@subsection Changing Environments
-
-Here are functions for changing symbols' bindings and values.
-
-Although it is common to say that an environment binds a symbol to a
-value, this is not quite accurate; an environment binds a symbol to a
-location, and the location contains a value. In the descriptions below,
-we will try to make clear how each function affects bindings and
-locations.
-
-Note that some environments may contain some immutable bindings, or may
-bind symbols to immutable locations. If you attempt to change an
-immutable binding or value, these functions will signal an
-@code{environment:immutable-binding} or
-@code{environment:immutable-location} error. However, simply because a
-binding cannot be changed via these functions does @emph{not} imply that
-it is constant. Mechanisms outside the scope of this section (say,
-re-loading a module's source code) may change a binding or value which
-is immutable via these functions.
-
-@deffn Primitive environment-define env symbol value
-Bind @var{symbol} to a new location containing @var{value} in @var{env}.
-If @var{symbol} is already bound to another location in @var{env}, that
-binding is replaced. The new binding and location are both mutable.
-The return value is unspecified.
-
-If @var{symbol} is already bound in @var{env}, and the binding is
-immutable, signal an @code{environment:immutable-binding} error.
-@end deffn
-
-@deffn Primitive environment-undefine env symbol
-Remove any binding for @var{symbol} from @var{env}. If @var{symbol} is
-unbound in @var{env}, do nothing. The return value is unspecified.
-
-If @var{symbol} is already bound in @var{env}, and the binding is
-immutable, signal an @code{environment:immutable-binding} error.
-@end deffn
-
-@deffn Primitive environment-set! env symbol value
-If @var{env} binds @var{symbol} to some location, change that location's
-value to @var{value}. The return value is unspecified.
-
-If @var{symbol} is not bound in @var{env}, signal an
-@code{environment:unbound} error. If @var{env} binds @var{symbol} to an
-immutable location, signal an @code{environment:immutable-location}
-error.
-@end deffn
-
-
-@node Caching Environment Lookups, Observing Changes to Environments , Changing Environments, Common Environment Operations
-@subsection Caching Environment Lookups
-
-Some applications refer to variables' values so frequently that the
-overhead of @code{environment-ref} and @code{environment-set!} is
-unacceptable. For example, variable reference speed is a critical
-factor in the performance of the Guile interpreter itself. If an
-application can tolerate some additional complexity, the
-@code{environment-cell} function described here can provide very
-efficient access to variable values.
-
-In the Guile interpreter, most variables are represented by pairs; the
-@sc{cdr} of the pair holds the variable's value. Thus, a variable
-reference corresponds to taking the @sc{cdr} of one of these pairs, and
-setting a variable corresponds to a @code{set-cdr!} operation. A pair
-used to represent a variable's value in this manner is called a
-@dfn{value cell}. Value cells represent the ``locations'' to which
-environments bind symbols.
-
-The @code{environment-cell} function returns the value cell bound to a
-symbol. For example, an interpreter might make the call
-@code{(environment-cell @var{env} @var{symbol} #t)} to find the value
-cell which @var{env} binds to @var{symbol}, and then use @code{cdr} and
-@code{set-cdr!} to reference and assign to that variable, instead of
-calling @code{environment-ref} or @var{environment-set!} for each
-variable reference.
-
-There are a few caveats that apply here:
-
-@itemize @bullet
-
-@item
-Environments are not required to represent variables' values using value
-cells. An environment is free to return @code{#f} in response to a
-request for a symbol's value cell; in this case, the caller must use
-@code{environment-ref} and @code{environment-set!} to manipulate the
-variable.
-
-@item
-An environment's binding for a symbol may change. For example, the user
-could override an imported variable with a local definition, associating
-a new value cell with that symbol. If an interpreter has used
-@code{environment-cell} to obtain the variable's value cell, it no
-longer needs to use @code{environment-ref} and @code{environment-set!}
-to access the variable, and it may not see the new binding.
-
-Thus, code which uses @code{environment-cell} should almost always use
-@code{environment-observe} to track changes to the symbol's binding;
-this is the additional complexity hinted at above. @xref{Observing
-Changes to Environments}.
-
-@item
-Some variables should be immutable. If a program uses
-@code{environment-cell} to obtain the value cell of such a variable,
-then it is impossible for the environment to prevent the program from
-changing the variable's value, using @code{set-cdr!}. However, this is
-discouraged; it is probably better to redesign the interface than to
-disregard such a request. To make it easy for programs to honor the
-immutability of a variable, @code{environment-cell} takes an argument
-indicating whether the caller intends to mutate the cell's value; if
-this argument is true, then @code{environment-cell} signals an
-@code{environment:immutable-location} error.
-
-Programs should therefore make separate calls to @code{environment-cell}
-to obtain value cells for reference and for assignment. It is incorrect
-for a program to call @code{environment-cell} once to obtain a value
-cell, and then use that cell for both reference and mutation.
-
-@end itemize
-
-@deffn Primitive environment-cell env symbol for-write
-Return the value cell which @var{env} binds to @var{symbol}, or
-@code{#f} if the binding does not live in a value cell.
-
-The argument @var{for-write} indicates whether the caller intends to
-modify the variable's value by mutating the value cell. If the variable
-is immutable, then @code{environment-cell} signals an
-@code{environment:immutable-location} error.
-
-If @var{symbol} is unbound in @var{env}, signal an @code{environment:unbound}
-error.
-
-If you use this function, you should consider using
-@code{environment-observe}, to be notified when @code{symbol} gets
-re-bound to a new value cell, or becomes undefined.
-@end deffn
-
-@deftypefn {Libguile function} SCM scm_c_environment_cell (SCM @var{env}, SCM @var{symbol}, int for_write)
-This C function is identical to @code{environment-cell}, except that if
-@var{symbol} is unbound in @var{env}, it returns the value
-@code{SCM_UNDEFINED}, instead of signalling an error.
-@end deftypefn
-
-[[After we have some experience using this, we may find that we want to
-be able to explicitly ask questions like, "Is this variable mutable?"
-without the annoyance of error handling. But maybe this is fine.]]
-
-
-@node Observing Changes to Environments , Environment Errors, Caching Environment Lookups, Common Environment Operations
-@subsection Observing Changes to Environments
-
-The procedures described here allow you to add and remove @dfn{observing
-procedures} for an environment.
-
-
-@menu
-* Registering Observing Procedures::
-* Observations and Garbage Collection::
-* Observing Environments from C Code::
-@end menu
-
-@node Registering Observing Procedures, Observations and Garbage Collection, Observing Changes to Environments , Observing Changes to Environments
-@subsubsection Registering Observing Procedures
-
-A program may register an @dfn{observing procedure} for an environment,
-which will be called whenever a binding in a particular environment
-changes. For example, if the user changes a module's source code and
-re-loads the module, other parts of the system may want to throw away
-information they have cached about the bindings of the older version of
-the module. To support this, each environment retains a set of
-observing procedures which it will invoke whenever its bindings change.
-We say that these procedures @dfn{observe} the environment's bindings.
-You can register new observing procedures for an environment using
-@code{environment-observe}.
-
-@deffn Primitive environment-observe env proc
-Whenever @var{env}'s bindings change, apply @var{proc} to @var{env}.
-
-This function returns an object, @var{token}, which you can pass to
-@code{environment-unobserve} to remove @var{proc} from the set of
-procedures observing @var{env}. The type and value of @var{token} is
-unspecified.
-@end deffn
-
-@deffn Primitive environment-unobserve token
-Cancel the observation request which returned the value @var{token}.
-The return value is unspecified.
-
-If a call @code{(environment-observe @var{env} @var{proc})} returns
-@var{token}, then the call @code{(environment-unobserve @var{token})}
-will cause @var{proc} to no longer be called when @var{env}'s bindings
-change.
-@end deffn
-
-There are some limitations on observation:
-@itemize @bullet
-@item
-These procedures do not allow you to observe specific bindings; you
-can only observe an entire environment.
-@item
-These procedures observe bindings, not locations. There is no way
-to receive notification when a location's value changes, using these
-procedures.
-@item
-These procedures do not promise to call the observing procedure for each
-individual binding change. However, if multiple bindings do change
-between calls to the observing procedure, those changes will appear
-atomic to the entire system, not just to a few observing procedures.
-@item
-Since a single environment may have several procedures observing it, a
-correct design obviously may not assume that nothing else in the system
-has yet observed a given change.
-@end itemize
-
-(One weakness of this observation architecture is that observing
-procedures make no promises to the observer. That's fine if you're just
-trying to implement an accurate cache, but too weak to implement things
-that walk the environment tree.)
-
-@node Observations and Garbage Collection, Observing Environments from C Code, Registering Observing Procedures, Observing Changes to Environments
-@subsubsection Observations and Garbage Collection
-
-When writing observing procedures, pay close attention to garbage
-collection issues. If you use @code{environment-observe} to register
-observing procedures for an environment, the environment will hold a
-reference to those procedures; while that environment is alive, its
-observing procedures will live, as will any data they close over. If
-this is not appropriate, you can use the @code{environment-observe-weak}
-procedure to create a weak reference from the environment to the
-observing procedure.
-
-For example, suppose an interpreter uses @code{environment-cell} to
-reference variables efficiently, as described above in @ref{Caching
-Environment Lookups}. That interpreter must register observing
-procedures to track changes to the environment. If those procedures
-retain any reference to the data structure representing the program
-being interpreted, then that structure cannot be collected as long as
-the observed environment lives. This is almost certainly incorrect ---
-if there are no other references to the structure, it can never be
-invoked, so it should be collected. In this case, the interpreter
-should register its observing procedure using
-@code{environment-observe-weak}, and retain a pointer to it from the
-code it updates. Thus, when the code is no longer referenced elsewhere
-in the system, the weak link will be broken, and Guile will collect the
-code (and its observing procedure).
-
-@deffn Primitive environment-observe-weak env proc
-This function is the same as @code{environment-observe}, except that the
-reference @var{env} retains to @var{proc} is a weak reference. This
-means that, if there are no other live, non-weak references to
-@var{proc}, it will be garbage-collected, and dropped from @var{env}'s
-list of observing procedures.
-@end deffn
-
-
-@node Observing Environments from C Code, , Observations and Garbage Collection, Observing Changes to Environments
-@subsubsection Observing Environments from C Code
-
-It is also possible to write code that observes an environment in C.
-The @code{scm_c_environment_observe} function registers a C
-function to observe an environment. The typedef
-@code{scm_environment_observer} is the type a C observer function must
-have.
-
-@deftypefn {Libguile function} SCM scm_c_environment_observe (SCM @var{env}, scm_environment_observer *proc, SCM @var{data}, int weak_p)
-This is the C-level analog of the Scheme function
-@code{environment-observe}. Whenever @var{env}'s bindings change, call
-the function @var{proc}, passing it @var{env} and @var{data}. If
-@var{weak_p} is non-zero, @var{env} will retain only a weak reference to
-@var{data}, and if @var{data} is garbage collected, the entire
-observation will be dropped.
-
-This function returns a token, with the same meaning as those returned
-by @code{environment-observe}.
-@end deftypefn
-
-@deftp {Libguile data type} scm_environment_observer void (SCM @var{env}, SCM @var{data})
-The type for observing functions written in C. A function meant to be
-passed to @code{scm_c_environment_observe} should have the type
-@code{scm_environment_observer}.
-@end deftp
-
-Note that, like all other primitives, @code{environment-observe} is also
-available from C, under the name @code{scm_environment_observe}.
-
-
-@node Environment Errors, , Observing Changes to Environments , Common Environment Operations
-@subsection Environment Errors
-
-Here are the error conditions signalled by the environment routines
-described above. In these conditions, @var{func} is a string naming a
-particular procedure.
-
-@deffn Condition environment:unbound func message args env symbol
-By calling @var{func}, the program attempted to retrieve the value of
-@var{symbol} in @var{env}, but @var{symbol} is unbound in @var{env}.
-@end deffn
-
-@deffn Condition environment:immutable-binding func message args env symbol
-By calling @var{func}, the program attempted to change the binding of
-@var{symbol} in @var{env}, but that binding is immutable.
-@end deffn
-
-@deffn Condition environment:immutable-location func message args env symbol
-By calling @var{func}, the program attempted to change the value of
-the location to which @var{symbol} is bound in @var{env}, but that
-location is immutable.
-@end deffn
-
-
-@node Standard Environment Types, Implementing Environments, Common Environment Operations, Top-Level Environments in Guile
-@section Standard Environment Types
-
-Guile supports several different kinds of environments. The operations
-described above are actually only the common functionality provided by
-all the members of a family of environment types, each designed for a
-separate purpose.
-
-Each environment type has a constructor procedure for building elements
-of that type, and extends the set of common operations with its own
-procedures, providing specialized functions. For an example of how
-these environment types work together, see @ref{Modules of Interpreted
-Scheme Code}.
-
-Guile allows users to define their own environment types. Given a set
-of procedures that implement the common environment operations, Guile
-will construct a new environment object based on those procedures.
-
-@menu
-* Leaf Environments:: A simple set of bindings.
-* Eval Environments:: Local definitions, shadowing
- imported definitions.
-* Import Environments:: The union of a list of environments.
-* Export Environments:: A selected subset of an environment.
-* General Environments:: Environments implemented by user
- functions.
-@end menu
-
-@node Leaf Environments, Eval Environments, Standard Environment Types, Standard Environment Types
-@subsection Leaf Environments
-
-A @dfn{leaf} environment is simply a mutable set of definitions. A mutable
-environment supports no operations beyond the common set.
-
-@deffn Primitive make-leaf-environment
-Create a new leaf environment, containing no bindings. All bindings
-and locations in the new environment are mutable.
-@end deffn
-
-@deffn Primitive leaf-environment? object
-Return @code{#t} if @var{object} is a leaf environment, or @var{#f}
-otherwise.
-@end deffn
-
-
-In Guile, each module of interpreted Scheme code uses a leaf
-environment to hold the definitions made in that module.
-
-Leaf environments are so named because their bindings are not computed
-from the contents of other environments. Most other environment types
-have no bindings of their own, but compute their binding sets based on
-those of their operand environments. Thus, the environments in a
-running Guile system form a tree, with interior nodes computing their
-contents from their child nodes. Leaf environments are the leaves of
-such trees.
-
-
-@node Eval Environments, Import Environments, Leaf Environments, Standard Environment Types
-@subsection Eval Environments
-
-A module's source code refers to definitions imported from other
-modules, and definitions made within itself. An @dfn{eval} environment
-combines two environments --- a @dfn{local} environment and an
-@dfn{imported} environment --- to produce a new environment in which
-both sorts of references can be resolved.
-
-@deffn Primitive make-eval-environment local imported
-Return a new environment object @var{eval} whose bindings are the union
-of the bindings in the environments @var{local} and @var{imported}, with
-bindings from @var{local} taking precedence. Definitions made in
-@var{eval} are placed in @var{local}.
-
-Applying @code{environment-define} or @code{environment-undefine} to
-@var{eval} has the same effect as applying the procedure to @var{local}.
-This means that applying @code{environment-undefine} to a symbol bound
-in @var{imported} and free in @var{local} has no effect on the bindings
-visible in @var{eval}, which may be surprising.
-
-Note that @var{eval} incorporates @var{local} and @var{imported}
-@emph{by reference} --- if, after creating @var{eval}, the program
-changes the bindings of @var{local} or @var{imported}, those changes
-will be visible in @var{eval}.
-
-Since most Scheme evaluation takes place in @var{eval} environments,
-they transparenty cache the bindings received from @var{local} and
-@var{imported}. Thus, the first time the program looks up a symbol in
-@var{eval}, @var{eval} may make calls to @var{local} or @var{imported}
-to find their bindings, but subsequent references to that symbol will be
-as fast as references to bindings in leaf environments.
-
-In typical use, @var{local} will be a leaf environment, and
-@var{imported} will be an import environment, described below.
-@end deffn
-
-@deffn Primitive eval-environment? object
-Return @code{#t} if @var{object} is an eval environment, or @code{#f}
-otherwise.
-@end deffn
-
-@deffn Primitive eval-environment-local env
-@deffnx Primitive eval-environment-imported env
-Return the @var{local} or @var{imported} environment of @var{env};
-@var{env} must be an eval environment.
-@end deffn
-
-
-@node Import Environments, Export Environments, Eval Environments, Standard Environment Types
-@subsection Import Environments
-
-An @dfn{import} environment combines the bindings of a set of
-argument environments, and checks for naming clashes.
-
-@deffn Primitive make-import-environment imports conflict-proc
-Return a new environment @var{imp} whose bindings are the union of the
-bindings from the environments in @var{imports}; @var{imports} must be a
-list of environments. That is, @var{imp} binds @var{symbol} to
-@var{location} when some element of @var{imports} does.
-
-If two different elements of @var{imports} have a binding for the same
-symbol, apply @var{conflict-proc} to the two environments. If the bindings
-of any of the @var{imports} ever changes, check for conflicts again.
-
-All bindings in @var{imp} are immutable. If you apply
-@code{environment-define} or @code{environment-undefine} to @var{imp},
-Guile will signal an @code{environment:immutable-binding} error.
-However, notice that the set of bindings in @var{imp} may still change,
-if one of its imported environments changes.
-@end deffn
-
-@deffn Primitive import-environment? object
-Return @code{#t} if @var{object} is an import environment, or @code{#f}
-otherwise.
-@end deffn
-
-@deffn Primitive import-environment-imports env
-Return the list of @var{env}'s imported environments; @var{env} must be
-an import env.
-@end deffn
-
-@deffn Primitive import-environment-set-imports! env imports
-Change @var{env}'s list of imported environments to @var{imports}, and
-check for conflicts.
-@end deffn
-
-I'm not at all sure about the way @var{conflict-proc} works. I think
-module systems should warn you if it seems you're likely to get the
-wrong binding, but exactly how and when those warnings should be
-generated, I don't know.
-
-
-@node Export Environments, General Environments, Import Environments, Standard Environment Types
-@subsection Export Environments
-
-An export environment restricts an environment a specified set of
-bindings.
-
-@deffn Primitive make-export-environment private signature
-Return a new environment @var{exp} containing only those bindings in
-@var{private} whose symbols are present in @var{signature}. The
-@var{private} argument must be an environment.
-
-The environment @var{exp} binds @var{symbol} to @var{location} when
-@var{env} does, and @var{symbol} is exported by @var{signature}.
-
-@var{Signature} is a list specifying which of the bindings in
-@var{private} should be visible in @var{exp}. Each element of
-@var{signature} should be a list of the form:
-@example
-(@var{symbol} @var{attribute} ...)
-@end example
-@noindent
-where each @var{attribute} is one of the following:
-@table @asis
-@item the symbol @code{mutable-location}
-@var{exp} should treat the location bound to @var{symbol} as mutable.
-That is, @var{exp} will pass calls to @var{env-set!} or
-@code{environment-cell} directly through to @var{private}.
-
-@item the symbol @code{immutable-location}
-@var{exp} should treat the location bound to @var{symbol} as immutable.
-If the program applies @code{environment-set!} to @var{exp} and
-@var{symbol}, or calls @code{environment-cell} to obtain a writable
-value cell, @code{environment-set!} will signal an
-@code{environment:immutable-location} error.
-
-Note that, even if an export environment treats a location as immutable,
-the underlying environment may treat it as mutable, so its value may
-change.
-@end table
-
-It is an error for an element of @var{signature} to specify both
-@code{mutable-location} and @code{immutable-location}. If neither is
-specified, @code{immutable-location} is assumed.
-
-As a special case, if an element of @var{signature} is a lone symbol
-@var{sym}, it is equivalent to an element of the form
-@code{(@var{sym})}.
-
-All bindings in @var{exp} are immutable. If you apply
-@code{environment-define} or @code{environment-undefine} to @var{exp},
-Guile will signal an @code{environment:immutable-binding} error.
-However, notice that the set of bindings in @var{exp} may still change,
-if the bindings in @var{private} change.
-@end deffn
-
-@deffn Primitive export-environment? object
-Return @code{#t} if @var{object} is an export environment, or @code{#f}
-otherwise.
-@end deffn
-
-@deffn Primitive export-environment-private env
-@deffnx Primitive export-environment-set-private! env
-@deffnx Primitive export-environment-signature env
-@deffnx Primitive export-environment-set-signature! env
-Accessors and mutators for the private environment and signature of
-@var{env}; @var{env} must be an export environment.
-@end deffn
-
-
-@node General Environments, , Export Environments, Standard Environment Types
-@subsection General Environments
-
-[[user provides the procedures]]
-[[A observers B and C; B observes C; C changes; A should only be
-notified once, right?]]
-[[observation loops?]]
-
-@node Implementing Environments, Switching to Environments, Standard Environment Types, Top-Level Environments in Guile
-@section Implementing Environments
-
-This section describes how to implement new environment types in Guile.
-
-Guile's internal representation of environments allows you to extend
-Guile with new kinds of environments without modifying Guile itself.
-Every environment object carries a pointer to a structure of pointers to
-functions implementing the common operations for that environment. The
-procedures @code{environment-ref}, @code{environment-set!}, etc. simply
-find this structure and invoke the appropriate function.
-
-[[It would be nice to have an example around here. How about a
-persistent environment, bound to a directory, where ref and set actually
-access files? Ref on a directory would return another
-environment... Hey, let's import my home directory!]]
-
-
-@menu
-* Environment Function Tables::
-* Environment Data::
-* Environment Example::
-@end menu
-
-
-@node Environment Function Tables, Environment Data, Implementing Environments, Implementing Environments
-@subsection Environment Function Tables
-
-An environment object is a smob whose @sc{cdr} is a pointer to a pointer
-to a @code{struct environment_funcs}:
-@example
-struct environment_funcs @{
- SCM (*ref) (SCM self, SCM symbol);
- SCM (*fold) (SCM self, scm_environment_folder *proc, SCM data, SCM init);
- void (*define) (SCM self, SCM symbol, SCM value);
- void (*undefine) (SCM self, SCM symbol);
- void (*set) (SCM self, SCM symbol, SCM value);
- SCM (*cell) (SCM self, SCM symbol, int for_write);
- SCM (*observe) (SCM self, scm_environment_observer *proc, SCM data, int weak_p);
- void (*unobserve) (SCM self, SCM token);
- SCM (*mark) (SCM self);
- scm_sizet (*free) (SCM self);
- int (*print) (SCM self, SCM port, scm_print_state *pstate);
-@};
-@end example
-
-You can use the following macro to access an environment's function table:
-
-@deftypefn {Libguile macro} struct environment_funcs *SCM_ENVIRONMENT_FUNCS (@var{env})
-Return a pointer to the @code{struct environment_func} for the environment
-@var{env}. If @var{env} is not an environment object, the behavior of
-this macro is undefined.
-@end deftypefn
-
-Here is what each element of @var{env_funcs} must do to correctly
-implement an environment. In all of these calls, @var{self} is the
-environment whose function is being invoked.
-
-@table @code
-
-@item SCM ref (SCM @var{self}, SCM @var{symbol});
-This function must have the effect described above for the C call:
-@example
-scm_c_environment_ref (@var{self}, @var{symbol})
-@end example
-@xref{Examining Environments}.
-
-Note that the @code{ref} element of a @code{struct environment_funcs}
-may be zero if a @code{cell} function is provided.
-
-@item SCM fold (SCM self, scm_environment_folder *proc, SCM data, SCM init);
-This function must have the effect described above for the C call:
-@example
-scm_c_environment_fold (@var{self}, @var{proc}, @var{data}, @var{init})
-@end example
-@xref{Examining Environments}.
-
-@item void define (SCM self, SCM symbol, SCM value);
-This function must have the effect described above for the Scheme call:
-@example
-(environment-define @var{self} @var{symbol} @var{value})
-@end example
-@xref{Changing Environments}.
-
-@item void undefine (SCM self, SCM symbol);
-This function must have the effect described above for the Scheme call:
-@example
-(environment-undefine @var{self} @var{symbol})
-@end example
-@xref{Changing Environments}.
-
-@item void set (SCM self, SCM symbol, SCM value);
-This function must have the effect described above for the Scheme call:
-@example
-(environment-set! @var{self} @var{symbol} @var{value})
-@end example
-@xref{Changing Environments}.
-
-Note that the @code{set} element of a @code{struct environment_funcs}
-may be zero if a @code{cell} function is provided.
-
-@item SCM cell (SCM self, SCM symbol, int for_write);
-This function must have the effect described above for the C call:
-@example
-scm_c_environment_cell (@var{self}, @var{symbol})
-@end example
-@xref{Caching Environment Lookups}.
-
-@item SCM observe (SCM self, scm_environment_observer *proc, SCM data, int weak_p);
-This function must have the effect described above for the C call:
-@example
-scm_c_environment_observe (@var{env}, @var{proc}, @var{data}, @var{weak_p})
-@end example
-@xref{Observing Changes to Environments}.
-
-@item void unobserve (SCM self, SCM token);
-Cancel the request to observe @var{self} that returned @var{token}.
-@xref{Observing Changes to Environments}.
-
-@item SCM mark (SCM self);
-Set the garbage collection mark all Scheme cells referred to by
-@var{self}. Assume that @var{self} itself is already marked. Return a
-final object to be marked recursively.
-
-@item scm_sizet free (SCM self);
-Free all non-cell storage associated with @var{self}; return the number
-of bytes freed that were obtained using @code{scm_must_malloc} or
-@code{scm_must_realloc}.
-
-@item SCM print (SCM self, SCM port, scm_print_state *pstate);
-Print an external representation of @var{self} on @var{port}, passing
-@var{pstate} to any recursive calls to the object printer.
-
-@end table
-
-
-@node Environment Data, Environment Example, Environment Function Tables, Implementing Environments
-@subsection Environment Data
-
-When you implement a new environment type, you will likely want to
-associate some data of your own design with each environment object.
-Since ANSI C promises that casts will safely convert between a pointer
-to a structure and a pointer to its first element, you can have the
-@sc{cdr} of an environment smob point to your structure, as long as your
-structure's first element is a pointer to a @code{struct
-environment_funcs}. Then, your code can use the macro below to retrieve
-a pointer to the structure, and cast it to the appropriate type.
-
-@deftypefn {Libguile macro} struct environment_funcs **SCM_ENVIRONMENT_DATA (@var{env})
-Return the @sc{cdr} of @var{env}, as a pointer to a pointer to an
-@code{environment_funcs} structure.
-@end deftypefn
-
-@node Environment Example, , Environment Data, Implementing Environments
-@subsection Environment Example
-
-[[perhaps a simple environment based on association lists]]
-
-
-@node Switching to Environments, , Implementing Environments, Top-Level Environments in Guile
-@section Switching to Environments
-
-Here's what we'd need to do to today's Guile to install the system
-described above. This work would probably be done on a branch, because
-it involves crippling Guile while a lot of work gets done. Also, it
-could change the default set of bindings available pretty drastically,
-so the next minor release should not contain these changes.
-
-After each step here, we should have a Guile that we can at least
-interact with, perhaps with some limitations.
-
-@itemize @bullet
-
-@item
-For testing purposes, make an utterly minimal version of
-@file{boot-9.scm}: no module system, no R5RS, nothing. I think a simple
-REPL is all we need.
-
-@item
-Implement the environment datatypes in libguile, and test them using
-this utterly minimal system.
-
-@item
-Change the interpreter to use the @code{environment-cell} and
-@code{environment-observe} instead of the symbol value slots,
-first-class variables, etc. Modify the rest of libguile as necessary to
-register all the primitives in a single environment. We'll segregate
-them into modules later.
-
-@item
-Reimplement the current module system in terms of environments. It
-should still be in Scheme.
-
-@item
-Reintegrate the rest of @file{boot-9.scm}. This might be a good point
-to move it into modules.
-
-@item
-Do some profiling and optimization.
-
-@end itemize
-
-Once this is done, we can make the following simplifications to Guile:
-
-@itemize @bullet
-
-@item
-A good portion of symbols.c can go away. Symbols no longer need value
-slots. The mismash of @code{scm_sym2ovcell},
-@code{scm_intern_obarray_soft}, etc. can go away. @code{intern} becomes
-simpler.
-
-@item
-Remove first-class variables: @file{variables.c} and @file{variables.h}.
-
-@item
-Organize the primitives into environments.
-
-@item
-The family of environment types is clearly an abstract class/concrete
-subclass arrangement. We should provide GOOPS classes/metaclasses that
-make defining new environment types easy and consistent.
-
-@end itemize
-
-
-
-@node Modules, , Top-Level Environments in Guile, Top
-@chapter Modules
-
-The material here is just a sketch. Don't take it too seriously. The
-point is that environments allow us to experiment without getting
-tangled up with the interpreter.
-
-@menu
-* Modules of Guile Primitives::
-* Modules of Interpreted Scheme Code::
-@end menu
-
-@node Modules of Guile Primitives, Modules of Interpreted Scheme Code, Modules, Modules
-@section Modules of Guile Primitives
-
-@node Modules of Interpreted Scheme Code, , Modules of Guile Primitives, Modules
-@section Modules of Interpreted Scheme Code
-
-If a module is implemented by interpreted Scheme code, Guile represents
-it using several environments:
-
-@table @asis
-
-@item the @dfn{local} environment
-This environment holds all the definitions made locally by the module,
-both public and private.
-
-@item the @dfn{import} environment
-This environment holds all the definitions this module imports from
-other modules.
-
-@item the @dfn{evaluation} environment
-This is the environment in which the module's code is actually
-evaluated, and the one closed over by the module's procedures, both
-public and private. Its bindings are the union of the @var{local} and
-@var{import} environments, with local bindings taking precedence.
-
-@item the @dfn{exported} environment
-This environment holds the module's public definitions. This is the
-only environment that the module's users have access to. It is the
-@var{evaluation} environment, restricted to the set of exported
-definitions.
-
-@end table
-
-Each of these environments is implemented using a separate environment
-type. Some of these types, like the evaluation and import environments,
-actually just compute their bindings by consulting other environments;
-they have no bindings in their own right. They implement operations
-like @code{environment-ref} and @code{environment-define} by passing
-them through to the environments from which they are derived. For
-example, the evaluation environment will pass definitions through to the
-local environment, and search for references and assignments first in
-the local environment, and then in the import environment.
-
-
-
-@bye
diff --git a/doc/sources/format.texi b/doc/sources/format.texi
deleted file mode 100644
index 122e0453d..000000000
--- a/doc/sources/format.texi
+++ /dev/null
@@ -1,434 +0,0 @@
-
-@menu
-* Format Interface::
-* Format Specification::
-@end menu
-
-@node Format Interface, Format Specification, Format, Format
-@subsection Format Interface
-
-@defun format destination format-string . 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{format-string}. If @var{destination} is @code{#t},
-the output is to the current output port and @code{#t} is returned. If
-@var{destination} is @code{#f}, a formatted string is returned as the
-result of the call. NEW: If @var{destination} is a string,
-@var{destination} is regarded as the format string; @var{format-string} is
-then the first argument and the output is returned as a string. If
-@var{destination} 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{#t} is returned.@refill
-
-@var{format-string} must be a string. In case of a formatting error
-format returns @code{#f} and prints a message on the current output or
-error port. Characters are output as if the string were output by the
-@code{display} function with the exception of those prefixed by a tilde
-(~). For a detailed description of the @var{format-string} syntax
-please consult a Common LISP format reference manual. For a test suite
-to verify this format implementation load @file{formatst.scm}. Please
-send bug reports to @code{lutzeb@@cs.tu-berlin.de}.
-
-Note: @code{format} is not reentrant, i.e. only one @code{format}-call
-may be executed at a time.
-
-@end defun
-
-@node Format Specification, , Format Interface, Format
-@subsection Format Specification (Format version 3.0)
-
-Please consult a Common LISP format reference manual for a detailed
-description of the format string syntax. For a demonstration of the
-implemented directives see @file{formatst.scm}.@refill
-
-This implementation supports directive parameters and modifiers
-(@code{:} and @code{@@} characters). Multiple parameters must be
-separated by a comma (@code{,}). Parameters can be numerical parameters
-(positive or negative), character parameters (prefixed by a quote
-character (@code{'}), variable parameters (@code{v}), number of rest
-arguments parameter (@code{#}), empty and default parameters. Directive
-characters are case independent. The general form of a directive
-is:@refill
-
-@noindent
-@var{directive} ::= ~@{@var{directive-parameter},@}[:][@@]@var{directive-character}
-
-@noindent
-@var{directive-parameter} ::= [ [-|+]@{0-9@}+ | '@var{character} | v | # ]
-
-
-@subsubsection Implemented CL Format Control Directives
-
-Documentation syntax: Uppercase characters represent the corresponding
-control directive characters. Lowercase characters represent control
-directive parameter descriptions.
-
-@table @asis
-@item @code{~A}
-Any (print as @code{display} does).
-@table @asis
-@item @code{~@@A}
-left pad.
-@item @code{~@var{mincol},@var{colinc},@var{minpad},@var{padchar}A}
-full padding.
-@end table
-@item @code{~S}
-S-expression (print as @code{write} does).
-@table @asis
-@item @code{~@@S}
-left pad.
-@item @code{~@var{mincol},@var{colinc},@var{minpad},@var{padchar}S}
-full padding.
-@end table
-@item @code{~D}
-Decimal.
-@table @asis
-@item @code{~@@D}
-print number sign always.
-@item @code{~:D}
-print comma separated.
-@item @code{~@var{mincol},@var{padchar},@var{commachar}D}
-padding.
-@end table
-@item @code{~X}
-Hexadecimal.
-@table @asis
-@item @code{~@@X}
-print number sign always.
-@item @code{~:X}
-print comma separated.
-@item @code{~@var{mincol},@var{padchar},@var{commachar}X}
-padding.
-@end table
-@item @code{~O}
-Octal.
-@table @asis
-@item @code{~@@O}
-print number sign always.
-@item @code{~:O}
-print comma separated.
-@item @code{~@var{mincol},@var{padchar},@var{commachar}O}
-padding.
-@end table
-@item @code{~B}
-Binary.
-@table @asis
-@item @code{~@@B}
-print number sign always.
-@item @code{~:B}
-print comma separated.
-@item @code{~@var{mincol},@var{padchar},@var{commachar}B}
-padding.
-@end table
-@item @code{~@var{n}R}
-Radix @var{n}.
-@table @asis
-@item @code{~@var{n},@var{mincol},@var{padchar},@var{commachar}R}
-padding.
-@end table
-@item @code{~@@R}
-print a number as a Roman numeral.
-@item @code{~:@@R}
-print a number as an ``old fashioned'' Roman numeral.
-@item @code{~:R}
-print a number as an ordinal English number.
-@item @code{~:@@R}
-print a number as a cardinal English number.
-@item @code{~P}
-Plural.
-@table @asis
-@item @code{~@@P}
-prints @code{y} and @code{ies}.
-@item @code{~:P}
-as @code{~P but jumps 1 argument backward.}
-@item @code{~:@@P}
-as @code{~@@P but jumps 1 argument backward.}
-@end table
-@item @code{~C}
-Character.
-@table @asis
-@item @code{~@@C}
-prints a character as the reader can understand it (i.e. @code{#\} prefixing).
-@item @code{~:C}
-prints a character as emacs does (eg. @code{^C} for ASCII 03).
-@end table
-@item @code{~F}
-Fixed-format floating-point (prints a flonum like @var{mmm.nnn}).
-@table @asis
-@item @code{~@var{width},@var{digits},@var{scale},@var{overflowchar},@var{padchar}F}
-@item @code{~@@F}
-If the number is positive a plus sign is printed.
-@end table
-@item @code{~E}
-Exponential floating-point (prints a flonum like @var{mmm.nnn}@code{E}@var{ee}).
-@table @asis
-@item @code{~@var{width},@var{digits},@var{exponentdigits},@var{scale},@var{overflowchar},@var{padchar},@var{exponentchar}E}
-@item @code{~@@E}
-If the number is positive a plus sign is printed.
-@end table
-@item @code{~G}
-General floating-point (prints a flonum either fixed or exponential).
-@table @asis
-@item @code{~@var{width},@var{digits},@var{exponentdigits},@var{scale},@var{overflowchar},@var{padchar},@var{exponentchar}G}
-@item @code{~@@G}
-If the number is positive a plus sign is printed.
-@end table
-@item @code{~$}
-Dollars floating-point (prints a flonum in fixed with signs separated).
-@table @asis
-@item @code{~@var{digits},@var{scale},@var{width},@var{padchar}$}
-@item @code{~@@$}
-If the number is positive a plus sign is printed.
-@item @code{~:@@$}
-A sign is always printed and appears before the padding.
-@item @code{~:$}
-The sign appears before the padding.
-@end table
-@item @code{~%}
-Newline.
-@table @asis
-@item @code{~@var{n}%}
-print @var{n} newlines.
-@end table
-@item @code{~&}
-print newline if not at the beginning of the output line.
-@table @asis
-@item @code{~@var{n}&}
-prints @code{~&} and then @var{n-1} newlines.
-@end table
-@item @code{~|}
-Page Separator.
-@table @asis
-@item @code{~@var{n}|}
-print @var{n} page separators.
-@end table
-@item @code{~~}
-Tilde.
-@table @asis
-@item @code{~@var{n}~}
-print @var{n} tildes.
-@end table
-@item @code{~}<newline>
-Continuation Line.
-@table @asis
-@item @code{~:}<newline>
-newline is ignored, white space left.
-@item @code{~@@}<newline>
-newline is left, white space ignored.
-@end table
-@item @code{~T}
-Tabulation.
-@table @asis
-@item @code{~@@T}
-relative tabulation.
-@item @code{~@var{colnum,colinc}T}
-full tabulation.
-@end table
-@item @code{~?}
-Indirection (expects indirect arguments as a list).
-@table @asis
-@item @code{~@@?}
-extracts indirect arguments from format arguments.
-@end table
-@item @code{~(@var{str}~)}
-Case conversion (converts by @code{string-downcase}).
-@table @asis
-@item @code{~:(@var{str}~)}
-converts by @code{string-capitalize}.
-@item @code{~@@(@var{str}~)}
-converts by @code{string-capitalize-first}.
-@item @code{~:@@(@var{str}~)}
-converts by @code{string-upcase}.
-@end table
-@item @code{~*}
-Argument Jumping (jumps 1 argument forward).
-@table @asis
-@item @code{~@var{n}*}
-jumps @var{n} arguments forward.
-@item @code{~:*}
-jumps 1 argument backward.
-@item @code{~@var{n}:*}
-jumps @var{n} arguments backward.
-@item @code{~@@*}
-jumps to the 0th argument.
-@item @code{~@var{n}@@*}
-jumps to the @var{n}th argument (beginning from 0)
-@end table
-@item @code{~[@var{str0}~;@var{str1}~;...~;@var{strn}~]}
-Conditional Expression (numerical clause conditional).
-@table @asis
-@item @code{~@var{n}[}
-take argument from @var{n}.
-@item @code{~@@[}
-true test conditional.
-@item @code{~:[}
-if-else-then conditional.
-@item @code{~;}
-clause separator.
-@item @code{~:;}
-default clause follows.
-@end table
-@item @code{~@{@var{str}~@}}
-Iteration (args come from the next argument (a list)).
-@table @asis
-@item @code{~@var{n}@{}
-at most @var{n} iterations.
-@item @code{~:@{}
-args from next arg (a list of lists).
-@item @code{~@@@{}
-args from the rest of arguments.
-@item @code{~:@@@{}
-args from the rest args (lists).
-@end table
-@item @code{~^}
-Up and out.
-@table @asis
-@item @code{~@var{n}^}
-aborts if @var{n} = 0
-@item @code{~@var{n},@var{m}^}
-aborts if @var{n} = @var{m}
-@item @code{~@var{n},@var{m},@var{k}^}
-aborts if @var{n} <= @var{m} <= @var{k}
-@end table
-@end table
-
-
-@subsubsection Not Implemented CL Format Control Directives
-
-@table @asis
-@item @code{~:A}
-print @code{#f} as an empty list (see below).
-@item @code{~:S}
-print @code{#f} as an empty list (see below).
-@item @code{~<~>}
-Justification.
-@item @code{~:^}
-(sorry I don't understand its semantics completely)
-@end table
-
-
-@subsubsection Extended, Replaced and Additional Control Directives
-
-@table @asis
-@item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}D}
-@item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}X}
-@item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}O}
-@item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}B}
-@item @code{~@var{n},@var{mincol},@var{padchar},@var{commachar},@var{commawidth}R}
-@var{commawidth} is the number of characters between two comma characters.
-@end table
-
-@table @asis
-@item @code{~I}
-print an R5RS complex number as @code{~F~@@Fi} with passed parameters for
-@code{~F}.
-@item @code{~Y}
-Pretty print formatting of an argument for scheme code lists.
-@item @code{~K}
-Same as @code{~?.}
-@item @code{~!}
-Flushes the output if format @var{destination} is a port.
-@item @code{~_}
-Print a @code{#\space} character
-@table @asis
-@item @code{~@var{n}_}
-print @var{n} @code{#\space} characters.
-@end table
-@item @code{~/}
-Print a @code{#\tab} character
-@table @asis
-@item @code{~@var{n}/}
-print @var{n} @code{#\tab} characters.
-@end table
-@item @code{~@var{n}C}
-Takes @var{n} as an integer representation for a character. No arguments
-are consumed. @var{n} is converted to a character by
-@code{integer->char}. @var{n} must be a positive decimal number.@refill
-@item @code{~:S}
-Print out readproof. Prints out internal objects represented as
-@code{#<...>} as strings @code{"#<...>"} so that the format output can always
-be processed by @code{read}.
-@refill
-@item @code{~:A}
-Print out readproof. Prints out internal objects represented as
-@code{#<...>} as strings @code{"#<...>"} so that the format output can always
-be processed by @code{read}.
-@item @code{~Q}
-Prints information and a copyright notice on the format implementation.
-@table @asis
-@item @code{~:Q}
-prints format version.
-@end table
-@refill
-@item @code{~F, ~E, ~G, ~$}
-may also print number strings, i.e. passing a number as a string and
-format it accordingly.
-@end table
-
-@subsubsection Configuration Variables
-
-Format has some configuration variables at the beginning of
-@file{format.scm} to suit the systems and users needs. There should be
-no modification necessary for the configuration that comes with SLIB.
-If modification is desired the variable should be set after the format
-code is loaded. Format detects automatically if the running scheme
-system implements floating point numbers and complex numbers.
-
-@table @asis
-
-@item @var{format:symbol-case-conv}
-Symbols are converted by @code{symbol->string} so the case type of the
-printed symbols is implementation dependent.
-@code{format:symbol-case-conv} is a one arg closure which is either
-@code{#f} (no conversion), @code{string-upcase}, @code{string-downcase}
-or @code{string-capitalize}. (default @code{#f})
-
-@item @var{format:iobj-case-conv}
-As @var{format:symbol-case-conv} but applies for the representation of
-implementation internal objects. (default @code{#f})
-
-@item @var{format:expch}
-The character prefixing the exponent value in @code{~E} printing. (default
-@code{#\E})
-
-@end table
-
-@subsubsection Compatibility With Other Format Implementations
-
-@table @asis
-@item SLIB format 2.x:
-See @file{format.doc}.
-
-@item SLIB format 1.4:
-Downward compatible except for padding support and @code{~A}, @code{~S},
-@code{~P}, @code{~X} uppercase printing. SLIB format 1.4 uses C-style
-@code{printf} padding support which is completely replaced by the CL
-@code{format} padding style.
-
-@item MIT C-Scheme 7.1:
-Downward compatible except for @code{~}, which is not documented
-(ignores all characters inside the format string up to a newline
-character). (7.1 implements @code{~a}, @code{~s},
-~@var{newline}, @code{~~}, @code{~%}, numerical and variable
-parameters and @code{:/@@} modifiers in the CL sense).@refill
-
-@item Elk 1.5/2.0:
-Downward compatible except for @code{~A} and @code{~S} which print in
-uppercase. (Elk implements @code{~a}, @code{~s}, @code{~~}, and
-@code{~%} (no directive parameters or modifiers)).@refill
-
-@item Scheme->C 01nov91:
-Downward compatible except for an optional destination parameter: S2C
-accepts a format call without a destination which returns a formatted
-string. This is equivalent to a #f destination in S2C. (S2C implements
-@code{~a}, @code{~s}, @code{~c}, @code{~%}, and @code{~~} (no directive
-parameters or modifiers)).@refill
-
-@end table
-
-This implementation of format is solely useful in the SLIB context
-because it requires other components provided by SLIB.@refill
diff --git a/doc/sources/guile-slib.texi b/doc/sources/guile-slib.texi
deleted file mode 100644
index c8f07d1b2..000000000
--- a/doc/sources/guile-slib.texi
+++ /dev/null
@@ -1,2 +0,0 @@
-@node Guile and SLIB
-@chapter Guile and SLIB
diff --git a/doc/sources/jimb-org.texi b/doc/sources/jimb-org.texi
deleted file mode 100644
index 5ec4216db..000000000
--- a/doc/sources/jimb-org.texi
+++ /dev/null
@@ -1,131 +0,0 @@
-@menu
-Preliminary
-
-* Introduction::
-* Using Guile::
-
-
-
-@bye
-
->You can actually put any English text to break up the menu, so you
->could put the "Part n" headings in it.
-
-
-
-Introduction
- --- Explains Guile's goals, and gives brief examples of how to use
- Guile interactively (show off repl), as a script interpreter,
- and as an embedded interpreter.
-
-Part I: Guile Scheme
- R4RS Scheme as a Starting Point
- --- Here we refer to R4RS, and explain that we're only
- describing differences.
- Block comments and interpreter triggers
- Symbol case
- Keywords
- Exceptions
- Modules
- --- the preceeding three come first, because we need them
- in order to explain the behavior of some things later
- Exception Handling
- --- mention that repls usually establish default exception handlers
- Dynamic Wind
- Records
- Structures
- Arrays
- Binary Numeric Operations
- Shared and Read-Only Strings
- Object Properties
- Association Lists and Hash Tables
- (Dictionaries In General)
- association lists
- hash tables (Hash Values)
- Input/Output ports
- file ports
- soft ports
- string ports
- extended I/O (fseek; line read/write)
- Garbage Collection
- Threads and Dynamic Roots
- Reflection
- eval
- Tag Values
- Weak references
- Regular Expressions
- SLIB
- POSIX system calls and networking
- --- I think people will generally know whether they're looking
- for a system call or not, so this should be an okay category.
- conventions (includes error handling)
- ports vs. file descriptors
- file system (mknod goes here, no?)
- user database
- time (includes gettimeofday or whatever, strftime, strptime)
- processes
- terminals and pseudo-terminals
- pipes
- networking (includes databases, address conversion, and sockets)
- system identification (uname)
- locales (setlocale)
- --- Note that there is no more 'misc'. It's better to have
- small sections than unhelpful names.
- SCSH
- --- includes info on how to get SCSH features (open this
- module), but mostly just a pointer to the SCSH manual.
- This should not be under POSIX. SCSH includes plenty of
- high-level stuff for starting processes and string
- processing. SCSH is not a subset of POSIX, nor the
- reverse.
- Tcl/Tk interface
- Module internals
- first-class variables
- first-class modules
- internal debugging interface
- --- The name of this chapter needs to clearly distinguish it
- from the appendix describing the debugger UI. The intro
- should have a pointer to the UI appendix.
-
-Part II: Using Scheme with C --- a Portable Interface
- --- We cover gh in a completely separate section. Why? I admit
- I'm on shaky ground, but here's my reasoning: People who want
- to write portable C code need to restrict themselves to only
- using GH, and GH's semantics are (necessarily) well-defined
- without reference to Guile's particulars. This makes life
- more difficult for folks who just prefer to use the GH
- interface when they can, but I really think the SCM interface
- is not so bad, once you're used to it. A *lot* of GH
- functions are just wrappers for SCM functions.
- --- We cover repls here too, since GH has repl functions.
-
-Part III: Using Scheme with C --- Guile's Interface
- Scheme data representation
- Relationship between Scheme and C functions
- --- this is where we explain that all the functions marked as
- "Primitive Functions" are also accessible from C, and how
- to derive the C interface given the Scheme interface, when
- we don't spell it out.
- ... I think there's other stuff needed here ...
- I/O internals
- linking Guile with your code
- --- Mark's "Tools to automate adding libraries" is not a
- well-defined concept. I think this is closer to what we
- want to cover for now.
- snarfing
-
-Appendices:
- Obtaining and Installing Guile
- Invoking Guile
- --- mentions read-eval-print loops
- --- both the SCSH and GAWK manuals relegate invocation details
- to an appendix. We can give examples in the introduction.
- debugger user interface
- --- The title and introduction of this appendix need to
- distinguish this clearly from the chapter on the internal
- debugging interface.
-
-Indices:
- --- At the top of the function/variable index, remind people
- to look for functions under their Scheme names as well as
- their C names.
diff --git a/doc/sources/libguile-overview.texi b/doc/sources/libguile-overview.texi
deleted file mode 100644
index 96a4a76ce..000000000
--- a/doc/sources/libguile-overview.texi
+++ /dev/null
@@ -1,30 +0,0 @@
-@node Libguile overview
-@chapter Libguile overview
-@cindex libguile - overview
-
-Extension languages, like Guile, Python and Tcl, can be embedded into a
-C program, @footnote{Or a C++ or Fortran or Pascal program if you want.}
-and thus allow the user to @emph{extend} the C program.
-
-The way this is done is by providing a C language library with a well
-defined interface. The interface consists of a set of public and
-documented C-callable routines that offer the full interpreter
-functionality, and allow the conversion of data between C and the
-extension language.
-
-@menu
-* An example of libguile functionality::
-* What can be done with libguile::
-* Schizofrenia -- two APIs::
-@end menu
-
-@node An example of libguile functionality
-@section An example of libguile functionality
-
-[Two examples: using strings and using data conversion.]
-
-@node What can be done with libguile
-@section What can be done with libguile
-
-@node Schizofrenia -- two APIs
-@section Schizofrenia -- two APIs
diff --git a/doc/sources/libguile-tools.texi b/doc/sources/libguile-tools.texi
deleted file mode 100644
index d434406e9..000000000
--- a/doc/sources/libguile-tools.texi
+++ /dev/null
@@ -1,191 +0,0 @@
-@node Tools to automate adding libraries
-@chapter Tools to automate adding libraries
-
-You want to ...
-
-The chapters @ref{Libguile -- high level interface} and @ref{Libguile --
-SCM interface} showed how to make C libraries available from Scheme.
-Here I will describe some automated tools that the Guile team has made
-available. Some have been written especially for Guile (the Guile Magic
-Snarfer), and some are also in use with other languages (Python, Perl,
-...)
-
-@menu
-* By hand with gh_::
-* By hand with Guile Magic Snarfer::
-* Automatically using libtool::
-* Automatically using SWIG::
-@end menu
-
-@node By hand with gh_
-@section By hand with gh_
-
-@node By hand with Guile Magic Snarfer
-@section By hand with Guile Magic Snarfer
-
-When writing C code for use with Guile, you typically define a set of C
-functions, and then make some of them visible to the Scheme world by
-calling the @code{scm_make_gsubr} function; a C functions published in
-this way is called a @dfn{subr}. If you have many subrs to publish, it
-can sometimes be annoying to keep the list of calls to
-@code{scm_make_gsubr} in sync with the list of function definitions.
-Frequently, a programmer will define a new subr in C, recompile his
-application, and then discover that the Scheme interpreter cannot see
-the subr, because he forgot to call @code{scm_make_gsubr}.
-
-Guile provides the @code{guile-snarf} command to manage this problem.
-Using this tool, you can keep all the information needed to define the
-subr alongside the function definition itself; @code{guile-snarf} will
-extract this information from your source code, and automatically
-generate a file of calls to @code{scm_make_gsubr} which you can
-@code{#include} into an initialization function. (The command name
-comes from the verb ``to snarf'', here meaning ``to unceremoniously
-extract information from a somewhat unwilling source.'')
-
-@menu
-* How guile-snarf works:: Using the @code{guile-snarf} command.
-* Macros guile-snarf recognizes:: How to mark up code for @code{guile-snarf}.
-@end menu
-
-@node How guile-snarf works
-@subsection How @code{guile-snarf} works
-
-For example, here is how you might define a new subr called
-@code{clear-image}, implemented by the C function @code{clear_image}:
-
-@example
-@group
-#include <libguile.h>
-
-@dots{}
-
-SCM_PROC (s_clear_image, "clear-image", 1, 0, 0, clear_image);
-
-SCM
-clear_image (SCM image_smob)
-@{
- @dots{}
-@}
-
-@dots{}
-
-void
-init_image_type ()
-@{
-#include "image-type.x"
-@}
-@end group
-@end example
-
-The @code{SCM_PROC} declaration says that the C function
-@code{clear_image} implements a Scheme subr called @code{clear-image},
-which takes one required argument, no optional arguments, and no tail
-argument. @code{SCM_PROC} also declares a static array of characters
-named @code{s_clear_image}, initialized to the string
-@code{"clear-image"}. The body of @code{clear_image} may use the array
-in error messages, instead of writing out the literal string; this may
-save string space on some systems.
-
-Assuming the text above lives in a file named @file{image-type.c}, you will
-need to execute the following command to compile this file:
-@example
-guile-snarf image-type.c > image-type.x
-@end example
-@noindent This scans @file{image-type.c} for @code{SCM_PROC}
-declarations, and sends the following output to the file
-@file{image-type.x}:
-@example
-scm_make_gsubr (s_clear_image, 1, 0, 0, clear_image);
-@end example
-When compiled normally, @code{SCM_PROC} is a macro which expands to a
-declaration of the @code{s_clear_image} string.
-
-In other words, @code{guile-snarf} scans source code looking for uses of
-the @code{SCM_PROC} macro, and generates C code to define the
-appropriate subrs. You need to provide all the same information you
-would if you were using @code{scm_make_gsubr} yourself, but you can
-place the information near the function definition itself, so it is less
-likely to become incorrect or out-of-date.
-
-If you have many files that @code{guile-snarf} must process, you should
-consider using a rule like the following in your Makefile:
-@example
-.SUFFIXES: .x
-.c.x:
- ./guile-snarf $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS) $< > $@
-@end example
-This tells make to run @code{guile-snarf} to produce each needed
-@file{.x} file from the corresponding @file{.c} file.
-
-@code{guile-snarf} passes all its command-line arguments directly to the
-C preprocessor, which it uses to extract the information it needs from
-the source code. this means you can pass normal compilation flags to
-@code{guile-snarf} to define preprocessor symbols, add header file
-directories, and so on.
-
-
-
-@node Macros guile-snarf recognizes
-@subsection Macros @code{guile-snarf} recognizes
-
-Here are the macros you can use in your source code from which
-@code{guile-snarf} can construct initialization code:
-
-
-@defmac SCM_PROC (@var{namestr}, @var{name}, @var{req}, @var{opt}, @var{tail}, @var{c_func})
-Declare a new Scheme primitive function, or @dfn{subr}. The new subr
-will be named @var{name} in Scheme code, and be implemented by the C
-function @var{c_func}. The subr will take @var{req} required arguments
-and @var{opt} optional arguments. If @var{tail} is non-zero, the
-function will accept any remaining arguments as a list.
-
-Use this macro outside all function bodies, preferably above the
-definition of @var{c_func} itself. When compiled, the @code{SCM_PROC}
-declaration will expand to a definition for the @var{namestr} array,
-initialized to @var{name}. The @code{guile-snarf} command uses this
-declaration to automatically generate initialization code to create the
-subr and bind it in the top-level environment. @xref{How guile-snarf
-works}, for more info.
-
-@xref{Subrs}, for details on argument passing and how to write
-@var{c_func}.
-@end defmac
-
-
-@defmac SCM_GLOBAL (@var{var}, @var{scheme_name})
-Declare a global Scheme variable named @var{scheme_name}, and a static C
-variable named @var{var} to point to it. The value of the Scheme
-variable lives in the @sc{cdr} of the cell @var{var} points to.
-Initialize the variable to @code{#f}.
-
-Use this macro outside all function bodies. When compiled, the
-@code{SCM_GLOBAL} macro will expand to a definition for the variable
-@var{var}, initialized to an innocuous value. The @code{guile-snarf}
-command will use this declaration to automatically generate code to
-create a global variable named @var{scheme_name}, and store a pointer to
-its cell in @var{var}.
-@end defmac
-
-
-@defmac SCM_CONST_LONG (@var{var}, @var{scheme_name}, @var{value})
-Like @code{SCM_GLOBAL}, but initialize the variable to @var{value},
-which must be an integer.
-@end defmac
-
-
-@defmac SCM_SYMBOL (@var{var}, @var{name})
-Declare a C variable of type @code{SCM} named @var{var}, and initialize
-it to the Scheme symbol object whose name is @var{name}.
-
-Use this macro outside all function bodies. When compiled, the
-@code{SCM_SYMBOL} macro will expand to a definition for the variable
-@var{var}, initialized to an innocuous value. The @code{guile-snarf}
-command will use this declaration to automatically generate code to
-create a symbol named @var{name}, and store it in @var{var}.
-@end defmac
-
-@node Automatically using libtool
-@section Automatically using libtool
-
-@node Automatically using SWIG
-@section Automatically using SWIG
diff --git a/doc/sources/new-types.texi b/doc/sources/new-types.texi
deleted file mode 100644
index 1840b214f..000000000
--- a/doc/sources/new-types.texi
+++ /dev/null
@@ -1,2 +0,0 @@
-@node Adding types to Guile
-@chapter Adding types to Guile
diff --git a/doc/sources/old-intro.texi b/doc/sources/old-intro.texi
deleted file mode 100644
index 0774f64d4..000000000
--- a/doc/sources/old-intro.texi
+++ /dev/null
@@ -1,290 +0,0 @@
-@node Introduction
-@chapter Introduction
-
-Guile is an interpreter for Scheme, a clean, economical programming
-language in the Lisp family. You can invoke Guile from the shell to
-evaluate Scheme expressions interactively, or use it as an interpreter
-for script files. However, Guile is also packaged as a library, to be
-embedded as an extension language into other applications. The
-application can supplement the base language with special-purpose
-functions and datatypes, allowing the user to customize and extend it by
-writing Scheme code.
-
-In its simplest form, Guile is an ordinary interpreter. The
-@code{guile} program can read and evaluate Scheme expressions entered
-from the terminal. Here is a sample interaction between Guile and a
-user; the user's input appears after the @code{$} and @code{guile>}
-prompts:
-
-@example
-$ guile
-guile> (+ 1 2 3) ; add some numbers
-6
-guile> (define (factorial n) ; define a function
- (if (zero? n) 1 (* n (factorial (- n 1)))))
-guile> (factorial 20)
-2432902008176640000
-guile> (getpwnam "jimb") ; find my entry in /etc/passwd
-#("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
- "/usr/local/bin/bash")
-guile> @kbd{C-d}
-$
-@end example
-
-Guile can also interpret script files. For example, here is a Guile script
-containing a script which displays the
-
-
-application can
-supplement the base language with its own functions, datatypes and
-syntax, allowing the user to extend and
-
-
- Guile interpret
-
-. An
-application the Guile interpreter to allow
-
-
-, allowing
-applications to incorporate the Scheme interpreter for customization
-
-[[interactive]]
-[[script interpreter]]
-[[embedded]]
-
-[[other languages]]
-The concept of an extension language library does not originate with
-Guile. However, Guile is the first to offer users a choice of languages
-to program in.
-
-
-Guile currently supports Scheme and Ctax , and we expect to support Emacs Lisp in the near future.
-
-
-Scheme is powerful enough that other languages can be
-conveniently translated into it,
-
-However, unlike other extension packages, Guile gives users a choice of
-languages to program in. Guile can
-
-
-In this sense, Guile resembles the Tcl and Python packages, providing
-both an ordinary interpreter and an extension language library.
-However, unlike those packages, Guile supports more than one programming
-language.
-
-; users can
-write Scheme code to control and customize applications which
-incorporate Guile
-
-, adding their own functions,
-datatypes, and syntax, to allow the user to programm
-
-
-link it into your own programs to make them
-
-
-
-Guile is a library containing an interpreter for Scheme, a complete but
-economical programming language, which the developer can customize to
-suit the application at hand by adding new functions, data types, and
-control structures. These may be implemented in C, and then
-``exported'' for use by the interpreted code. Because Guile already
-provides a full-featured interpreter, the developer need not neglect the
-language's design in order to concentrate on code relevant to the task.
-In this way, Guile provides a framework for the construction of
-domain-specific languages.
-
-Guile provides first-class functions, a rich set of data types,
-exception handling, a module system, and a powerful macro facility.
-Guile also supports dynamic linking and direct access to Unix system
-calls. Releases in the near future will support a source-level
-debugger and bindings for the Tk user interface toolkit.
-
-
-
-Guile is a framework for writing applications controlled by specialized
-languages. In its simplest form, Guile is an interpreter for Scheme, a
-clean, economical programming language in the Lisp family. However,
-Guile is packaged as a library, allowing applications to link against it
-and use Scheme as their extension language. The application can add
-primitive functions to the language, implement new data types, and even
-adjust the language's syntax.
-
-
-
-[the introduction is probably not what Jim has in mind; I just took the
-one I had in earlier, since the file had the same name intro.texi]
-
-Guile is an implementation of the Scheme programming language, but, like
-other modern implementations of Scheme, it adds many features that the
-community of Scheme programmers considers necessary for an ``industrial
-strength'' language.
-
-Examples of extensions to Scheme are the module system
-(@pxref{Modules}), the Unix system programming tools (@pxref{POSIX
-system calls and networking} and @pxref{The Scheme shell (scsh)}), an
-interface to @emph{libtool} to make it easier to add C libraries as
-primitives (@pxref{Linking Guile with your code}), and (FIXME add more).
-
-On top of these extensions, which many other Scheme implementations
-provide, Guile also offers the possibility of writing routines in other
-languages and running them simultaneously with Scheme. The desire to
-implement other languages (in particular Emacs Lisp) on top of Scheme is
-responsible for Guile's only deviation from the R4RS @footnote{R4RS is
-the Revised^4 Report on the Algorithmic Language Scheme, the closest
-thing to a standard Scheme specification today} Scheme standard
-(@cite{r4rs}): Guile is case sensitive, whereas ``standard'' Scheme is
-not.
-
-But even more fundamentally, Guile is meant to be an @emph{embeddable}
-Scheme interpreter. This means that a lot of work has gone into
-packaging the interpreter as a C library (@pxref{A Portable C to Scheme Interface} and @pxref{Scheme data representation}).
-
-This reference manual is mainly driven by the need to document all the
-features that go beyond standard Scheme.
-
-@menu
-* Getting started::
-* Guile feature list::
-* What you need to use Guile::
-* Roadmap to the Manual::
-* Motivation for Guile::
-* History of Guile::
-@end menu
-
-@node Getting started
-@section Getting started
-
-We assume that you know how to program in Scheme, although we do not
-assume advanced knowledge. If you don't know Scheme, there are many
-good books on Scheme at all levels, and the Guile Tutorial might give
-you a good enough feel for the language. We also assume that you know
-how to program in C, since there will be many examples of how to program
-in C using Guile as a library.
-
-Many diverse topics from the world of Unix hacking will be covered here,
-such as shared libraries, socket programming, garbage collection, and so
-forth. If at any time you feel you don't have enough background on a
-given topic, just go up a level or two in the manual, and you will find
-that the chapter begins with a few paragraphs that introduce the topic.
-If you are still lost, read through the Guile tutorial and then come
-back to this reference manual.
-
-To run the core Guile interpreter and extension library you need no more
-than a basically configured GNU/Unix system and the Guile sources. You
-should download and install the Guile sources (@pxref{Obtaining and
-Installing Guile}).
-
-
-@node Guile feature list
-@section Guile feature list
-
-In a reductionist view, Guile could be regarded as:
-@itemize @bullet
-@item
-An R4RS-compliant Scheme interpreter.
-
-@item
-Some Scheme features that go beyond the R4RS standard, notably a module
-system, exception handling primitives and an interface to Aubrey
-Jaffer's SLIB.
-
-@item
-A symbolic debugger for Scheme, and gdb extensions to facilitate
-debugging libguile programs.
-
-@item
-An embeddable version of the same interpreter, called @emph{libguile}.
-
-@item
-A portable high level API on top of libguile (the @code{gh_} interface).
-
-@item
-A collection of bundled C libraries with a Guile API. As we write, this
-list includes:
-
-@table @strong
-@item Rx
-a regular expression library.
-
-@item Unix
-a low-level interface to the POSIX system calls, socket library
-and other Unix system services.
-
-@item Tk
-an interface to John Ousterhout's Tk toolkit.
-
-@end table
-
-@item
-A set of tools for implementing other languages @emph{on top of Scheme},
-and an example implementation of a language called @emph{Ctax}.
-
-
-@end itemize
-
-
-@node What you need to use Guile
-@section What you need to use Guile
-
-
-@node Roadmap to the Manual
-@section Roadmap to the Manual
-
-@node Motivation for Guile
-@section Motivation for Guile
-
-@node History of Guile
-@section History of Guile
-
-@page
-@node Using Guile
-@chapter Using Guile
-
-[I think that this might go in the appendix in Jim's view of the manual]
-
-@page
-@node Invoking Guile
-@appendix Invoking Guile
- --- mentions read-eval-print loops
- --- both the SCSH and GAWK manuals relegate invocation details
- to an appendix. We can give examples in the introduction.
-
-@table @samp
-@item -h
-@itemx --help
-Display a helpful message.
-@item -v
-@item --version
-Display the current version.
-@item --emacs
-To be used for emacs editing support.
-@item -s @var{file}
-Process @var{file} as a script then quit. This is a terminating option:
-any further command line arguments can be accessed by the script using
-the @code{(program-arguments)} procedure.
-
-An executable script can start with the following:
-
-@smallexample
-#!/usr/bin/guile -s
-!#
-@end smallexample
-
-Note the @code{!#} token on the second line. It is very important
-to include this token when writing Guile scripts. Guile and SCSH,
-the Scheme shell, share the convention that @code{#!} and
-@code{!#} may be used to mark block comments (@pxref{Block
-comments and interpreter triggers}). If the closing @code{!#}
-token is not included, then Guile will consider the block comment
-to be unclosed, and the script will probably not compile
-correctly.
-
-It is also important to include the @samp{-s} option at the
-beginning of the Guile script, so that Guile knows not to behave
-in an interactive fashion.
-
-@end table
-
diff --git a/doc/sources/sample-APIs.texi b/doc/sources/sample-APIs.texi
deleted file mode 100644
index c8c4b8e72..000000000
--- a/doc/sources/sample-APIs.texi
+++ /dev/null
@@ -1,6 +0,0 @@
-@node Examples of adding libraries
-@chapter Examples of adding libraries
-
-Should contain examples of brute-force gh_, Guile magic snarfer,
-libtool, SWIG on a dummy API, followed by some real examples of how
-libraries are added.
diff --git a/doc/sources/scheme-concepts.texi b/doc/sources/scheme-concepts.texi
deleted file mode 100644
index e8e78f14d..000000000
--- a/doc/sources/scheme-concepts.texi
+++ /dev/null
@@ -1,249 +0,0 @@
-@node Guile Scheme concepts
-@chapter Guile Scheme concepts
-
-Most Scheme implementations go beyond what is specified in the R4RS
-document @footnote{Remember? R4RS is the Revised^4 report on the
-Algorithmic Language Scheme}, mostly because R4RS does not give
-specifications (or even recommendations) regarding some issues that are
-quite important in practical programming.
-
-Here is a list of how Guile implements some of these much-needed Scheme
-extensions; other Scheme implementations do so quite similarly.
-
-@menu
-* Scheme slang::
-* Read-eval-print loops::
-* Extra data types::
-* Miscellaneous features::
-@end menu
-
-@node Scheme slang
-@section Scheme slang
-@cindex slang
-
-Even if you read some of the nice books on Scheme, or the R4RS report,
-you might not find some of the terms frequently used by Scheme hackers,
-both in the manual and in the @url{news:comp.lang.scheme} newsgroup.
-
-Here is a glossary of some of the terms that make Scheme beginners and
-intermediate users say ``huh?''
-
-@table @strong
-@item thunk
-@cindex thunk
-A Scheme procedure that takes no arguments. In this example,
-@code{thunk} and @code{another-thunk} are both thunks:
-@lisp
-(define (thunk)
- (display "Dude, I'm a thunk!")
- (newline))
-(define another-thunk
- (lambda ()
- (display "Me too!\n")
- (newline)))
-@end lisp
-
-@item closure
-@cindex closure
-A closure is a procedure. However, the term emphasizes the fact that a
-Scheme procedure remembers (or @dfn{closes over}) the variables that
-were visible when the @code{lambda} expression was
-evaluated.
-
-In the example below, we might refer to @code{q} as a closure, because
-it has closed over the value of @code{x}:
-@lisp
-(define p
- (lambda (x)
- (lambda (y)
- (+ x y))))
-(define q (p 5.7))
-
-(q 10)
-@result{} 15.7
-@end lisp
-
-However, strictly speaking, every Scheme procedure is really a closure,
-since it closes over the top-level environment.
-
-@item alist
-@itemx association list
-
-@item plist
-@itemx property list
-
-@end table
-
-
-@node Read-eval-print loops
-@section Read-eval-print loops
-@cindex Read-eval-print loop
-@cindex REPL
-
-To explicitly mention the Scheme read-eval-print loop (REPL) seems weird
-because we are all accustomed to firing up an interpreter and having it
-read and execute commands.
-
-But the REPL is not specified in R4RS; rather, it is proposed by the
-Scheme Bible @cite{Structure and Interpretation of Computer Programs}
-(also known as @emph{SICP}), and implemented in some form in all Scheme
-interpreters.
-@cindex Structure and Interpretation of Computer Programs
-@cindex SICP
-
-[FIXME: Someone needs to tell me what needs to be said about Guile's
-REPL.]
-
-@node Extra data types
-@section Extra data types
-
-The fundamental Scheme data types specified in R4RS are @emph{numbers}
-(both exact and inexact), @emph{characters}, @emph{strings},
-@emph{symbols}, @emph{vectors}, @emph{pairs} and @emph{lists} [FIXME: is
-this complete?].
-
-Many Scheme interpreters offer more types, and Guile is no exception.
-Guile is based on Aubrey Jaffer's SCM interpreter, and thus inherits
-@emph{uniform arrays}, [FIXME: any others? How about records?].
-
-On top of that, Guile allows you to add extra types, but that is covered
-in @ref{Adding types to Guile}. Here I will simply document all the
-extra Scheme types shipped with Guile.
-
-@menu
-* Conventional arrays::
-* Uniform arrays::
-* Bit vectors::
-* Complex numbers::
-@end menu
-
-@node Conventional arrays
-@subsection Conventional arrays
-
-@node Uniform arrays
-@subsection Uniform arrays
-@cindex arrays - uniform
-
-The motivation for uniform arrays in Scheme is performance. A vector
-provides a performance increase over lists when you want a fixed-size
-indexable list. But the elements in a vector can be of different types,
-and this makes for larger storage requirements and slightly lower
-performance.
-
-A uniform array is similar to a vector, but all elements have to be of
-the same type.
-
-arrays, uniform arrays, bit vectors:
-
-@deffn procedure array-fill ra fill
-@end deffn
-@deffn procedure serial-array-copy! src dst
-@end deffn
-@deffn procedure serial-array-map ra0 proc [lra]
-@end deffn
-@deffn procedure array-map ra0 proc [lra]
-@end deffn
-@deffn procedure array-for-each proc ra0 [lra]
-@end deffn
-@deffn procedure array-index-map! ra proc
-@end deffn
-@deffn procedure array-copy! src dst
-@end deffn
-@deffn procedure array-copy! src dst
-@end deffn
-@deffn procedure array-copy! src dst
-@end deffn
-@deffn procedure array-copy! src dst
-@end deffn
-@deffn procedure array-copy! src dst
-@end deffn
-@deffn procedure array? ra [prot]
-@end deffn
-@deffn procedure array-rank ra
-@end deffn
-@deffn procedure array-dimensions ra
-@end deffn
-@deffn procedure dimensions->uniform-array dims prot fill ...
-@end deffn
-@deffn procedure make-shared-array ra mapfunc dims ...
-@end deffn
-@deffn procedure transpose-array arg ...
-@end deffn
-@deffn procedure enclose-array axes ...
-@end deffn
-@deffn procedure array-in-bounds? arg ...
-@end deffn
-@deffn procedure array-ref ra arg ..
-@end deffn
-@deffn procedure uniform-vector-ref vec pos
-@end deffn
-@deffn procedure array-set! ra obj arg ...
-@end deffn
-@deffn procedure uniform-array-set1! ua obj arg
-@end deffn
-@deffn procedure array-contents ra [strict]
-@end deffn
-@deffn procedure uniform-array-read! ra [port-or-fd] [start] [end]
-@end deffn
-@deffn procedure uniform-array-write! ra [port-or-fd] [start] [end]
-@end deffn
-@deffn procedure bit-count item seq
-@end deffn
-@deffn procedure bit-position item v k
-@end deffn
-@deffn procedure bit-set! v kv obj
-@end deffn
-@deffn procedure bit-count* v kv obj
-@end deffn
-@deffn procedure bit-invert v
-@end deffn
-@deffn procedure array->list ra
-@end deffn
-@deffn procedure list->uniform-array ndim prot list
-@end deffn
-@deffn procedure array-prototype ra
-@end deffn
-
-Unform arrays can be written and read, but @code{read} won't recognize
-them unless the optional @code{read-sharp} parameter is supplied,
-e.g,
-@smalllisp
-(read port #t read-sharp)
-@end smalllisp
-
-where @code{read-sharp} is the default procedure for parsing extended
-sharp notations.
-
-Reading an array is not very efficient at present, since it's implemented
-by reading a list and converting the list to an array.
-
-@c FIXME: must use @deftp, but its generation of TeX code is buggy.
-@c Must fix it when TeXinfo gets fixed.
-@deftp {Scheme type} {uniform array}
-
-@end deftp
-
-@node Bit vectors
-@subsection Bit vectors
-
-@node Complex numbers
-@subsection Complex numbers
-
-@c FIXME: must use @deftp, but its generation of TeX code is buggy.
-@c Must fix it when TeXinfo gets fixed.
-@deftp {Scheme type} complex
-Standard complex numbers.
-@end deftp
-
-@node Miscellaneous features
-@section Miscellaneous features
-
-@defun defined? symbol
-Returns @code{#t} if a symbol is bound to a value, @code{#f} otherwise.
-This kind of procedure is not specified in R4RS because @c FIXME: finish
-this thought
-@end defun
-
-@defun object-properties OBJ
-and so forth
-@end defun
diff --git a/doc/sources/scm-ref.texi b/doc/sources/scm-ref.texi
deleted file mode 100644
index eca672580..000000000
--- a/doc/sources/scm-ref.texi
+++ /dev/null
@@ -1,4 +0,0 @@
-@node Libguile -- SCM interface
-@chapter Libguile -- SCM interface
-
-
diff --git a/doc/sources/strings.texi b/doc/sources/strings.texi
deleted file mode 100644
index 9a1ddc952..000000000
--- a/doc/sources/strings.texi
+++ /dev/null
@@ -1,45 +0,0 @@
-@node Strings
-@chapter Facilities for string manipulation
-
-@deffn procedure string? string
-@end deffn
-@deffn procedure read-only-string? string
-@end deffn
-@deffn procedure list->string list
-@end deffn
-@deffn procedure make-string length [char]
-@end deffn
-@deffn procedure string-length string
-@end deffn
-@deffn procedure string-ref string [index]
-@end deffn
-@deffn procedure string-set! string index char
-@end deffn
-@deffn procedure substring string start [end]
-@end deffn
-@deffn procedure string-append arg ...
-@end deffn
-@deffn procedure make-shared-substring string [from] [to]
-@end deffn
-@deffn procedure string-set! string index char
-@end deffn
-@deffn procedure string-index string char [from] [to]
-@end deffn
-@deffn procedure string-rindex string char [from] [to]
-@end deffn
-@deffn procedure substring-move-left! string1 start1 [end1] [string2] [start2]
-@end deffn
-@deffn procedure substring-move-right! string1 start1 [end1] [string2] [start2]
-@end deffn
-@deffn procedure substring-fill! string start [end] [fill]
-@end deffn
-@deffn procedure string-null? string
-@end deffn
-@deffn procedure string->list string
-@end deffn
-@deffn procedure string-copy string
-@end deffn
-@deffn procedure string-upcase! string
-@end deffn
-@deffn procedure string-downcase! string
-@end deffn
diff --git a/doc/sources/tk.texi b/doc/sources/tk.texi
deleted file mode 100644
index 176c8c7b8..000000000
--- a/doc/sources/tk.texi
+++ /dev/null
@@ -1,5 +0,0 @@
-@node Tk interface
-@chapter Tk interface
-
-For now Guile has no well-specified Tk interface. It is an important part
-of Guile, though, and will be documented here when it is written.
diff --git a/doc/sources/unix-other.texi b/doc/sources/unix-other.texi
deleted file mode 100644
index 7b810d5d6..000000000
--- a/doc/sources/unix-other.texi
+++ /dev/null
@@ -1,132 +0,0 @@
-@node Other Unix
-@chapter Other Unix-specific facilities
-
-@menu
-* Expect:: Expect, for pattern matching from a port.
-@end menu
-
-@node Expect
-@section Expect: Pattern Matching from a Port
-
-@code{expect} is a macro for selecting actions based on the output from
-a port. The name comes from a tool of similar functionality by Don Libes.
-Actions can be taken when a particular string is matched, when a timeout
-occurs, or when end-of-file is seen on the port. The @code{expect} macro
-is described below; @code{expect-strings} is a front-end to @code{expect}
-based on regexec @xref{Regular expressions}.
-
-Using these macros requires for now:
-@smalllisp
-(load-from-path "ice-9/expect")
-@end smalllisp
-
-@defun expect-strings clause @dots{}
-By default, @code{expect-strings} will read from the current input port.
-The first term in each clause consists of an expression evaluating to
-a string pattern (regular expression). As characters
-are read one-by-one from the port, they are accumulated in a buffer string
-which is matched against each of the patterns. When a
-pattern matches, the remaining expression(s) in
-the clause are evaluated and the value of the last is returned. For example:
-
-@smalllisp
-(with-input-from-file "/etc/passwd"
- (lambda ()
- (expect-strings
- ("^nobody" (display "Got a nobody user.\n")
- (display "That's no problem.\n"))
- ("^daemon" (display "Got a daemon user.\n")))))
-@end smalllisp
-
-The regular expression is compiled with the @code{REG_NEWLINE} flag, so
-that the @code{^} and @code{$} anchors will match at any newline, not
-just at the start
-and end of the string.
-
-There are two other ways to write a clause:
-
-The expression(s) to evaluate on a match
-can be omitted, in which case the result of the match
-(converted to strings, as obtained from regexec with @var{match-pick}
-set to @code{""}) will be returned if the pattern matches.
-
-The symbol @code{=>} can be used to indicate that there is a single
-expression to evaluate on a match, which must be a
-procedure which will accept the result of a successful match (converted
-to strings, as obtained from regexec with @var{match-pick} set to
-@code{""}). E.g.,
-
-@smalllisp
-("^daemon" => write)
-("^d\\(aemon\\)" => (lambda args (map write args)))
-("^da\\(em\\)on" => (lambda (all sub)
- (write all)
- (write sub)))
-@end smalllisp
-
-The order of the substrings corresponds to the order in which the
-opening brackets occur in the regular expression.
-
-A number of variables can be used to control the behaviour
-of @code{expect} (and @code{expect-strings}).
-By default they are all bound at the top level to
-the value @code{#f}, which produces the default behaviour.
-They can be redefined at the
-top level or locally bound in a form enclosing the @code{expect} expression.
-
-@table @code
-@item expect-port
-A port to read characters from, instead of the current input port.
-@item expect-timeout
-@code{expect} will terminate after this number of
-seconds, returning @code{#f} or the value returned by
-@code{expect-timeout-proc}.
-@item expect-timeout-proc
-A procedure called if timeout occurs. The procedure takes a single argument:
-the accumulated string.
-@item expect-eof-proc
-A procedure called if end-of-file is detected on the input port. The
-procedure takes a single argument: the accumulated string.
-@item expect-char-proc
-A procedure to be called every time a character is read from the
-port. The procedure takes a single argument: the character which was read.
-@end table
-
-Here's an example using all of the variables:
-
-@smalllisp
-(let ((expect-port (open-input-file "/etc/passwd"))
- (expect-timeout 1)
- (expect-timeout-proc
- (lambda (s) (display "Times up!\n")))
- (expect-eof-proc
- (lambda (s) (display "Reached the end of the file!\n")))
- (expect-char-proc display))
- (expect-strings
- ("^nobody" (display "Got a nobody user\n"))))
-@end smalllisp
-@end defun
-
-@defun expect clause @dots{}
-@code{expect} is used in the same way as @code{expect-strings},
-but tests are specified not as patterns, but as procedures. The
-procedures are called in turn after each character is read from the
-port, with the value of the accumulated string as the argument. The
-test is successful if the procedure returns a non-false value.
-
-If the @code{=>} syntax is used, then if the test succeeds it must return
-a list containing the arguments to be provided to the corresponding
-expression.
-
-In the following example, a string will only be matched at the beginning
-of the file:
-@smalllisp
-(let ((expect-port (open-input-file "/etc/passwd")))
- (expect
- ((lambda (s) (string=? s "fnord!"))
- (display "Got a nobody user!\n"))))
-@end smalllisp
-
-The control variables described for @code{expect-strings} can also
-be used with @code{expect}.
-@end defun
diff --git a/doc/sources/unix.texi b/doc/sources/unix.texi
deleted file mode 100644
index e8a189c5b..000000000
--- a/doc/sources/unix.texi
+++ /dev/null
@@ -1,622 +0,0 @@
-@node Low level Unix
-@chapter Low level Unix interfaces
-
-The low level Unix interfaces are currently available by
-default in the Guile top level. However in the future they will probably
-be placed in a module and @code{use-modules} or something similar will
-be required to make them available.
-
-@menu
-* Unix conventions:: Conventions followed by the low level Unix
- interfaces.
-* Ports and descriptors:: Ports, file descriptors and how they
- interact.
-* Extended I/O:: Reading and writing to ports.
-* File system:: Working in a hierarchical filesystem.
-* User database:: Information about users from system databases.
-* Processes:: Information and control of Unix processes.
-* Terminals:: Terminals and pseudo-terminals.
-* Network databases:: Network address conversion and information
- from system databases.
-* Network sockets:: An interface to the BSD socket library.
-* Miscellaneous Unix:: Miscellaneous Unix interfaces.
-@end menu
-
-@node Unix conventions
-@section Low level Unix conventions
-
-The low-level interfaces are designed to give Scheme programs
-access to as much functionality as possible from the underlying
-Unix system. They can be used to implement higher level
-intefaces such as the Scheme shell @ref{scsh}.
-
-Generally there is a single procedure for each corresponding Unix
-facility. However some of the procedures are implemented for
-speed and convenience in Scheme and have no Unix equivalent
-(e.g., @code{read-delimited}, @code{copy-file}.)
-
-This interface is intended as far as possible to be portable across
-different versions of Unix, so that Scheme programmers don't need to be
-concerned with implementation differences. In some cases procedures
-which can't be implemented (or reimplemented) on particular systems may
-become no-ops, or perform limited actions. In other cases they may
-throw errors. It should be possible to use the feature system to
-determine what functionality is available.
-
-General naming conventions are as follows:
-
-@itemize @bullet
-@item
-The Scheme name is often identical to the name of the underlying Unix
-facility.
-@item
-Underscores in Unix names are converted to hyphens.
-@item
-Procedures which destructively modify Scheme data gain postpended
-exclaimation marks, e.g., @code{recv!}.
-@item
-Predicates are postpended with question marks, e.g., @code{access?}.
-@item
-Some names are changed to avoid conflict with dissimilar interfaces
-defined by scsh.
-@item
-Unix preprocessor names such as @code{EPERM} or @code{R_OK} are converted
-to Scheme variables of the same name (underscores are not replaced
-with hyphens)
-@end itemize
-
-Most of the Unix interface procedures can be relied on to return a
-well-specified value. Unexpected conditions are handled by raising
-exceptions.
-
-There are a few procedures which return a special
-value if they don't succeed, e.g., @code{getenv} returns @code{#f}
-if it the requested string is not found in the environment. These
-cases will be noted in the documentation.
-
-For ways to deal with exceptions, @ref{Exceptions}.
-
-Errors which the C-library would report by returning a NULL
-pointer or through some other means cause a @code{system-error} exception
-to be raised. The value of the Unix @code{errno} variable is available
-in the data passed by the exception, so there is no need to access the
-global errno value (doing so would be unreliable in the presence of
-continuations or multiple threads).
-
-@deffn procedure errno [n]
-@end deffn
-@deffn procedure perror string
-@end deffn
-
-@node Ports and descriptors
-@section Ports and file descriptors
-
-@deffn procedure move->fdes port fd
-@end deffn
-@deffn procedure release-port-handle port
-@end deffn
-@deffn procedure set-port-revealed! @var{port} count
-@end deffn
-@deffn procedure fdes->ports fdes
-@end deffn
-@deffn procedure fileno port
-@end deffn
-@deffn procedure fdopen fdes modes
-@end deffn
-@deffn procedure duplicate-port port modes
-@end deffn
-@deffn procedure redirect-port into-port from-port
-@end deffn
-@deffn procedure freopen filename modes port
-@end deffn
-
-@node Extended I/O
-@section Extended I/O
-
-Extended I/O procedures are available which read or write lines of text,
-read text delimited by a specified set of characters, or report or
-set the current position of a port.
-
-@findex fwrite
-@findex fread
-Interfaces to @code{read}/@code{fread} and @code{write}/@code{fwrite} are
-also available, as @code{uniform-array-read!} and @code{uniform-array-write!},
-@ref{Uniform arrays}.
-
-@deffn procedure read-line [port] [handle-delim]
-Return a line of text from @var{port} if specified, otherwise from the
-value returned by @code{(current-input-port)}. Under Unix, a line of text
-is terminated by the first end-of-line character or by end-of-file.
-
-If @var{handle-delim} is specified, it should be one of the following
-symbols:
-@table @code
-@item trim
-Discard the terminating delimiter. This is the default, but it will
-be impossible to tell whether the read terminated with a delimiter or
-end-of-file.
-@item concat
-Append the terminating delimiter (if any) to the returned string.
-@item peek
-Push the terminating delimiter (if any) back on to the port.
-@item split
-Return a pair containing the string read from the port and the
-terminating delimiter or end-of-file object.
-
-NOTE: if the scsh module is loaded then
-multiple values are returned instead of a pair.
-@end table
-@end deffn
-@deffn procedure read-line! buf [port]
-Read a line of text into the supplied string @var{buf} and return the
-number of characters added to @var{buf}. If @var{buf} is filled, then
-@code{#f} is returned.
-Read from @var{port} if
-specified, otherwise from the value returned by @code{(current-input-port)}.
-@end deffn
-@deffn procedure read-delimited delims [port] [handle-delim]
-Read text until one of the characters in the string @var{delims} is found
-or end-of-file is reached. Read from @var{port} if supplied, otherwise
-from the value returned by @code{(current-input-port)}.
-@var{handle-delim} takes the same values as described for @code{read-line}.
-
-NOTE: if the scsh module is loaded then @var{delims} must be an scsh
-char-set, not a string.
-@end deffn
-@deffn procedure read-delimited! delims buf [port] [handle-delim] [start] [end]
-Read text into the supplied string @var{buf} and return the number of
-characters added to @var{buf} (subject to @var{handle-delim}, which takes
-the same values specified for @code{read-line}. If @var{buf} is filled,
-@code{#f} is returned for both the number of characters read and the
-delimiter. Also terminates if one of the characters in the string
-@var{delims} is found
-or end-of-file is reached. Read from @var{port} if supplied, otherwise
-from the value returned by @code{(current-input-port)}.
-
-NOTE: if the scsh module is loaded then @var{delims} must be an scsh
-char-set, not a string.
-@end deffn
-@deffn procedure write-line obj [port]
-Display @var{obj} and a new-line character to @var{port} if specified,
-otherwise to the
-value returned by @code{(current-output-port)}; equivalent to:
-
-@smalllisp
-(display obj [port])
-(newline [port])
-@end smalllisp
-@end deffn
-@deffn procedure ftell port
-Returns an integer representing the current position of @var{port},
-measured from the beginning.
-@end deffn
-@deffn procedure fseek port offset whence
-Sets the current position of @var{port} to the integer @var{offset},
-which is interpreted according to the value of @var{whence}.
-
-One of the following variables should be supplied
-for @var{whence}:
-@defvar SEEK_SET
-Seek from the beginning of the file.
-@end defvar
-@defvar SEEK_CUR
-Seek from the current position.
-@end defvar
-@defvar SEEK_END
-Seek from the end of the file.
-@end defvar
-@end deffn
-
-@node File system
-@section File system
-
-These procedures query and set file system attributes (such as owner,
-permissions, sizes and types of files); deleting, copying, renaming and
-linking files; creating and removing directories and querying their
-contents; and the @code{sync} interface.
-
-@deffn procedure access? path how
-Evaluates to @code{#t} if @var{path} corresponds to an existing
-file and the current process
-has the type of access specified by @var{how}, otherwise
-@code{#f}.
-@var{how} should be specified
-using the values of the variables listed below. Multiple values can
-be combined using a bitwise or, in which case @code{#t} will only
-be returned if all accesses are granted.
-
-Permissions are checked using the real id of the current process,
-not the effective id, although it's the effective id which determines
-whether the access would actually be granted.
-
-@defvar R_OK
-test for read permission.
-@end defvar
-@defvar W_OK
-test for write permission.
-@end defvar
-@defvar X_OK
-test for execute permission.
-@end defvar
-@defvar F_OK
-test for existence of the file.
-@end defvar
-@end deffn
-@findex fstat
-@deffn procedure stat obj
-Evaluates to an object containing various information
-about the file determined by @var{obj}.
-@var{obj} can be a string containing a file name or a port or file
-descriptor which is open on a file (in which case @code{fstat} is used
-as the underlying system call).
-
-The object returned by @code{stat} can be passed as a single parameter
-to the following procedures, all of which return integers:
-
-@table @r
-@item stat:dev
-The device containing the file.
-@item stat:ino
-The file serial number, which distinguishes this file from all other
-files on the same device.
-@item stat:mode
-The mode of the file. This includes file type information
-and the file permission bits. See @code{stat:type} and @code{stat:perms}
-below.
-@item stat:nlink
-The number of hard links to the file.
-@item stat:uid
-The user ID of the file's owner.
-@item stat:gid
-The group ID of the file.
-@item stat:rdev
-Device ID; this entry is defined only for character or block
-special files.
-@item stat:size
-The size of a regular file in bytes.
-@item stat:atime
-The last access time for the file.
-@item stat:mtime
-The last modification time for the file.
-@item stat:ctime
-The last modification time for the attributes of the file.
-@item stat:blksize
-The optimal block size for reading or writing the file, in bytes.
-@item stat:blocks
-The amount of disk space that the file occupies measured in units of
-512 byte blocks.
-@end table
-
-In addition, the following procedures return the information
-from stat:mode in a more convenient form:
-
-@table @r
-@item stat:type
-A symbol representing the type of file. Possible values are
-currently: regular, directory, symlink, block-special, char-special,
-fifo, socket, unknown
-@item stat:perms
-An integer representing the access permission bits.
-@end table
-@end deffn
-@deffn procedure lstat path
-Similar to @code{stat}, but does not follow symbolic links, i.e.,
-it will return information about a symbolic link itself, not the
-file it points to. @var{path} must be a string.
-@end deffn
-@deffn procedure readlink path
-@end deffn
-@deffn procedure chown path owner group
-@end deffn
-@deffn procedure chmod port-or-path mode
-@end deffn
-@deffn procedure utime path [actime] [modtime]
-@end deffn
-@deffn procedure delete-file path
-@end deffn
-@deffn procedure copy-file path-from path-to
-@end deffn
-@deffn procedure rename-file path-from path-to
-@end deffn
-@deffn procedure link path-from path-to
-@end deffn
-@deffn procedure symlink path-from path-to
-@end deffn
-@deffn procedure mkdir path [mode]
-@end deffn
-@deffn procedure rmdir path
-@end deffn
-@deffn procedure opendir path
-@end deffn
-@deffn procedure readdir port
-@end deffn
-@deffn procedure rewinddir port
-@end deffn
-@deffn procedure closedir port
-@end deffn
-@deffn procedure sync
-@end deffn
-
-@node User database
-@section User database
-
-@deffn procedure getpwuid uid
-@end deffn
-@deffn procedure getpwnam name
-@end deffn
-@deffn procedure getpwent
-@end deffn
-@deffn procedure setpwent port
-@end deffn
-@deffn procedure endpwent
-@end deffn
-@deffn procedure getgrgid uid
-@end deffn
-@deffn procedure getgrnam name
-@end deffn
-@deffn procedure getgrent
-@end deffn
-@deffn procedure setgrent port
-@end deffn
-@deffn procedure endgrent
-@end deffn
-
-@node Processes
-@section Processes
-
-@deffn procedure chdir path
-@end deffn
-@deffn procedure getcwd
-@end deffn
-@deffn procedure umask [mode]
-@end deffn
-@deffn procedure getpid
-@end deffn
-@deffn procedure getgroups
-@end deffn
-@deffn procedure kill pid sig
-
-@var{sig} should be specified using a variable corresponding to
-the Unix symbolic name, e.g,
-@defvar SIGHUP
-Hang-up signal.
-@end defvar
-@defvar SIGINT
-Interrupt signal.
-@end defvar
-@end deffn
-@deffn procedure waitpid pid options
-@defvar WAIT_ANY
-@end defvar
-@defvar WAIT_MYPGRP
-@end defvar
-@defvar WNOHANG
-@end defvar
-@defvar WUNTRACED
-@end defvar
-@end deffn
-@deffn procedure getppid
-@end deffn
-@deffn procedure getuid
-@end deffn
-@deffn procedure getgid
-@end deffn
-@deffn procedure geteuid
-@end deffn
-@deffn procedure getegid
-@end deffn
-@deffn procedure setuid id
-@end deffn
-@deffn procedure setgid id
-@end deffn
-@deffn procedure seteuid id
-@end deffn
-@deffn procedure setegid id
-@end deffn
-@deffn procedure getpgrp
-@end deffn
-@deffn procedure setpgid pid pgid
-@end deffn
-@deffn procedure setsid
-@end deffn
-@deffn procedure execl arg ...
-@end deffn
-@deffn procedure execlp arg ...
-@end deffn
-@deffn procedure primitive-fork
-@end deffn
-@deffn procedure environ [env]
-@end deffn
-@deffn procedure putenv string
-@end deffn
-@deffn procedure nice incr
-@end deffn
-
-@node Terminals
-@section Terminals and pseudo-terminals
-
-@deffn procedure isatty? port
-@end deffn
-@deffn procedure ttyname port
-@end deffn
-@deffn procedure ctermid
-@end deffn
-@deffn procedure tcgetpgrp port
-@end deffn
-@deffn procedure tcsetpgrp port pgid
-@end deffn
-
-@node Network databases
-@section Network address conversion and system databases
-
-@deffn procedure inet-aton address
-@end deffn
-@deffn procedure inet-ntoa number
-@end deffn
-@deffn procedure inet-netof address
-@end deffn
-@deffn procedure inet-lnaof address
-@end deffn
-@deffn procedure inet-makeaddr net lna
-@end deffn
-@deffn procedure gethostbyname name
-@end deffn
-@deffn procedure gethostbyaddr address
-@end deffn
-@deffn procedure gethostent
-@end deffn
-@deffn procedure sethostent port
-@end deffn
-@deffn procedure endhostent
-@end deffn
-@deffn procedure getnetbyname name
-@end deffn
-@deffn procedure getnetbyaddr address
-@end deffn
-@deffn procedure getnetent
-@end deffn
-@deffn procedure setnetent port
-@end deffn
-@deffn procedure endnetent
-@end deffn
-@deffn procedure getprotobyname name
-@end deffn
-@deffn procedure getprotobynumber number
-@end deffn
-@deffn procedure getprotoent
-@end deffn
-@deffn procedure setprotoent port
-@end deffn
-@deffn procedure endprotoent
-@end deffn
-@deffn procedure getservbyname name protocol
-@end deffn
-@deffn procedure getservbyport port protocol
-@end deffn
-@deffn procedure getservent
-@end deffn
-@deffn procedure setservent port
-@end deffn
-@deffn procedure endservent
-@end deffn
-
-@node Network sockets
-@section BSD socket library interface
-
-@deffn procedure socket family style protocol
-@end deffn
-@deffn procedure socketpair family style protocol
-@end deffn
-@deffn procedure getsockopt socket level optname
-@end deffn
-@deffn procedure setsockopt socket level optname value
-@end deffn
-@deffn procedure shutdown socket how
-@end deffn
-@deffn procedure connect socket family address arg ...
-@end deffn
-@deffn procedure bind socket family address arg ...
-@end deffn
-@deffn procedure listen socket backlog
-@end deffn
-@deffn procedure accept socket
-@end deffn
-@deffn procedure getsockname socket
-@end deffn
-@deffn procedure getpeername socket
-@end deffn
-@deffn procedure recv! socket buf [flags]
-@end deffn
-@deffn procedure send socket message [flags]
-@end deffn
-@deffn procedure recvfrom! socket buf [flags] [start] [end]
-@end deffn
-@deffn procedure sendto socket message family address args ... [flags]
-@end deffn
-
-@node Miscellaneous Unix
-@section Miscellaneous Unix interfaces
-
-Things which haven't been classified elsewhere (yet?).
-
-@deffn procedure open path flags [mode]
-@defvar O_RDONLY
-@end defvar
-@defvar O_WRONLY
-@end defvar
-@defvar O_RDWR
-@end defvar
-@defvar O_CREAT
-@end defvar
-@defvar O_EXCL
-@end defvar
-@defvar O_NOCTTY
-@end defvar
-@defvar O_TRUNC
-@end defvar
-@defvar O_APPEND
-@end defvar
-@defvar O_NONBLOCK
-@end defvar
-@defvar O_NDELAY
-@end defvar
-@defvar O_SYNC
-@end defvar
-@end deffn
-@deffn procedure select reads writes excepts secs msecs
-@end deffn
-@deffn procedure uname
-@end deffn
-@deffn procedure pipe
-@end deffn
-@deffn procedure open-pipe command modes
-@end deffn
-@deffn procedure open-input-pipe command
-@end deffn
-@deffn procedure open-output-pipe command
-@end deffn
-@deffn procedure setlocale category [locale]
-@defvar LC_COLLATE
-@end defvar
-@defvar LC_CTYPE
-@end defvar
-@defvar LC_MONETARY
-@end defvar
-@defvar LC_NUMERIC
-@end defvar
-@defvar LC_TIME
-@end defvar
-@defvar LC_MESSAGES
-@end defvar
-@defvar LC_ALL
-@end defvar
-@end deffn
-@deffn procedure strftime format stime
-@end deffn
-@deffn procedure strptime format string
-@end deffn
-@deffn procedure mknod
-@end deffn
-
-@node scsh
-@chapter The Scheme shell (scsh)
-
-Guile includes an incomplete port of the Scheme shell (scsh) 0.4.4.
-
-For information about scsh on the Web see
-@url{http://www-swiss.ai.mit.edu/scsh/scsh.html}.
-The original scsh is available by ftp from
-@url{ftp://swiss-ftp.ai.mit.edu:/pub/su}.
-
-This port of scsh does not currently use the Guile module system, but
-can be initialized using:
-@smalllisp
-(load-from-path "scsh/init")
-@end smalllisp
-
-Note that SLIB must be installed before scsh can be initialized, see
-@ref{SLIB} for details.
-
-@node Threads
-@chapter Programming Threads.
-
diff --git a/doc/tutorial/.cvsignore b/doc/tutorial/.cvsignore
deleted file mode 100644
index cda758436..000000000
--- a/doc/tutorial/.cvsignore
+++ /dev/null
@@ -1,22 +0,0 @@
-Makefile
-Makefile.in
-stamp-vti
-stamp-vti.1
-*.log
-*.dvi
-*.aux
-*.toc
-*.cp
-*.fn
-*.vr
-*.tp
-*.ky
-*.pg
-*.cps
-*.fns
-*.tps
-*.vrs
-*.ps
-*.info*
-*.html
-version.texi
diff --git a/doc/tutorial/ChangeLog b/doc/tutorial/ChangeLog
deleted file mode 100644
index b24d6004f..000000000
--- a/doc/tutorial/ChangeLog
+++ /dev/null
@@ -1,34 +0,0 @@
-2002-07-16 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile-tut.texi (Jump Start): Apply patch from M. Luedde on use
- of tail recursion to avoid stack overflow (with minor editing).
-
-2002-07-14 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile-tut.texi (Jump Start):
- (Jump Start):
-
-2001-11-18 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile-tut.texi (History of Guile and its motivations): Update
- Tcl war URLs.
-
-2001-09-19 Thien-Thi Nguyen <ttn@glug.org>
-
- * guile-tut.texi: Fix improper `@result' usage.
- Fix number typo in "Jump Start" section.
-
-2001-08-27 Neil Jerram <neil@ossau.uklinux.net>
-
- * Makefile.am (guile_tut_TEXINFOS): Removed.
- (TEXINFO_TEX): Added; avoids shipping multiple copies of
- texinfo.tex in a single distribution.
-
- * guile-tut.texi: Incorporate text previously in separate AUTHORS
- file.
-
-2001-08-27 Neil Jerram <neil@ossau.uklinux.net>
-
- The change log for files in this directory continues backwards
- from 2001-08-27 in ../ChangeLog, as all the Guile documentation
- prior to this date was contained in a single directory.
diff --git a/doc/tutorial/ChangeLog-guile-doc-tutorial b/doc/tutorial/ChangeLog-guile-doc-tutorial
deleted file mode 100644
index 9d7233a31..000000000
--- a/doc/tutorial/ChangeLog-guile-doc-tutorial
+++ /dev/null
@@ -1,16 +0,0 @@
-2001-01-27 Neil Jerram <neil@ossau.uklinux.net>
-
- * texinfo.tex: Replaced by latest version from ftp.gnu.org.
-
-1999-12-06 Gary Houston <ghouston@freewire.co.uk>
-
- * guile-tut.texi: tweaked the dircategory.
-
-1998-01-28 Mark Galassi <rosalia@nis.lanl.gov>
-
- * guile-tut.texi: set @dircategory to "Scheme Programming".
-
-Mon Aug 18 16:11:43 1997 Jim Blandy <jimb@totoro.red-bean.com>
-
- * texinfo.tex: Installed from texinfo release 3.11.
-
diff --git a/doc/tutorial/Makefile.am b/doc/tutorial/Makefile.am
deleted file mode 100644
index 4f9a6658f..000000000
--- a/doc/tutorial/Makefile.am
+++ /dev/null
@@ -1,39 +0,0 @@
-## Process this file with Automake to create Makefile.in
-##
-## Copyright (C) 1998 Free Software Foundation, Inc.
-##
-## This file is part of GUILE.
-##
-## GUILE 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 2, or
-## (at your option) any later version.
-##
-## GUILE 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 GUILE; see the file COPYING. If not, write
-## to the Free Software Foundation, Inc., 59 Temple Place, Suite
-## 330, Boston, MA 02111-1307 USA
-
-AUTOMAKE_OPTIONS = gnu
-
-info_TEXINFOS = guile-tut.texi
-
-TEXINFO_TEX = ../ref/texinfo.tex
-
-# Optionally support building an HTML version of the reference manual.
-
-if HTMLDOC
-
-htmldir = $(prefix)/html/guile-$(VERSION)
-
-html_DATA = guile-tut_toc.html $(shell ls guile-tut_*.html 2>/dev/null)
-
-guile-tut_toc.html: guile-tut.texi
- $(TEXI2HTML) -split_chapter guile-tut.texi
-
-endif
diff --git a/doc/tutorial/guile-tut.texi b/doc/tutorial/guile-tut.texi
deleted file mode 100644
index e73f9b248..000000000
--- a/doc/tutorial/guile-tut.texi
+++ /dev/null
@@ -1,1373 +0,0 @@
-\input texinfo @c -*-texinfo-*-
-@c %**start of header
-@setfilename guile-tut.info
-@settitle Guile Tutorial
-@set guile-tut
-
-@include version.texi
-
-@dircategory The Algorithmic Language Scheme
-@direntry
-* Guile Tutorial: (guile-tut). The Guile tutorial.
-@end direntry
-
-@setchapternewpage off
-@c Choices for setchapternewpage are {on,off,odd}.
-@paragraphindent 2
-@c %**end of header
-
-@iftex
-@finalout
-@c DL: lose the egregious vertical whitespace, esp. around examples
-@c but paras in @defun-like things don't have parindent
-@parskip 4pt plus 1pt
-@end iftex
-
-@titlepage
-@title Guile Tutorial
-@subtitle For use with Guile @value{VERSION}
-@subtitle Last updated @value{UPDATED}
-
-@author Mark Galassi
-@author Cygnus Solutions and Los Alamos National Laboratory
-@author @email{rosalia@@nis.lanl.gov}
-
-@page
-@vskip 0pt plus 1filll
-Copyright @copyright{} 1997, 1998 Free Software Foundation
-
-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.
-@end titlepage
-
-
-@ifinfo
-@node Top
-@top Guile Tutorial
-@end ifinfo
-
-@ifinfo
-This file gives a tutorial introductionto Guile.
-
-Copyright (C) 1997 Free Software Foundation
-
-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.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-
-@end ignore
-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.
-@end ifinfo
-
-
-@menu
-* Jump Start::
-* Introduction::
-* Using Guile to program in Scheme::
-* Guile in a Library::
-* Regular Expression Support::
-* UNIX System Programming::
-* Where to find more Guile/Scheme resources::
-* Concept Index::
-* Procedure and Macro Index::
-* Variable Index::
-* Type Index::
-@end menu
-
-
-@node Jump Start
-@chapter Jump Start
-
-@noindent
-Before giving an overview of Guile, I present some simple commands and
-programs that you can type to get going immediately.
-
-Start by invoking the Guile interpreter. Usually you do this by just
-typing @code{guile}. Then type (or paste) the following expressions at
-the prompt; the interpreter's response is preceded (in this manual) by
-@result{}.
-
-@example
-<shell-prompt> guile
-@end example
-@lisp
-(+ 20 35)
-@result{} 55
-(define (recursive-factorial n)
- (if (zero? n)
- 1
- (* n (recursive-factorial (- n 1)))))
-(recursive-factorial 5)
-@result{} 120
-(quit)
-@end lisp
-
-In this example we did some simple arithmetic @code{(+ 20 35)} and got
-the answer @code{55}. Then we coded the classic (and rather wasteful)
-factorial algorithm and computed the factorial of @code{55}. Finally we
-quit with @code{(quit)}.
-
-@cindex bignumbers
-We can find out about some of Scheme's nice features by asking for the
-factorial of some big number, say @code{500}. On some systems the
-correct answer will be returned (I do not indicate calling and leaving
-the guile session anymore).
-
-@lisp
-(recursive-factorial 500)
-@result{} 1220136825991110068701238785423046926253574342803192842192413588
- 3858453731538819976054964475022032818630136164771482035841633787
- 2207817720048078520515932928547790757193933060377296085908627042
- 9174547882424912726344305670173270769461062802310452644218878789
- 4657547771498634943677810376442740338273653974713864778784954384
- 8959553753799042324106127132698432774571554630997720278101456108
- 1188373709531016356324432987029563896628911658974769572087926928
- 8712817800702651745077684107196243903943225364226052349458501299
- 1857150124870696156814162535905669342381300885624924689156412677
- 5654481886506593847951775360894005745238940335798476363944905313
- 0623237490664450488246650759467358620746379251842004593696929810
- 2226397195259719094521782333175693458150855233282076282002340262
- 6907898342451712006207714640979456116127629145951237229913340169
- 5523638509428855920187274337951730145863575708283557801587354327
- 6888868012039988238470215146760544540766353598417443048012893831
- 3896881639487469658817504506926365338175055478128640000000000000
- 0000000000000000000000000000000000000000000000000000000000000000
- 00000000000000000000000000000000000000000000000
-@end lisp
-
-The result is an example of Scheme's @emph{bignumbers}. However, there
-are operating environments that provide (by default) too little stack
-space. They will instead produce an error message like this:
-
-@lisp
-(recursive-factorial 500)
-@print{}
-ERROR: Stack overflow
-ABORT: (stack-overflow)
-@end lisp
-
-Rather than enlarging the system's stack, we can implement the algorithm
-such that it does not consume increasing stack space. This is called a
-@emph{tail recursive} implementation. The following definition is tail
-recursive and so should work on all systems.
-
-@lisp
-(define (tail-recursive-factorial n)
- (define (loop k l)
- (if (zero? k) l
- (loop (- k 1) (* k l))))
- (loop n 1))
-
-(tail-recursive-factorial 500)
-@result{} 1220136825991110068701238785423046926253574342803192842192413588
- ;; ... skipped
-@end lisp
-
-This is the most basic use of Guile: a simple Scheme interpreter. In
-the rest of this tutorial I will show you how Guile has many facets: it
-is also an @emph{extensible} interpreter (to which many features can be
-easilly added) and an @emph{embeddable} interpreter (which can be
-invoked from your C programs).
-
-
-@node Introduction
-@chapter Introduction
-
-@noindent
-@dfn{Guile} (which can stand for @emph{GNU Ubiquitous Intelligent
-Language Extension}) is the GNU extension language. It started out as
-an embeddable Scheme interpreter, and has rapidly evolved into a
-kitchen-sink package including a standalone Scheme interpreter, an
-embeddable Scheme interpreter, several graphics options, other languages
-that can be used along with Scheme (for now just @emph{ctax} and
-@emph{Tcl}), and hooks for much more.
-
-
-@menu
-* What are scripting and extension languages::
-* History of Guile and its motivations::
-* How to characterize Guile::
-@end menu
-
-@node What are scripting and extension languages
-@section What are scripting and extension languages
-@cindex scripting languages
-@cindex extension languages
-
-A @dfn{scripting language} is a programming language which serves as
-glue between other system programs. In the UNIX world, the traditional
-scripting language is the @emph{Bourne shell}, which allows many UNIX
-commands to be executed in sequence, or in a pipeline. Traditional UNIX
-commands are cleverly written to work well when put together in a
-script.
-
-Other examples of UNIX scripting languages are AWK, Perl, Scsh (the
-Scheme Shell: a Scheme interpreter enhanced to do good scripting),
-Python, Tcl, Java @dots{}
-@cindex scripting languages - examples
-
-UNIX programmers noticed, more than 25 years ago, that scripting
-languages can do serious work, so the Bourne shell was written to have
-variables, operators and control structures, just like a full-featured
-programming language.
-@cindex Bourne shell
-
-What scripting languages have, that traditional programming languages do
-not, is the ability to easily run an external program (or a pipeline of
-external programs) and use the returned values and output from that
-program in useful ways.
-
-An @dfn{extension language} is a programming language interpreter
-offered by an application program, so that users can write macros or
-even full-fledged programs to extend the original application.
-Extension languages have a C interface (it is usually C, but it could be
-any other compiled language), and can be given access to the C data
-structures. Likewise, there are C routines to access the extension
-language data structures.
-
-Extension languages abound in the software world, even though the name
-@emph{extension language} is seldom used. Examples are:
-@cindex extension languages - examples
-
-@itemize @bullet
-@item
-Emacs Lisp, the language used to program and customize GNU Emacs.
-@cindex Emacs Lisp
-
-@item
-Tcl, John Ousterhout's general-purpose scripting and extension language.
-@cindex Tcl
-
-@item
-The Lotus 1-2-3 macro language (any spreadsheet macro language,
-really). I mention this one first because it is a classic, even though
-it is seldom used any more.
-@cindex Lotus 1-2-3
-
-@item
-Other spreadsheet and database macro languages.
-
-@item
-The Dominion empire-style game's @emph{exec} files.
-@cindex Dominion
-
-@item
-Any syntax for a ".*rc" file you might have used. Almost all programs
-end up parsing some kind of startup or configuration file. The syntax
-for those can get pretty involved, thus justifying calling them
-"extension languages". The @emph{fvwm} window manager, for example,
-parses a rather elaborate @file{.fvwmrc} file.
-
-@item
-Brent Benson's libscheme.a, an embeddable Scheme interpreter.
-@cindex Benson, Brent
-@cindex libscheme
-
-@item
-Guile, the GNU extension language, which is the subject of this
-tutorial.
-
-@end itemize
-
-One lesson we can learn from looking at classical large software
-applications is that "writers of large programs" always end up throwing
-in some kind of parser for configuration or scripting.
-
-Of the examples listed above, Emacs Lisp, Tcl, Libscheme and Guile have
-an important property: they are not added as an afterthought for a
-specific application. They are general-purpose languages which a user
-can learn (even in college courses) and then use to customize the
-application program.
-
-This is a recent and (in my opinion) very exciting direction in
-large-program software engineering: program designers can link in the
-Guile or Tcl library from the very beginning, and tell their users "You
-want to customize this program? Just use Scheme (or Tcl, or whatever
-language), which you already know!"
-@cindex large programs
-
-
-@node History of Guile and its motivations
-@section History of Guile and its motivations
-
-A few separate threads of events led to the development of Guile.
-
-In the fall of 1994, Richard Stallman, director of the GNU project,
-posted an article with the subject "Why you should not use Tcl", in
-which he argued that Tcl is inadequate as an extension language. This
-generated a flurry of flames (available in the hypermail archive
-(@url{http://www.vanderburg.org/Tcl/war/}) @strong{The Tcl War}).
-@cindex Stallman, Richard
-@cindex GNU project
-@cindex Tcl
-
-The result was that Stallman then proposed his design for the GNU
-Extension Language, first called GEL and then renamed Guile. The
-discussion triggered by that article is also available in a hypermail
-archive, @url{http://www.vanderburg.org/Tcl/war2/}.
-
-One interesting feature of this GNU Extension Language plan was that
-users should have a @emph{choice} of languages to use in extending their
-program. The basic language would be a slightly modified Scheme, and
-translators would be written to convert other languages (like Tcl,
-Python, Perl, C-like languages @dots{}) into Scheme.
-
-Tom Lord started working on this project immediately, taking Aubrey
-Jaffer's small and portable implementation of Scheme, SCM, and making it
-into an embeddable interpreter: callable from C and allowing new Scheme
-procedures to be written in C.
-@cindex Lord, Tom
-@cindex Jaffer, Aubrey
-
-In the spring of 1995, the guile-ii snapshot was released. This made it
-possible to start writing code in C and Scheme using the guile
-facilities.
-
-The guile-iii snapshot was released the summer of 1995, and it had fixed
-enough problems so that the access to Scheme data structures from C was
-almost complete.
-
-After this, Cygnus Support added many features to Guile and finished
-implementing others, so that Guile acquired thread support, a regular
-expression matcher, a Tk interface, an interface to the SGI OpenGL
-graphics system, an @emph{applet} formalism, and some other packages.
-This was all in the Cygnus Guile r0.3 and r0.4 releases.
-@cindex Cygnus Support
-
-Meanwhile, Tom Lord left the project after having produced a divergent
-version of Guile: 1.0b2. The Free Software Foundation hired Jim Blandy
-to coordinate Guile development. The FSF released its first version of
-Guile in January 1997. In the future, many of the Cygnus packages will
-be re-integrated into Guile.
-@cindex Blandy, Jim
-@cindex Free Software Foundation
-
-
-
-@node How to characterize Guile
-@section How to characterize Guile
-
-I have already mentioned that Guile has become a kitchen sink package;
-here you can see how Guile freely takes new commands and constructs from
-the portable Scheme library @emph{slib}, the @emph{Tk} widget set, a
-posix library (useful for UNIX systems programming), the regular
-expression library @emph{rx}, and many more @dots{}
-@cindex slib
-@cindex Tk
-@cindex POSIX
-@c @cindex OpenGL
-@cindex rx
-
-So Guile has many more primitive procedures available to it than those
-specified in @ref{Standard Procedures, Revised(5) Report on the
-Algorithmic Language Scheme, , r5rs, Revised(5) Report on the
-Algorithmic Language Scheme}. On top of that, Guile will interpret
-almost all standard Scheme programs. The only incompatible difference
-between the basic Guile language and R5RS Scheme is that Guile is case
-sensitive, whereas R5RS is case insensitive. We hope that few people
-have written Scheme programs that depend on case insensitivity.
-@cindex case sensitivity
-@cindex Revised(5) Report on the Algorithmic Language Scheme
-@cindex report on Scheme
-@cindex Scheme language - report
-@cindex Scheme language - definition
-
-Here is a possible view of the @emph{sum of the parts} in Guile:
-@cindex extensions to standard Scheme
-@cindex extensions to R5RS
-@cindex Scheme extensions
-@example
-guile = standard Scheme (R5RS)
- PLUS extensions to R5RS offered by SCM
- PLUS some extra primitives offered by Guile (catch/throw)
- PLUS portable Scheme library (SLIB)
- PLUS embeddable Scheme interpreter library (libguile)
- PLUS Tk toolkit
- PLUS threads
- PLUS Posix library
-@c PLUS OpenGL library (mesa)
-@c PLUS OpenGL toolkit (glut)
- PLUS Regular expression library (rx)
-@c PLUS Applet formalism
- PLUS Tcl library
-@end example
-
-
-@node Using Guile to program in Scheme
-@chapter Using Guile to program in Scheme
-@cindex Scheme programming tutorial
-@cindex tutorial on Scheme programming
-
-In this section I give a tutorial introduction to programming in Scheme,
-with a slant toward the interesting things that can be done in Guile.
-
-@c Applets are so @emph{chic} that they get their own section, but this
-This section will try to touch on many of the interesting and cool
-aspects of Guile, showing you how new types of problems can be solved
-with Guile. Note that using Guile as a library with @code{libguile.a}
-is described in its own chapter (@pxref{Guile in a Library}). Also note
-that some small examples are given in @ref{Jump Start}.
-
-To get started you need to know how to program in @dfn{Scheme} (a
-dialect of LISP). Fortunately Scheme is a small, clean language and is
-not hard to learn. It is also used in many undergraduate courses to
-introduce computer programming.
-@cindex lisp dialects
-
-I will not try to teach you Scheme here (although you might end up
-learning by example), since there are many good books on the subject,
-listed in @ref{Where to find more Guile/Scheme resources}. @footnote{To
-get started, look at the books @cite{Simply Scheme} and @cite{The Little
-Schemer} from that list.}
-
-
-@subsection Hello World
-@cindex hello world
-
-Our first program is the typical Scheme "hello world" program. Put the
-following code in a file called @code{hello.scm} (this can be find in
-@file{examples/scheme/hello.scm}).
-
-@smalllisp
-#!/usr/local/bin/guile -s
-!#
-
-(display "hello world")
-(newline)
-@end smalllisp
-
-Then run guile on it. One way to do so is to start up guile and load
-this file:
-
-@smallexample
-<shell-prompt> @kbd{guile}
-guile> @kbd{(load "hello")}
-@end smallexample
-
-Another way is to make the file executable and execute it directly.
-Notice how Guile recognizes a @code{-s} option which tells it to run a
-script and then exit. Guile also has a new type of block comment
-enclosed by @code{#!} and @code{!#}, so that you can make executable
-Scheme scripts with the standard UNIX @code{#!} mechanism.
-
-In the given example, the first line is used to invoke the Guile
-interpreter (make sure you correct the path if you installed Guile in
-something other than /usr/local/bin). Once Guile is invoked on this
-file, it will understand that the first line is a comment. The comment
-is then terminated with @code{!#} on the second line so as to not
-interfere with the execution mechanism.
-
-
-@subsection A bunch of operations in Scheme
-
-Here is some code you can type at the @code{guile>} prompt to see some
-of the Scheme data types at work (mostly lists and vectors). I have
-inserted brief comments @emph{before} each line of code explaining what
-happens.
-
-@smalllisp
-;; @r{make a list and bind it to the symbol @code{ls}}
-guile> @kbd{(define ls (list 1 2 3 4 5 6 7))}
- @result{}
-;; @r{display the list}
-guile> @kbd{ls}
- @result{} (1 2 3 4 5 6 7)
-;; @r{ask if @code{ls} is a vector; @code{#f} means it is not}
-guile> @kbd{(vector? ls)}
- @result{} #f
-;; @r{ask if @code{ls} is a list; @code{#t} means it is}
-guile> @kbd{(list? ls)}
- @result{} #t
-;; @r{ask for the length of @code{ls}}
-guile> @kbd{(length ls)}
- @result{} 7
-;; @r{pick out the first element of the list}
-guile> @kbd{(car ls)}
- @result{} 1
-;; @r{pick the rest of the list without the first element}
-guile> @kbd{(cdr ls)}
- @result{} (2 3 4 5 6 7)
-;; @r{this should pick out the 3rd element of the list}
-guile> @kbd{(car (cdr (cdr ls)))}
- @result{} 3
-;; @r{a shorthand for doing the same thing}
-guile> @kbd{(caddr ls)}
- @result{} 3
-;; @r{append the given list onto @code{ls}, print the result}
-;; @r{@strong{NOTE:} the original list @code{ls} is @emph{not} modified}
-guile> @kbd{(append ls (list 8 9 10))}
- @result{} (1 2 3 4 5 6 7 8 9 10)
-guile> @kbd{(reverse ls)}
- @result{} (10 9 8 7 6 5 4 3 2 1)
-;; @r{ask if 12 is in the list --- it obviously is not}
-guile> @kbd{(memq 12 ls)}
- @result{} #f
-;; @r{ask if 4 is in the list --- returns the list from 4 on.}
-;; @r{Notice that the result will behave as true in conditionals}
-guile> @kbd{(memq 4 ls)}
- @result{} (4 5 6 7)
-;; @r{an @code{if} statement using the aforementioned result}
-guile> @kbd{(if (memq 4 ls)
- (display "hey, it's true!\n")
- (display "dude, it's false\n"))}
- @print{hey, it's true!}
- @result{}
-guile> @kbd{(if (memq 12 ls)
- (display "hey, it's true!\n")
- (display "dude, it's false\n"))}
- @print{dude, it's false}
- @result{}
-guile> @kbd{(memq 4 (reverse ls))}
- @result{} (4 3 2 1)
-;; @r{make a smaller list @code{ls2} to work with}
-guile> @kbd{(define ls2 (list 2 3 4))}
-;; @r{make a list in which the function @code{sin} has been}
-;; @r{applied to all elements of @code{ls2}}
-guile> @kbd{(map sin ls2)}
- @result{} (0.909297426825682 0.141120008059867 -0.756802495307928)
-;; @r{make a list in which the squaring function has been}
-;; @r{applied to all elements of @code{ls}}
-guile> @kbd{(map (lambda (n) (expt n n)) ls)}
- @result{} (1 4 27 256 3125 46656 823543)
-@end smalllisp
-
-@smalllisp
-;; @r{make a vector and bind it to the symbol @code{v}}
-guile> @kbd{(define v #(1 2 3 4 5 6 7))}
-guile> @kbd{v}
- @result{} #(1 2 3 4 5 6 7)
-guile> @kbd{(vector? v)}
- @result{} #t
-guile> @kbd{(list? v)}
- @result{} #f
-guile> @kbd{(vector-length v)}
- @result{} 7
-;; @r{vector-ref allows you to pick out elements by index}
-guile> @kbd{(vector-ref v 2)}
- @result{} 3
-;; @r{play around with the vector: make it into a list, reverse}
-;; @r{the list, go back to a vector and take the second element}
-guile> @kbd{(vector-ref (list->vector (reverse (vector->list v))) 2)}
- @result{} 5
-;; @r{this demonstrates that the entries in a vector do not have}
-;; @r{to be of uniform type}
-guile> @kbd{(vector-set! v 4 "hi there")}
- @result{} "hi there"
-guile> @kbd{v}
- @result{} #(1 2 3 4 "hi there" 6 7)
-@end smalllisp
-
-
-@subsection Using recursion to process lists
-@cindex recursion
-@cindex list processing
-
-Here are some typical examples of using recursion to process a list.
-
-@smalllisp
-;; @r{this is a rather trivial way of reversing a list}
-(define (my-reverse l)
- (if (null? l)
- l
- (append (my-reverse (cdr l)) (list (car l)))))
-(my-reverse '(27 32 33 40))
-@result{} (40 33 32 27)
-@end smalllisp
-
-
-@subsection Processing matrices
-
-Suppose you have a matrix represented as a list of lists:
-
-@smalllisp
-(define m
- (list
- (list 7 2 1 3 2 8 5 3 6)
- (list 4 1 1 1 3 8 9 8 1)
- (list 5 5 4 8 1 8 2 2 4)))
-@end smalllisp
-
-Then you could apply a certain function to each element of the matrix in
-the following manner:
-@smalllisp
-;; @r{apply the function func to the matrix m element-by-element;}
-;; @r{return a matrix with the result.}
-(define (process-matrix m func)
- (map (lambda (l)
- (map func l))
- m))
-@end smalllisp
-Notice that I have used the Scheme @code{map} procedure because I am
-interested in the matrix that results from the application of
-@code{func}, rather than in the side effects associated with applying
-@code{func}.
-
-This could be invoked with @code{(process-matrix m sin)} or
-@code{(process-matrix m (lambda (x) (* x x)))}; for example:
-
-@smalllisp
-(process-matrix m (lambda (x) (* x x)))
-@result{} ((49 4 1 9 4 64 25 9 36) (16 1 1 1 9 64 81 64 1) (25 25 16 64 1 64 4 4 16))
-@end smalllisp
-
-To print a representation of the matrix, we could define a generalized
-routine:
-@smalllisp
-;; @r{proc is a procedure to represent the single element,}
-;; @r{row-proc is a procedure that is invoked after each row.}
-;; @r{Example: proc could be (lambda (x) (begin (display x) (display " ")))}
-;; @r{and row-proc could be (lambda (l) (display "\n"))}
-(define (represent-matrix m proc row-proc)
- (for-each (lambda (l)
- (begin
- (for-each proc l)
- (row-proc l)))
- m))
-@end smalllisp
-@findex represent-matrix
-
-And then invoke it with
-@smalllisp
-(represent-matrix m
- (lambda (x) (begin (display x) (display " ")))
- (lambda (l) (begin (display "\n"))))
-@print{7 2 1 3 2 8 5 3 6}
-@print{4 1 1 1 3 8 9 8 1}
-@print{5 5 4 8 1 8 2 2 4}
-@end smalllisp
-
-@cindex objects
-
-Now we write a helper routine that uses Scheme @dfn{closures} to make
-objects with state that then receive messages to draw little squares.
-@cindex closures
-@cindex syntactic closures
-
-But let us take it one step at a time. I will start by showing you a
-simple example of object in Scheme. The object I make here represents a
-cell, which could be a cell in a matrix. The cell responds to commands
-to draw itself, to return the next cell, and so forth. @emph{Guile does
-not currently have a Tk interface, so I will leave the hooks for
-graphical rendering. In a future release of Guile I will add graphical
-rendering messages to the cell object.}
-
-@smallexample
-;; @r{cell-object.scm: routines for creating and manipulating cell objects}
-
-;; @r{(the-x, the-y) is the initial position of the cell.}
-;; @r{the-color is a string representing a color; must be something Tk can grok.}
-;; @r{square-size is the size of the square that gets drawn.}
-;; @r{(sizex, sizey) is the size of the matrix.}
-(define (MAKE-CELL the-x the-y the-color square-size sizex sizey)
- (define (get-x) the-x)
- (define (get-y) the-y)
-
- (define (set-x! new-x)
- (set! the-x new-x)
- the-x)
- (define (set-y! new-y)
- (set! the-y new-y)
- the-y)
- (define (get-color) the-color)
- (define (set-color! new-color)
- (set! the-color new-color)
- the-color)
- (define (next!)
- (set! the-x (+ the-x 1))
- (if (>= the-x sizex)
- (begin
- (set! the-x 0)
- (set! the-y (+ the-y 1))))
- (if (>= the-y sizey)
- (begin
- (display "CELL next!: value of y is too big; not changing it\n")
- (set! the-y (- the-y 1))))
- (cons the-x the-y))
- (define (draw)
- (let* ((x0 (* the-x square-size))
- (y0 (* the-y square-size))
- (x1 (+ x0 square-size))
- (y1 (+ y0 square-size)))
- (display "I should draw a ")
- (display the-color)
- (display " rectangle with corners at ")
- (display x0) (display y0) (display x1) (display y1)
- ))
-
- ;; self is the dispatch procedure
- (define (self message)
- (case message
- ((x) get-x)
- ((y) get-y)
- ((set-x!) set-x!)
- ((set-y!) set-y!)
- ((color) get-color)
- ((set-color!) set-color!)
- ((next!) next!)
- ((draw) draw)
- (else (error "CELL: Unknown message -> " message))))
- ;; and now return the dispatch procedure
- self
- )
-@end smallexample
-@cindex cell-object
-@findex MAKE-CELL
-
-What does this procedure do? It returns another procedure
-(@code{self}) which receives a message (x, y, set-x!, set-y!, @dots{})
-and takes an action to return or modify its state. The state consists
-of the values of variables @code{the-x}, @code{the-y}, @code{the-color}
-and so forth.
-
-Here are some examples of how to use MAKE-CELL and the cell object it
-creates:
-@smallexample
-(define c (MAKE-CELL 0 0 "red" 10 7 9))
-
-;; @r{retrieve the x and y coordinates}
-((c 'x))
-@result{} 0
-((c 'y))
-@result{} 0
-;; @r{change the x coordinate}
-((c 'set-x!) 5)
-@result{} 5
-((c 'x))
-@result{} 5
-;; @r{change the color}
-((c 'color))
-@result{} "red"
-((c 'set-color!) "green")
-@result{} "green"
-((c 'color))
-@result{} "green"
-;; @r{now use the next! message to move to the next cell}
-((c 'next!))
-@result{} (6 . 0)
-((c 'x))
-@result{} 6
-((c 'y))
-@result{} 0
-;; @r{now make things wrap around}
-((c 'next!))
-@result{} (0 . 1)
-((c 'next!))
-@result{} (1 . 1)
-((c 'next!))
-@result{} (2 . 1)
-((c 'x))
-@result{} 2
-((c 'y))
-@result{} 1
-@end smallexample
-
-You will notice that expressions like @code{(c 'next)} return procedures
-that do the job, so we have to use extra parentheses to make the job
-happen. This syntax is rather awkward; one way around it is to define a
-@code{send} procedure:
-
-@smallexample
-;; @r{send makes object syntax a bit easier; instead of saying}
-;; @r{ ((my-cell 'set-x!) 4)}
-;; @r{you can say}
-;; @r{ (send my-cell 'set-x! 4)}
-(define (send obj . args)
- (let ((first-eval (apply obj (list (car args)))))
- (if (null? (cdr args))
- (first-eval)
- (apply first-eval (cdr args)))))
-@end smallexample
-@findex send
-
-You can see that @code{send} passes the message to the object, making
-sure that things are evaluated the proper number of times. You can now
-type:
-
-@smallexample
-(define c2 (MAKE-CELL 0 0 "red" 10 7 9))
-(send c2 'x)
-@result{} 0
-(send c2 'set-x! 5)
-@result{} 5
-(send c2 'color)
-@result{} "red"
-(send c2 'set-color! "green")
-@result{} "green"
-(send c2 'next!)
-@result{} (1 . 0)
-(send c2 'x)
-@result{} 1
-(send c2 'y)
-@result{} 0
-@end smallexample
-
-@cindex object-based programming
-@cindex object-oriented programming
-
-This is the simplest way of implementing objects in Scheme, but it does
-not really allow for full @emph{object-oriented programming} (for
-example, there is no inheritance). But it is useful for
-@emph{object-based programming}.
-
-Guile comes with a couple more complete object-oriented extensions to
-Scheme: these are part of slib (@pxref{Object, , , slib, SLIB: the
-portable Scheme library} and @pxref{Yasos, , , slib, SLIB: the portable
-Scheme library}).
-
-@node Guile in a Library
-@chapter Guile in a Library
-
-@iftex
-@nobreak
-@end iftex
-In the previous chapters Guile was used to write programs entirely in
-Scheme, and no C code was seen; but I have been claiming @emph{ad
-nauseam} that Guile is an @emph{extension} language. Here we see how
-that is done, and how that can be useful.
-@cindex libguile
-@cindex extending C programs
-
-
-@menu
-* Two world views::
-* What is libguile::
-* How to get started with libguile::
-* More interesting programming with libguile::
-* Further examples::
-@end menu
-
-@node Two world views
-@section Two world views
-@cindex master world
-
-In this manual, I usually jump into examples and explain them as you
-type in the code; here I will digress and ramble for a few paragraphs to
-set some concepts straight, and then let you type (or paste) in fun
-examples.
-
-In 1995, I implemented a large program, @dfn{Gnudl}, using Guile quite
-extensively. In the design phase of Gnudl, I found I had to make a
-choice: should the fundamental data structures be C or Scheme data
-structures?
-@cindex gnudl
-@cindex GNU Data Language
-@cindex Galassi, Mark
-
-Guile allows C to see its data structures (scalar types, lists, vectors,
-strings @dots{}). C also allows Guile to see its data structures. As a
-large program designer, you have to decide which of those capabilities
-to use. You have two main choices:
-
-@enumerate 1
-@item
-You can write your software mostly in Scheme. In this case, your C
-software will mostly parse the Scheme code with Guile calls, and provide
-some new primitive procedures to be used by Scheme. This is what Gnudl
-does.
-
-@item
-You can write your software mostly in C, occasionally allowing Scheme
-code to be parsed by Guile, either to allow the user to modify data
-structures, or to parse a configuration file, @dots{}
-@end enumerate
-
-Mixing the two approaches seems unwise: the overall layout would be
-confusing. But who knows? There might be problems that are best solved
-by a hybrid approach. Please let me know if you think of such a
-problem.
-
-If you use the former approach, we will say that the @dfn{master world}
-is Scheme, and the C routines serve Scheme and access Scheme data
-structures. In the latter case, the master world is C, and Scheme
-routines serve the C code and access C data structures.
-
-In both approaches the @code{libguile.a} library is the same, but a
-predominantly different set of routines will be used. When we go
-through examples of libguile use, we will point out which is the master
-world in order to clarify these two approaches.
-
-
-@node What is libguile
-@section What is libguile
-@cindex libguile
-@cindex gh interface
-@cindex scm interface
-
-@dfn{Libguile} is the library which allows C programs to start a Scheme
-interpreter and execute Scheme code. There are also facilities in
-libguile to make C data structures available to Scheme, and vice versa.
-
-The interface provided by the libguile C library is somewhat specific to
-the implementation of the Scheme interpreter. This low-level libguile
-interface is usually referred to as the @code{scm_} interface, since its
-public calls (API) all have the @code{scm_} prefix.
-
-There is also a higher-level libguile interface, which is usually
-referred to as the @code{gh_} interface (libGuile High). Its public
-calls all have the @code{gh_} prefix. The @code{gh_} library interface
-is designed to hide the implementation details, thus making it easier to
-assimilate and portable to other underlying Scheme implementations.
-
-People extending Guile by adding bindings to C libraries (like OpenGL or
-Rx) are encouraged to use the @code{gh_} interface, so their work will
-be portable to other Scheme systems. The @code{gh_} interface should be
-more stable, because it is simpler.
-
-The @code{scm_} interface is necessary if you want to poke into the
-innards of Scheme data structures, or do anything else that is not
-offered by the @code{gh_} interface. It is not covered in this
-tutorial, but is covered extensively in @ref{Scheme data representation,
-Guile Reference Manual, guile-ref, Guile Reference Manual}.
-
-This chapter gives a gentle introduction to the @code{gh_} interface,
-presenting some @emph{hello world}-style programs which I wrote while
-teaching myself to use libguile.
-@cindex hello world
-
-The @cite{Guile Programmer's Manual} gives more examples of programs
-written using libguile, illustrating diverse applications. You can also
-consult my @emph{Gnudl} documentation at
-@url{http://nis-www.lanl.gov/~rosalia/mydocs/} to see a large scale
-project that uses C and Scheme code together.
-
-
-@node How to get started with libguile
-@section How to get started with libguile
-@cindex learn0
-
-Here is an elementary first program, @code{learn0}, to get going with
-libguile. The program (which uses Scheme as a master world) is in a
-single source file, @code{learn0.c}:
-
-@smallexample
-/* @r{test the new libgh.a (Guile High-level library) with a trivial
- program} */
-
-#include <stdio.h>
-
-#include <guile/gh.h>
-
-void main_prog(int argc, char *argv[]);
-
-main(int argc, char *argv[])
-@{
- gh_enter(argc, argv, main_prog);
-@}
-
-void main_prog(int argc, char *argv[])
-@{
- int done;
- char input_str[200];
-
- gh_eval_str("(display \"hello Guile\")");
- gh_eval_str("(newline)");
-
- /* @r{for fun, evaluate some simple Scheme expressions here} */
- gh_eval_str("(define (square x) (* x x))");
- gh_eval_str("(define (fact n) (if (= n 1) 1 (* n (fact (- n 1)))))");
- gh_eval_str("(square 9)");
-
- /* @r{now sit in a Scheme eval loop: I input the expressions, have
- Guile evaluate them, and then get another expression.} */
- done = 0;
- fputs("learn0> ", stdout);
- while (fgets(input_str, 199, stdin) != NULL) @{
- gh_eval_str(input_str);
- fputs("\nlearn0> ", stdout);
- @}
-
- exit(0);
-@}
-@end smallexample
-
-If you name this program @code{learn0.c}, it can now be compiled with:
-@smallexample
-gcc -g -c learn0.c -o learn0.o
-gcc -o learn0 learn0.o -lguile -lm
-@end smallexample
-
-@c @emph{NOTE: If you are in the Guile development tree, you can simply do
-@c ``cd doc/examples/c; make; ./learn0''.}
-
-The program is simple: it creates a Scheme interpreter, passes a couple
-of strings to it that define new Scheme functions @code{square} and
-@code{factorial}, and then a couple of strings that invoke those
-functions.
-
-It then goes into a read-eval-print-loop (REPL), so you could type
-one-line Scheme expressions to it and have them evaluated. For example:
-@smallexample
-<shell-prompt> ./learn0
-hello Guile
-learn0> (display (sin 1.3))
-963.558185417193e-3
-learn0> (display (fact 10))
-3628800
-learn0> (quit)
-<shell-prompt>
-@end smallexample
-
-You should notice the key steps involved in this @code{learn0} program:
-
-@cartouche
-@enumerate
-@item
-@code{#include <guile/gh.h>}
-@item
-You need to invoke the initialization routine @code{gh_enter()}. This
-starts up a Scheme interpreter, handling many implementation-specific
-details.
-@item
-Your main() function should be almost empty: the real main program goes
-in a separate function main_prog() which is passed to gh_enter(). This
-rather arcane convention is due to the way Guile's garbage collector
-works: the whole program has to run in the dynamic context of
-@code{gh_enter()}.
-@item
-You pass strings to the Scheme interpreter with the @code{gh_eval_str()}
-routine.
-@item
-You link your program with @code{-lguile}.
-@end enumerate
-@end cartouche
-
-
-@node More interesting programming with libguile
-@section More interesting programming with libguile
-@cindex learn1
-@cindex callback
-@cindex builtin functions
-
-The @code{learn0} program shows how you can invoke Scheme commands from
-a C program. This is not such a great achievement: the same could have
-been done by opening a pipe to SCM or any other Scheme interpreter.
-
-A true extension language must allow @dfn{callbacks}. Callbacks allow
-you to write C routines that can be invoked as Scheme procedures, thus
-adding new primitive procedures to Scheme. This also means that a
-Scheme procedure can modify a C data structure.
-
-Guile allows you to define new Scheme procedures in C, and provides a
-mechanism to go back and forth between C and Scheme data types.
-
-Here is a second program, @code{learn1}, which demonstrates these
-features. It is split into three source files: @code{learn1.c},
-@code{c_builtins.h} and @code{c_builtins.c}. I am including the code
-here.
-@c , but you might just want to look at the online source code and the
-@c Makefile.am that come with Guile in the
-@c @file{doc/examples/c} directory.
-
-Notice that @code{learn1} uses a Scheme master world, and the C routines
-in @code{c_builtins.c} are simply adding new primitives to Scheme.
-
-@menu
-* learn1.c::
-* c_builtins.h::
-* c_builtins.c::
-* What learn1 is doing::
-* Compiling and running learn1::
-@end menu
-
-@node learn1.c
-@subsection learn1.c
-
-Here is @file{learn1.c}:
-@smallexample
-#include <stdio.h>
-
-#include <guile/gh.h>
-
-#include "c_builtins.h"
-
-void main_prog(int argc, char *argv[]);
-
-main(int argc, char *argv[])
-@{
- gh_enter(argc, argv, main_prog);
-@}
-
-void main_prog(int argc, char *argv[])
-@{
- char input_str[200]; /* @r{ugly hack: assume strlen(line) < 200} */
- int done;
-
- /* @r{for fun, evaluate some simple Scheme expressions here} */
- gh_eval_str("(define (square x) (* x x))");
- gh_eval_str("(define (fact n) (if (= n 1) 1 (* n (fact (- n 1)))))");
- gh_eval_str("(square 9)");
- gh_eval_str("(fact 100)");
-
- /* @r{now try to define some new builtins, coded in C, so that they are
- available in Scheme.} */
- gh_new_procedure1_0("c-factorial", c_factorial);
- gh_new_procedure1_0("c-sin", c_sin);
- gh_new_procedure1_0("v-t", vector_test);
-
- /* @r{now sit in a Scheme eval loop: I input the expressions, have
- Guile evaluate them, and then get another expression.} */
- done = 0;
- fputs("learn1> ", stdout);
- while (!done) @{
- if (gets(input_str) == NULL) @{
- done = 1;
- @} else @{
- gh_eval_str(input_str);
- fputs("learn1> ", stdout);
- @}
- @}
-
- exit(0);
-@}
-@end smallexample
-
-@node c_builtins.h
-@subsection c_builtins.h
-
-Here is @file{c_builtins.h}:
-@smallexample
-/* @r{builtin function prototypes} */
-
-#include <guile/gh.h>
-
-SCM c_factorial(SCM n);
-SCM c_sin(SCM n);
-SCM vector_test(SCM s_length);
-@end smallexample
-
-@node c_builtins.c
-@subsection c_builtins.c
-
-Here is @file{c_builtins.c}:
-@smallexample
-#include <stdio.h>
-#include <math.h>
-
-#include <guile/gh.h>
-
-#include "c_builtins.h"
-
-/* @r{this is a factorial routine in C, made to be callable by Scheme} */
-SCM c_factorial(SCM s_n)
-@{
- int i;
- unsigned long result = 1, n;
-
- n = gh_scm2ulong(s_n);
-
- gh_defer_ints();
- for (i = 1; i <= n; ++i) @{
- result = result*i;
- @}
- gh_allow_ints();
- return gh_ulong2scm(result);
-@}
-
-/* @r{a sin routine in C, callable from Scheme. it is named c_sin() to
- distinguish it from the default Scheme sin function} */
-SCM c_sin(SCM s_x)
-@{
- double x = gh_scm2double(s_x);
-
- return gh_double2scm(sin(x));
-@}
-
-/* @r{play around with vectors in Guile: this routine creates a vector of
- the given length, initializes it all to zero except element 2 which
- is set to 1.9.} */
-SCM vector_test(SCM s_length)
-@{
- SCM xvec;
-
- c_length = gh_scm2ulong(s_length);
- printf("requested length for vector: %ld\n", gh_scm2ulong(s_length));
-
- /* create a vector */
- xvec = gh_make_vector(s_length, gh_double2scm(0.0));
- /* set the second element in it */
- gh_vector_set_x(xvec, gh_int2scm(2), gh_double2scm(1.9));
-
- return xvec;
-@}
-@end smallexample
-
-@node What learn1 is doing
-@subsection What learn1 is doing
-@cindex registering callbacks
-@cindex registering C functions
-@cindex primitive procedures
-
-If you compare learn1 to learn0, you will find that learn1 uses a new
-Guile construct: the function @code{gh_new_procedure()}, and its
-siblings:
-
-@smallexample
- /* @r{now try to define some new builtins, coded in C, so that they are
- available in Scheme.} */
- gh_new_procedure1_0("c-factorial", c_factorial);
- gh_new_procedure1_0("c-sin", c_sin);
- gh_new_procedure1_0("v-t", vector_test);
-@end smallexample
-
-It is clear that @code{gh_new_procedure()} adds a new builtin
-routine written in C which can be invoked from Scheme. We can now
-revise our checklist for programming with libguile, so it includes
-adding callbacks.
-@cindex libguile - step by step
-
-@cartouche
-@enumerate
-@item
-@code{#include <guile/gh.h>}
-@item
-You need to invoke the initialization routine @code{gh_enter()}. This
-starts up a Scheme interpreter, handling many details.
-@item
-Your main() function should be almost empty: the real main program goes
-in a separate function main_prog() which is passed to gh_enter(). This
-rather arcane convention is due to the way Guile's garbage collector
-works: the whole program has to run in the dynamic context of
-@code{gh_enter()}.
-@item
-You pass strings to the Scheme interpreter with the @code{gh_eval_str()}
-routine.
-@item
-@strong{[new]} You can now define new builtin Scheme functions;
-i.e. define new builtin Scheme functions, with the
-@code{gh_new_procedure()} routine.
-@item
-You pass strings to the Scheme interpreter with the
-@code{gh_eval_str()} routine.
-@item
-You link your program with @code{-lguile}.
-@end enumerate
-@end cartouche
-
-I breezed by the issue of how to write your C routines that are
-registered to be called from Scheme. This is non-trivial, and is
-discussed at length in the @cite{Guile Programmer's Manual}.
-
-
-@node Compiling and running learn1
-@subsection Compiling and running learn1
-
-@smallexample
-gcc -g -c learn1.c -o learn1.o
-gcc -g -c c_builtins.c -o c_builtins.o
-gcc -o learn1 learn1.o c_builtins.o -lguile -lm
-@end smallexample
-
-If you run @code{learn1}, it will prompt you for a one-line Scheme
-expression, just as @code{learn0} did. The difference is that you can
-use the new C builtin procedures (@code{c-factorial}, @code{c-sin},
-@code{v-t}).
-
-@smallexample
-<shell-prompt> ./learn1
-welcome to Guile
-hello Guile
-learn1> (display (c-factorial 6))
-720
-learn1> (display (c-factorial 20))
-2192834560
-learn1> (display (c-factorial 100))
-0
-learn1> (display (c-sin 1.5))
-0.997494986604054
-learn1> (display (v-t 10))
-requested length for vector: 10
-#(0.0 0.0 1.9 0.0 0.0 0.0 0.0 0.0 0.0 0.0)
-learn1> (display (v-t 15))
-requested length for vector: 15
-#(0.0 0.0 1.9 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0)
-learn1> (quit)
-<shell-prompt>
-@end smallexample
-
-As you see, taking @code{(c-factorial 100)} does not use bignumbers and
-returns a bogus answer.
-
-@node Further examples
-@section Further examples
-
-Further ``idealized'' examples are included in the @code{doc/examples/c}
-distribution. They include programs to:
-
-@c [FIXME: still have to write some of these; then I will revise the list.]
-
-@itemize @bullet
-@item
-Parse a startup file (C is the master world).
-@item
-Set up initial conditions for an n-body simulation (C is the master
-world).
-@item
-Implement a Scheme interpreter with all of Guile's goodies, @emph{plus}
-the readline library @emph{and} a fast Fourier transform routine
-provided in C (Scheme is the master world).
-@end itemize
-
-@node Regular Expression Support
-@chapter Regular Expression Support
-
-@node UNIX System Programming
-@chapter UNIX System Programming
-
-@node Where to find more Guile/Scheme resources
-@chapter Where to find more Guile/Scheme resources
-
-
-@node Concept Index
-@unnumbered Concept Index
-
-@printindex cp
-
-@node Procedure and Macro Index
-@unnumbered Procedure and Macro Index
-
-This is an alphabetical list of all the procedures and macros in Dominion.
-
-@printindex fn
-
-@node Variable Index
-@unnumbered Variable Index
-
-This is an alphabetical list of the major global variables in Dominion.
-
-@printindex vr
-
-@node Type Index
-@unnumbered Type Index
-
-This is an alphabetical list of the major data structures in Dominion.
-
-@printindex tp
-
-@contents
-
-@bye
diff --git a/doc/use-cases.fig b/doc/use-cases.fig
deleted file mode 100644
index 24118ff31..000000000
--- a/doc/use-cases.fig
+++ /dev/null
@@ -1,199 +0,0 @@
-#FIG 3.2
-Portrait
-Center
-Metric
-A4
-100.00
-Single
--2
-1200 2
-0 32 #424242
-0 33 #848484
-0 34 #c6c6c6
-0 35 #8c8c8c
-0 36 #c6c6c6
-0 37 #848484
-0 38 #8c8c8c
-0 39 #424242
-0 40 #848484
-0 41 #c6c6c6
-0 42 #e7e7e7
-0 43 #c6b594
-0 44 #efffff
-0 45 #decea5
-0 46 #adadad
-0 47 #525252
-0 48 #8c8c8c
-0 49 #424242
-0 50 #848484
-0 51 #c6c6c6
-0 52 #e7e7e7
-0 53 #424242
-0 54 #848484
-0 55 #c6c6c6
-0 56 #e7e7e7
-0 57 #424242
-0 58 #848484
-0 59 #c6c6c6
-0 60 #e7e7e7
-0 61 #424242
-0 62 #848484
-0 63 #c6c6c6
-0 64 #e7e7e7
-0 65 #424242
-0 66 #848484
-0 67 #c6c6c6
-0 68 #e7e7e7
-0 69 #8c8c8c
-0 70 #424242
-0 71 #848484
-0 72 #c6c6c6
-0 73 #424242
-0 74 #c6c6c6
-0 75 #e7e7e7
-0 76 #424242
-0 77 #848484
-0 78 #c6c6c6
-0 79 #848484
-0 80 #c6c6c6
-0 81 #e7e7e7
-0 82 #424242
-0 83 #8c8c8c
-0 84 #424242
-0 85 #8c8c8c
-0 86 #424242
-0 87 #8c8c8c
-0 88 #424242
-0 89 #8c8c8c
-0 90 #424242
-0 91 #8c8c8c
-0 92 #424242
-0 93 #8c8c8c
-0 94 #424242
-0 95 #8c8c8c
-0 96 #424242
-0 97 #8c8c8c
-0 98 #c6c6c6
-0 99 #e7e7e7
-0 100 #848484
-0 101 #c6c6c6
-0 102 #e7e7e7
-0 103 #8c8c8c
-0 104 #424242
-0 105 #8c8c8c
-0 106 #424242
-0 107 #848484
-0 108 #c6c6c6
-0 109 #e7e7e7
-0 110 #8c8c8c
-0 111 #424242
-0 112 #8c8c8c
-0 113 #8c8c8c
-0 114 #8c8c8c
-0 115 #424242
-0 116 #adadad
-6 450 225 1350 1710
-1 4 0 1 0 7 100 0 -1 4.000 1 0.0000 900 406 176 176 765 294 1035 519
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 0 0 3
- 450 1710 900 1260 1350 1710
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 0 0 16
- 900 1260 900 1215 900 1170 900 1125 900 1080 900 1035
- 900 990 900 945 900 900 900 855 900 810 900 765
- 900 720 900 675 900 630 900 585
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 0 0 2
- 450 810 1350 810
--6
-6 450 2250 1350 3735
-1 4 0 1 0 7 100 0 -1 4.000 1 0.0000 900 2431 176 176 765 2319 1035 2544
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 0 0 3
- 450 3735 900 3285 1350 3735
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 0 0 16
- 900 3285 900 3240 900 3195 900 3150 900 3105 900 3060
- 900 3015 900 2970 900 2925 900 2880 900 2835 900 2790
- 900 2745 900 2700 900 2655 900 2610
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 0 0 2
- 450 2835 1350 2835
--6
-6 450 4275 1350 5760
-1 4 0 1 0 7 100 0 -1 4.000 1 0.0000 900 4456 176 176 765 4344 1035 4569
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 0 0 3
- 450 5760 900 5310 1350 5760
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 0 0 16
- 900 5310 900 5265 900 5220 900 5175 900 5130 900 5085
- 900 5040 900 4995 900 4950 900 4905 900 4860 900 4815
- 900 4770 900 4725 900 4680 900 4635
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 0 0 2
- 450 4860 1350 4860
--6
-6 2250 540 3645 1305
-1 2 0 1 0 7 100 0 20 4.000 1 0.0000 2947 922 697 382 2250 540 3645 1305
-4 0 0 100 0 16 12 0.0000 4 135 1245 2340 990 Hack On Guile\001
--6
-6 2250 2745 3645 3510
-1 2 0 1 0 7 100 0 20 4.000 1 0.0000 2947 3127 697 382 2250 2745 3645 3510
-4 0 0 100 0 16 12 0.0000 4 135 915 2520 3060 Write Guile\001
-4 0 0 50 0 16 12 0.0000 4 135 900 2520 3285 Extensions\001
--6
-6 2250 4770 3645 5535
-1 2 0 1 0 7 100 0 20 4.000 1 0.0000 2947 5152 697 382 2250 4770 3645 5535
-4 0 0 100 0 16 12 0.0000 4 135 1065 2430 5220 Embed Guile\001
--6
-6 2250 3690 3645 4455
-1 2 0 1 0 7 100 0 20 4.000 1 0.0000 2947 4072 697 382 2250 3690 3645 4455
-4 0 0 100 0 16 12 0.0000 4 180 1215 2385 4140 Use Guile App\001
--6
-6 2250 1620 3645 2385
-1 2 0 1 0 7 100 0 20 4.000 1 0.0000 2947 2002 697 382 2250 1620 3645 2385
-4 0 0 100 0 16 12 0.0000 4 180 1050 2430 2070 Write Scripts\001
--6
-6 4635 1350 5535 2835
-1 4 0 1 0 7 100 0 -1 4.000 1 0.0000 5085 1531 176 176 4950 1419 5220 1644
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 0 0 3
- 4635 2835 5085 2385 5535 2835
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 0 0 16
- 5085 2385 5085 2340 5085 2295 5085 2250 5085 2205 5085 2160
- 5085 2115 5085 2070 5085 2025 5085 1980 5085 1935 5085 1890
- 5085 1845 5085 1800 5085 1755 5085 1710
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 0 0 2
- 4635 1935 5535 1935
--6
-6 4635 3375 5535 4860
-1 4 0 1 0 7 100 0 -1 4.000 1 0.0000 5085 3556 176 176 4950 3444 5220 3669
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 0 0 3
- 4635 4860 5085 4410 5535 4860
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 0 0 16
- 5085 4410 5085 4365 5085 4320 5085 4275 5085 4230 5085 4185
- 5085 4140 5085 4095 5085 4050 5085 4005 5085 3960 5085 3915
- 5085 3870 5085 3825 5085 3780 5085 3735
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 0 0 2
- 4635 3960 5535 3960
--6
-2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
- 1 0 1.00 314.32 228.60
- 1395 945 2272 945
-2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
- 1 0 1.00 314.32 228.60
- 1395 3150 2272 3150
-2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
- 1 0 1.00 314.32 228.60
- 1395 5130 2272 5130
-2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
- 1 0 1.00 314.32 228.60
- 1395 4860 2295 3330
-2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
- 1 0 1.00 314.32 228.60
- 1395 1215 2385 2880
-2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
- 1 0 1.00 314.32 228.60
- 4545 1980 3668 1980
-2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
- 1 0 1.00 314.32 228.60
- 4545 4050 3668 4050
-2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
- 1980 135 3960 135 3960 6075 1980 6075 1980 135
-4 0 0 50 0 16 12 0.0000 4 180 1365 225 1935 Guile Developer\001
-4 0 0 50 0 16 12 0.0000 4 180 1740 90 3960 Extension Developer\001
-4 0 0 50 0 16 12 0.0000 4 180 1875 45 5985 Application Developer\001
-4 0 0 50 0 16 12 0.0000 4 135 435 2790 360 Guile\001
-4 0 0 50 0 16 12 0.0000 4 180 1725 4230 3060 Scheme Programmer\001
-4 0 0 50 0 16 12 0.0000 4 180 1380 4410 5085 Application User\001
diff --git a/doc/use-cases.txt b/doc/use-cases.txt
deleted file mode 100644
index e455fd1b8..000000000
--- a/doc/use-cases.txt
+++ /dev/null
@@ -1,22 +0,0 @@
- +-------------------+
- | Guile |
- O | |
- -+- | .---------------. |
- | -------->| Hack On Guile | |
- / \ \ | `---------------' | O
-Guile Developer | .---------------. | -+-
- \ | | Write Scripts |<------ |
- O \ | `---------------' | / \
- -+- `--->.---------------. | Scheme Programmer
- | -------->| Write Guile | |
- / \ .-->| Extensions | |
- Extension / | `---------------' | O
- Developer / | .---------------. | -+-
- / | | Use Guile App |<------ |
- O / | `---------------' | / \
- -+- / | .---------------. | Application User
- | -------->| Embed Guile | |
- / \ | `---------------' |
- Application | |
- Developer | |
- +-------------------+