[Top] [Contents] [Index] [ ? ]

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.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 Hooks For C Code.
24.6.4 Hooks Provided by Guile
24.6.4.1 Hooks for Garbage Collection
24.6.4.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. Runtime Options and Configuration
33.1 General option interface
33.2 Reader options
33.3 Printing options
33.4 Evaluator options
33.5 Evaluator trap options
33.6 Debugger options
33.6.1 Stack overflow
33.7 Examples of option use
33.8 Installation and Configuration Data
33.9 Feature Tracking
33.9.1 Feature Manipulation
33.9.2 Common Feature Symbols
34. Support for Translating Other Languages
34.1 Emacs Lisp Support
35. Debugging Infrastructure
35.1 Using Traps
35.2 Capturing the Stack or Innermost Stack Frame
35.3 Examining the Stack
35.4 Examining Stack Frames
35.5 Decoding Memoized Source Expressions
35.6 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

This document was generated by Ingo Ruhnke on September, 12 2002 using texi2html