www.delorie.com/gnu/docs/guile/guile_toc.html

search

	Buy GNU books!

Guile Reference Manual

Table of Contents

1. The Guile License
2. Layout of this Manual
3. Conventions used in this Manual
4. What is Guile?
5. A Whirlwind Tour

5.1 Running Guile Interactively
5.2 Guile Scripts

5.2.1 The Top of a Script File
5.2.2 Scripting Examples

5.3 Linking Programs With Guile

5.3.1 Guile Initialization Functions
5.3.2 A Sample Guile Main Program

5.4 Writing Extensions for Guile

5.4.1 A Sample Guile Extension

5.5 Guile Modules

5.5.1 Intro to Using Existing Modules
5.5.2 Intro to Writing New Modules
5.5.3 Intro to Modules and Extensions

6. Obtaining and Installing Guile

6.1 The Basic Guile Package
6.2 Packages not shipped with Guile

7. Reporting Bugs
Part II: Writing and Running Guile Scheme
8. Guile's Implementation of Scheme
9. Guile Scripting

9.1 Invoking Guile
9.2 The Meta Switch

10. Handling Command Line Options and Arguments

10.1 Using Command Line Arguments
10.2 The (ice-9 getopt-long) Module

10.2.1 A Short getopt-long Example
10.2.2 How to Write an Option Specification
10.2.3 Expected Command Line Format
10.2.4 Reference Documentation for getopt-long
10.2.5 Reference Documentation for option-ref

11. Debugging Features

11.1 Single-Step
11.2 Trace
11.3 Backtrace

12. Autoconf Support

12.1 Autoconf Background
12.2 Autoconf Macros
12.3 Using Autoconf Macros
12.4 Autofrisk
12.5 Using Autofrisk

13. Miscellaneous Tools

13.1 Snarfing

13.1.1 Init Snarfing with guile-snarf

13.1.1.1 How guile-snarf works
13.1.1.2 Macros guile-snarf recognizes
13.1.1.3 Writing your own snarfing macros

13.1.2 Doc Snarfing

13.2 Executable Modules

13.2.1 Writing Executable Modules

14. Basic Ideas in Scheme

14.1 Data Types, Values and Variables

14.1.1 Latent Typing
14.1.2 Values and Variables
14.1.3 Defining and Setting Variables

14.2 The Representation and Use of Procedures

14.2.1 Procedures as Values
14.2.2 Simple Procedure Invocation
14.2.3 Creating and Using a New Procedure
14.2.4 Lambda Alternatives

14.3 Expressions and Evaluation

14.3.1 Evaluating Expressions and Executing Programs

14.3.1.1 Evaluating Literal Data
14.3.1.2 Evaluating a Variable Reference
14.3.1.3 Evaluating a Procedure Invocation Expression
14.3.1.4 Evaluating Special Syntactic Expressions

14.3.2 Using the Guile REPL
14.3.3 Summary of Common Syntax

14.4 The Concept of Closure

14.4.1 Names, Locations, Values and Environments
14.4.2 Local Variables and Environments
14.4.3 Environment Chaining
14.4.4 Lexical Scope

14.4.4.1 An Example of Non-Lexical Scoping

14.4.5 Closure
14.4.6 Example 1: A Serial Number Generator
14.4.7 Example 2: A Shared Persistent Variable
14.4.8 Example 3: The Callback Closure Problem
14.4.9 Example 4: Object Orientation

15. Further Reading
Part III: Guile as an Extension Language
16. Using Guile as an Extension Language
17. An Overview of Guile Programming

17.1 How One Might Extend Dia Using Guile

17.1.1 Deciding Why You Want to Add Guile
17.1.2 Four Steps Required to Add Guile
17.1.3 How to Represent Dia Data in Scheme
17.1.4 Writing Guile Primitives for Dia
17.1.5 Providing a Hook for the Evaluation of Scheme Code
17.1.6 Top-level Structure of Guile-enabled Dia
17.1.7 Going Further with Dia and Guile

17.2 Why Scheme is More Hackable Than C
17.3 Example: Using Guile for an Application Testbed
17.4 A Choice of Programming Options

17.4.1 What Functionality is Already Available?
17.4.2 Functional and Performance Constraints
17.4.3 Your Preferred Programming Style
17.4.4 What Controls Program Execution?

17.5 How About Application Users?

18. Data Representation in Guile

18.1 Data Representation in Scheme

18.1.1 A Simple Representation
18.1.2 Faster Integers
18.1.3 Cheaper Pairs
18.1.4 Guile Is Hairier

18.2 How Guile does it

18.2.1 General Rules
18.2.2 Conservative Garbage Collection
18.2.3 Immediates vs Non-immediates
18.2.4 Immediate Datatypes

18.2.4.1 Integers
18.2.4.2 Characters
18.2.4.3 Booleans
18.2.4.4 Unique Values

