Guile Reference Manual
Edition 1.1, for use with Guile 1.8.6

The Guile Developers

Table of Contents

1 Preface ... 1

1.1 Layout of this Manual ... 1
1.2 Conventions used in this Manual ... 1
1.3 Contributors to this Manual ... 2
1.4 The Guile License ... 2

2 Introduction to Guile ... 5

2.1 What is Guile? ... 5

2.2 Obtaining and Installing Guile ... 5

2.3 A Whirlwind Tour ... 6
2.3.1 Running Guile Interactively ... 6
2.3.2 Running Guile Scripts ... 6
2.3.3 Linking Guile into Programs ... 7
2.3.4 Writing Guile Extensions ... 8
2.3.5 Using the Guile Module System ... 8
2.3.5.1 Using Modules ... 8
2.3.5.2 Writing new Modules ... 9
2.3.5.3 Putting Extensions into Modules ... 9

2.4 Discouraged and Deprecated ... 9

2.5 Reporting Bugs ... 10

3 Programming in Scheme ... 13

3.1 Basic Ideas in Scheme ... 13
3.1.1 Data Types, Values and Variables ... 13
3.1.1.1 Latent Typing ... 13
3.1.1.2 Values and Variables ... 14
3.1.1.3 Defining and Setting Variables ... 14
3.1.2 The Representation and Use of Procedures ... 15
3.1.2.1 Procedures as Values ... 15
3.1.2.2 Simple Procedure Invocation ... 16
3.1.2.3 Creating and Using a New Procedure ... 17
3.1.2.4 Lambda Alternatives ... 18
3.1.3 Expressions and Evaluation ... 18
3.1.3.1 Evaluating Expressions and Executing Programs ... 19
3.1.3.2 Tail calls ... 22
3.1.3.3 Using the Guile REPL ... 23
3.1.3.4 Summary of Common Syntax ... 23
3.1.4 The Concept of Closure ... 24
3.1.4.1 Names, Locations, Values and Environments ... 24
3.1.4.2 Local Variables and Environments ... 25
3.1.4.3 Environment Chaining ... 25
3.1.4.4 Lexical Scope ... 26
3.1.4.5 Closure ... 28
3.1.4.6 Example 1: A Serial Number Generator ... 29
3.1.4.7 Example 2: A Shared Persistent Variable ... 29
3.1.4.8 Example 3: The Callback Closure Problem ... 30
3.1.4.9 Example 4: Object Orientation ... 31

3.2 Guile’s Implementation of Scheme ... 32

3.3 Guile Scripting ... 33
3.3.1 The Top of a Script File ... 33
3.3.2 Invoking Guile ... 33
3.3.3 The Meta Switch ... 35
3.3.4 Command Line Handling ... 36
3.3.5 Scripting Examples ... 37

3.4 Using Guile Interactively ... 40
3.4.1 Readline ... 40
3.4.2 Value History ... 40
3.4.3 Error Handling ... 41
3.4.4 Using the Interactive Debugger ... 42
3.4.4.1 Display Backtrace ... 42
3.4.4.2 Frame Selection ... 42
3.4.4.3 Frame Information ... 43
3.4.4.4 Frame Evaluation ... 44
3.4.4.5 Single Stepping and Continuing Execution ... 44

3.5 Using Guile in Emacs ... 44
3.5.1 GDS Introduction ... 46
3.5.2 GDS Architecture ... 46
3.5.3 Getting Started with GDS ... 47
3.5.3.1 Invoking GDS when an Exception Occurs ... 48
3.5.3.2 Accepting GDS Instructions at Any Time ... 49
3.5.3.3 Utility Guile Implementation ... 49
3.5.4 Working with GDS in Scheme Buffers ... 49
3.5.4.1 Access to Guile Help and Completion ... 49
3.5.4.2 Evaluating Scheme Code ... 50
3.5.5 Displaying the Scheme Stack ... 50
3.5.6 Continuing Execution ... 51
3.5.7 Associating Buffers with Clients ... 52
3.5.8 An Example GDS Session ... 53

3.6 Further Reading ... 55

4 Programming in C ... 57

