@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 (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 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.2 or any later version published by the Free Software
-Foundation; with the no Invariant Sections, with the Front-Cover
-Texts being ``A GNU Manual,'' and with the Back-Cover Texts as in
-(a) below. A copy of the license is included in the section
-entitled "GNU Free Documentation License".
-
-(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
-this GNU Manual.''
+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.2 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
@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
@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
* 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.29 2004-02-18 20:07:19 mvo Exp $
+@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
@set example-dir doc/examples
@ifnottex
-@node Top, Contributors, (dir), (dir)
+@node Top, Preface, (dir), (dir)
@top The Guile Reference Manual
@insertcopying
@end ifnottex
@menu
-Preface
-
-* Contributors:: Contributors to this manual.
-* 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
+* Preface::
+* Introduction::
-* 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.
+* Hello Guile!::
+* Hello Scheme!::
-Part II: Writing and Running Guile Scheme
+* Programming in Scheme::
+* Programming in C::
-* 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.
+* API Reference::
-Part IV: Guile API Reference
+* Guile Modules::
+* Standard Library::
-* 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:: Configuration, features and runtime options.
-* Translation:: Support for translating other languages.
-* Debugging:: Internal debugging interface.
-* Deprecated:: Features that are planned to disappear.
+* GOOPS::
-Part V: Guile Modules
+* Guile Implementation::
-* 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.
-* File Tree Walk:: Traversing the file system.
-* Queues:: First-in first-out queuing.
-* Expect:: Controlling interactive programs with Guile.
-* The Scheme shell (scsh):: Using scsh interfaces in Guile.
+* Autoconf Support::
Appendices
@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
+@include tour.texi
-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.
+@raisesections
+@include scheme-ideas.texi
+@lowersections
+@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 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),
+@xref{API Reference}.
-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}).
+@menu
+* Guile Scheme:: Guile's implementation of Scheme.
+* Guile Scripting:: How to write Guile scripts.
+* Using Guile Interactively:: Guile's REPL features.
+* Using Guile in Emacs:: Guile and Emacs.
+@end menu
@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
+@include scheme-scripts.texi
+@include scheme-using.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
+@node Programming in C
+@chapter Programming in C
-@page
-@node Reference Intro
-@unnumbered Part IV: Guile API Reference
+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.
+
+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.
+@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
+
+@node API Reference
+@chapter 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
+@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.
+* 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.
+* 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.
+* Other Languages:: Emacs Lisp, ECMAScript, and more.
+* Internationalization:: Support for gettext, etc.
+* Debugging:: Debugging infrastructure and Scheme interface.
+@end menu
+
+@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 scheme-options.texi
-@include scheme-translation.texi
-@include scheme-debug.texi
-@include deprecated.texi
+@include api-options.texi
+@include api-languages.texi
+@include api-i18n.texi
+@include api-debug.texi
-@iftex
-@page
-@unnumbered{Part V: Guile Modules}
-@end iftex
+@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.
+* 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.
+* 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.
+* The Scheme shell (scsh):: Using scsh interfaces in Guile.
+* Tracing:: Tracing program execution.
+@end menu
@include slib.texi
@include posix.texi
+@include mod-getopt-long.texi
@include srfi-modules.texi
@include repl-modules.texi
@include misc-modules.texi
@include expect.texi
@include scsh.texi
+@include scheme-debugging.texi
+
+@node Standard Library
+@chapter Standard Library
+
+@lowersections
+@include standard-library.texi
+@raisesections
+
+@include goops.texi
+
+@node Guile Implementation
+@chapter Guile Implementation
+
+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'.''
+
+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.
+
+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.
+
+@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
+
+@include history.texi
+@include data-rep.texi
+@include vm.texi
+@include compiler.texi
+
+@include autoconf.texi
@include fdl.texi
HCoop / bpt / guile.git / blobdiff