diff options
Diffstat (limited to 'doc')
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 | | - +-------------------+ |