4.1 Linking Programs With Guile ... 57
4.1.1 Guile Initialization Functions ... 57
4.1.2 A Sample Guile Main Program ... 58

4.2 Linking Guile with Libraries ... 60
4.2.1 A Sample Guile Extension ... 60

4.3 General concepts for using libguile ... 62
4.3.1 Dynamic Types ... 62
4.3.2 Garbage Collection ... 64
4.3.3 Control Flow ... 65
4.3.4 Asynchronous Signals ... 67
4.3.5 Multi-Threading ... 68

4.4 Defining New Types (Smobs) ... 71
4.4.1 Describing a New Type ... 71
4.4.2 Creating Instances ... 72
4.4.3 Type checking ... 74
4.4.4 Garbage Collecting Smobs ... 75
4.4.5 Garbage Collecting Simple Smobs ... 77
4.4.6 Remembering During Operations ... 77
4.4.7 Double Smobs ... 78
4.4.8 The Complete Example ... 78

4.5 Function Snarfing ... 82

4.6 An Overview of Guile Programming ... 84
4.6.1 How One Might Extend Dia Using Guile ... 84
4.6.1.1 Deciding Why You Want to Add Guile ... 84
4.6.1.2 Four Steps Required to Add Guile ... 85
4.6.1.3 How to Represent Dia Data in Scheme ... 85
4.6.1.4 Writing Guile Primitives for Dia ... 87
4.6.1.5 Providing a Hook for the Evaluation of Scheme Code ... 88
4.6.1.6 Top-level Structure of Guile-enabled Dia ... 88
4.6.1.7 Going Further with Dia and Guile ... 89
4.6.2 Why Scheme is More Hackable Than C ... 90
4.6.3 Example: Using Guile for an Application Testbed ... 91
4.6.4 A Choice of Programming Options ... 91
4.6.4.1 What Functionality is Already Available? ... 92
4.6.4.2 Functional and Performance Constraints ... 93
4.6.4.3 Your Preferred Programming Style ... 93
4.6.4.4 What Controls Program Execution? ... 93
4.6.5 How About Application Users? ... 93

5 API Reference ... 95

5.1 Overview of the Guile API ... 96

5.2 The SCM Type ... 96

5.3 Initializing Guile ... 97

5.4 Snarfing Macros ... 99

5.5 Simple Generic Data Types ... 101
5.5.1 Booleans ... 101
5.5.2 Numerical data types ... 102
5.5.2.1 Scheme’s Numerical “Tower” ... 102
5.5.2.2 Integers ... 103
5.5.2.3 Real and Rational Numbers ... 107
5.5.2.4 Complex Numbers ... 109
5.5.2.5 Exact and Inexact Numbers ... 110
5.5.2.6 Read Syntax for Numerical Data ... 111
5.5.2.7 Operations on Integer Values ... 112
5.5.2.8 Comparison Predicates ... 113
5.5.2.9 Converting Numbers To and From Strings ... 114
5.5.2.10 Complex Number Operations ... 114
5.5.2.11 Arithmetic Functions ... 115
5.5.2.12 Scientific Functions ... 116
5.5.2.13 Primitive Numeric Functions ... 117
5.5.2.14 Bitwise Operations ... 119
5.5.2.15 Random Number Generation ... 122
5.5.3 Characters ... 123
5.5.4 Character Sets ... 125
5.5.4.1 Character Set Predicates/Comparison ... 125
5.5.4.2 Iterating Over Character Sets ... 126
5.5.4.3 Creating Character Sets ... 127
5.5.4.4 Querying Character Sets ... 128
5.5.4.5 Character-Set Algebra ... 129
5.5.4.6 Standard Character Sets ... 131
5.5.5 Strings ... 132
5.5.5.1 String Read Syntax ... 133
5.5.5.2 String Predicates ... 133
5.5.5.3 String Constructors ... 134
5.5.5.4 List/String conversion ... 135
5.5.5.5 String Selection ... 136
5.5.5.6 String Modification ... 138
5.5.5.7 String Comparison ... 139
5.5.5.8 String Searching ... 141
5.5.5.9 Alphabetic Case Mapping ... 143
5.5.5.10 Reversing and Appending Strings ... 144
5.5.5.11 Mapping, Folding, and Unfolding ... 145
5.5.5.12 Miscellaneous String Operations ... 147
5.5.5.13 Conversion to/from C ... 148
5.5.6 Regular Expressions ... 149
5.5.6.1 Regexp Functions ... 149
5.5.6.2 Match Structures ... 153
5.5.6.3 Backslash Escapes ... 155
5.5.7 Symbols ... 156
5.5.7.1 Symbols as Discrete Data ... 157
5.5.7.2 Symbols as Lookup Keys ... 158
5.5.7.3 Symbols as Denoting Variables ... 159
5.5.7.4 Operations Related to Symbols ... 159
5.5.7.5 Function Slots and Property Lists ... 162
5.5.7.6 Extended Read Syntax for Symbols ... 163
5.5.7.7 Uninterned Symbols ... 163
5.5.8 Keywords ... 165
5.5.8.1 Why Use Keywords? ... 165
5.5.8.2 Coding With Keywords ... 166
5.5.8.3 Keyword Read Syntax ... 166
5.5.8.4 Keyword Procedures ... 167
5.5.9 “Functionality-Centric” Data Types ... 168

