Guile Reference ManualEdition 3.0.4, revision 1, for use with Guile 3.0.4

The Guile Developers

This manual documents Guile version 3.0.4.

Copyright (C) 1996-1997, 2000-2005, 2009-2020 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms ofthe GNU Free Documentation License, Version 1.3 or any later version published by the FreeSoftware Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-CoverTexts. A copy of the license is included in the section entitled “GNU Free DocumentationLicense.”

i

Table of Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Contributors to this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1The Guile License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.1 Guile and Scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Combining with C Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3 Guile and the GNU Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4 Interactive Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.5 Supporting Multiple Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.6 Obtaining and Installing Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.7 Organisation of this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.8 Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2 Hello Guile! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.1 Running Guile Interactively . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.2 Running Guile Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.3 Linking Guile into Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.4 Writing Guile Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.5 Using the Guile Module System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.5.1 Using Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.5.2 Writing new Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.5.3 Putting Extensions into Modules . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2.6 Reporting Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3 Hello Scheme! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.1 Data Types, Values and Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3.1.1 Latent Typing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.1.2 Values and Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.1.3 Defining and Setting Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.2 The Representation and Use of Procedures . . . . . . . . . . . . . . . . . . . . . 173.2.1 Procedures as Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173.2.2 Simple Procedure Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183.2.3 Creating and Using a New Procedure . . . . . . . . . . . . . . . . . . . . . 193.2.4 Lambda Alternatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.3 Expressions and Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203.3.1 Evaluating Expressions and Executing Programs . . . . . . . . . . 21

3.3.1.1 Evaluating Literal Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213.3.1.2 Evaluating a Variable Reference . . . . . . . . . . . . . . . . . . . . . . 223.3.1.3 Evaluating a Procedure Invocation Expression . . . . . . . . 223.3.1.4 Evaluating Special Syntactic Expressions . . . . . . . . . . . . . 23

3.3.2 Tail calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

ii Guile Reference Manual

3.3.3 Using the Guile REPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253.3.4 Summary of Common Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

3.4 The Concept of Closure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263.4.1 Names, Locations, Values and Environments . . . . . . . . . . . . . . 263.4.2 Local Variables and Environments . . . . . . . . . . . . . . . . . . . . . . . . 273.4.3 Environment Chaining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273.4.4 Lexical Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

3.4.4.1 An Example of Non-Lexical Scoping . . . . . . . . . . . . . . . . . . 283.4.5 Closure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303.4.6 Example 1: A Serial Number Generator . . . . . . . . . . . . . . . . . . . 313.4.7 Example 2: A Shared Persistent Variable . . . . . . . . . . . . . . . . . . 313.4.8 Example 3: The Callback Closure Problem . . . . . . . . . . . . . . . . 323.4.9 Example 4: Object Orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

3.5 Further Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

4 Programming in Scheme . . . . . . . . . . . . . . . . . . . . . . . 354.1 Guile’s Implementation of Scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354.2 Invoking Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

4.2.1 Command-line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354.2.2 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

4.3 Guile Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414.3.1 The Top of a Script File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414.3.2 The Meta Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424.3.3 Command Line Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434.3.4 Scripting Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

4.4 Using Guile Interactively . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474.4.1 The Init File, ~/.guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484.4.2 Readline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484.4.3 Value History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484.4.4 REPL Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

4.4.4.1 Help Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504.4.4.2 Module Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504.4.4.3 Language Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514.4.4.4 Compile Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514.4.4.5 Profile Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514.4.4.6 Debug Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524.4.4.7 Inspect Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534.4.4.8 System Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

4.4.5 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544.4.6 Interactive Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

4.5 Using Guile in Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564.6 Using Guile Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574.7 Installing Site Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574.8 Distributing Guile Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

iii

5 Programming in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595.1 Parallel Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595.2 Linking Programs With Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

5.2.1 Guile Initialization Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605.2.2 A Sample Guile Main Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 615.2.3 Building the Example with Make . . . . . . . . . . . . . . . . . . . . . . . . . 615.2.4 Building the Example with Autoconf . . . . . . . . . . . . . . . . . . . . . . 62

5.3 Linking Guile with Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635.3.1 A Sample Guile Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

5.4 General concepts for using libguile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645.4.1 Dynamic Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655.4.2 Garbage Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675.4.3 Control Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685.4.4 Asynchronous Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705.4.5 Multi-Threading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

5.5 Defining New Foreign Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 745.5.1 Defining Foreign Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745.5.2 Creating Foreign Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755.5.3 Type Checking of Foreign Objects . . . . . . . . . . . . . . . . . . . . . . . . 765.5.4 Foreign Object Memory Management . . . . . . . . . . . . . . . . . . . . . 775.5.5 Foreign Objects and Scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

5.6 Function Snarfing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815.7 An Overview of Guile Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

5.7.1 How One Might Extend Dia Using Guile . . . . . . . . . . . . . . . . . . 835.7.1.1 Deciding Why You Want to Add Guile . . . . . . . . . . . . . . . 845.7.1.2 Four Steps Required to Add Guile . . . . . . . . . . . . . . . . . . . 845.7.1.3 How to Represent Dia Data in Scheme . . . . . . . . . . . . . . . 855.7.1.4 Writing Guile Primitives for Dia . . . . . . . . . . . . . . . . . . . . . 865.7.1.5 Providing a Hook for the Evaluation of Scheme Code . . 875.7.1.6 Top-level Structure of Guile-enabled Dia . . . . . . . . . . . . . 885.7.1.7 Going Further with Dia and Guile . . . . . . . . . . . . . . . . . . . 88

5.7.2 Why Scheme is More Hackable Than C . . . . . . . . . . . . . . . . . . . 905.7.3 Example: Using Guile for an Application Testbed . . . . . . . . . 905.7.4 A Choice of Programming Options . . . . . . . . . . . . . . . . . . . . . . . . 91

