X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/05c4ffe1a7299c81ac01350e93d15d22c58e1a24..845cbcfeb92501f7e7ed176aec9fceecb732bb7d:/doc/ref/guile.texi diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index ce25a7f6c..29b6570c8 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -4,39 +4,27 @@ @setfilename guile.info @settitle Guile Reference Manual @set guile -@set MANUAL-EDITION 1.1 +@set MANUAL-REVISION 1 @c %**end of header @include version.texi +@include lib-version.texi +@include effective-version.texi @copying -This reference manual documents Guile, GNU's Ubiquitous Intelligent -Language for Extensions, manual edition @value{MANUAL-EDITION} -corresponding to Guile @value{VERSION}. - -Copyright 1996, 1997, 2000, 2001, 2002, 2003 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. +This manual documents Guile version @value{VERSION}. + +Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010 Free +Software Foundation. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with +no Invariant Sections, with the Front-Cover Texts being ``A GNU +Manual,'' and with the Back-Cover Text ``You are free to copy and +modify this GNU Manual.''. A copy of the license is included in the +section entitled ``GNU Free Documentation License''. @end copying -@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 - @c Notes @c @@ -85,6 +73,29 @@ notice identical to this one except for the removal of this paragraph @end macro +@c The following, @le{} and @ge{}, are standard tex directives, given +@c definitions for use in non-tex. +@c +@ifnottex +@macro ge +>= +@end macro +@macro le +<= +@end macro +@end ifnottex + +@c @cross{} is a \times symbol in tex, or an "x" in info. In tex it works +@c inside or outside $ $. +@tex +\gdef\cross{\ifmmode\times\else$\times$\fi} +@end tex +@ifnottex +@macro cross +x +@end macro +@end ifnottex + @c @m{T,N} is $T$ in tex or @math{N} otherwise. This is an easy way to give @c different forms for math in tex and info. @iftex @@ -98,18 +109,15 @@ notice identical to this one except for the removal of this paragraph @end macro @end ifnottex -@c @nicode{S} is plain S in info, or @code{S} elsewhere. This can be -@c used when the quotes that @code{} gives in info aren't wanted, but -@c the fontification in tex or html is wanted. +@c @nicode{S} is plain S in info, or @code{S} elsewhere. This can be used +@c when the quotes that @code{} gives in info aren't wanted, but the +@c fontification in tex or html is wanted. @alias is used rather +@c than @macro because backslashes don't work properly in an @macro. @ifinfo -@macro nicode {S} -\S\ -@end macro +@alias nicode=asis @end ifinfo @ifnotinfo -@macro nicode {S} -@code{\S\} -@end macro +@alias nicode=code @end ifnotinfo @@ -122,66 +130,17 @@ notice identical to this one except for the removal of this paragraph * Guile Reference: (guile). The Guile reference manual. @end direntry -@setchapternewpage off +@setchapternewpage odd @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.24 2003-08-29 23:02:36 kryde 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} +@subtitle Edition @value{EDITION}, revision @value{MANUAL-REVISION}, for use with Guile @value{VERSION} +@c @subtitle $Id: guile.texi,v 1.49 2008-03-19 22:51:23 ossau Exp $ + +@c See preface.texi for the list of authors +@author The Guile Developers @c The following two commands start the copyright page. @page @@ -198,7 +157,7 @@ notice identical to this one except for the removal of this paragraph @set example-dir doc/examples @ifnottex -@node Top, Guile License, (dir), (dir) +@node Top, Preface, (dir), (dir) @top The Guile Reference Manual @insertcopying @@ -206,179 +165,270 @@ notice identical to this one except for the removal of this paragraph @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. +* Preface:: +* Introduction:: + +* Hello Guile!:: +* Hello Scheme!:: + +* Programming in Scheme:: +* Programming in C:: + +* API Reference:: + +* Guile Modules:: +* Standard Library:: + +* GOOPS:: -Part I: Introduction to Guile +* Guile Implementation:: -* 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. +* Autoconf Support:: -Part II: Writing and Running Guile Scheme +Appendices -* Running Intro:: Introduction to this part. +* GNU Free Documentation License:: The license of this manual. + +Indices + +* Concept Index:: +* Procedure Index:: +* Variable Index:: +* Type Index:: +* R5RS Index:: + +@end menu + +@contents + +@include preface.texi + +@include intro.texi + +@include tour.texi + +@include scheme-ideas.texi +@include scheme-reading.texi + +@node Programming in Scheme +@chapter Programming in Scheme + +Guile's core language is Scheme, and a lot can be achieved simply by using Guile +to write and run Scheme programs --- as opposed to having to dive into C code. +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 detailed reference information on the variables, functions +etc. that make up Guile's application programming interface (API), +@xref{API Reference}. + +@menu * 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. +* Using Guile Interactively:: Guile's REPL features. +* Using Guile in Emacs:: Guile and Emacs. +@end menu + +@include scheme-intro.texi +@include scheme-scripts.texi +@include scheme-using.texi + +@node Programming in C +@chapter Programming in C -Part III: Guile as an Extension Language +This part of the manual explains the general concepts that you need to +understand when interfacing to Guile from C. You will learn about how +the latent typing of Scheme is embedded into the static typing of C, how +the garbage collection of Guile is made available to C code, and how +continuations influence the control flow in a C program. -* Programming Intro:: Introduction to this part. -* Libguile Intro:: Using Guile as an extension language. +This knowledge should make it straightforward to add new functions to +Guile that can be called from Scheme. Adding new data types is also +possible and is done by defining @dfn{smobs}. + +The @ref{Programming Overview} section of this part contains general +musings and guidelines about programming with Guile. It explores +different ways to design a program around Guile, or how to embed Guile +into existing programs. + +For a pedagogical yet detailed explanation of how the data representation of +Guile is implemented, @xref{Data Representation}. You don't need to know the +details given there to use Guile from C, but they are useful when you want to +modify Guile itself or when you are just curious about how it is all done. + +For detailed reference information on the variables, functions +etc. that make up Guile's application programming interface (API), +@xref{API Reference}. + +@menu +* Linking Programs With Guile:: More precisely, with the libguile library. +* Linking Guile with Libraries:: To extend Guile itself. +* General Libguile Concepts:: General concepts for using libguile. +* Defining New Types (Smobs):: Adding new types to Guile. +* Function Snarfing:: A way to define new functions. * Programming Overview:: An overview of Guile programming. -* Data Representation:: Data representation in Guile. -* GH:: The deprecated GH interface. +@end menu + +@include libguile-linking.texi +@include libguile-extensions.texi +@include libguile-concepts.texi +@include libguile-smobs.texi +@include libguile-snarf.texi +@include libguile-program.texi -Part IV: Guile API Reference +@node API Reference +@chapter API Reference -* Reference Intro:: Introduction to the 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. + +@menu * API Overview:: Overview of the Guile API. +* Discouraged and Deprecated:: Obsolete back-compatible APIs. +* The SCM Type:: The fundamental data type for C code. +* Initialization:: Initializing Guile. +* Snarfing Macros:: Macros for snarfing initialization actions. * Simple Data Types:: Numbers, strings, booleans and so on. * Compound Data Types:: Data types for holding other data. -* Procedures and Macros:: Procedures and macros. +* Smobs:: Defining new data types in C. +* Procedures:: Procedures. +* Macros:: Extending the syntax of Scheme. * 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. +* LALR(1) Parsing:: Generating LALR(1) parsers. +* Read/Load/Eval/Compile:: Reading and evaluating Scheme code. * Memory Management:: Memory management and garbage collection. * Objects:: Low level object orientation support. * Modules:: Designing reusable code libraries. +* Foreign Function Interface:: Interacting with C procedures and data. * Scheduling:: Threads, mutexes, asyncs and dynamic roots. * Options and Config:: Configuration, features and runtime options. -* Translation:: Support for translating other languages. -* Debugging:: Internal debugging interface. -* Deprecated:: Features that are planned to disappear. +* Other Languages:: Emacs Lisp, ECMAScript, and more. +* Internationalization:: Support for gettext, etc. +* Debugging:: Debugging infrastructure and Scheme interface. +* Code Coverage:: Gathering code coverage data. +@end menu -Part V: Guile Modules +@include api-overview.texi +@include api-discdepr.texi +@include api-scm.texi +@include api-init.texi +@include api-snarf.texi +@include api-data.texi +@include api-compound.texi +@include api-smobs.texi +@include api-procedures.texi +@include api-macros.texi +@include api-utility.texi +@include api-binding.texi +@include api-control.texi +@include api-io.texi +@include api-lalr.texi +@include api-evaluation.texi +@include api-memory.texi +@include api-modules.texi +@include api-foreign.texi +@include api-scheduling.texi +@c object orientation support here +@include api-options.texi +@include api-languages.texi +@include api-i18n.texi +@include api-debug.texi +@include api-coverage.texi +@node Guile Modules +@chapter Guile Modules + +@menu * SLIB:: Using the SLIB Scheme library. * POSIX:: POSIX system calls and networking. +* getopt-long:: Command line handling. * SRFI Support:: Support for various SRFIs. +* R6RS Support:: Modules defined by the R6RS. * 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. +* File Tree Walk:: Traversing the file system. +* Queues:: First-in first-out queuing. +* Streams:: Sequences of values. +* Buffered Input:: Ports made from a reader function. * Expect:: Controlling interactive programs with Guile. +* sxml-match:: Pattern matching of SXML. * The Scheme shell (scsh):: Using scsh interfaces in Guile. - -Indices - -* Concept Index:: -* Procedure Index:: -* Variable Index:: -* Type Index:: -* R5RS Index:: - +* Tracing:: Tracing program execution. @end menu -@contents +@include slib.texi +@include posix.texi +@include mod-getopt-long.texi +@include srfi-modules.texi +@include r6rs.texi +@include repl-modules.texi +@include misc-modules.texi +@include expect.texi -@include preface.texi +@c XXX: Would be nicer if it were close to the (sxml simple) documentation. +@include sxml-match.texi -@iftex -@page -@unnumbered{Part I: Introduction to Guile} -@end iftex +@include scsh.texi +@include scheme-debugging.texi -@include intro.texi +@node Standard Library +@chapter Standard Library -@page -@node Running Intro -@unnumbered Part II: Writing and Running Guile Scheme +@lowersections +@include standard-library.texi +@raisesections -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. +@include goops.texi -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. +@node Guile Implementation +@chapter Guile Implementation -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}). +At some point, after one has been programming in Scheme for some time, +another level of Scheme comes into view: its implementation. Knowledge +of how Scheme can be implemented turns out to be necessary to become +an expert hacker. As Peter Norvig notes in his retrospective on +PAIP@footnote{PAIP is the common abbreviation for @cite{Paradigms of +Artificial Intelligence Programming}, an old but still useful text on +Lisp. Norvig's retrospective sums up the lessons of PAIP, and can be +found at @uref{http://norvig.com/Lisp-retro.html}.}, ``The expert Lisp +programmer eventually develops a good `efficiency model'.'' -@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 +By this Norvig means that over time, the Lisp hacker eventually +develops an understanding of how much her code ``costs'' in terms of +space and time. -@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 +This chapter describes Guile as an implementation of Scheme: its +history, how it represents and evaluates its data, and its compiler. +This knowledge can help you to make that step from being one who is +merely familiar with Scheme to being a real hacker. -@page -@node Reference Intro -@unnumbered Part IV: Guile API Reference +@menu +* History:: A brief history of Guile. +* Data Representation:: How Guile represents Scheme data. +* A Virtual Machine for Guile:: How compiled procedures work. +* Compiling to the Virtual Machine:: Not as hard as you might think. +@end menu -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 history.texi +@include data-rep.texi +@include vm.texi +@include compiler.texi -@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 +@include autoconf.texi -@iftex -@page -@unnumbered{Part V: Guile Modules} -@end iftex +@node GNU Free Documentation License +@appendix GNU Free Documentation License -@include slib.texi -@include posix.texi -@include srfi-modules.texi -@include repl-modules.texi -@include misc-modules.texi -@include expect.texi -@include scsh.texi +@include fdl.texi @iftex @page