5.6 Compound Data Types ... 169
5.6.1 Pairs ... 169
5.6.2 Lists ... 172
5.6.2.1 List Read Syntax ... 172
5.6.2.2 List Predicates ... 172
5.6.2.3 List Constructors ... 173
5.6.2.4 List Selection ... 173
5.6.2.5 Append and Reverse ... 174
5.6.2.6 List Modification ... 175
5.6.2.7 List Searching ... 176
5.6.2.8 List Mapping ... 177
5.6.3 Vectors ... 177
5.6.3.1 Read Syntax for Vectors ... 177
5.6.3.2 Dynamic Vector Creation and Validation ... 178
5.6.3.3 Accessing and Modifying Vector Contents ... 178
5.6.3.4 Vector Accessing from C ... 180
5.6.4 Uniform Numeric Vectors ... 181
5.6.5 Bit Vectors ... 190
5.6.6 Generalized Vectors ... 193
5.6.7 Arrays ... 194
5.6.7.1 Array Syntax ... 194
5.6.7.2 Array Procedures ... 195
5.6.7.3 Shared Arrays ... 199
5.6.7.4 Accessing Arrays from C ... 201
5.6.8 Records ... 207
5.6.9 Structures ... 208
5.6.9.1 Vtables ... 208
5.6.9.2 Structure Basics ... 209
5.6.9.3 Vtable Contents ... 210
5.6.9.4 Vtable Vtables ... 212
5.6.10 Dictionary Types ... 213
5.6.11 Association Lists ... 214
5.6.11.1 Alist Key Equality ... 214
5.6.11.2 Adding or Setting Alist Entries ... 214
5.6.11.3 Retrieving Alist Entries ... 216
5.6.11.4 Removing Alist Entries ... 217
5.6.11.5 Sloppy Alist Functions ... 218
5.6.11.6 Alist Example ... 219
5.6.12 Hash Tables ... 220
5.6.12.1 Hash Table Examples ... 220
5.6.12.2 Hash Table Reference ... 222

5.7 Smobs ... 226

5.8 Procedures and Macros ... 229
5.8.1 Lambda: Basic Procedure Creation ... 229
5.8.2 Primitive Procedures ... 230
5.8.3 Optional Arguments ... 230
5.8.3.1 let-optional Reference ... 230
5.8.3.2 let-keywords Reference ... 231
5.8.3.3 lambda* Reference ... 232
5.8.3.4 define* Reference ... 233
5.8.4 Procedure Properties and Meta-information ... 234
5.8.5 Procedures with Setters ... 235
5.8.6 Lisp Style Macro Definitions ... 236
5.8.7 The R5RS syntax-rules System ... 237
5.8.7.1 The syntax-rules Pattern Language ... 238
5.8.7.2 Top Level Syntax Definitions ... 238
5.8.7.3 Local Syntax Definitions ... 238
5.8.8 Support for the syntax-case System ... 238
5.8.9 Internal Representation of Macros and Syntax ... 238