5.7.4.1 What Functionality is Already Available? . . . . . . . . . . . . 925.7.4.2 Functional and Performance Constraints . . . . . . . . . . . . . 925.7.4.3 Your Preferred Programming Style . . . . . . . . . . . . . . . . . . . 925.7.4.4 What Controls Program Execution? . . . . . . . . . . . . . . . . . . 92

5.7.5 How About Application Users? . . . . . . . . . . . . . . . . . . . . . . . . . . . 925.8 Autoconf Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

5.8.1 Autoconf Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945.8.2 Autoconf Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945.8.3 Using Autoconf Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

iv Guile Reference Manual

6 API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996.1 Overview of the Guile API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996.2 Deprecation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006.3 The SCM Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006.4 Initializing Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016.5 Snarfing Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026.6 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

6.6.1 Booleans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1046.6.2 Numerical data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

6.6.2.1 Scheme’s Numerical “Tower” . . . . . . . . . . . . . . . . . . . . . . . . 1056.6.2.2 Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1066.6.2.3 Real and Rational Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 1106.6.2.4 Complex Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1136.6.2.5 Exact and Inexact Numbers . . . . . . . . . . . . . . . . . . . . . . . . 1136.6.2.6 Read Syntax for Numerical Data . . . . . . . . . . . . . . . . . . . . 1156.6.2.7 Operations on Integer Values . . . . . . . . . . . . . . . . . . . . . . . 1166.6.2.8 Comparison Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1176.6.2.9 Converting Numbers To and From Strings . . . . . . . . . . . 1186.6.2.10 Complex Number Operations . . . . . . . . . . . . . . . . . . . . . . 1186.6.2.11 Arithmetic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1196.6.2.12 Scientific Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1236.6.2.13 Bitwise Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1256.6.2.14 Random Number Generation . . . . . . . . . . . . . . . . . . . . . . 127

6.6.3 Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1296.6.4 Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

6.6.4.1 Character Set Predicates/Comparison . . . . . . . . . . . . . . . 1346.6.4.2 Iterating Over Character Sets . . . . . . . . . . . . . . . . . . . . . . . 1346.6.4.3 Creating Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1356.6.4.4 Querying Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1376.6.4.5 Character-Set Algebra . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1386.6.4.6 Standard Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

6.6.5 Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1416.6.5.1 String Read Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1416.6.5.2 String Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436.6.5.3 String Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1446.6.5.4 List/String conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1456.6.5.5 String Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1456.6.5.6 String Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1476.6.5.7 String Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1486.6.5.8 String Searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1526.6.5.9 Alphabetic Case Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . 1546.6.5.10 Reversing and Appending Strings . . . . . . . . . . . . . . . . . . 1556.6.5.11 Mapping, Folding, and Unfolding . . . . . . . . . . . . . . . . . . 1566.6.5.12 Miscellaneous String Operations . . . . . . . . . . . . . . . . . . . 1586.6.5.13 Representing Strings as Bytes . . . . . . . . . . . . . . . . . . . . . . 1596.6.5.14 Conversion to/from C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1606.6.5.15 String Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

6.6.6 Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

v

6.6.6.1 Symbols as Discrete Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 1656.6.6.2 Symbols as Lookup Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 1666.6.6.3 Symbols as Denoting Variables . . . . . . . . . . . . . . . . . . . . . . 1676.6.6.4 Operations Related to Symbols . . . . . . . . . . . . . . . . . . . . . 1676.6.6.5 Function Slots and Property Lists . . . . . . . . . . . . . . . . . . . 1706.6.6.6 Extended Read Syntax for Symbols . . . . . . . . . . . . . . . . . 1716.6.6.7 Uninterned Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

6.6.7 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1746.6.7.1 Why Use Keywords? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1746.6.7.2 Coding With Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1746.6.7.3 Keyword Read Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1756.6.7.4 Keyword Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

6.6.8 Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1786.6.9 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

6.6.9.1 List Read Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1816.6.9.2 List Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1816.6.9.3 List Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1826.6.9.4 List Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1836.6.9.5 Append and Reverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1836.6.9.6 List Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1846.6.9.7 List Searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1856.6.9.8 List Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

6.6.10 Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1866.6.10.1 Read Syntax for Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . 1876.6.10.2 Dynamic Vector Creation and Validation . . . . . . . . . . . 1876.6.10.3 Accessing and Modifying Vector Contents . . . . . . . . . . 1886.6.10.4 Vector Accessing from C . . . . . . . . . . . . . . . . . . . . . . . . . . . 1896.6.10.5 Uniform Numeric Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . 190

6.6.11 Bit Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1916.6.12 Bytevectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

6.6.12.1 Endianness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1936.6.12.2 Manipulating Bytevectors . . . . . . . . . . . . . . . . . . . . . . . . . . 1946.6.12.3 Interpreting Bytevector Contents as Integers . . . . . . . 1956.6.12.4 Converting Bytevectors to/from Integer Lists . . . . . . 1976.6.12.5 Interpreting BytevectorContents as Floating Point Numbers . . . . . . . . . . . . . . . . . . . . . . 198

6.6.12.6 Interpreting Bytevector Contents as Unicode Strings . . 1996.6.12.7 Accessing Bytevectors with the Array API . . . . . . . . . 1996.6.12.8 Accessing Bytevectors with the SRFI-4 API . . . . . . . . 200

6.6.13 Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2006.6.13.1 Array Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2006.6.13.2 Array Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2016.6.13.3 Shared Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2056.6.13.4 Arrays as arrays of arrays . . . . . . . . . . . . . . . . . . . . . . . . . . 2076.6.13.5 Accessing Arrays from C . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

