Guile reference manual

✍ Scribed by The guile developers

• Tongue: English
• Leaves: 964
• Edition: 3.0.5
• Category: Library

✦ Table of Contents

Preface
Contributors to this Manual
The Guile License
Introduction
Guile and Scheme
Combining with C Code
Guile and the GNU Project
Interactive Programming
Supporting Multiple Languages
Obtaining and Installing Guile
Organisation of this Manual
Typographical Conventions
Hello Guile!
Running Guile Interactively
Running Guile Scripts
Linking Guile into Programs
Writing Guile Extensions
Using the Guile Module System
Using Modules
Writing new Modules
Putting Extensions into Modules
Reporting Bugs
Hello Scheme!
Data Types, Values and Variables
Latent Typing
Values and Variables
Defining and Setting Variables
The Representation and Use of Procedures
Procedures as Values
Simple Procedure Invocation
Creating and Using a New Procedure
Lambda Alternatives
Expressions and Evaluation
Evaluating Expressions and Executing Programs
Evaluating Literal Data
Evaluating a Variable Reference
Evaluating a Procedure Invocation Expression
Evaluating Special Syntactic Expressions
Tail calls
Using the Guile REPL
Summary of Common Syntax
The Concept of Closure
Names, Locations, Values and Environments
Local Variables and Environments
Environment Chaining
Lexical Scope
An Example of Non-Lexical Scoping
Closure
Example 1: A Serial Number Generator
Example 2: A Shared Persistent Variable
Example 3: The Callback Closure Problem
Example 4: Object Orientation
Further Reading
Programming in Scheme
Guile's Implementation of Scheme
Invoking Guile
Command-line Options
Environment Variables
Guile Scripting
The Top of a Script File
The Meta Switch
Command Line Handling
Scripting Examples
Using Guile Interactively
The Init File, ~/.guile
Readline
Value History
REPL Commands
Help Commands
Module Commands
Language Commands
Compile Commands
Profile Commands
Debug Commands
Inspect Commands
System Commands
Error Handling
Interactive Debugging
Using Guile in Emacs
Using Guile Tools
Installing Site Packages
Distributing Guile Code
Programming in C
Parallel Installations
Linking Programs With Guile
Guile Initialization Functions
A Sample Guile Main Program
Building the Example with Make
Building the Example with Autoconf
Linking Guile with Libraries
A Sample Guile Extension
General concepts for using libguile
Dynamic Types
Garbage Collection
Control Flow
Asynchronous Signals
Multi-Threading
Defining New Foreign Object Types
Defining Foreign Object Types
Creating Foreign Objects
Type Checking of Foreign Objects
Foreign Object Memory Management
Foreign Objects and Scheme
Function Snarfing
An Overview of Guile Programming
How One Might Extend Dia Using Guile
Deciding Why You Want to Add Guile
Four Steps Required to Add Guile
How to Represent Dia Data in Scheme
Writing Guile Primitives for Dia
Providing a Hook for the Evaluation of Scheme Code
Top-level Structure of Guile-enabled Dia
Going Further with Dia and Guile
Why Scheme is More Hackable Than C
Example: Using Guile for an Application Testbed
A Choice of Programming Options
What Functionality is Already Available?
Functional and Performance Constraints
Your Preferred Programming Style
What Controls Program Execution?
How About Application Users?
Autoconf Support
Autoconf Background
Autoconf Macros
Using Autoconf Macros
API Reference
Overview of the Guile API
Deprecation
The SCM Type
Initializing Guile
Snarfing Macros
Data Types
Booleans
Numerical data types
Scheme's Numerical Tower'' Integers Real and Rational Numbers Complex Numbers Exact and Inexact Numbers Read Syntax for Numerical Data Operations on Integer Values Comparison Predicates Converting Numbers To and From Strings Complex Number Operations Arithmetic Functions Scientific Functions Bitwise Operations Random Number Generation Characters Character Sets Character Set Predicates/Comparison Iterating Over Character Sets Creating Character Sets Querying Character Sets Character-Set Algebra Standard Character Sets Strings String Read Syntax String Predicates String Constructors List/String conversion String Selection String Modification String Comparison String Searching Alphabetic Case Mapping Reversing and Appending Strings Mapping, Folding, and Unfolding Miscellaneous String Operations Representing Strings as Bytes Conversion to/from C String Internals Symbols Symbols as Discrete Data Symbols as Lookup Keys Symbols as Denoting Variables Operations Related to Symbols Function Slots and Property Lists Extended Read Syntax for Symbols Uninterned Symbols Keywords Why Use Keywords? Coding With Keywords Keyword Read Syntax Keyword Procedures Pairs Lists List Read Syntax List Predicates List Constructors List Selection Append and Reverse List Modification List Searching List Mapping Vectors Read Syntax for Vectors Dynamic Vector Creation and Validation Accessing and Modifying Vector Contents Vector Accessing from C Uniform Numeric Vectors Bit Vectors Bytevectors Endianness Manipulating Bytevectors Interpreting Bytevector Contents as Integers Converting Bytevectors to/from Integer Lists Interpreting Bytevector Contents as Floating Point Numbers Interpreting Bytevector Contents as Unicode Strings Accessing Bytevectors with the Array API Accessing Bytevectors with the SRFI-4 API Arrays Array Syntax Array Procedures Shared Arrays Arrays as arrays of arrays Accessing Arrays from C VLists Record Overview SRFI-9 Records Non-toplevel Record Definitions Custom Printers FunctionalSetters''
Records
Structures
Vtables
Structure Basics
Vtable Contents
Meta-Vtables
Vtable Example
Dictionary Types
Association Lists
Alist Key Equality
Adding or Setting Alist Entries
Retrieving Alist Entries
Removing Alist Entries
Sloppy Alist Functions
Alist Example
VList-Based Hash Lists or VHashes'' Hash Tables Hash Table Examples Hash Table Reference Other Types Foreign Objects Smobs Procedures Lambda: Basic Procedure Creation Primitive Procedures Compiled Procedures Optional Arguments lambda* and define*. (ice-9 optargs) Case-lambda Higher-Order Functions Procedure Properties and Meta-information Procedures with Setters Inlinable Procedures Macros Defining Macros Syntax-rules Macros Patterns Hygiene Shorthands Reporting Syntax Errors in Macros Specifying a Custom Ellipsis Identifier Further Information Support for the syntax-case System Why syntax-case? Custom Ellipsis Identifiers for syntax-case Macros Syntax Transformer Helpers Lisp-style Macro Definitions Identifier Macros Syntax Parameters Eval-when Macro Expansion Hygiene and the Top-Level Internal Macros General Utility Functions Equality Object Properties Sorting Copying Deep Structures General String Conversion Hooks Hook Usage by Example Hook Reference Hooks For C Code. Hooks for Garbage Collection Hooks into the Guile REPL Definitions and Variable Bindings Top Level Variable Definitions Local Variable Bindings Internal definitions Querying variable bindings Binding multiple return values Controlling the Flow of Program Execution Sequencing and Splicing Simple Conditional Evaluation Conditional Evaluation of a Sequence of Expressions Iteration mechanisms Prompts Prompt Primitives Shift, Reset, and All That Continuations Returning and Accepting Multiple Values Exceptions Exception Objects Raising and Handling Exceptions Throw and Catch Exceptions and C Procedures for Signaling Errors Dynamic Wind Fluids and Dynamic States Parameters How to Handle Errors C Support Signalling Type Errors Continuation Barriers Input and Output Ports Binary I/O Encoding Textual I/O Simple Textual Output Buffering Random Access Line Oriented and Delimited Text Default Ports for Input, Output and Errors Types of Port File Ports Bytevector Ports String Ports Custom Ports Soft Ports Void Ports Venerable Port Interfaces Using Ports from C Implementing New Port Types in C Non-Blocking I/O Handling of Unicode Byte Order Marks Regular Expressions Regexp Functions Match Structures Backslash Escapes LALR(1) Parsing PEG Parsing PEG Syntax Reference PEG API Reference PEG Tutorial PEG Internals Reading and Evaluating Scheme Code Scheme Syntax: Standard and Guile Extensions Expression Syntax Comments Block Comments Case Sensitivity Keyword Syntax Reader Extensions Reading Scheme Code Writing Scheme Values Procedures for On the Fly Evaluation Compiling Scheme Code Loading Scheme Code from File Load Paths Character Encoding of Source Files Delayed Evaluation Local Evaluation Local Inclusion Sandboxed Evaluation REPL Servers Cooperative REPL Servers Memory Management and Garbage Collection Function related to Garbage Collection Memory Blocks Weak References Weak hash tables Weak vectors Guardians Modules General Information about Modules Using Guile Modules Creating Guile Modules Modules and the File System R6RS Version References R6RS Libraries Variables Module System Reflection Declarative Modules Accessing Modules from C provide and require Environments Foreign Function Interface Foreign Libraries Foreign Functions C Extensions Modules and Extensions Foreign Pointers Foreign Types Foreign Variables Void Pointers and Byte Access Foreign Structs Dynamic FFI Threads, Mutexes, Asyncs and Dynamic Roots Threads Thread-Local Variables Asynchronous Interrupts Atomics Mutexes and Condition Variables Blocking in Guile Mode Futures Parallel forms Configuration, Features and Runtime Options Configuration, Build and Installation Feature Tracking Feature Manipulation Common Feature Symbols Runtime Options Examples of option use Support for Other Languages Using Other Languages Emacs Lisp Nil Dynamic Binding Other Elisp Features ECMAScript Support for Internationalization Internationalization with Guile Text Collation Character Case Mapping Number Input and Output Accessing Locale Information Gettext Support Debugging Infrastructure Evaluation and the Scheme Stack Stack Capture Stacks Frames Source Properties Programmatic Error Handling Catching Exceptions Pre-Unwind Debugging call-with-error-handling Stack Overflow Debug options Traps VM Hooks Trap Interface Low-Level Traps Tracing Traps Trap States High-Level Traps GDB Support Code Coverage Reports Guile Modules SLIB SLIB installation JACAL POSIX System Calls and Networking POSIX Interface Conventions Ports and File Descriptors File System User Information Time Runtime Environment Processes Signals Terminals and Ptys Pipes Networking Network Address Conversion Network Databases Network Socket Address Network Sockets and Communication Network Socket Examples System Identification Locales Encryption HTTP, the Web, and All That Types and the Web Universal Resource Identifiers The Hyper-Text Transfer Protocol HTTP Headers HTTP Header Types General Headers Entity Headers Request Headers Response Headers Transfer Codings HTTP Requests An Important Note on Character Sets Request API HTTP Responses Web Client Web Server Web Examples Hello, World! Inspecting the Request Higher-Level Interfaces Conclusion The (ice-9 getopt-long) Module A Short getopt-long Example How to Write an Option Specification Expected Command Line Format Reference Documentation for getopt-long Reference Documentation for option-ref SRFI Support Modules About SRFI Usage SRFI-0 - cond-expand SRFI-1 - List library Constructors Predicates Selectors Length, Append, Concatenate, etc. Fold, Unfold & Map Filtering and Partitioning Searching Deleting Association Lists Set Operations on Lists SRFI-2 - and-let* SRFI-4 - Homogeneous numeric vector datatypes SRFI-4 - Overview SRFI-4 - API SRFI-4 - Relation to bytevectors SRFI-4 - Guile extensions SRFI-6 - Basic String Ports SRFI-8 - receive SRFI-9 - define-record-type SRFI-10 - Hash-Comma Reader Extension SRFI-11 - let-values SRFI-13 - String Library SRFI-14 - Character-set Library SRFI-16 - case-lambda SRFI-17 - Generalized set! SRFI-18 - Multithreading support SRFI-18 Threads SRFI-18 Mutexes SRFI-18 Condition variables SRFI-18 Time SRFI-18 Exceptions SRFI-19 - Time/Date Library SRFI-19 Introduction SRFI-19 Time SRFI-19 Date SRFI-19 Time/Date conversions SRFI-19 Date to string SRFI-19 String to date SRFI-23 - Error Reporting SRFI-26 - specializing parameters SRFI-27 - Sources of Random Bits The Default Random Source Random Sources Obtaining random number generator procedures SRFI-28 - Basic Format Strings SRFI-30 - Nested Multi-line Comments SRFI-31 - A special form `rec' for recursive evaluation SRFI-34 - Exception handling for programs SRFI-35 - Conditions SRFI-37 - args-fold SRFI-38 - External Representation for Data With Shared Structure SRFI-39 - Parameters SRFI-41 - Streams SRFI-41 Stream Fundamentals SRFI-41 Stream Primitives SRFI-41 Stream Library SRFI-42 - Eager Comprehensions SRFI-43 - Vector Library SRFI-43 Constructors SRFI-43 Predicates SRFI-43 Selectors SRFI-43 Iteration SRFI-43 Searching SRFI-43 Mutators SRFI-43 Conversion SRFI-45 - Primitives for Expressing Iterative Lazy Algorithms SRFI-46 Basic syntax-rules Extensions SRFI-55 - Requiring Features SRFI-60 - Integers as Bits SRFI-61 - A more general cond clause SRFI-62 - S-expression comments. SRFI-64 - A Scheme API for test suites. SRFI-67 - Compare procedures SRFI-69 - Basic hash tables Creating hash tables Accessing table items Table properties Hash table algorithms SRFI-71 - Extended let-syntax for multiple values SRFI-87 => in case clauses SRFI-88 Keyword Objects SRFI-98 Accessing environment variables. SRFI-105 Curly-infix expressions. SRFI-111 Boxes. Transducers SRFI-171 General Discussion Applying Transducers Reducers Transducers Helper functions for writing transducers R6RS Support Incompatibilities with the R6RS R6RS Standard Libraries Library Usage rnrs base rnrs unicode rnrs bytevectors rnrs lists rnrs sorting rnrs control R6RS Records rnrs records syntactic rnrs records procedural rnrs records inspection rnrs exceptions rnrs conditions I/O Conditions Transcoders rnrs io ports R6RS File Ports rnrs io simple rnrs files rnrs programs rnrs arithmetic fixnums rnrs arithmetic flonums rnrs arithmetic bitwise rnrs syntax-case rnrs hashtables rnrs enums rnrs rnrs eval rnrs mutable-pairs rnrs mutable-strings rnrs r5rs R7RS Support Incompatibilities with the R7RS R7RS Standard Libraries Pattern Matching Readline Support Loading Readline Support Readline Options Readline Functions Readline Port Completion Pretty Printing Formatted Output File Tree Walk Queues Streams Buffered Input Expect sxml-match: Pattern Matching of SXML Syntax Matching XML Elements Ellipses in Patterns Ellipses in Quasiquote'd Output Matching Nodesets Matching theRest'' of a Nodeset
Matching the Unmatched Attributes
Default Values in Attribute Patterns
Guards in Patterns
Catamorphisms
Named-Catamorphisms
sxml-match-let and sxml-match-let*
The Scheme shell (scsh)
Curried Definitions
Statprof
SXML
SXML Overview
Reading and Writing XML
SSAX: A Functional XML Parsing Toolkit
History
Implementation
Usage
Transforming SXML
Overview
Usage
SXML Tree Fold
Overview
Usage
SXPath
Overview
Basic Converters and Applicators
Converter Combinators
(sxml ssax input-parse)
Overview
Usage
(sxml apply-templates)
Overview
Usage
Texinfo Processing
(texinfo)
Overview
Usage
(texinfo docbook)
Overview
Usage
(texinfo html)
Overview
Usage
(texinfo indexing)
Overview
Usage
(texinfo string-utils)
Overview
Usage
(texinfo plain-text)
Overview
Usage
(texinfo serialize)
Overview
Usage
(texinfo reflection)
Overview
Usage
GOOPS
Copyright Notice
Class Definition
Instance Creation and Slot Access
Slot Options
Illustrating Slot Description
Methods and Generic Functions
Accessors
Extending Primitives
Merging Generics
Next-method
Generic Function and Method Examples
Handling Invocation Errors
Inheritance
Class Precedence List
Sorting Methods
Introspection
Classes
Instances
Slots
Generic Functions
Accessing Slots
Error Handling
GOOPS Object Miscellany
The Metaobject Protocol
Metaobjects and the Metaobject Protocol
Metaclasses
MOP Specification
Instance Creation Protocol
Class Definition Protocol
Customizing Class Definition
Method Definition
Method Definition Internals
Generic Function Internals
Generic Function Invocation
Redefining a Class
Redefinable Classes
Default Class Redefinition Behaviour
Customizing Class Redefinition
Changing the Class of an Instance
Guile Implementation
A Brief History of Guile
The Emacs Thesis
Early Days
A Scheme of Many Maintainers
A Timeline of Selected Guile Releases
Status, or: Your Help Needed
Data Representation
A Simple Representation
Faster Integers
Cheaper Pairs
Conservative Garbage Collection
The SCM Type in Guile
Relationship Between SCM and scm_t_bits
Immediate Objects
Non-Immediate Objects
Allocating Heap Objects
Heap Object Type Information
Accessing Heap Object Fields
A Virtual Machine for Guile
Why a VM?
VM Concepts
Stack Layout
Variables and the VM
Compiled Procedures are VM Programs
Object File Format
Instruction Set
Call and Return Instructions
Function Prologue Instructions
Shuffling Instructions
Trampoline Instructions
Non-Local Control Flow Instructions
Instrumentation Instructions
Intrinsic Call Instructions
Constant Instructions
Memory Access Instructions
Atomic Memory Access Instructions
Tagging and Untagging Instructions
Integer Arithmetic Instructions
Floating-Point Arithmetic Instructions
Comparison Instructions
Branch Instructions
Raw Memory Access Instructions
Just-In-Time Native Code
Compiling to the Virtual Machine
Compiler Tower
The Scheme Compiler
Tree-IL
Continuation-Passing Style
An Introduction to CPS
CPS in Guile
Building CPS
CPS Soup
Compiling CPS
Bytecode
Writing New High-Level Languages
Extending the Compiler
GNU Free Documentation License
Concept Index
Procedure Index
Variable Index
Type Index
R5RS Index