5.9 General Utility Functions ... 241
5.9.1 Equality ... 241
5.9.2 Object Properties ... 243
5.9.2.1 Low Level Property Implementation ... 243
5.9.2.2 An Older Approach to Properties ... 244
5.9.3 Sorting ... 244
5.9.4 Copying Deep Structures ... 246
5.9.5 General String Conversion ... 246
5.9.6 Hooks ... 246
5.9.6.1 Hook Usage by Example ... 247
5.9.6.2 Hook Reference ... 248
5.9.6.3 Handling Scheme-level hooks from C code ... 249
5.9.6.4 Hooks For C Code ... 249
5.9.6.5 Hooks for Garbage Collection ... 251
5.9.6.6 Hooks into the Guile REPL ... 251

5.10 Definitions and Variable Bindings ... 252
5.10.1 Top Level Variable Definitions ... 252
5.10.2 Local Variable Bindings ... 253
5.10.3 Internal definitions ... 254
5.10.4 Querying variable bindings ... 255

5.11 Controlling the Flow of Program Execution ... 256
5.11.1 Evaluating a Sequence of Expressions ... 256
5.11.2 Simple Conditional Evaluation ... 256
5.11.3 Conditional Evaluation of a Sequence of Expressions ... 257
5.11.4 Iteration mechanisms ... 257
5.11.5 Continuations ... 260
5.11.6 Returning and Accepting Multiple Values ... 262
5.11.7 Exceptions ... 263
5.11.7.1 Exception Terminology ... 263
5.11.7.2 Catching Exceptions ... 264
5.11.7.3 Throw Handlers ... 266
5.11.7.4 Catch Without Unwinding ... 266
5.11.7.5 Throwing Exceptions ... 269
5.11.7.6 How Guile Implements Exceptions ... 270
5.11.8 Procedures for Signaling Errors ... 270
5.11.9 Dynamic Wind ... 271
5.11.10 How to Handle Errors ... 274
5.11.10.1 C Support ... 275

5.12 Input and Output ... 276
5.12.1 Ports ... 276
5.12.2 Reading ... 277
5.12.3 Writing ... 278
5.12.4 Closing ... 280
5.12.5 Random Access ... 280
5.12.6 Line Oriented and Delimited Text ... 281
5.12.7 Block reading and writing ... 282
5.12.8 Default Ports for Input, Output and Errors ... 283
5.12.9 Types of Port ... 284
5.12.9.1 File Ports ... 285
5.12.9.2 String Ports ... 287
5.12.9.3 Soft Ports ... 288
5.12.9.4 Void Ports ... 288
5.12.10 Using and Extending Ports in C ... 289
5.12.10.1 C Port Interface ... 289
5.12.10.2 Port Implementation ... 290

5.13 Reading and Evaluating Scheme Code ... 293
5.13.1 Scheme Syntax: Standard and Guile Extensions ... 293
5.13.1.1 Expression Syntax ... 293
5.13.1.2 Comments ... 294
5.13.1.3 Block Comments ... 295
5.13.1.4 Case Sensitivity ... 295
5.13.1.5 Keyword Syntax ... 295
5.13.1.6 Reader Extensions ... 295
5.13.2 Reading Scheme Code ... 295
5.13.3 Procedures for On the Fly Evaluation ... 296
5.13.4 Loading Scheme Code from File ... 297
5.13.5 Delayed Evaluation ... 299
5.13.6 Local Evaluation ... 299
5.13.7 Evaluator Behaviour ... 299

5.14 Memory Management and Garbage Collection ... 301
5.14.1 Function related to Garbage Collection ... 301
5.14.2 Memory Blocks ... 302
5.14.2.1 Upgrading from scm must malloc et al ... 304
5.14.3 Weak References ... 304
5.14.3.1 Weak hash tables ... 305
5.14.3.2 Weak vectors ... 305
5.14.4 Guardians ... 306

5.15 Objects ... 307