18.2.5 Non-immediate Datatypes

18.2.5.1 Pairs
18.2.5.2 Vectors, Strings, and Symbols
18.2.5.3 Procedures
18.2.5.4 Closures
18.2.5.5 Subrs
18.2.5.6 Ports

18.2.6 Signalling Type Errors
18.2.7 Unpacking the SCM Type

18.2.7.1 Relationship between SCM and scm_t_bits
18.2.7.2 Immediate objects
18.2.7.3 Non-immediate objects
18.2.7.4 Heap Cell Type Information
18.2.7.5 Accessing Cell Entries
18.2.7.6 Basic Rules for Accessing Cell Entries

18.3 Defining New Types (Smobs)

18.3.1 Describing a New Type
18.3.2 Creating Instances
18.3.3 Type checking
18.3.4 Garbage Collecting Smobs
18.3.5 A Common Mistake In Allocating Smobs
18.3.6 Garbage Collecting Simple Smobs
18.3.7 A Complete Example

19. GH: A Portable C to Scheme Interface

19.1 Why the GH Interface is Now Deprecated
19.2 gh preliminaries
19.3 Data types and constants defined by gh
19.4 Starting and controlling the interpreter
19.5 Error messages
19.6 Executing Scheme code
19.7 Defining new Scheme procedures in C
19.8 Converting data between C and Scheme

19.8.1 C to Scheme
19.8.2 Scheme to C

19.9 Type predicates
19.10 Equality predicates
19.11 Memory allocation and garbage collection
19.12 Calling Scheme procedures from C
19.13 Mixing gh and scm APIs
19.14 Transitioning to the scm Interface

Part IV: Guile API Reference
20. Overview of the Guile API

20.1 Identical Function in both Scheme and C

20.1.1 Transforming Scheme name to C name
20.1.2 Structuring argument lists for C functions

20.2 Elements Available Only in C
20.3 Elements Available Only in Scheme
20.4 Reference Material Layout

21. Simple Generic Data Types

21.1 Booleans
21.2 Numerical data types

21.2.1 Scheme's Numerical "Tower"
21.2.2 Integers
21.2.3 Real and Rational Numbers
21.2.4 Complex Numbers
21.2.5 Exact and Inexact Numbers
21.2.6 Read Syntax for Numerical Data
21.2.7 Operations on Integer Values
21.2.8 Comparison Predicates
21.2.9 Converting Numbers To and From Strings
21.2.10 Complex Number Operations
21.2.11 Arithmetic Functions
21.2.12 Scientific Functions
21.2.13 Primitive Numeric Functions
21.2.14 Bitwise Operations
21.2.15 Random Number Generation

21.3 Characters
21.4 Strings

21.4.1 String Read Syntax
21.4.2 String Predicates
21.4.3 String Constructors
21.4.4 List/String conversion
21.4.5 String Selection
21.4.6 String Modification
21.4.7 String Comparison
21.4.8 String Searching
21.4.9 Alphabetic Case Mapping
21.4.10 Appending Strings

21.5 Regular Expressions

21.5.1 Regexp Functions
21.5.2 Match Structures
21.5.3 Backslash Escapes

21.6 Symbols

21.6.1 Symbols as Discrete Data
21.6.2 Symbols as Lookup Keys
21.6.3 Symbols as Denoting Variables
21.6.4 Operations Related to Symbols
21.6.5 Function Slots and Property Lists
21.6.6 Extended Read Syntax for Symbols

21.7 Keywords

21.7.1 Why Use Keywords?
21.7.2 Coding With Keywords
21.7.3 Keyword Read Syntax
21.7.4 Keyword Procedures
21.7.5 Keyword Primitives

21.8 "Functionality-Centric" Data Types

22. Compound Data Types

22.1 Pairs
22.2 Lists

22.2.1 List Read Syntax
22.2.2 List Predicates
22.2.3 List Constructors
22.2.4 List Selection
22.2.5 Append and Reverse
22.2.6 List Modification
22.2.7 List Searching
22.2.8 List Mapping

22.3 Vectors

22.3.1 Read Syntax for Vectors
22.3.2 Dynamic Vector Creation and Validation
22.3.3 Accessing and Modifying Vector Contents

22.4 Records
22.5 Structures

22.5.1 Structure Concepts
22.5.2 Structure Layout
22.5.3 Structure Basics
22.5.4 Vtables

22.6 Arrays

22.6.1 Conventional Arrays
22.6.2 Array Mapping
22.6.3 Uniform Arrays
22.6.4 Bit Vectors

22.7 Association Lists and Hash Tables

22.7.1 Dictionary Types
22.7.2 Association Lists

