Guile Reference Manual 2.0.9

7/27/2019 Guile Reference Manual 2.0.9

1/880

Guile Reerence ManualEdition 2.0.9, revision 1, or use with Guile 2.0.9

The Guile Developers


2/880

This manual documents Guile version 2.0.9.Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010, 2011, 2012, 2013Free Sotware Foundation.

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


3/880

i

Table o Contents

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

1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.1 Guile and Scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Combining with C Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Guile and the GNU Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4 Interactive Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.5 Supporting Multiple Languages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.6 Obtaining and Installing Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.7 Organisation o this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.8 Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

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 Dening and Setting Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.2 The Representation and Use o Procedures . . . . . . . . . . . . . . . . . . . . 173.2.1 Procedures as Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173.2.2 Simple Procedure Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183.2.3 Creating and Using a New Procedure . . . . . . . . . . . . . . . . . . . . . 19

3.2.4 Lambda Alternatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203.3 Expressions and Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.3.1 Evaluating Expressions and Executing Programs . . . . . . . . . . 213.3.1.1 Evaluating Literal Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213.3.1.2 Evaluating a Variable Reerence . . . . . . . . . . . . . . . . . . . . . 223.3.1.3 Evaluating a Procedure Invocation Expression . . . . . . . 223.3.1.4 Evaluating Special Syntactic Expressions . . . . . . . . . . . . 23

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


4/880

ii Guile Reerence Manual

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

3.4 The Concept o 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 o 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 Guiles Implementation o Scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

4.2 Invoking Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354.2.1 Command-line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354.2.2 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

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

4.4 Using Guile Interactively . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464.4.1 The Init File, ~/.guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464.4.2 Readline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

4.4.3 Value History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474.4.4 REPL Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484.4.4.1 Help Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484.4.4.2 Module Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494.4.4.3 Language Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494.4.4.4 Compile Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494.4.4.5 Prole Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504.4.4.6 Debug Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504.4.4.7 Inspect Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514.4.4.8 System Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

4.4.5 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524.4.6 Interactive Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

4.5 Using Guile in Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554.6 Using Guile Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554.7 Installing Site Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56


5/880

iii

5 Programming in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575.1 Parallel Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575.2 Linking Programs With Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

5.2.1 Guile Initialization Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585.2.2 A Sample Guile Main Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

5.3 Linking Guile with Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615.3.1 A Sample Guile Extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615.4 General concepts or using libguile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

5.4.1 Dynamic Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635.4.2 Garbage Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655.4.3 Control Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665.4.4 Asynchronous Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685.4.5 Multi-Threading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