6.6.14 VLists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2156.6.15 Record Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2176.6.16 SRFI-9 Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

vi Guile Reference Manual

Non-toplevel Record Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Custom Printers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Functional “Setters” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

6.6.17 Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2216.6.18 Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

6.6.18.1 Vtables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2236.6.18.2 Structure Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2246.6.18.3 Vtable Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2256.6.18.4 Meta-Vtables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2266.6.18.5 Vtable Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

6.6.19 Dictionary Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2296.6.20 Association Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

6.6.20.1 Alist Key Equality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2306.6.20.2 Adding or Setting Alist Entries . . . . . . . . . . . . . . . . . . . . 2306.6.20.3 Retrieving Alist Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2326.6.20.4 Removing Alist Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2336.6.20.5 Sloppy Alist Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2346.6.20.6 Alist Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

6.6.21 VList-Based Hash Lists or “VHashes” . . . . . . . . . . . . . . . . . . 2366.6.22 Hash Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

6.6.22.1 Hash Table Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2386.6.22.2 Hash Table Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

6.6.23 Other Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2436.7 Foreign Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2436.8 Smobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2456.9 Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

6.9.1 Lambda: Basic Procedure Creation . . . . . . . . . . . . . . . . . . . . . . 2486.9.2 Primitive Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2496.9.3 Compiled Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2506.9.4 Optional Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