22.7.2.1 Alist Key Equality
22.7.2.2 Adding or Setting Alist Entries
22.7.2.3 Retrieving Alist Entries
22.7.2.4 Removing Alist Entries
22.7.2.5 Sloppy Alist Functions
22.7.2.6 Alist Example

22.7.3 Hash Tables

22.7.3.1 Hash Table Examples
22.7.3.2 Hash Table Reference

23. Procedures and Macros

23.1 Lambda: Basic Procedure Creation
23.2 Optional Arguments

23.2.1 let-optional Reference
23.2.2 let-keywords Reference
23.2.3 lambda* Reference
23.2.4 define* Reference

23.3 Procedure Properties and Meta-information
23.4 Procedures with Setters
23.5 Lisp Style Macro Definitions
23.6 The R5RS syntax-rules System

23.6.1 The syntax-rules Pattern Language
23.6.2 Top Level Syntax Definitions
23.6.3 Local Syntax Definitions

23.7 Support for the syntax-case System
23.8 Internal Representation of Macros and Syntax

24. General Utility Functions

24.1 Equality
24.2 Object Properties

24.2.1 Low Level Property Implementation.
24.2.2 An Older Approach to Properties

24.3 Sorting
24.4 Copying Deep Structures
24.5 General String Conversion
24.6 Hooks

24.6.1 Hook Usage by Example
24.6.2 Hook Reference
24.6.3 Handling Scheme-level hooks from C code
24.6.4 Hooks For C Code.
24.6.5 Hooks Provided by Guile

24.6.5.1 Hooks for Garbage Collection
24.6.5.2 Hooks into the Guile REPL

25. Definitions and Variable Bindings

25.1 Top Level Variable Definitions
25.2 Local Variable Bindings
25.3 Internal definitions
25.4 Querying variable bindings

26. Controlling the Flow of Program Execution

26.1 Evaluating a Sequence of Expressions
26.2 Simple Conditional Evaluation
26.3 Conditional Evaluation of a Sequence of Expressions
26.4 Iteration mechanisms
26.5 Continuations
26.6 Returning and Accepting Multiple Values
26.7 Exceptions

26.7.1 Exception Terminology
26.7.2 Catching Exceptions
26.7.3 Throwing Exceptions
26.7.4 Catch Without Unwinding
26.7.5 How Guile Implements Exceptions

26.8 Procedures for Signaling Errors
26.9 Dynamic Wind
26.10 How to Handle Errors in C Code

26.10.1 C Support

27. Input and Output

27.1 Ports
27.2 Reading
27.3 Writing
27.4 Closing
27.5 Random Access
27.6 Line Oriented and Delimited Text
27.7 Block reading and writing
27.8 Default Ports for Input, Output and Errors
27.9 Types of Port

27.9.1 File Ports
27.9.2 String Ports
27.9.3 Soft Ports
27.9.4 Void Ports

27.10 Using and Extending Ports in C

27.10.1 C Port Interface

27.10.1.1 Port basics
27.10.1.2 Port buffers
27.10.1.3 The rw_random flag
27.10.1.4 The rw_active variable
27.10.1.5 Reading from a port.
27.10.1.6 Writing to a port.

27.10.2 Port Implementation

28. Reading and Evaluating Scheme Code

28.1 Scheme Syntax: Standard and Guile Extensions

28.1.1 Expression Syntax
28.1.2 Comments
28.1.3 Block Comments
28.1.4 Case Sensitivity
28.1.5 Keyword Syntax
28.1.6 Reader Extensions

28.2 Reading Scheme Code
28.3 Procedures for On the Fly Evaluation
28.4 Loading Scheme Code from File
28.5 Delayed Evaluation
28.6 Local Evaluation
28.7 Evaluator Behaviour

29. Memory Management and Garbage Collection

29.1 Garbage Collection
29.2 Weak References

29.2.1 Weak key hashes
29.2.2 Weak vectors

29.3 Guardians

30. Objects
31. Modules

31.1 provide and require
31.2 Environments
31.3 The Guile module system

31.3.1 General Information about Modules
31.3.2 Using Guile Modules
31.3.3 Creating Guile Modules
31.3.4 Module System Quirks
31.3.5 Included Guile Modules
31.3.6 Accessing Modules from C

31.4 Dynamic Libraries

31.4.1 Low level dynamic linking
31.4.2 Writing Dynamically Loadable Extensions

31.5 Variables

32. Threads, Mutexes, Asyncs and Dynamic Roots

32.1 Arbiters
32.2 Asyncs
32.3 Dynamic Roots
32.4 Threads

32.4.1 Low level thread primitives
32.4.2 Higher level thread procedures

32.5 Fluids

33. Configuration, Features and Runtime Options

33.1 Configuration, Build and Installation
33.2 Feature Tracking

33.2.1 Feature Manipulation
33.2.2 Common Feature Symbols

33.3 Runtime Options