5.16 Modules ... 308
5.16.1 provide and require ... 308
5.16.2 Environments ... 308
5.16.3 The Guile module system ... 309
5.16.3.1 General Information about Modules ... 309
5.16.3.2 Using Guile Modules ... 310
5.16.3.3 Creating Guile Modules ... 312
5.16.3.4 Module System Reflection ... 315
5.16.3.5 Module System Quirks ... 316
5.16.3.6 Included Guile Modules ... 316
5.16.3.7 Accessing Modules from C ... 318
5.16.4 Dynamic Libraries ... 320
5.16.4.1 Low level dynamic linking ... 320
5.16.4.2 Putting Compiled Code into Modules ... 322
5.16.4.3 Dynamic Linking and Compiled Code Modules ... 322
5.16.4.4 Compiled Code Installation ... 325
5.16.5 Variables ... 326

5.17 Threads, Mutexes, Asyncs and Dynamic Roots ... 328
5.17.1 Arbiters ... 328
5.17.2 Asyncs ... 328
5.17.2.1 System asyncs ... 328
5.17.2.2 User asyncs ... 330
5.17.3 Continuation Barriers ... 330
5.17.4 Threads ... 330
5.17.5 Mutexes and Condition Variables ... 331
5.17.6 Blocking in Guile Mode ... 334
5.17.7 Critical Sections ... 334
5.17.8 Fluids and Dynamic States ... 335
5.17.9 Parallel forms ... 337

5.18 Configuration, Features and Runtime Options ... 339
5.18.1 Configuration, Build and Installation ... 339
5.18.2 Feature Tracking ... 341
5.18.2.1 Feature Manipulation ... 341
5.18.2.2 Common Feature Symbols ... 341
5.18.3 Runtime Options ... 343
5.18.3.1 Low Level Options Interfaces ... 343
5.18.3.2 User Level Options Interfaces ... 344
5.18.3.3 Reader options ... 344
5.18.3.4 Printing options ... 345
5.18.3.5 Evaluator options ... 345
5.18.3.6 Evaluator trap options ... 345
5.18.3.7 Debugger options ... 346
5.18.3.8 Examples of option use ... 347

5.19 Support for Translating Other Languages ... 349
5.19.1 Emacs Lisp Support ... 349

5.20 Support for Internationalization ... 350

5.21 Debugging Infrastructure ... 352
5.21.1 Evaluation and the Scheme Stack ... 352
5.21.1.1 Capturing the Stack or Innermost Stack Frame ... 352
5.21.1.2 Examining the Stack ... 353
5.21.1.3 Examining Stack Frames ... 354
5.21.1.4 Source Properties ... 355
5.21.1.5 Decoding Memoized Source Expressions ... 356
5.21.1.6 Starting a New Stack ... 356
5.21.2 Debugging when an error occurs ... 356
5.21.2.1 Intercepting basic error information ... 357
5.21.2.2 Capturing the full error stack ... 358
5.21.2.3 Displaying or interrogating the captured stack ... 360
5.21.2.4 What the Guile REPL does ... 360
5.21.3 Traps ... 360
5.21.3.1 A Quick Note on Terminology ... 361
5.21.3.2 How to Set a Trap ... 361
5.21.3.3 Specifying Trap Behaviour ... 362
5.21.3.4 Trap Context ... 363
5.21.3.5 Tracing Examples ... 364
5.21.3.6 Tracing Configuration ... 365
5.21.3.7 Tracing and (ice-9 debug) ... 367
5.21.3.8 Traps Installing More Traps ... 368
5.21.3.9 Common Trap Options ... 369
5.21.3.10 Procedure Traps ... 369
5.21.3.11 Exit Traps ... 370
5.21.3.12 Entry Traps ... 370
5.21.3.13 Apply Traps ... 371
5.21.3.14 Step Traps ... 371
5.21.3.15 Source Traps ... 372
5.21.3.16 Location Traps ... 373
5.21.3.17 Trap Shorthands ... 374
5.21.3.18 Trap Utilities ... 374
5.21.4 Debugging Examples ... 375
5.21.4.1 Single Stepping through a Procedure’s Code ... 375
5.21.4.2 Profiling or Tracing a Procedure’s Code ... 376