5.5 Dening New Types (Smobs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715.5.1 Describing a New Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715.5.2 Creating Smob Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735.5.3 Type checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

5.5.4 Garbage Collecting Smobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765.5.5 Garbage Collecting Simple Smobs . . . . . . . . . . . . . . . . . . . . . . . . 775.5.6 Remembering During Operations . . . . . . . . . . . . . . . . . . . . . . . . . 785.5.7 Double Smobs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795.5.8 The Complete Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

5.6 Function Snarng . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825.7 An Overview o Guile Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

5.7.1 How One Might Extend Dia Using Guile. . . . . . . . . . . . . . . . . . 845.7.1.1 Deciding Why You Want to Add Guile . . . . . . . . . . . . . . 845.7.1.2 Four Steps Required to Add Guile . . . . . . . . . . . . . . . . . . . 855.7.1.3 How to Represent Dia Data in Scheme. . . . . . . . . . . . . . . 855.7.1.4 Writing Guile Primitives or Dia . . . . . . . . . . . . . . . . . . . . . 875.7.1.5 Providing a Hook or the Evaluation o Scheme Code

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885.7.1.6 Top-level Structure o Guile-enabled Dia . . . . . . . . . . . . . 885.7.1.7 Going Further with Dia and Guile . . . . . . . . . . . . . . . . . . . 89

5.7.2 Why Scheme is More Hackable Than C . . . . . . . . . . . . . . . . . . . 915.7.3 Example: Using Guile or an Application Testbed. . . . . . . . . 915.7.4 A Choice o Programming Options . . . . . . . . . . . . . . . . . . . . . . . 92

5.7.4.1 What Functionality is Already Available? . . . . . . . . . . . . 925.7.4.2 Functional and Perormance Constraints . . . . . . . . . . . . . 935.7.4.3 Your Preerred Programming Style . . . . . . . . . . . . . . . . . . 935.7.4.4 What Controls Program Execution? . . . . . . . . . . . . . . . . . 93

5.7.5 How About Application Users? . . . . . . . . . . . . . . . . . . . . . . . . . . . 935.8 Autocon Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955.8.1 Autocon Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955.8.2 Autocon Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955.8.3 Using Autocon Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97


6/880

iv Guile Reerence Manual

6 API Reerence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996.1 Overview o the Guile API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996.2 Deprecation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006.3 The SCM Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006.4 Initializing Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

6.5 Snarng Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026.6 Simple Generic Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1046.6.1 Booleans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1046.6.2 Numerical data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

6.6.2.1 Schemes Numerical Tower . . . . . . . . . . . . . . . . . . . . . . . 1056.6.2.2 Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1066.6.2.3 Real and Rational Numbers . . . . . . . . . . . . . . . . . . . . . . . . 1106.6.2.4 Complex Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126.6.2.5 Exact and Inexact Numbers . . . . . . . . . . . . . . . . . . . . . . . . 1136.6.2.6 Read Syntax or Numerical Data . . . . . . . . . . . . . . . . . . . 1146.6.2.7 Operations on Integer Values . . . . . . . . . . . . . . . . . . . . . . . 1156.6.2.8 Comparison Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

6.6.2.9 Converting Numbers To and From Strings . . . . . . . . . . 1176.6.2.10 Complex Number Operations . . . . . . . . . . . . . . . . . . . . . . 1186.6.2.11 Arithmetic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1196.6.2.12 Scientic Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1236.6.2.13 Bitwise Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1246.6.2.14 Random Number Generation . . . . . . . . . . . . . . . . . . . . . . 127

6.6.3 Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1296.6.4 Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

6.6.4.1 Character Set Predicates/Comparison . . . . . . . . . . . . . . 1336.6.4.2 Iterating Over Character Sets . . . . . . . . . . . . . . . . . . . . . . 1346.6.4.3 Creating Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1356.6.4.4 Querying Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366.6.4.5 Character-Set Algebra . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1376.6.4.6 Standard Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

6.6.5 Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1406.6.5.1 String Read Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1416.6.5.2 String Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1426.6.5.3 String Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436.6.5.4 List/String conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1446.6.5.5 String Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1456.6.5.6 String Modication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1476.6.5.7 String Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1486.6.5.8 String Searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

6.6.5.9 Alphabetic Case Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . 1536.6.5.10 Reversing and Appending Strings. . . . . . . . . . . . . . . . . . 1556.6.5.11 Mapping, Folding, and Unolding . . . . . . . . . . . . . . . . . . 1566.6.5.12 Miscellaneous String Operations . . . . . . . . . . . . . . . . . . . 1576.6.5.13 Representing Strings as Bytes . . . . . . . . . . . . . . . . . . . . . 1586.6.5.14 Conversion to/rom C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1596.6.5.15 String Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

6.6.6 Bytevectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163


7/880

v

6.6.6.1 Endianness. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636.6.6.2 Manipulating Bytevectors . . . . . . . . . . . . . . . . . . . . . . . . . . 1646.6.6.3 Interpreting Bytevector Contents as Integers . . . . . . . . 1656.6.6.4 Converting Bytevectors to/rom Integer Lists . . . . . . . 1676.6.6.5 Interpreting Bytevector Contents as Floating Point

Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1686.6.6.6 Interpreting Bytevector Contents as Unicode Strings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1696.6.6.7 Accessing Bytevectors with the Array API . . . . . . . . . . 1696.6.6.8 Accessing Bytevectors with the SRFI-4 API . . . . . . . . 170

6.6.7 Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1706.6.7.1 Symbols as Discrete Data . . . . . . . . . . . . . . . . . . . . . . . . . . 1716.6.7.2 Symbols as Lookup Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 1726.6.7.3 Symbols as Denoting Variables . . . . . . . . . . . . . . . . . . . . . 1736.6.7.4 Operations Related to Symbols . . . . . . . . . . . . . . . . . . . . . 1736.6.7.5 Function Slots and Property Lists . . . . . . . . . . . . . . . . . . 1766.6.7.6 Extended Read Syntax or Symbols. . . . . . . . . . . . . . . . . 177

6.6.7.7 Uninterned Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1786.6.8 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1796.6.8.1 Why Use Keywords? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1796.6.8.2 Coding With Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1806.6.8.3 Keyword Read Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1816.6.8.4 Keyword Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

6.6.9 Functionality-Centric Data Types . . . . . . . . . . . . . . . . . . . . . 1846.7 Compound Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

6.7.1 Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1846.7.2 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

6.7.2.1 List Read Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1876.7.2.2 List Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

6.7.2.3 List Constructors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1886.7.2.4 List Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1896.7.2.5 Append and Reverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1906.7.2.6 List Modication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1906.7.2.7 List Searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1926.7.2.8 List Mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

6.7.3 Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1936.7.3.1 Read Syntax or Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1936.7.3.2 Dynamic Vector Creation and Validation . . . . . . . . . . . 1936.7.3.3 Accessing and Modiying Vector Contents. . . . . . . . . . . 1946.7.3.4 Vector Accessing rom C . . . . . . . . . . . . . . . . . . . . . . . . . . . 1956.7.3.5 Uniorm Numeric Vectors. . . . . . . . . . . . . . . . . . . . . . . . . . . 197

6.7.4 Bit Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976.7.5 Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

6.7.5.1 Array Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2006.7.5.2 Array Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2016.7.5.3 Shared Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2056.7.5.4 Accessing Arrays rom C . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

6.7.6 VLists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212


8/880

vi Guile Reerence Manual

6.7.7 Record Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2146.7.8 SRFI-9 Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Non-toplevel Record Denitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Custom Printers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Functional Setters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

6.7.9 Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2186.7.10 Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

6.7.10.1 Vtables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2206.7.10.2 Structure Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2216.7.10.3 Vtable Contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2226.7.10.4 Meta-Vtables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2236.7.10.5 Vtable Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2246.7.10.6 Tail Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

6.7.11 Dictionary Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2276.7.12 Association Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

6.7.12.1 Alist Key Equality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2276.7.12.2 Adding or Setting Alist Entries . . . . . . . . . . . . . . . . . . . . 228

6.7.12.3 Retrieving Alist Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . 2306.7.12.4 Removing Alist Entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2306.7.12.5 Sloppy Alist Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2316.7.12.6 Alist Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

6.7.13 VList-Based Hash Lists or VHashes . . . . . . . . . . . . . . . . . . 2336.7.14 Hash Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

6.7.14.1 Hash Table Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2356.7.14.2 Hash Table Reerence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

6.8 Smobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2406.9 Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

6.9.1 Lambda: Basic Procedure Creation. . . . . . . . . . . . . . . . . . . . . . 2436.9.2 Primitive Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

6.9.3 Compiled Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2456.9.4 Optional Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

6.9.4.1 lambda* and dene*. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2486.9.4.2 (ice-9 optargs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

6.9.5 Case-lambda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2506.9.6 Higher-Order Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2526.9.7 Procedure Properties and Meta-inormation . . . . . . . . . . . . . 2536.9.8 Procedures with Setters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2546.9.9 Inlinable Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

6.10 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2566.10.1 Dening Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2566.10.2 Syntax-rules Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

6.10.2.1 Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2586.10.2.2 Hygiene . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2606.10.2.3 Shorthands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2616.10.2.4 Further Inormation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

6.10.3 Support or the syntax-case System . . . . . . . . . . . . . . . . . . . 2616.10.3.1 Why syntax-case? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

6.10.4 Syntax Transormer Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266


9/880

vii

6.10.5 Lisp-style Macro Denitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2686.10.6 Identier Macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2696.10.7 Syntax Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2706.10.8 Eval-when . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2726.10.9 Internal Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

6.11 General Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2736.11.1 Equality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2736.11.2 Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2756.11.3 Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2766.11.4 Copying Deep Structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2786.11.5 General String Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2786.11.6 Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

6.11.6.1 Hook Usage by Example . . . . . . . . . . . . . . . . . . . . . . . . . . 2796.11.6.2 Hook Reerence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2806.11.6.3 Handling Scheme-level hooks rom C code . . . . . . . . . 2816.11.6.4 Hooks For C Code.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2816.11.6.5 Hooks or Garbage Collection . . . . . . . . . . . . . . . . . . . . . 283

6.11.6.6 Hooks into the Guile REPL . . . . . . . . . . . . . . . . . . . . . . . 2836.12 Denitions and Variable Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . 2846.12.1 Top Level Variable Denitions. . . . . . . . . . . . . . . . . . . . . . . . . . 2846.12.2 Local Variable Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2856.12.3 Internal denitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2866.12.4 Querying variable bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

6.13 Controlling the Flow o Program Execution . . . . . . . . . . . . . . . . . 2886.13.1 Sequencing and Splicing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2886.13.2 Simple Conditional Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . 2896.13.3 Conditional Evaluation o a Sequence o Expressions . . . . 2916.13.4 Iteration mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2916.13.5 Prompts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

6.13.5.1 Prompt Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2936.13.5.2 Shit, Reset, and All That . . . . . . . . . . . . . . . . . . . . . . . . . 296

6.13.6 Continuations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2976.13.7 Returning and Accepting Multiple Values . . . . . . . . . . . . . . 2996.13.8 Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

6.13.8.1 Exception Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3016.13.8.2 Catching Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3016.13.8.3 Throw Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3036.13.8.4 Throwing Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3056.13.8.5 How Guile Implements Exceptions. . . . . . . . . . . . . . . . . 305

6.13.9 Procedures or Signaling Errors . . . . . . . . . . . . . . . . . . . . . . . . 3066.13.10 Dynamic Wind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3076.13.11 How to Handle Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

6.13.11.1 C Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3116.13.11.2 Signalling Type Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

6.13.12 Continuation Barriers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3126.14 Input and Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

6.14.1 Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3136.14.2 Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315


10/880

viii Guile Reerence Manual

6.14.3 Writing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3176.14.4 Closing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3186.14.5 Random Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3196.14.6 Line Oriented and Delimited Text . . . . . . . . . . . . . . . . . . . . . . 3196.14.7 Block reading and writing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3216.14.8 Deault Ports or Input, Output and Errors . . . . . . . . . . . . . 3226.14.9 Types o Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

6.14.9.1 File Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3246.14.9.2 String Ports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3276.14.9.3 Sot Ports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3286.14.9.4 Void Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

6.14.10 R6RS I/O Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3296.14.10.1 File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3296.14.10.2 File Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3306.14.10.3 Bufer Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3306.14.10.4 Transcoders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3316.14.10.5 The End-o-File Object . . . . . . . . . . . . . . . . . . . . . . . . . . 334

6.14.10.6 Port Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3346.14.10.7 Input Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3356.14.10.8 Binary Input. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3366.14.10.9 Textual Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3386.14.10.10 Output Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3406.14.10.11 Binary Output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3416.14.10.12 Textual Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

6.14.11 Using and Extending Ports in C. . . . . . . . . . . . . . . . . . . . . . . 3426.14.11.1 C Port Interace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3426.14.11.2 Port Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

6.14.12 Handling o Unicode byte order marks. . . . . . . . . . . . . . . . . 3466.15 Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

6.15.1 Regexp Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3476.15.2 Match Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3516.15.3 Backslash Escapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

6.16 LALR(1) Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3536.17 Reading and Evaluating Scheme Code . . . . . . . . . . . . . . . . . . . . . . . 354

6.17.1 Scheme Syntax: Standard and Guile Extensions . . . . . . . . 3546.17.1.1 Expression Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3546.17.1.2 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3566.17.1.3 Block Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3566.17.1.4 Case Sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3566.17.1.5 Keyword Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3576.17.1.6 Reader Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

6.17.2 Reading Scheme Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3576.17.3 Writing Scheme Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3586.17.4 Procedures or On the Fly Evaluation . . . . . . . . . . . . . . . . . . 3596.17.5 Compiling Scheme Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3616.17.6 Loading Scheme Code rom File . . . . . . . . . . . . . . . . . . . . . . . . 3636.17.7 Load Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3656.17.8 Character Encoding o Source Files . . . . . . . . . . . . . . . . . . . . . 367


11/880

ix

6.17.9 Delayed Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3686.17.10 Local Evaluation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3686.17.11 Local Inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3696.17.12 REPL Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

6.18 Memory Management and Garbage Collection . . . . . . . . . . . . . . . 3716.18.1 Function related to Garbage Collection . . . . . . . . . . . . . . . . . 3716.18.2 Memory Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372

6.18.2.1 Upgrading rom scm must malloc et al. . . . . . . . . . . . 3746.18.3 Weak Reerences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

6.18.3.1 Weak hash tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3756.18.3.2 Weak vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

6.18.4 Guardians . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3766.19 Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

6.19.1 General Inormation about Modules . . . . . . . . . . . . . . . . . . . . 3776.19.2 Using Guile Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3786.19.3 Creating Guile Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3806.19.4 Modules and the File System . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

6.19.5 R6RS Version Reerences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3836.19.6 R6RS Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3846.19.7 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3866.19.8 Module System Reection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3876.19.9 Accessing Modules rom C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3896.19.10 provide and require . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3916.19.11 Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392

6.20 Foreign Function Interace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3926.20.1 Foreign Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3926.20.2 Foreign Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3946.20.3 C Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3956.20.4 Modules and Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

6.20.5 Foreign Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3986.20.5.1 Foreign Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3986.20.5.2 Foreign Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3996.20.5.3 Void Pointers and Byte Access . . . . . . . . . . . . . . . . . . . . 4006.20.5.4 Foreign Structs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

6.20.6 Dynamic FFI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4036.21 Threads, Mutexes, Asyncs and Dynamic Roots . . . . . . . . . . . . . . 406

6.21.1 Arbiters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4066.21.2 Asyncs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

6.21.2.1 System asyncs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4076.21.2.2 User asyncs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408

6.21.3 Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4096.21.4 Mutexes and Condition Variables. . . . . . . . . . . . . . . . . . . . . . . 4116.21.5 Blocking in Guile Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4146.21.6 Critical Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4156.21.7 Fluids and Dynamic States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4156.21.8 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4186.21.9 Futures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4206.21.10 Parallel orms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421


12/880

x Guile Reerence Manual

6.22 Conguration, Features and Runtime Options . . . . . . . . . . . . . . . 4236.22.1 Conguration, Build and Installation . . . . . . . . . . . . . . . . . . . 4236.22.2 Feature Tracking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

6.22.2.1 Feature Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4256.22.2.2 Common Feature Symbols . . . . . . . . . . . . . . . . . . . . . . . . . 425

6.22.3 Runtime Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4276.22.3.1 Examples o option use. . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

6.23 Support or Other Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4286.23.1 Using Other Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4286.23.2 Emacs Lisp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

6.23.2.1 Nil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4296.23.2.2 Equality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4306.23.2.3 Dynamic Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4316.23.2.4 Other Elisp Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

6.23.3 ECMAScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4316.24 Support or Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

6.24.1 Internationalization with Guile . . . . . . . . . . . . . . . . . . . . . . . . . 432

6.24.2 Text Collation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4336.24.3 Character Case Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4346.24.4 Number Input and Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4356.24.5 Accessing Locale Inormation. . . . . . . . . . . . . . . . . . . . . . . . . . . 4356.24.6 Gettext Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438

6.25 Debugging Inrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4406.25.1 Evaluation and the Scheme Stack . . . . . . . . . . . . . . . . . . . . . . 441

6.25.1.1 Stack Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4416.25.1.2 Stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4426.25.1.3 Frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442

6.25.2 Source Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4436.25.3 Programmatic Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . 445

6.25.3.1 Catching Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4456.25.3.2 Capturing the ull error stack. . . . . . . . . . . . . . . . . . . . . . 4466.25.3.3 Pre-Unwind Debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . 4496.25.3.4 Debug options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

6.25.4 Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4516.25.4.1 VM Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4516.25.4.2 Trap Interace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4536.25.4.3 Low-Level Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4546.25.4.4 Tracing Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4566.25.4.5 Trap States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4576.25.4.6 High-Level Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458

6.26 Code Coverage Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460


13/880

xi

7 Guile Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4637.1 SLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463

7.1.1 SLIB installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4637.1.2 JACAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464

7.2 POSIX System Calls and Networking . . . . . . . . . . . . . . . . . . . . . . . . . 464

7.2.1 POSIX Interace Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4647.2.2 Ports and File Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4657.2.3 File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4727.2.4 User Inormation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4797.2.5 Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4817.2.6 Runtime Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4847.2.7 Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4867.2.8 Signals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4927.2.9 Terminals and Ptys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4957.2.10 Pipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4967.2.11 Networking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497

7.2.11.1 Network Address Conversion . . . . . . . . . . . . . . . . . . . . . . 497

7.2.11.2 Network Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4997.2.11.3 Network Socket Address . . . . . . . . . . . . . . . . . . . . . . . . . . . 5057.2.11.4 Network Sockets and Communication . . . . . . . . . . . . . . 5077.2.11.5 Network Socket Examples . . . . . . . . . . . . . . . . . . . . . . . . . 513

7.2.12 System Identication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5147.2.13 Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5147.2.14 Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515

7.3 HTTP, the Web, and All That . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5157.3.1 Types and the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5167.3.2 Universal Resource Identiers . . . . . . . . . . . . . . . . . . . . . . . . . . . 5177.3.3 The Hyper-Text Transer Protocol . . . . . . . . . . . . . . . . . . . . . . . 5197.3.4 HTTP Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522

7.3.4.1 HTTP Header Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5227.3.4.2 General Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5237.3.4.3 Entity Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5247.3.4.4 Request Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5267.3.4.5 Response Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528

7.3.5 Transer Codings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5297.3.6 HTTP Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530

7.3.6.1 An Important Note on Character Sets . . . . . . . . . . . . . . 5307.3.6.2 Request API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531

7.3.7 HTTP Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5337.3.8 Web Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535

7.3.9 Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5367.3.10 Web Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5397.3.10.1 Hello, World!. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5397.3.10.2 Inspecting the Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5407.3.10.3 Higher-Level Interaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5417.3.10.4 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542

7.4 The (ice-9 getopt-long) Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5427.4.1 A Short getopt-long Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . 543


14/880

xii Guile Reerence Manual

7.4.2 How to Write an Option Specication . . . . . . . . . . . . . . . . . . . 5447.4.3 Expected Command Line Format. . . . . . . . . . . . . . . . . . . . . . . . 5447.4.4 Reerence Documentation or getopt-long . . . . . . . . . . . . . . 5457.4.5 Reerence Documentation or option-ref . . . . . . . . . . . . . . . 547

7.5 SRFI Support Modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5477.5.1 About SRFI Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5477.5.2 SRFI-0 - cond-expand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5487.5.3 SRFI-1 - List library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549

7.5.3.1 Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5497.5.3.2 Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5507.5.3.3 Selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5517.5.3.4 Length, Append, Concatenate, etc. . . . . . . . . . . . . . . . . . 5527.5.3.5 Fold, Unold & Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5537.5.3.6 Filtering and Partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . 5567.5.3.7 Searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5567.5.3.8 Deleting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5587.5.3.9 Association Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559

7.5.3.10 Set Operations on Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . 5597.5.4 SRFI-2 - and-let* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5627.5.5 SRFI-4 - Homogeneous numeric vector datatypes . . . . . . . . 563

7.5.5.1 SRFI-4 - Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5637.5.5.2 SRFI-4 - API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5647.5.5.3 SRFI-4 - Generic operations . . . . . . . . . . . . . . . . . . . . . . . . 5707.5.5.4 SRFI-4 - Relation to bytevectors. . . . . . . . . . . . . . . . . . . . 5717.5.5.5 SRFI-4 - Guile extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 572

7.5.6 SRFI-6 - Basic String Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5727.5.7 SRFI-8 - receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5737.5.8 SRFI-9 - dene-record-type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5737.5.9 SRFI-10 - Hash-Comma Reader Extension . . . . . . . . . . . . . . . 573

7.5.10 SRFI-11 - let-values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5757.5.11 SRFI-13 - String Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5757.5.12 SRFI-14 - Character-set Library . . . . . . . . . . . . . . . . . . . . . . . . 5757.5.13 SRFI-16 - case-lambda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5757.5.14 SRFI-17 - Generalized set! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5757.5.15 SRFI-18 - Multithreading support . . . . . . . . . . . . . . . . . . . . . . 576

7.5.15.1 SRFI-18 Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5767.5.15.2 SRFI-18 Mutexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5787.5.15.3 SRFI-18 Condition variables . . . . . . . . . . . . . . . . . . . . . . . 5797.5.15.4 SRFI-18 Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5797.5.15.5 SRFI-18 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580

7.5.16 SRFI-19 - Time/Date Library . . . . . . . . . . . . . . . . . . . . . . . . . . 5817.5.16.1 SRFI-19 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5817.5.16.2 SRFI-19 Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5817.5.16.3 SRFI-19 Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5837.5.16.4 SRFI-19 Time/Date conversions . . . . . . . . . . . . . . . . . . . 5847.5.16.5 SRFI-19 Date to string . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5857.5.16.6 SRFI-19 String to date . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587

7.5.17 SRFI-23 - Error Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588


15/880

xiii

7.5.18 SRFI-26 - specializing parameters . . . . . . . . . . . . . . . . . . . . . . 5887.5.19 SRFI-27 - Sources o Random Bits . . . . . . . . . . . . . . . . . . . . . 589

7.5.19.1 The Deault Random Source . . . . . . . . . . . . . . . . . . . . . . 5897.5.19.2 Random Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5907.5.19.3 Obtaining random number generator procedures . . . 590

7.5.20 SRFI-30 - Nested Multi-line Comments . . . . . . . . . . . . . . . . . 5917.5.21 SRFI-31 - A special orm rec or recursive evaluation . . 5917.5.22 SRFI-34 - Exception handling or programs. . . . . . . . . . . . . 5917.5.23 SRFI-35 - Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5917.5.24 SRFI-37 - args-old. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5947.5.25 SRFI-38 - External Representation or Data With Shared

Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5957.5.26 SRFI-39 - Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5967.5.27 SRFI-41 - Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597

7.5.27.1 SRFI-41 Stream Fundamentals . . . . . . . . . . . . . . . . . . . . 5977.5.27.2 SRFI-41 Stream Primitives . . . . . . . . . . . . . . . . . . . . . . . . 5977.5.27.3 SRFI-41 Stream Library. . . . . . . . . . . . . . . . . . . . . . . . . . . 599

7.5.28 SRFI-42 - Eager Comprehensions. . . . . . . . . . . . . . . . . . . . . . . 6067.5.29 SRFI-45 - Primitives or Expressing Iterative LazyAlgorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606

7.5.30 SRFI-55 - Requiring Features . . . . . . . . . . . . . . . . . . . . . . . . . . 6087.5.31 SRFI-60 - Integers as Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6087.5.32 SRFI-61 - A more general cond clause . . . . . . . . . . . . . . . . . . 6107.5.33 SRFI-67 - Compare procedures . . . . . . . . . . . . . . . . . . . . . . . . . 6107.5.34 SRFI-69 - Basic hash tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610

7.5.34.1 Creating hash tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6107.5.34.2 Accessing table items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6117.5.34.3 Table properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6127.5.34.4 Hash table algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612

7.5.35 SRFI-88 Keyword Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6137.5.36 SRFI-98 Accessing environment variables. . . . . . . . . . . . . . . 6137.5.37 SRFI-105 Curly-inx expressions. . . . . . . . . . . . . . . . . . . . . . . 614

7.6 R6RS Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6147.6.1 Incompatibilities with the R6RS . . . . . . . . . . . . . . . . . . . . . . . . . 6147.6.2 R6RS Standard Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615

7.6.2.1 Library Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6167.6.2.2 rnrs base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6167.6.2.3 rnrs unicode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6237.6.2.4 rnrs bytevectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6247.6.2.5 rnrs lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6247.6.2.6 rnrs sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6257.6.2.7 rnrs control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6267.6.2.8 R6RS Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6267.6.2.9 rnrs records syntactic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6277.6.2.10 rnrs records procedural . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6297.6.2.11 rnrs records inspection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6297.6.2.12 rnrs exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6307.6.2.13 rnrs conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631


16/880


17/880

xv

7.22 SXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6897.22.1 SXML Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6907.22.2 Reading and Writing XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6907.22.3 SSAX: A Functional XML Parsing Toolkit. . . . . . . . . . . . . . 692

7.22.3.1 History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6927.22.3.2 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6937.22.3.3 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694

7.22.4 Transorming SXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6957.22.4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6957.22.4.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696

7.22.5 SXML Tree Fold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6967.22.5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6977.22.5.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697

7.22.6 SXPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6987.22.6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6987.22.6.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699

7.22.7 (sxml ssax input-parse) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700

7.22.7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7017.22.7.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7017.22.8 (sxml apply-templates) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701

7.22.8.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7017.22.8.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702

7.23 Texino Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7027.23.1 (texino) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702

7.23.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7027.23.1.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702

7.23.2 (texino docbook) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7037.23.2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7037.23.2.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703

7.23.3 (texino html). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7047.23.3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7047.23.3.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704

7.23.4 (texino indexing) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7057.23.4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7057.23.4.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705

7.23.5 (texino string-utils). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7057.23.5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7057.23.5.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705

7.23.6 (texino plain-text) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7087.23.6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7087.23.6.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708

7.23.7 (texino serialize) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7087.23.7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7087.23.7.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708

7.23.8 (texino reection) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7087.23.8.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7087.23.8.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708


18/880

xvi Guile Reerence Manual

8 GOOPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7118.1 Copyright Notice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7118.2 Class Denition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7118.3 Instance Creation and Slot Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7128.4 Slot Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713

8.5 Illustrating Slot Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7168.6 Methods and Generic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7188.6.1 Accessors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7208.6.2 Extending Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7208.6.3 Merging Generics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7208.6.4 Next-method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7218.6.5 Generic Function and Method Examples . . . . . . . . . . . . . . . . . 7228.6.6 Handling Invocation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725

8.7 Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7258.7.1 Class Precedence List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7268.7.2 Sorting Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727

8.8 Introspection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728

8.8.1 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7288.8.2 Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7298.8.3 Slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7298.8.4 Generic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7318.8.5 Accessing Slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732

8.9 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7348.10 GOOPS Object Miscellany . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7348.11 The Metaobject Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735

8.11.1 Metaobjects and the Metaobject Protocol . . . . . . . . . . . . . . 7358.11.2 Metaclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7378.11.3 MOP Specication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7388.11.4 Instance Creation Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7388.11.5 Class Denition Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7398.11.6 Customizing Class Denition . . . . . . . . . . . . . . . . . . . . . . . . . . . 7428.11.7 Method Denition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7448.11.8 Method Denition Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7448.11.9 Generic Function Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7458.11.10 Generic Function Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . 746

8.12 Redening a Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7478.12.1 Deault Class Redenition Behaviour . . . . . . . . . . . . . . . . . . . 7478.12.2 Customizing Class Redenition . . . . . . . . . . . . . . . . . . . . . . . . . 747

8.13 Changing the Class o an Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . 748


19/880

xvii

9 Guile Implementation. . . . . . . . . . . . . . . . . . . . . . . . 7519.1 A Brie History o Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751

9.1.1 The Emacs Thesis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7519.1.2 Early Days. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7519.1.3 A Scheme o Many Maintainers. . . . . . . . . . . . . . . . . . . . . . . . . . 752

9.1.4 A Timeline o Selected Guile Releases . . . . . . . . . . . . . . . . . . . 7539.1.5 Status, or: Your Help Needed . . . . . . . . . . . . . . . . . . . . . . . . . . . 7549.2 Data Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755

9.2.1 A Simple Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7569.2.2 Faster Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7569.2.3 Cheaper Pairs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7589.2.4 Conservative Garbage Collection . . . . . . . . . . . . . . . . . . . . . . . . 7599.2.5 The SCM Type in Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760

9.2.5.1 Relationship between SCM and scm_t_bits . . . . . . . . . . 7609.2.5.2 Immediate objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7619.2.5.3 Non-immediate objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7629.2.5.4 Allocating Cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762

9.2.5.5 Heap Cell Type Inormation . . . . . . . . . . . . . . . . . . . . . . . . 7639.2.5.6 Accessing Cell Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763

9.3 A Virtual Machine or Guile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7649.3.1 Why a VM? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7649.3.2 VM Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7659.3.3 Stack Layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7669.3.4 Variables and the VM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7679.3.5 Compiled Procedures are VM Programs . . . . . . . . . . . . . . . . . 7689.3.6 Instruction Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769

9.3.6.1 Lexical Environment Instructions . . . . . . . . . . . . . . . . . . . 7699.3.6.2 Top-Level Environment Instructions . . . . . . . . . . . . . . . . 7719.3.6.3 Procedure Call and Return Instructions. . . . . . . . . . . . . 7729.3.6.4 Function Prologue Instructions . . . . . . . . . . . . . . . . . . . . . 7749.3.6.5 Trampoline Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7769.3.6.6 Branch Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7769.3.6.7 Data Constructor Instructions . . . . . . . . . . . . . . . . . . . . . . 7779.3.6.8 Loading Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7789.3.6.9 Dynamic Environment Instructions . . . . . . . . . . . . . . . . . 7799.3.6.10 Miscellaneous Instructions . . . . . . . . . . . . . . . . . . . . . . . . . 7809.3.6.11 Inlined Scheme Instructions . . . . . . . . . . . . . . . . . . . . . . . 7819.3.6.12 Inlined Mathematical Instructions . . . . . . . . . . . . . . . . . 7829.3.6.13 Inlined Bytevector Instructions . . . . . . . . . . . . . . . . . . . . 782

9.4 Compiling to the Virtual Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783

9.4.1 Compiler Tower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7849.4.2 The Scheme Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7859.4.3 Tree-IL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7879.4.4 GLIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7919.4.5 Assembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7949.4.6 Bytecode and Objcode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7959.4.7 Writing New High-Level Languages . . . . . . . . . . . . . . . . . . . . . . 7969.4.8 Extending the Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796


20/880

xviii Guile Reerence Manual

Appendix A GNU Free Documentation License. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799

Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807

Procedure Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

813

Variable Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853

Type Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857

R5RS Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859


21/880

Preace 1

Preace

This manual describes how to use Guile, GNUs Ubiquitous Intelligent Language or Ex-tensions. It relates particularly to Guile version 2.0.9.

Contributors to this Manual

Like Guile itsel, the Guile reerence manual is a living entity, cared or by many peopleover a long period o time. As such, it is hard to identiy individuals o whom to say yes,this person, she wrote the manual.

Still, among the many contributions, some caretakers stand out. First among them isNeil Jerram, who has been working on this document or ten years now. Neils attentionboth to detail and to the big picture have made a real diference in the understanding o ageneration o Guile hackers.

Next we should note Marius Vollmers efect on this document. Marius maintained Guile

during a period in which Guiles API was clariedput to the re, so to speakand hehad the good sense to efect the same change on the manual.

Martin Grabmueller made substantial contributions throughout the manual in prepara-tion or the Guile 1.6 release, including lling out a lot o the documentation o Schemedata types, control mechanisms and procedures. In addition, he wrote the documentationor Guiles SRFI modules and modules associated with the Guile REPL.

Ludovic Courtes and Andy Wingo, the Guile maintainers at the time o this writing (late2010), have also made their dent in the manual, writing documentation or new modulesand subsystems in Guile 2.0. They are also responsible or ensuring that the existing textretains its relevance as Guile evolves. See Section 2.6 [Reporting Bugs], page 12, or moreinormation on reporting problems in this manual.

The content or the rst versions o this manual incorporated and was inspired by docu-ments rom Aubrey Jafer, author o the SCM system on which Guile was based, and romTom Lord, Guiles rst maintainer. Although most o this text has been rewritten, all o itwas important, and some o the structure remains.

The manual or the rst versions o Guile were largely written, edited, and compiled byMark Galassi and Jim Blandy. In particular, Jim wrote the original tutorial on Guiles datarepresentation and the C API or accessing Guile objects.

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

The Guile License

Guile is Free Sotware. 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 les are published under the terms o theGNU Lesser General Public License version 3 or later. See the les COPYING.LESSERand COPYING.
http://www.gnu.org/software/guile/http://www.gnu.org/software/guile/


22/880

2 Guile Reerence Manual

The Guile readline module is published under the terms o the GNU General PublicLicense version 3 or later. See the le COPYING.

The manual youre now reading is published under the terms o the GNU Free Docu-

mentation License (see Appendix A [GNU Free Documentation License], page 799).C code linking to the Guile library is subject to terms o that library. Basically such

code may be published on any terms, provided users can re-link against a new or modiedversion o Guile.

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

Scheme level code written to be run by Guile (but not derived rom Guile itsel) 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 or Guile. This is described in ullin the licenses.


23/880

Chapter 1: Introduction 3

1 Introduction

Guile is an implementation o the Scheme programming language. Scheme (http://schemers.org/

) is an elegant and conceptually simple dialect o Lisp, originated by GuySteele and Gerald Sussman, and since evolved by the series o reports known as RnRS (theRevisedn Reports on Scheme).

Unlike, or example, Python or Perl, Scheme has no benevolent dictator. There are manyScheme implementations, with diferent characteristics and with communities and academicactivities around them, and the language develops as a result o the interplay between these.Guiles 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 ew sections explain what we mean by these points. The sections ater 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, ull access to POSIX system calls, networking support, multiple threads,dynamic linking, a oreign unction call interace, powerul string processing, and many

other eatures needed or programming in the real world.The Scheme community has recently agreed and published R6RS, the latest installment

in the RnRS series. R6RS signicantly expands the core Scheme language, and standardisesmany non-core unctions that implementationsincluding Guilehave previously done indiferent ways. Guile has been updated to incorporate some o the eatures o R6RS, and toadjust some existing eatures to conorm to the R6RS specication, but it is by no meansa complete R6RS implementation. See Section 7.6 [R6RS Support], page 614.

Between R5RS and R6RS, the SRFI process (http://srfi.schemers.org/) standard-ised interaces or many practical needs, such as multithreaded programming and multi-dimensional arrays. Guile supports many SRFIs, as documented in detail in Section 7.5[SRFI Support], page 547.

In summary, so ar as relationship to the Scheme standards is concerned, Guile is anR5RS implementation with many extensions, some o which conorm to SRFIs or to therelevant parts o R6RS.

1.2 Combining with C Code

Like a shell, Guile can run interactivelyreading expressions rom the user, evaluatingthem, and displaying the resultsor as a script interpreter, reading and executing Schemecode rom a le. Guile also provides an object library, libguile, that allows other applications
http://schemers.org/http://schemers.org/http://srfi.schemers.org/http://srfi.schemers.org/http://schemers.org/http://schemers.org/


24/880


to easily incorporate a complete Scheme interpreter. An application can then use Guile asan extension language, a clean and powerul conguration language, or as multi-purposeglue, connecting primitives provided by the application. It is easy to call Scheme coderom C code and vice versa, giving the application designer ull control o how and when toinvoke the interpreter. Applications can add new unctions, data types, control structures,and even syntax to Guile, creating a domain-specic language tailored to the task at hand,but based on a robust language design.

This kind o combination is helped by our aspects o Guiles design and history. First isthat Guile has always been targeted as an extension language. Hence its C API has alwaysbeen o great importance, and has been developed accordingly. Second and third are rathertechnical pointsthat Guile uses conservative garbage collection, and that it implementsthe Scheme concept o continuations by copying and reinstating the C stackbut whosepractical consequence is that most existing C code can be glued into Guile as is, withoutneeding modications to cope with strange Scheme execution ows. Last is the modulesystem, which helps extensions to coexist without stepping on each others toes.

Guiles module system allows one to break up a large program into manageable sectionswith well-dened interaces between them. Modules may contain a mixture o interpretedand compiled code; Guile can use either static or dynamic linking to incorporate compiledcode. Modules also encourage developers to package up useul collections o routines orgeneral distribution; as o this writing, one can nd Emacs interaces, database accessroutines, compilers, GUI toolkit interaces, and HTTP client unctions, among others.

1.3 Guile and the GNU Project

Guile was conceived by the GNU Project ollowing the antastic success o Emacs Lisp as anextension language within Emacs. Just as Emacs Lisp allowed complete and unanticipatedapplications to be written within the Emacs environment, the idea was that Guile shoulddo the same or other GNU Project applications. This remains true today.

The idea o extensibility is closely related to the GNU projects primary goal, that opromoting sotware reedom. Sotware reedom means that people receiving a sotwarepackage can modiy or enhance it to their own desires, including in ways that may not haveoccurred at all to the sotwares original developers. For programs written in a compiledlanguage like C, this reedom covers modiying and rebuilding the C code; but i the programalso provides an extension language, that is usually a much riendlier and lower-barrier-o-entry way or the user to start making their own changes.

Guile is now used by GNU project applications such as AutoGen, Lilypond, Denemo,Mailutils, TeXmacs and Gnucash, and we hope that there will be many more in uture.

1.4 Interactive Programming

Non-ree sotware has no interest in its users being able to see how it works. They aresupposed to just accept it, or to report problems and hope that the source code owners willchoose to work on them.

Free sotware aims to work reliably just as much as non-ree sotware does, but it shouldalso empower its users by making its workings available. This is useul or many reasons,including education, auditing and enhancements, as well as or debugging problems.


25/880

Chapter 1: Introduction 5

The ideal ree sotware system achieves this by making it easy or interested users to seethe source code or a eature that they are using, and to ollow through that source codestep-by-step, as it runs. In Emacs, good examples o this are the source code hyperlinks inthe help system, and edebug. Then, or bonus points and maximising the ability or theuser to experiment quickly with code changes, the system should allow parts o the sourcecode to be modied and reloaded into the running program, to take immediate efect.

Guile is designed or this kind o interactive programming, and this distinguishes itrom many Scheme implementations that instead prioritise running a xed Scheme programas ast as possiblebecause there are tradeofs between perormance and the ability tomodiy parts o an already running program. There are aster Schemes than Guile, butGuile is a GNU project and so prioritises the GNU vision o programming reedom andexperimentation.

1.5 Supporting Multiple Languages

Since the 2.0 release, Guiles architecture supports compiling any language to its core virtualmachine bytecode, and Scheme is just one o the supported languages. Other supportedlanguages are Emacs Lisp, ECMAScript (commonly known as Javascript) and Brainuck,and work is under discussion or Lua, Ruby and Python.

This means that users can program applications which use Guile in the language o theirchoice, rather than having the tastes o the applications author imposed on them.

1.6 Obtaining and Installing Guile

Guile can be obtained rom the main GNU archive site ftp://ftp.gnu.org or any o itsmirrors. The le will be named guile-version.tar.gz. The current version is 2.0.9, so the le

you should grab is:ftp://ftp.gnu.org/gnu/guile/guile-2.0.9.tar.gz

To unbundle Guile use the instruction

zcat guile-2.0.9.tar.gz | tar xvf -

which will create a directory called guile-2.0.9 with all the sources. You can look at thele INSTALL or detailed instructions on how to build and install Guile, but you should beable to just do

cd guile-2.0.9

./configure

make

make install

This will install the Guile executable guile, the Guile library libguile and variousassociated header les and support libraries. It will also install the Guile reerence manual.

Since this manual requently reers to the Scheme standard, also known as R5RS, orthe Revised5 Report on the Algorithmic Language Scheme, we have included the report inthe Guile distribution; see Section Introduction in Revised(5) Report on the AlgorithmicLanguage Scheme. This will also be installed in your ino directory.
ftp://ftp.gnu.org/ftp://ftp.gnu.org/gnu/guile/guile-2.0.9.tar.gzhttp://r5rs.pdf/http://r5rs.pdf/http://r5rs.pdf/http://r5rs.pdf/http://r5rs.pdf/ftp://ftp.gnu.org/gnu/guile/guile-2.0.9.tar.gzftp://ftp.gnu.org/


26/880


1.7 Organisation o this Manual

The rest o this manual is organised into the ollowing chapters.

Chapter 2: Hello Guile!A whirlwind tour shows how Guile can be used interactively and as a scriptinterpreter, how to link Guile into your own applications, and how to writemodules o interpreted and compiled code or use with Guile. Everything in-troduced here is documented again and in ull by the later parts o the manual.

Chapter 3: Hello Scheme!For readers new to Scheme, this chapter provides an introduction to the ba-sic ideas o the Scheme language. This material would apply to any Schemeimplementation and so does not make reerence to anything Guile-specic.

Chapter 4: Programming in Sch

Documents

Guile Reference Manual 2.0.9