33.3.1 Low Level Options Interfaces
33.3.2 User Level Options Interfaces
33.3.3 Reader options
33.3.4 Printing options
33.3.5 Evaluator options
33.3.6 Evaluator trap options
33.3.7 Debugger options

33.3.7.1 Stack overflow

33.3.8 Examples of option use

34. Support for Translating Other Languages

34.1 Emacs Lisp Support

35. Debugging Infrastructure

35.1 Source Properties
35.2 Using Traps
35.3 Capturing the Stack or Innermost Stack Frame
35.4 Examining the Stack
35.5 Examining Stack Frames
35.6 Decoding Memoized Source Expressions
35.7 Starting a New Stack

36. Deprecated

36.1 Shared And Read Only Strings

36.1.1 Shared Substrings
36.1.2 Read Only Strings

36.2 `Sloppy' List Membership Procedures
36.3 Strange Variations on eval
36.4 Closing All Ports Except Some ...
36.5 Old Method for Registering C Modules.
36.6 Obarray Symbol Manipulation
36.7 Previously Deprecated Items Now Removed

37. SLIB

37.1 SLIB installation
37.2 JACAL

38. POSIX System Calls and Networking

38.1 POSIX Interface Conventions
38.2 Ports and File Descriptors
38.3 File System
38.4 User Information
38.5 Time
38.6 Runtime Environment
38.7 Processes
38.8 Signals
38.9 Terminals and Ptys
38.10 Pipes
38.11 Networking

38.11.1 Network Address Conversion

38.11.1.1 IPv4 Address Conversion
38.11.1.2 IPv6 Address Conversion

38.11.2 Network Databases

38.11.2.1 The Host Database
38.11.2.2 The Network Database
38.11.2.3 The Protocol Database
38.11.2.4 The Service Database

38.11.3 Network Sockets and Communication
38.11.4 Network Socket Examples

38.11.4.1 Internet Socket Client Example
38.11.4.2 Internet Socket Server Example

38.12 System Identification
38.13 Locales
38.14 Encryption

39. SRFI Support Modules

39.1 About SRFI Usage
39.2 SRFI-0 - cond-expand
39.3 SRFI-1 - List library

39.3.1 Constructors
39.3.2 Predicates
39.3.3 Selectors
39.3.4 Length, Append, Concatenate, etc.
39.3.5 Fold, Unfold & Map
39.3.6 Filtering and Partitioning
39.3.7 Searching
39.3.8 Deleting
39.3.9 Association Lists
39.3.10 Set Operations on Lists

39.4 SRFI-2 - and-let*
39.5 SRFI-4 - Homogeneous numeric vector datatypes.

39.5.1 SRFI-4 - Read Syntax
39.5.2 SRFI-4 Procedures

39.6 SRFI-6 - Basic String Ports
39.7 SRFI-8 - receive
39.8 SRFI-9 - define-record-type
39.9 SRFI-10 - Hash-Comma Reader Extension
39.10 SRFI-11 - let-values
39.11 SRFI-13 - String Library

39.11.1 Loading SRFI-13
39.11.2 Predicates
39.11.3 Constructors
39.11.4 List/String Conversion
39.11.5 Selection
39.11.6 Modification
39.11.7 Comparison
39.11.8 Prefixes/Suffixes
39.11.9 Searching
39.11.10 Alphabetic Case Mapping
39.11.11 Reverse/Append
39.11.12 Fold/Unfold/Map
39.11.13 Replicate/Rotate
39.11.14 Miscellaneous
39.11.15 Filtering/Deleting

39.12 SRFI-14 - Character-set Library

39.12.1 Loading SRFI-14
39.12.2 Character Set Data Type
39.12.3 Predicates/Comparison
39.12.4 Iterating Over Character Sets
39.12.5 Creating Character Sets
39.12.6 Querying Character Sets
39.12.7 Character-Set Algebra
39.12.8 Standard Character Sets

39.13 SRFI-16 - case-lambda
39.14 SRFI-17 - Generalized set!
39.15 SRFI-19 - Time/Date Library

39.15.1 SRFI-19 Constants
39.15.2 SRFI-19 Current time and clock resolution
39.15.3 SRFI-19 Time object and accessors
39.15.4 SRFI-19 Time comparison procedures
39.15.5 SRFI-19 Time arithmetic procedures
39.15.6 SRFI-19 Date object and accessors
39.15.7 SRFI-19 Time/Date/Julian Day/Modified Julian Day converters
39.15.8 SRFI-19 Date to string/string to date converters

40. Readline Support

40.1 Loading Readline Support
40.2 Readline Options

41. Value History
42. Pretty Printing
43. Formatted Output
44. The Rx Regular Expression Library
45. Expect
46. The Scheme shell (scsh)
Concept Index
Procedure Index
Variable Index
Type Index
R5RS Index