5.22 GH: A Portable C to Scheme Interface ... 380
5.22.1 Why the GH Interface is Now Deprecated ... 380
5.22.2 Transitioning away from GH ... 380
5.22.3 GH preliminaries ... 386
5.22.4 Data types and constants defined by GH ... 386
5.22.5 Starting and controlling the interpreter ... 387
5.22.6 Error messages ... 389
5.22.7 Executing Scheme code ... 389
5.22.8 Defining new Scheme procedures in C ... 389
5.22.9 Converting data between C and Scheme ... 390
5.22.9.1 C to Scheme ... 390
5.22.9.2 Scheme to C ... 391
5.22.10 Type predicates ... 392
5.22.11 Equality predicates ... 392
5.22.12 Memory allocation and garbage collection ... 393
5.22.13 Calling Scheme procedures from C ... 393

6 Guile Modules ... 397

6.1 SLIB ... 398
6.1.1 SLIB installation ... 398
6.1.2 JACAL ... 398

6.2 POSIX System Calls and Networking ... 399
6.2.1 POSIX Interface Conventions ... 399
6.2.2 Ports and File Descriptors ... 400
6.2.3 File System ... 407
6.2.4 User Information ... 412
6.2.5 Time ... 415
6.2.6 Runtime Environment ... 418
6.2.7 Processes ... 420
6.2.8 Signals ... 425
6.2.9 Terminals and Ptys ... 428
6.2.10 Pipes ... 428
6.2.11 Networking ... 430
6.2.11.1 Network Address Conversion ... 430
6.2.11.2 Network Databases ... 431
6.2.11.3 Network Socket Address ... 436
6.2.11.4 Network Sockets and Communication ... 437
6.2.11.5 Network Socket Examples ... 443
6.2.12 System Identification ... 444
6.2.13 Locales ... 444
6.2.14 Encryption ... 445

6.3 The (ice-9 getopt-long) Module ... 445
6.3.1 A Short getopt-long Example ... 446
6.3.2 How to Write an Option Specification ... 447
6.3.3 Expected Command Line Format ... 447
6.3.4 Reference Documentation for getopt-long ... 448
6.3.5 Reference Documentation for option-ref ... 449

6.4 SRFI Support Modules ... 451
6.4.1 About SRFI Usage ... 451
6.4.2 SRFI-0 - cond-expand ... 451
6.4.3 SRFI-1 - List library ... 452
6.4.3.1 Constructors ... 452
6.4.3.2 Predicates ... 453
6.4.3.3 Selectors ... 454
6.4.3.4 Length, Append, Concatenate, etc ... 455
6.4.3.5 Fold, Unfold & Map ... 456
6.4.3.6 Filtering and Partitioning ... 459
6.4.3.7 Searching ... 460
6.4.3.8 Deleting ... 461
6.4.3.9 Association Lists ... 462
6.4.3.10 Set Operations on Lists ... 463
6.4.4 SRFI-2 - and-let* ... 465
6.4.5 SRFI-4 - Homogeneous numeric vector datatypes ... 466
6.4.6 SRFI-6 - Basic String Ports ... 466
6.4.7 SRFI-8 - receive ... 467
6.4.8 SRFI-9 - define-record-type ... 467
6.4.9 SRFI-10 - Hash-Comma Reader Extension ... 468
6.4.10 SRFI-11 - let-values ... 470
6.4.11 SRFI-13 - String Library ... 470
6.4.12 SRFI-14 - Character-set Library ... 470
6.4.13 SRFI-16 - case-lambda ... 470
6.4.14 SRFI-17 - Generalized set! ... 471
6.4.15 SRFI-19 - Time/Date Library ... 472
6.4.15.1 SRFI-19 Introduction ... 472
6.4.15.2 SRFI-19 Time ... 472
6.4.15.3 SRFI-19 Date ... 474
6.4.15.4 SRFI-19 Time/Date conversions ... 475
6.4.15.5 SRFI-19 Date to string ... 476
6.4.15.6 SRFI-19 String to date ... 478
6.4.16 SRFI-26 - specializing parameters ... 479
6.4.17 SRFI-31 - A special form ‘rec’ for recursive evaluation ... 480
6.4.18 SRFI-34 - Exception handling for programs ... 480
6.4.19 SRFI-35 - Conditions ... 480
6.4.20 SRFI-37 - args-fold ... 483
6.4.21 SRFI-39 - Parameters ... 484
6.4.22 SRFI-55 - Requiring Features ... 486
6.4.23 SRFI-60 - Integers as Bits ... 487
6.4.24 SRFI-61 - A more general cond clause ... 488
6.4.25 SRFI-69 - Basic hash tables ... 488
6.4.25.1 Creating hash tables ... 489
6.4.25.2 Accessing table items ... 489
6.4.25.3 Table properties ... 490
6.4.25.4 Hash table algorithms ... 491
6.4.26 SRFI-88 Keyword Objects ... 491

