1\input texinfo 2@c -*-texinfo-*- 3@c %**start of header 4@documentencoding ISO-8859-1 5@setfilename guile.info 6@documentencoding UTF-8 7@settitle Guile Reference Manual 8@set guile 9@set MANUAL-REVISION 1 10@c %**end of header 11@include version.texi 12@include effective-version.texi 13 14@copying 15This manual documents Guile version @value{VERSION}. 16 17Copyright (C) 1996-1997, 2000-2005, 2009-2021 Free Software Foundation, 18Inc. 19 20Permission is granted to copy, distribute and/or modify this document 21under the terms of the GNU Free Documentation License, Version 1.3 or 22any later version published by the Free Software Foundation; with no 23Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A 24copy of the license is included in the section entitled ``GNU Free 25Documentation License.'' 26@end copying 27 28 29@c Notes 30@c 31@c We no longer use the category "primitive" to distinguish C-defined 32@c Scheme procedures from those defined in Scheme. Instead, the 33@c reference manual now includes a C declaration as well as a Scheme 34@c declaration for each procedure that is available in both Scheme and 35@c C. 36@c 37@c When adding a new reference entry to the Guile manual, please 38@c document it with @deffn using one of the following categories: 39@c 40@c {Scheme Procedure} 41@c {Scheme Syntax} 42@c {C Function} 43@c {C Macro} 44@c 45@c If the entry is for a new primitive, it should have both a @deffn 46@c {Scheme Procedure} line and a @deffnx {C Function} line; see the 47@c manual source for plenty of existing examples of this. 48@c 49@c For {C Function} entries where the return type and all parameter 50@c types are SCM, we omit the SCMs. This is easier to read and also 51@c gets round the problem that Texinfo doesn't allow a @deftypefnx 52@c inside a @deffn. 53@c 54@c For a list of Guile primitives that are not yet incorporated into the 55@c reference manual, see the file `new-docstrings.texi', which holds all 56@c the docstrings snarfed from the libguile C sources for primitives 57@c that are not in the reference manual. If you have worked with some 58@c of these concepts, implemented them, or just happen to know what they 59@c do, please write up a little explanation -- it would be a big help. 60@c Alternatively, if you know of any reason why some of these should 61@c *not* go in the manual, please let the mailing list 62@c <guile-devel@gnu.org> know. 63 64@c Define indices that are used in the Guile Scheme part of the 65@c reference manual to group stuff according to whether it is R5RS or a 66@c Guile extension. 67@defcodeindex rn 68 69@c vnew - For (some) new items, indicates the Guile version in which 70@c item first appeared. In future, this could be made to expand to 71@c something like a "New in Guile 45!" banner. 72@macro vnew{VERSION} 73@end macro 74 75 76@c The following, @le{} and @ge{}, are standard tex directives, given 77@c definitions for use in non-tex. 78@c 79@ifnottex 80@macro ge 81>= 82@end macro 83@macro le 84<= 85@end macro 86@end ifnottex 87 88@c @cross{} is a \times symbol in tex, or an "x" in info. In tex it works 89@c inside or outside $ $. 90@tex 91\gdef\cross{\ifmmode\times\else$\times$\fi} 92@end tex 93@ifnottex 94@macro cross 95x 96@end macro 97@end ifnottex 98 99@c @m{T,N} is $T$ in tex or @math{N} otherwise. This is an easy way to give 100@c different forms for math in tex and info. 101@iftex 102@macro m {T,N} 103@tex$\T\$@end tex 104@end macro 105@end iftex 106@ifnottex 107@macro m {T,N} 108@math{\N\} 109@end macro 110@end ifnottex 111 112@c @nicode{S} is plain S in info, or @code{S} elsewhere. This can be used 113@c when the quotes that @code{} gives in info aren't wanted, but the 114@c fontification in tex or html is wanted. @alias is used rather 115@c than @macro because backslashes don't work properly in an @macro. 116@ifinfo 117@alias nicode=asis 118@end ifinfo 119@ifnotinfo 120@alias nicode=code 121@end ifnotinfo 122 123 124@c @iftex 125@c @cropmarks 126@c @end iftex 127 128@dircategory The Algorithmic Language Scheme 129@direntry 130* Guile Reference: (guile). The Guile reference manual. 131@end direntry 132 133@setchapternewpage odd 134 135@titlepage 136@sp 10 137@comment The title is printed in a large font. 138@title Guile Reference Manual 139@subtitle Edition @value{EDITION}, revision @value{MANUAL-REVISION}, for use with Guile @value{VERSION} 140@c @subtitle $Id: guile.texi,v 1.49 2008-03-19 22:51:23 ossau Exp $ 141 142@c See preface.texi for the list of authors 143@author The Guile Developers 144 145@c The following two commands start the copyright page. 146@page 147@vskip 0pt plus 1filll 148@vskip 0pt plus 1filll 149@insertcopying 150@end titlepage 151 152@c @smallbook 153@finalout 154@headings double 155 156@c Where to find Guile examples. 157@set example-dir doc/examples 158 159@ifnottex 160@node Top, Preface, (dir), (dir) 161@top The Guile Reference Manual 162 163@insertcopying 164@sp 1 165@end ifnottex 166 167@menu 168 169* Preface:: 170* Introduction:: 171 172* Hello Guile!:: 173* Hello Scheme!:: 174 175* Programming in Scheme:: 176* Programming in C:: 177 178* API Reference:: 179 180* Guile Modules:: 181 182* GOOPS:: 183 184* Guile Implementation:: 185 186Appendices 187 188* GNU Free Documentation License:: The license of this manual. 189 190Indices 191 192* Concept Index:: 193* Procedure Index:: 194* Variable Index:: 195* Type Index:: 196* R5RS Index:: 197 198@end menu 199 200@contents 201 202@include preface.texi 203 204@include intro.texi 205 206@include tour.texi 207 208@include scheme-ideas.texi 209@include scheme-reading.texi 210 211@node Programming in Scheme 212@chapter Programming in Scheme 213 214Guile's core language is Scheme, and a lot can be achieved simply by using Guile 215to write and run Scheme programs --- as opposed to having to dive into C code. 216In this part of the manual, we explain how to use Guile in this mode, and 217describe the tools that Guile provides to help you with script writing, 218debugging, and packaging your programs for distribution. 219 220For detailed reference information on the variables, functions, and so 221on that make up Guile's application programming interface (API), see 222@ref{API Reference}. 223 224@menu 225* Guile Scheme:: Guile's implementation of Scheme. 226* Invoking Guile:: Selecting optional features when starting Guile. 227* Guile Scripting:: How to write Guile scripts. 228* Using Guile Interactively:: Guile's REPL features. 229* Using Guile in Emacs:: Guile and Emacs. 230* Using Guile Tools:: A guild of scheming wizards. 231* Installing Site Packages:: Installing Scheme code. 232* Distributing Guile Code:: Building and distributing your code. 233@end menu 234 235@include scheme-intro.texi 236@include guile-invoke.texi 237@include scheme-scripts.texi 238@include scheme-using.texi 239 240@node Programming in C 241@chapter Programming in C 242 243This part of the manual explains the general concepts that you need to 244understand when interfacing to Guile from C. You will learn about how 245the latent typing of Scheme is embedded into the static typing of C, how 246the garbage collection of Guile is made available to C code, and how 247continuations influence the control flow in a C program. 248 249This knowledge should make it straightforward to add new functions to 250Guile that can be called from Scheme. Adding new data types is also 251possible and is done by defining @dfn{foreign objects}. 252 253The @ref{Programming Overview} section of this part contains general 254musings and guidelines about programming with Guile. It explores 255different ways to design a program around Guile, or how to embed Guile 256into existing programs. 257 258For a pedagogical yet detailed explanation of how the data representation of 259Guile is implemented, @xref{Data Representation}. You don't need to know the 260details given there to use Guile from C, but they are useful when you want to 261modify Guile itself or when you are just curious about how it is all done. 262 263For detailed reference information on the variables, functions 264etc. that make up Guile's application programming interface (API), 265@xref{API Reference}. 266 267@menu 268* Parallel Installations:: Finding the right Guile. 269* Linking Programs With Guile:: More precisely, with the libguile library. 270* Linking Guile with Libraries:: To extend Guile itself. 271* General Libguile Concepts:: General concepts for using libguile. 272* Defining New Foreign Object Types:: Adding new types to Guile. 273* Function Snarfing:: A way to define new functions. 274* Programming Overview:: An overview of Guile programming. 275* Autoconf Support:: Putting m4 to good use. 276@end menu 277 278@include libguile-parallel.texi 279@include libguile-linking.texi 280@include libguile-extensions.texi 281@include libguile-concepts.texi 282@include libguile-foreign-objects.texi 283@include libguile-snarf.texi 284@include libguile-program.texi 285@include libguile-autoconf.texi 286 287 288@node API Reference 289@chapter API Reference 290 291Guile provides an application programming interface (@dfn{API}) to 292developers in two core languages: Scheme and C. This part of the manual 293contains reference documentation for all of the functionality that is 294available through both Scheme and C interfaces. 295 296@menu 297* API Overview:: Overview of the Guile API. 298* Deprecation:: Obsolete back-compatible APIs. 299* The SCM Type:: The fundamental data type for C code. 300* Initialization:: Initializing Guile. 301* Snarfing Macros:: Macros for snarfing initialization actions. 302* Data Types:: Representing values in Guile. 303* Procedures:: Procedures. 304* Macros:: Extending the syntax of Scheme. 305* Utility Functions:: General utility functions. 306* Binding Constructs:: Definitions and variable bindings. 307* Control Mechanisms:: Controlling the flow of program execution. 308* Input and Output:: Ports, reading and writing. 309* Regular Expressions:: Pattern matching and substitution. 310* LALR(1) Parsing:: Generating LALR(1) parsers. 311* PEG Parsing:: Parsing Expression Grammars. 312* Read/Load/Eval/Compile:: Reading and evaluating Scheme code. 313* Memory Management:: Memory management and garbage collection. 314* Modules:: Designing reusable code libraries. 315* Foreign Function Interface:: Interacting with C procedures and data. 316* Foreign Objects:: Defining new data types in C. 317* Smobs:: Use foreign objects instead. 318* Scheduling:: Threads, mutexes, asyncs and dynamic roots. 319* Options and Config:: Configuration, features and runtime options. 320* Other Languages:: Emacs Lisp, ECMAScript, and more. 321* Internationalization:: Support for gettext, etc. 322* Debugging:: Debugging infrastructure and Scheme interface. 323* Code Coverage:: Gathering code coverage data. 324@end menu 325 326@include api-overview.texi 327@include api-deprecated.texi 328@include api-scm.texi 329@include api-init.texi 330@include api-snarf.texi 331@include api-data.texi 332@include api-procedures.texi 333@include api-macros.texi 334@include api-utility.texi 335@include api-binding.texi 336@include api-control.texi 337@include api-io.texi 338@include api-regex.texi 339@include api-lalr.texi 340@include api-peg.texi 341@include api-evaluation.texi 342@include api-memory.texi 343@include api-modules.texi 344@include api-foreign.texi 345@include api-foreign-objects.texi 346@include api-smobs.texi 347@include api-scheduling.texi 348@c object orientation support here 349@include api-options.texi 350@include api-languages.texi 351@include api-i18n.texi 352@include api-debug.texi 353@include api-coverage.texi 354 355@node Guile Modules 356@chapter Guile Modules 357 358@menu 359* SLIB:: Using the SLIB Scheme library. 360* POSIX:: POSIX system calls and networking. 361* Web:: HTTP, the web, and all that. 362* getopt-long:: Command line handling. 363* SRFI Support:: Support for various SRFIs. 364* R6RS Support:: Modules defined by the R6RS. 365* R7RS Support:: Modules defined by the R7RS. 366* Pattern Matching:: Generic pattern matching constructs. 367* Readline Support:: Module for using the readline library. 368* Pretty Printing:: Nicely formatting Scheme objects for output. 369* Formatted Output:: The @code{format} procedure. 370* File Tree Walk:: Traversing the file system. 371* Queues:: First-in first-out queuing. 372* Streams:: Sequences of values. 373* Buffered Input:: Ports made from a reader function. 374* Expect:: Controlling interactive programs with Guile. 375* sxml-match:: Pattern matching of SXML. 376* The Scheme shell (scsh):: Using scsh interfaces in Guile. 377* Curried Definitions:: Extended @code{define} syntax. 378* Statprof:: An easy-to-use statistical profiler. 379* SXML:: Parsing, transforming, and serializing XML. 380* Texinfo Processing:: Munging documents written in Texinfo. 381@end menu 382 383@include slib.texi 384@include posix.texi 385@include web.texi 386@include mod-getopt-long.texi 387@include srfi-modules.texi 388@include r6rs.texi 389@include r7rs.texi 390@include match.texi 391@include repl-modules.texi 392@include misc-modules.texi 393@include expect.texi 394 395@c XXX: Would be nicer if it were close to the (sxml simple) documentation. 396@include sxml-match.texi 397 398@include scsh.texi 399@include curried.texi 400 401@include statprof.texi 402@include sxml.texi 403@include texinfo.texi 404 405@include goops.texi 406 407@node Guile Implementation 408@chapter Guile Implementation 409 410At some point, after one has been programming in Scheme for some time, 411another level of Scheme comes into view: its implementation. Knowledge 412of how Scheme can be implemented turns out to be necessary to become 413an expert hacker. As Peter Norvig notes in his retrospective on 414PAIP@footnote{PAIP is the common abbreviation for @cite{Paradigms of 415Artificial Intelligence Programming}, an old but still useful text on 416Lisp. Norvig's retrospective sums up the lessons of PAIP, and can be 417found at @uref{http://norvig.com/Lisp-retro.html}.}, ``The expert Lisp 418programmer eventually develops a good `efficiency model'.'' 419 420By this Norvig means that over time, the Lisp hacker eventually 421develops an understanding of how much her code ``costs'' in terms of 422space and time. 423 424This chapter describes Guile as an implementation of Scheme: its 425history, how it represents and evaluates its data, and its compiler. 426This knowledge can help you to make that step from being one who is 427merely familiar with Scheme to being a real hacker. 428 429@menu 430* History:: A brief history of Guile. 431* Data Representation:: How Guile represents Scheme data. 432* A Virtual Machine for Guile:: How compiled procedures work. 433* Compiling to the Virtual Machine:: Not as hard as you might think. 434@end menu 435 436@include history.texi 437@include data-rep.texi 438@include vm.texi 439@include compiler.texi 440 441@node GNU Free Documentation License 442@appendix GNU Free Documentation License 443 444@include fdl.texi 445 446@include indices.texi 447@include scheme-indices.texi 448 449@bye 450