6.9.4.1 lambda* and define*. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2536.9.4.2 (ice-9 optargs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

6.9.5 Case-lambda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2566.9.6 Higher-Order Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2576.9.7 Procedure Properties and Meta-information . . . . . . . . . . . . . . 2586.9.8 Procedures with Setters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2596.9.9 Inlinable Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

6.10 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2616.10.1 Defining Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2616.10.2 Syntax-rules Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

6.10.2.1 Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2636.10.2.2 Hygiene . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2666.10.2.3 Shorthands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2666.10.2.4 Reporting Syntax Errors in Macros . . . . . . . . . . . . . . . . 2676.10.2.5 Specifying a Custom Ellipsis Identifier . . . . . . . . . . . . . 2676.10.2.6 Further Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

6.10.3 Support for the syntax-case System . . . . . . . . . . . . . . . . . . . 2686.10.3.1 Why syntax-case? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

vii

6.10.3.2 Custom Ellipsis Identifiers for syntax-case Macros . . 2726.10.4 Syntax Transformer Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2736.10.5 Lisp-style Macro Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2756.10.6 Identifier Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2766.10.7 Syntax Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2776.10.8 Eval-when . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2796.10.9 Macro Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2806.10.10 Hygiene and the Top-Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2816.10.11 Internal Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

6.11 General Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2836.11.1 Equality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2836.11.2 Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2856.11.3 Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2866.11.4 Copying Deep Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2876.11.5 General String Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2886.11.6 Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

6.11.6.1 Hook Usage by Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 2886.11.6.2 Hook Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2896.11.6.3 Hooks For C Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2916.11.6.4 Hooks for Garbage Collection . . . . . . . . . . . . . . . . . . . . . . 2926.11.6.5 Hooks into the Guile REPL . . . . . . . . . . . . . . . . . . . . . . . . 293

6.12 Definitions and Variable Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . 2936.12.1 Top Level Variable Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . 2936.12.2 Local Variable Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2946.12.3 Internal definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2966.12.4 Querying variable bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2976.12.5 Binding multiple return values . . . . . . . . . . . . . . . . . . . . . . . . . . 298

6.13 Controlling the Flow of Program Execution . . . . . . . . . . . . . . . . . . 2986.13.1 Sequencing and Splicing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2986.13.2 Simple Conditional Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . 2996.13.3 Conditional Evaluation of a Sequence of Expressions . . . . 3016.13.4 Iteration mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3016.13.5 Prompts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

6.13.5.1 Prompt Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3046.13.5.2 Shift, Reset, and All That . . . . . . . . . . . . . . . . . . . . . . . . . 306

6.13.6 Continuations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3076.13.7 Returning and Accepting Multiple Values . . . . . . . . . . . . . . . 3096.13.8 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

6.13.8.1 Exception Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3116.13.8.2 Raising and Handling Exceptions . . . . . . . . . . . . . . . . . . 3156.13.8.3 Throw and Catch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3166.13.8.4 Exceptions and C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

6.13.9 Procedures for Signaling Errors . . . . . . . . . . . . . . . . . . . . . . . . . 3196.13.10 Dynamic Wind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3206.13.11 Fluids and Dynamic States . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3236.13.12 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3266.13.13 How to Handle Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

6.13.13.1 C Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

viii Guile Reference Manual

6.13.13.2 Signalling Type Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3306.13.14 Continuation Barriers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

6.14 Input and Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3316.14.1 Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3316.14.2 Binary I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3326.14.3 Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3346.14.4 Textual I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3366.14.5 Simple Textual Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3386.14.6 Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3396.14.7 Random Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3406.14.8 Line Oriented and Delimited Text . . . . . . . . . . . . . . . . . . . . . . 3416.14.9 Default Ports for Input, Output and Errors . . . . . . . . . . . . . 3436.14.10 Types of Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

6.14.10.1 File Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3446.14.10.2 Bytevector Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3476.14.10.3 String Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3476.14.10.4 Custom Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3486.14.10.5 Soft Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3506.14.10.6 Void Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

6.14.11 Venerable Port Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3506.14.12 Using Ports from C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3526.14.13 Implementing New Port Types in C . . . . . . . . . . . . . . . . . . . 3536.14.14 Non-Blocking I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3566.14.15 Handling of Unicode Byte Order Marks . . . . . . . . . . . . . . . . 357

6.15 Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3586.15.1 Regexp Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3596.15.2 Match Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3636.15.3 Backslash Escapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

6.16 LALR(1) Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3656.17 PEG Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

6.17.1 PEG Syntax Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3666.17.2 PEG API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3686.17.3 PEG Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3736.17.4 PEG Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

6.18 Reading and Evaluating Scheme Code . . . . . . . . . . . . . . . . . . . . . . . 3826.18.1 Scheme Syntax: Standard and Guile Extensions . . . . . . . . . 382

6.18.1.1 Expression Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3826.18.1.2 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3836.18.1.3 Block Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3846.18.1.4 Case Sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3846.18.1.5 Keyword Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3846.18.1.6 Reader Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

6.18.2 Reading Scheme Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3856.18.3 Writing Scheme Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3866.18.4 Procedures for On the Fly Evaluation . . . . . . . . . . . . . . . . . . . 3876.18.5 Compiling Scheme Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3896.18.6 Loading Scheme Code from File . . . . . . . . . . . . . . . . . . . . . . . . 3926.18.7 Load Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

ix

6.18.8 Character Encoding of Source Files . . . . . . . . . . . . . . . . . . . . . 3956.18.9 Delayed Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3966.18.10 Local Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3976.18.11 Local Inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3986.18.12 Sandboxed Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3986.18.13 REPL Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4036.18.14 Cooperative REPL Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

6.19 Memory Management and Garbage Collection . . . . . . . . . . . . . . . 4046.19.1 Function related to Garbage Collection . . . . . . . . . . . . . . . . . 4046.19.2 Memory Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4056.19.3 Weak References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

6.19.3.1 Weak hash tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4086.19.3.2 Weak vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408

6.19.4 Guardians . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4096.20 Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

6.20.1 General Information about Modules . . . . . . . . . . . . . . . . . . . . 4106.20.2 Using Guile Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4116.20.3 Creating Guile Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4136.20.4 Modules and the File System . . . . . . . . . . . . . . . . . . . . . . . . . . . 4166.20.5 R6RS Version References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4166.20.6 R6RS Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4176.20.7 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4196.20.8 Module System Reflection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4206.20.9 Declarative Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4226.20.10 Accessing Modules from C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4246.20.11 provide and require . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4266.20.12 Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

6.21 Foreign Function Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4276.21.1 Foreign Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4276.21.2 Foreign Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4296.21.3 C Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4306.21.4 Modules and Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4326.21.5 Foreign Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

6.21.5.1 Foreign Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4336.21.5.2 Foreign Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4346.21.5.3 Void Pointers and Byte Access . . . . . . . . . . . . . . . . . . . . . 4356.21.5.4 Foreign Structs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438

6.21.6 Dynamic FFI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4396.22 Threads, Mutexes, Asyncs and Dynamic Roots . . . . . . . . . . . . . . 442

6.22.1 Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4426.22.2 Thread-Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4446.22.3 Asynchronous Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4456.22.4 Atomics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4476.22.5 Mutexes and Condition Variables . . . . . . . . . . . . . . . . . . . . . . . 4486.22.6 Blocking in Guile Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4526.22.7 Futures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4536.22.8 Parallel forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454

6.23 Configuration, Features and Runtime Options . . . . . . . . . . . . . . . 456

x Guile Reference Manual

6.23.1 Configuration, Build and Installation . . . . . . . . . . . . . . . . . . . 4566.23.2 Feature Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458

6.23.2.1 Feature Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4586.23.2.2 Common Feature Symbols . . . . . . . . . . . . . . . . . . . . . . . . . 458

6.23.3 Runtime Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4606.23.3.1 Examples of option use . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460

6.24 Support for Other Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4616.24.1 Using Other Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4616.24.2 Emacs Lisp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462

6.24.2.1 Nil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4626.24.2.2 Dynamic Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4646.24.2.3 Other Elisp Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464

6.24.3 ECMAScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4646.25 Support for Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

6.25.1 Internationalization with Guile . . . . . . . . . . . . . . . . . . . . . . . . . 4656.25.2 Text Collation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4666.25.3 Character Case Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4676.25.4 Number Input and Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4686.25.5 Accessing Locale Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 4686.25.6 Gettext Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472

6.26 Debugging Infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4746.26.1 Evaluation and the Scheme Stack . . . . . . . . . . . . . . . . . . . . . . . 474

6.26.1.1 Stack Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4746.26.1.2 Stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4756.26.1.3 Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476

6.26.2 Source Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4776.26.3 Programmatic Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . 478

6.26.3.1 Catching Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4796.26.3.2 Pre-Unwind Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4796.26.3.3 call-with-error-handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4806.26.3.4 Stack Overflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4816.26.3.5 Debug options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484

6.26.4 Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4846.26.4.1 VM Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4856.26.4.2 Trap Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4866.26.4.3 Low-Level Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4876.26.4.4 Tracing Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4896.26.4.5 Trap States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4916.26.4.6 High-Level Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491

6.26.5 GDB Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4936.27 Code Coverage Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493

7 Guile Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4957.1 SLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495

7.1.1 SLIB installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4957.1.2 JACAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496

7.2 POSIX System Calls and Networking . . . . . . . . . . . . . . . . . . . . . . . . . . 4967.2.1 POSIX Interface Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496

xi

7.2.2 Ports and File Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4977.2.3 File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5047.2.4 User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5117.2.5 Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5137.2.6 Runtime Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5177.2.7 Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5187.2.8 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5247.2.9 Terminals and Ptys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5287.2.10 Pipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5297.2.11 Networking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530

7.2.11.1 Network Address Conversion . . . . . . . . . . . . . . . . . . . . . . . 5307.2.11.2 Network Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5327.2.11.3 Network Socket Address . . . . . . . . . . . . . . . . . . . . . . . . . . . 5387.2.11.4 Network Sockets and Communication . . . . . . . . . . . . . . 5407.2.11.5 Network Socket Examples . . . . . . . . . . . . . . . . . . . . . . . . . 545

7.2.12 System Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5467.2.13 Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5477.2.14 Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548

7.3 HTTP, the Web, and All That . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5487.3.1 Types and the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5487.3.2 Universal Resource Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5507.3.3 The Hyper-Text Transfer Protocol . . . . . . . . . . . . . . . . . . . . . . . 5537.3.4 HTTP Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556

7.3.4.1 HTTP Header Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5567.3.4.2 General Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5577.3.4.3 Entity Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5587.3.4.4 Request Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5597.3.4.5 Response Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562

7.3.5 Transfer Codings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5637.3.6 HTTP Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564

7.3.6.1 An Important Note on Character Sets . . . . . . . . . . . . . . . 5647.3.6.2 Request API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565

7.3.7 HTTP Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5677.3.8 Web Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5697.3.9 Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5717.3.10 Web Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574

7.3.10.1 Hello, World! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5747.3.10.2 Inspecting the Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5747.3.10.3 Higher-Level Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5757.3.10.4 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577

7.4 The (ice-9 getopt-long) Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5777.4.1 A Short getopt-long Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5777.4.2 How to Write an Option Specification . . . . . . . . . . . . . . . . . . . . 5787.4.3 Expected Command Line Format . . . . . . . . . . . . . . . . . . . . . . . . 5797.4.4 Reference Documentation for getopt-long . . . . . . . . . . . . . . 5807.4.5 Reference Documentation for option-ref . . . . . . . . . . . . . . . . 582

7.5 SRFI Support Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5827.5.1 About SRFI Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582

xii Guile Reference Manual

7.5.2 SRFI-0 - cond-expand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5837.5.3 SRFI-1 - List library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584

7.5.3.1 Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5847.5.3.2 Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5857.5.3.3 Selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5867.5.3.4 Length, Append, Concatenate, etc. . . . . . . . . . . . . . . . . . . 5877.5.3.5 Fold, Unfold & Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5887.5.3.6 Filtering and Partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . . 5917.5.3.7 Searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5927.5.3.8 Deleting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5937.5.3.9 Association Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5947.5.3.10 Set Operations on Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595

7.5.4 SRFI-2 - and-let* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5977.5.5 SRFI-4 - Homogeneous numeric vector datatypes . . . . . . . . . 598

7.5.5.1 SRFI-4 - Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5997.5.5.2 SRFI-4 - API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6007.5.5.3 SRFI-4 - Relation to bytevectors . . . . . . . . . . . . . . . . . . . . 6067.5.5.4 SRFI-4 - Guile extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . 606

7.5.6 SRFI-6 - Basic String Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6077.5.7 SRFI-8 - receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6077.5.8 SRFI-9 - define-record-type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6077.5.9 SRFI-10 - Hash-Comma Reader Extension . . . . . . . . . . . . . . . 6077.5.10 SRFI-11 - let-values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6097.5.11 SRFI-13 - String Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6097.5.12 SRFI-14 - Character-set Library . . . . . . . . . . . . . . . . . . . . . . . . 6097.5.13 SRFI-16 - case-lambda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6097.5.14 SRFI-17 - Generalized set! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6097.5.15 SRFI-18 - Multithreading support . . . . . . . . . . . . . . . . . . . . . . 610

7.5.15.1 SRFI-18 Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6107.5.15.2 SRFI-18 Mutexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6117.5.15.3 SRFI-18 Condition variables . . . . . . . . . . . . . . . . . . . . . . . 6127.5.15.4 SRFI-18 Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6137.5.15.5 SRFI-18 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613

7.5.16 SRFI-19 - Time/Date Library . . . . . . . . . . . . . . . . . . . . . . . . . . 6147.5.16.1 SRFI-19 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6147.5.16.2 SRFI-19 Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6157.5.16.3 SRFI-19 Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6167.5.16.4 SRFI-19 Time/Date conversions . . . . . . . . . . . . . . . . . . . 6187.5.16.5 SRFI-19 Date to string . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6197.5.16.6 SRFI-19 String to date . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620

7.5.17 SRFI-23 - Error Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6217.5.18 SRFI-26 - specializing parameters . . . . . . . . . . . . . . . . . . . . . . . 6217.5.19 SRFI-27 - Sources of Random Bits . . . . . . . . . . . . . . . . . . . . . . 623

7.5.19.1 The Default Random Source . . . . . . . . . . . . . . . . . . . . . . . 6237.5.19.2 Random Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6237.5.19.3 Obtaining random number generator procedures . . . 624

7.5.20 SRFI-28 - Basic Format Strings . . . . . . . . . . . . . . . . . . . . . . . . . 6257.5.21 SRFI-30 - Nested Multi-line Comments . . . . . . . . . . . . . . . . . 625

xiii

7.5.22 SRFI-31 - A special form ‘rec’ for recursive evaluation . . . 6257.5.23 SRFI-34 - Exception handling for programs . . . . . . . . . . . . . 6257.5.24 SRFI-35 - Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6267.5.25 SRFI-37 - args-fold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6287.5.26 SRFI-38 - External Representation forData With Shared Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629

7.5.27 SRFI-39 - Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6317.5.28 SRFI-41 - Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631

7.5.28.1 SRFI-41 Stream Fundamentals . . . . . . . . . . . . . . . . . . . . . 6317.5.28.2 SRFI-41 Stream Primitives . . . . . . . . . . . . . . . . . . . . . . . . 6327.5.28.3 SRFI-41 Stream Library . . . . . . . . . . . . . . . . . . . . . . . . . . . 633

7.5.29 SRFI-42 - Eager Comprehensions . . . . . . . . . . . . . . . . . . . . . . . 6417.5.30 SRFI-43 - Vector Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641

7.5.30.1 SRFI-43 Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6417.5.30.2 SRFI-43 Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6427.5.30.3 SRFI-43 Selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6437.5.30.4 SRFI-43 Iteration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6437.5.30.5 SRFI-43 Searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6447.5.30.6 SRFI-43 Mutators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6457.5.30.7 SRFI-43 Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645

7.5.31 SRFI-45 - Primitives forExpressing Iterative Lazy Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . 646

7.5.32 SRFI-46 Basic syntax-rules Extensions . . . . . . . . . . . . . . . . . . 6487.5.33 SRFI-55 - Requiring Features . . . . . . . . . . . . . . . . . . . . . . . . . . . 6487.5.34 SRFI-60 - Integers as Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6487.5.35 SRFI-61 - A more general cond clause . . . . . . . . . . . . . . . . . . 6507.5.36 SRFI-62 - S-expression comments. . . . . . . . . . . . . . . . . . . . . . . 6507.5.37 SRFI-64 - A Scheme API for test suites. . . . . . . . . . . . . . . . . 6507.5.38 SRFI-67 - Compare procedures . . . . . . . . . . . . . . . . . . . . . . . . . 6507.5.39 SRFI-69 - Basic hash tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650

7.5.39.1 Creating hash tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6507.5.39.2 Accessing table items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6517.5.39.3 Table properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6527.5.39.4 Hash table algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652

7.5.40 SRFI-71 - Extended let-syntax for multiple values . . . . . . . 6537.5.41 SRFI-87 => in case clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6537.5.42 SRFI-88 Keyword Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6537.5.43 SRFI-98 Accessing environment variables. . . . . . . . . . . . . . . . 6547.5.44 SRFI-105 Curly-infix expressions. . . . . . . . . . . . . . . . . . . . . . . . 6547.5.45 SRFI-111 Boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6557.5.46 Transducers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655

7.5.46.1 SRFI-171 General Discussion . . . . . . . . . . . . . . . . . . . . . . 6557.5.46.2 Applying Transducers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6567.5.46.3 Reducers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6577.5.46.4 Transducers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6587.5.46.5 Helper functions for writing transducers . . . . . . . . . . . . 661

7.6 R6RS Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6627.6.1 Incompatibilities with the R6RS . . . . . . . . . . . . . . . . . . . . . . . . . 662

xiv Guile Reference Manual

7.6.2 R6RS Standard Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6637.6.2.1 Library Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6637.6.2.2 rnrs base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6647.6.2.3 rnrs unicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6717.6.2.4 rnrs bytevectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6727.6.2.5 rnrs lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6727.6.2.6 rnrs sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6737.6.2.7 rnrs control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6747.6.2.8 R6RS Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6747.6.2.9 rnrs records syntactic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6757.6.2.10 rnrs records procedural . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6767.6.2.11 rnrs records inspection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6777.6.2.12 rnrs exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6787.6.2.13 rnrs conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6797.6.2.14 I/O Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6827.6.2.15 Transcoders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6837.6.2.16 rnrs io ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6867.6.2.17 R6RS File Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6897.6.2.18 rnrs io simple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6917.6.2.19 rnrs files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6927.6.2.20 rnrs programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6927.6.2.21 rnrs arithmetic fixnums . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6927.6.2.22 rnrs arithmetic flonums . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6957.6.2.23 rnrs arithmetic bitwise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6977.6.2.24 rnrs syntax-case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6997.6.2.25 rnrs hashtables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7007.6.2.26 rnrs enums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7027.6.2.27 rnrs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7037.6.2.28 rnrs eval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7037.6.2.29 rnrs mutable-pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7037.6.2.30 rnrs mutable-strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7047.6.2.31 rnrs r5rs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704

7.7 R7RS Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7047.7.1 Incompatibilities with the R7RS . . . . . . . . . . . . . . . . . . . . . . . . . 7047.7.2 R7RS Standard Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705

7.8 Pattern Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7067.9 Readline Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711

7.9.1 Loading Readline Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7117.9.2 Readline Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7127.9.3 Readline Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712

7.9.3.1 Readline Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7137.9.3.2 Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713

7.10 Pretty Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7147.11 Formatted Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7167.12 File Tree Walk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7277.13 Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7327.14 Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7337.15 Buffered Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735

xv

7.16 Expect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7367.17 sxml-match: Pattern Matching of SXML . . . . . . . . . . . . . . . . . . . . 738

Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739Matching XML Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740Ellipses in Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740Ellipses in Quasiquote’d Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740Matching Nodesets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741Matching the “Rest” of a Nodeset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741Matching the Unmatched Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741Default Values in Attribute Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742Guards in Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742Catamorphisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742Named-Catamorphisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742sxml-match-let and sxml-match-let* . . . . . . . . . . . . . . . . . . . . . . . . 743

7.18 The Scheme shell (scsh) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7437.19 Curried Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7447.20 Statprof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7457.21 SXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748

7.21.1 SXML Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7497.21.2 Reading and Writing XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7497.21.3 SSAX: A Functional XML Parsing Toolkit . . . . . . . . . . . . . . 751

7.21.3.1 History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7517.21.3.2 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7527.21.3.3 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753

7.21.4 Transforming SXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7547.21.4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7547.21.4.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755

7.21.5 SXML Tree Fold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7557.21.5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7567.21.5.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756

7.21.6 SXPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7577.21.6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7577.21.6.2 Basic Converters and Applicators . . . . . . . . . . . . . . . . . . 7587.21.6.3 Converter Combinators . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760

7.21.7 (sxml ssax input-parse) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7637.21.7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7637.21.7.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763

7.21.8 (sxml apply-templates) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7637.21.8.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7637.21.8.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764

7.22 Texinfo Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7647.22.1 (texinfo) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764

7.22.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7647.22.1.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764

7.22.2 (texinfo docbook) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7657.22.2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7657.22.2.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765

7.22.3 (texinfo html) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766

xvi Guile Reference Manual

7.22.3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7667.22.3.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766

7.22.4 (texinfo indexing) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7677.22.4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7677.22.4.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767

7.22.5 (texinfo string-utils) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7677.22.5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7677.22.5.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767

7.22.6 (texinfo plain-text) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7707.22.6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7707.22.6.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770

7.22.7 (texinfo serialize) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7707.22.7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7707.22.7.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770

7.22.8 (texinfo reflection) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7717.22.8.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7717.22.8.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771

8 GOOPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7738.1 Copyright Notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7738.2 Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7738.3 Instance Creation and Slot Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7748.4 Slot Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7758.5 Illustrating Slot Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7788.6 Methods and Generic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780

8.6.1 Accessors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7828.6.2 Extending Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7828.6.3 Merging Generics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7828.6.4 Next-method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7838.6.5 Generic Function and Method Examples . . . . . . . . . . . . . . . . . 7848.6.6 Handling Invocation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787

8.7 Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7878.7.1 Class Precedence List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7888.7.2 Sorting Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789

8.8 Introspection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7908.8.1 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7908.8.2 Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7918.8.3 Slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7918.8.4 Generic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7938.8.5 Accessing Slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794

8.9 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7968.10 GOOPS Object Miscellany . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7968.11 The Metaobject Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797

8.11.1 Metaobjects and the Metaobject Protocol . . . . . . . . . . . . . . . 7978.11.2 Metaclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7998.11.3 MOP Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8008.11.4 Instance Creation Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8008.11.5 Class Definition Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801

xvii

8.11.6 Customizing Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . 8048.11.7 Method Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8068.11.8 Method Definition Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8068.11.9 Generic Function Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8078.11.10 Generic Function Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . 808

8.12 Redefining a Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8098.12.1 Redefinable Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8098.12.2 Default Class Redefinition Behaviour . . . . . . . . . . . . . . . . . . . 8098.12.3 Customizing Class Redefinition . . . . . . . . . . . . . . . . . . . . . . . . . 810

8.13 Changing the Class of an Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . 811

9 Guile Implementation . . . . . . . . . . . . . . . . . . . . . . . . 8139.1 A Brief History of Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813

9.1.1 The Emacs Thesis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8139.1.2 Early Days . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8139.1.3 A Scheme of Many Maintainers . . . . . . . . . . . . . . . . . . . . . . . . . . 8149.1.4 A Timeline of Selected Guile Releases . . . . . . . . . . . . . . . . . . . . 8159.1.5 Status, or: Your Help Needed . . . . . . . . . . . . . . . . . . . . . . . . . . . . 816

9.2 Data Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8189.2.1 A Simple Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8189.2.2 Faster Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8199.2.3 Cheaper Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8209.2.4 Conservative Garbage Collection . . . . . . . . . . . . . . . . . . . . . . . . . 8219.2.5 The SCM Type in Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822

9.2.5.1 Relationship Between SCM and scm_t_bits . . . . . . . . . . 8239.2.5.2 Immediate Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8239.2.5.3 Non-Immediate Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8249.2.5.4 Allocating Heap Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8259.2.5.5 Heap Object Type Information . . . . . . . . . . . . . . . . . . . . . 8259.2.5.6 Accessing Heap Object Fields . . . . . . . . . . . . . . . . . . . . . . . 826

9.3 A Virtual Machine for Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8279.3.1 Why a VM? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8279.3.2 VM Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8289.3.3 Stack Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8299.3.4 Variables and the VM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8309.3.5 Compiled Procedures are VM Programs . . . . . . . . . . . . . . . . . . 8319.3.6 Object File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8339.3.7 Instruction Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835

9.3.7.1 Call and Return Instructions . . . . . . . . . . . . . . . . . . . . . . . . 8369.3.7.2 Function Prologue Instructions . . . . . . . . . . . . . . . . . . . . . . 8379.3.7.3 Shuffling Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8399.3.7.4 Trampoline Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8399.3.7.5 Non-Local Control Flow Instructions . . . . . . . . . . . . . . . . 8409.3.7.6 Instrumentation Instructions . . . . . . . . . . . . . . . . . . . . . . . . 8419.3.7.7 Intrinsic Call Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . 8419.3.7.8 Constant Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8469.3.7.9 Memory Access Instructions . . . . . . . . . . . . . . . . . . . . . . . . 8489.3.7.10 Atomic Memory Access Instructions . . . . . . . . . . . . . . . 848

xviii Guile Reference Manual

9.3.7.11 Tagging and Untagging Instructions . . . . . . . . . . . . . . . . 8499.3.7.12 Integer Arithmetic Instructions . . . . . . . . . . . . . . . . . . . . 8499.3.7.13 Floating-Point Arithmetic Instructions . . . . . . . . . . . . . 8509.3.7.14 Comparison Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . 8509.3.7.15 Branch Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8539.3.7.16 Raw Memory Access Instructions . . . . . . . . . . . . . . . . . . 853

9.3.8 Just-In-Time Native Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8549.4 Compiling to the Virtual Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856

9.4.1 Compiler Tower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8569.4.2 The Scheme Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8589.4.3 Tree-IL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8599.4.4 Continuation-Passing Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863

9.4.4.1 An Introduction to CPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8639.4.4.2 CPS in Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8649.4.4.3 Building CPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8699.4.4.4 CPS Soup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8709.4.4.5 Compiling CPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872

9.4.5 Bytecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8739.4.6 Writing New High-Level Languages . . . . . . . . . . . . . . . . . . . . . . 8759.4.7 Extending the Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875

Appendix A GNU Free Documentation License . . 877

Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885

Procedure Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891

Variable Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935

Type Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939

R5RS Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941

1

Preface

This manual describes how to use Guile, GNU’s Ubiquitous Intelligent Language for Ex-tensions. It relates particularly to Guile version 3.0.4.

Contributors to this Manual

Like Guile itself, the Guile reference manual is a living entity, cared for by many peopleover a long period of time. As such, it is hard to identify individuals of whom to say “yes,this single person wrote the manual.”

Still, among the many contributions, some caretakers stand out. First among them isNeil Jerram, who has worked on this document for over ten years. Neil’s attention both todetail and to the big picture have made a real difference in the understanding of a generationof Guile hackers.

Next we should note Marius Vollmer’s effect on this document. Marius maintained Guileduring a period in which Guile’s API was clarified—put to the fire, so to speak—and hehad the good sense to effect the same change on the manual.

Martin Grabmueller made substantial contributions throughout the manual in prepara-tion for the Guile 1.6 release, including filling out a lot of the documentation of Schemedata types, control mechanisms and procedures. In addition, he wrote the documentationfor Guile’s SRFI modules and modules associated with the Guile REPL.

Ludovic Courtès and Andy Wingo, who co-maintain Guile since 2010, along with MarkWeaver, have also made their dent in the manual, writing documentation for new modulesand subsystems that arrived with Guile 2.0. Ludovic, Andy, and Mark are also responsiblefor ensuring that the existing text retains its relevance as Guile evolves. See Section 2.6[Reporting Bugs], page 12, for more information on reporting problems in this manual.

The content for the first versions of this manual incorporated and was inspired by docu-ments from Aubrey Jaffer, author of the SCM system on which Guile was based, and fromTom Lord, Guile’s first maintainer. Although most of this text has been rewritten, all of itwas important, and some of the structure remains.

The manual for the first versions of Guile were largely written, edited, and compiled byMark Galassi and Jim Blandy. In particular, Jim wrote the original tutorial on Guile’s datarepresentation and the C API for accessing Guile objects.

Significant portions were also contributed by Thien-Thi Nguyen, Kevin Ryde, MikaelDjurfeldt, Christian Lynbech, Julian Graham, Gary Houston, Tim Pierce, and a few dozenmore. You, reader, are most welcome to join their esteemed ranks. Visit Guile’s web siteat http://www.gnu.org/software/guile/ to find out how to get involved.

The Guile License

Guile is Free Software. Guile is copyrighted, not public domain, and there are restrictionson its distribution or redistribution, but these restrictions are designed to permit everythinga cooperating person would want to do.

• The Guile library (libguile) and supporting files are published under the terms of theGNU Lesser General Public License version 3 or later. See the files COPYING.LESSERand COPYING.

http://www.gnu.org/software/guile/

2 Guile Reference Manual

• The Guile readline module is published under the terms of the GNU General PublicLicense version 3 or later. See the file COPYING.

• The manual you’re now reading is published under the terms of the GNU Free Docu-mentation License (see Appendix A [GNU Free Documentation License], page 877).

C code linking to the Guile library is subject to terms of that library. Basically suchcode may be published on any terms, provided users can re-link against a new or modifiedversion of Guile.

C code linking to the Guile readline module is subject to the terms of that module.Basically such code must be published on Free terms.

Scheme level code written to be run by Guile (but not derived from Guile itself) is notrestricted in any way, and may be published on any terms. We encourage authors to publishon Free terms.

You must be aware there is no warranty whatsoever for Guile. This is described in fullin the licenses.

3

1 Introduction

Guile is an implementation of the Scheme programming language. Scheme (http://schemers.org/) is an elegant and conceptually simple dialect of Lisp, originated by GuySteele and Gerald Sussman, and since evolved by the series of reports known as RnRS (theRevisedn Reports on Scheme).

Unlike, for example, Python or Perl, Scheme has no benevolent dictator. There are manyScheme implementations, with different characteristics and with communities and academicactivities around them, and the language develops as a result of the interplay between these.Guile’s particular characteristics are that

• it is easy to combine with other code written in C• it has a historical and continuing connection with the GNU Project• it emphasizes interactive and incremental programming• it actually supports several languages, not just Scheme.

The next few sections explain what we mean by these points. The sections after that coverhow you can obtain and install Guile, and the typographical conventions that we use in thismanual.

1.1 Guile and Scheme

Guile implements Scheme as described in the Revised5 Report on the Algorithmic LanguageScheme (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 amodule system, full access to POSIX system calls, networking support, multiple threads,dynamic linking, a foreign function call interface, powerful string processing, and manyother features needed for programming in the real world.

In 2007, the Scheme community agreed upon and published R6RS, a significant install-ment in the RnRS series. R6RS expands the core Scheme language, and standardises manynon-core functions that implementations—including Guile—have previously done in differ-ent ways. Over time, Guile has been updated to incorporate almost all of the featuresof R6RS, and to adjust some existing features to conform to the R6RS specification. SeeSection 7.6 [R6RS Support], page 662, for full details.

In parallel to official standardization efforts, the SRFI process (http://srfi.schemers.org/) standardises interfaces for many practical needs, such as multithreadedprogramming and multidimensional arrays. Guile supports many SRFIs, as documented indetail in Section 7.5 [SRFI Support], page 582.

The process that led to the R6RS standard brought a split in the Scheme community tothe surface. The implementors that wrote R6RS considered that it was impossible to writeuseful, portable programs in R5RS, and that only an ambitious standard could solve thisproblem. However, part of the Scheme world saw th