6.5 Readline Support ... 492
6.5.1 Loading Readline Support ... 492
6.5.2 Readline Options ... 492
6.5.3 Readline Functions ... 493
6.5.3.1 Readline Port ... 493
6.5.3.2 Completion ... 494

6.6 Value History ... 496

6.7 Pretty Printing ... 497

6.8 Formatted Output ... 498

6.9 File Tree Walk ... 508

6.10 Queues ... 510

6.11 Streams ... 512

6.12 Buffered Input ... 514

6.13 Expect ... 515

6.14 The Scheme shell (scsh) ... 518

6.15 Tracing ... 519

7 Autoconf Support ... 521

7.1 Autoconf Background ... 521
7.2 Autoconf Macros ... 521
7.3 Using Autoconf Macros ... 522
7.4 Autofrisk ... 524
7.5 Using Autofrisk ... 525

Appendix A Data Representation in Guile ... 527

A.1 Data Representation in Scheme ... 527
A.1.1 A Simple Representation ... 527
A.1.2 Faster Integers ... 528
A.1.3 Cheaper Pairs ... 529
A.1.4 Guile Is Hairier ... 531

A.2 How Guile does it ... 531
A.2.1 General Rules ... 531
A.2.2 Conservative Garbage Collection ... 532
A.2.3 Immediates vs Non-immediates ... 533
A.2.4 Immediate Datatypes ... 533
A.2.4.1 Integers ... 533
A.2.4.2 Characters ... 534
A.2.4.3 Booleans ... 534
A.2.4.4 Unique Values ... 534
A.2.5 Non-immediate Datatypes ... 535
A.2.5.1 Pairs ... 535
A.2.5.2 Vectors, Strings, and Symbols ... 536
A.2.5.3 Procedures ... 537
A.2.5.4 Closures ... 537
A.2.5.5 Subrs ... 538
A.2.5.6 Ports ... 539

A.2.6 Signalling Type Errors ... 539

A.2.7 Unpacking the SCM Type ... 539
A.2.7.1 Relationship between SCM and scm_t_bits ... 539
A.2.7.2 Immediate objects ... 540
A.2.7.3 Non-immediate objects ... 540
A.2.7.4 Allocating Cells ... 541
A.2.7.5 Heap Cell Type Information ... 541
A.2.7.6 Accessing Cell Entries ... 541
A.2.7.7 Basic Rules for Accessing Cell Entries ... 543

Appendix B GNU Free Documentation License ... 545

B.0.1 ADDENDUM: How to use this License for your documents ... 551

Indices ... 553

Concept Index ... 555
Procedure Index ... 559
Variable Index ... 589
Type Index ... 593
R5RS Index ... 595

1 Preface

This reference manual documents Guile, GNU’s Ubiquitous Intelligent Language for Extensions. It describes how to use Guile in many useful and interesting ways.

This is edition 1.1 of the reference manual, and corresponds to Guile version 1.8.6.

1.1 Layout of this Manual

The manual is divided into five chapters.

Chapter 1: Introduction to Guile
This part provides an overview of what Guile is and how you can use it. A whirlwind tour shows how Guile can be used interactively and as a script interpreter, how to link Guile into your own applications, and how to write modules of interpreted and compiled code for use with Guile. Everything introduced here is documented again and in full by the later parts of the manual. This part also explains how to obtain and install new versions of Guile, and how to report bugs effectively.

Chapter 2: Programming in Scheme
This part provides an overview over programming in Scheme with Guile. It covers how to invoke the guile program from the command-line and how to write scripts in Scheme. It also gives an introduction into the basic ideas of Scheme itself and to the various extensions that Guile offers beyond standard Scheme.

