diff options
Diffstat (limited to 'doc/ref')
47 files changed, 0 insertions, 29632 deletions
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 |