Chapter 3: Programming in C
This part provides an overview of how to use Guile in a C program. It discusses the fundamental concepts that you need to understand to access the features of Guile, such as dynamic types and the garbage collector. It explains in a tutorial like manner how to define new data types and functions for the use by Scheme programs.

Chapter 4: Guile API Reference
This part of the manual documents the Guile API in functionality-based groups with the Scheme and C interfaces presented side by side.

Chapter 5: Guile Modules
Describes some important modules, distributed as part of the Guile distribution, that extend the functionality provided by the Guile Scheme core.

[...]

1.3 Contributors to this Manual

The Guile reference and tutorial manuals were written and edited largely by Mark Galassi and Jim Blandy. In particular, Jim wrote the original tutorial on Guile’s data representation and the C API for accessing Guile objects.

Significant portions were contributed by Gary Houston (contributions to POSIX system calls and networking, expect, I/O internals and extensions, slib installation, error handling) and Tim Pierce (sections on script interpreter triggers, alists, function tracing).

Tom Lord contributed a great deal of material with early Guile snapshots; although most of this text has been rewritten, all of it was important, and some of the structure remains.

Aubrey Jaffer wrote the SCM Scheme implementation and manual upon which the Guile program and manual are based. Some portions of the SCM and SLIB manuals have been included here verbatim.

Since Guile 1.4, Neil Jerram has been maintaining and improving the reference manual. Among other contributions, he wrote the Basic Ideas chapter, developed the tools for keeping the manual in sync with snarfed libguile docstrings, and reorganized the structure so as to accommodate docstrings for all Guile’s primitives.

Martin Grabmueller has made substantial contributions throughout the reference manual in preparation for the Guile 1.6 release, including filling out a lot of the documentation of Scheme data types, control mechanisms and procedures. In addition, he wrote the documentation for Guile’s SRFI modules and modules associated with the Guile REPL.

1.4 The Guile License

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

• The Guile library (libguile) and supporting files are published under the terms of the GNU Lesser General Public License version 2.1. See the file ‘COPYING.LIB’.
• The Guile readline module is published under the terms of the GNU General Public License version 2. See the file ‘COPYING’.
• The manual you’re now reading is published under the terms of the GNU Free Documentation License (see Appendix B [GNU Free Documentation License], page 545).

C code linking to the Guile library is subject to terms of that library. Basically such code may be published on any terms, provided users can re-link against a new or modified version 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 not resticted in any way, and may be published on any terms. We encourage authors to publish on Free terms.

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

2 Introduction to Guile

2.1 What is Guile?

Guile is an interpreter for the Scheme programming language, packaged for use in a wide variety of environments. Guile implements Scheme as described in the Revised5 Report on the Algorithmic Language Scheme (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 a module system, full access to POSIX system calls, networking support, multiple threads, dynamic linking, a foreign function call interface, powerful string processing, and many other features needed for programming in the real world.

Like a shell, Guile can run interactively, reading expressions from the user, evaluating them, and displaying the results, or as a script interpreter, reading and executing Scheme code from a file. However, Guile is also packaged as an object library, allowing other applications to easily incorporate a complete Scheme interpreter. An application can then use Guile as an extension language, a clean and powerful configuration language, or as multi-purpose “glue”, connecting primitives provided by the application. It is easy to call Scheme code from C code and vice versa, giving the application designer full control of how and when to invoke the interpreter. Applications can add new functions, data types, control structures, and even syntax to Guile, creating a domain-specific language tailored to the task at hand, but based on a robust language design.

Guile’s module system allows one to break up a large program into manageable sections with well-defined interfaces between them. Modules may contain a mixture of interpreted and compiled code; Guile can use either static or dynamic linking to incorporate compiled code. Modules also encourage developers to package up useful collections of routines for general distribution; as of this writing, one can find Emacs interfaces, database access routines, compilers, GUI toolkit interfaces, and HTTP client functions, among others.

In the future, we hope to expand Guile to support other languages like Tcl and Perl by translating them to Scheme code. This means that users can program applications which use Guile in the language of their choice, rather than having the tastes of the application’s author imposed on them.

[...]