Skip to content

Main Navigation

Home
(emacs)
- *Info*
  (intro)
  (manual)
- *Help*
  (describe-function)
  (describe-variable)
  (describe-face)

Appearance

Sidebar Navigation

Top

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
    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
    Bytevector Procedures in R7RS
    Bytevector Slices
  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
    Functional “Setters”
  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
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 objects can be data too
  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
    Signaling 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
    Low-Level Custom Ports
    Low-Level Custom Ports in C
  Venerable Port Interfaces
  Using Ports from 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
  Reading Scheme Code, For the Compiler
  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 Extensions
  Foreign Pointers
  Foreign Types
  Foreign Functions
  Void Pointers and Byte Access
  Foreign Structs
  More Foreign Functions
Foreign Objects
Smobs
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
- Simple Debugging
  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-64 Abstract
    SRFI-64 Rationale
    SRFI-64 Writing Basic Test Suites
    SRFI-64 Conditonal Test Suites and Other Advanced Features
    SRFI-64 Test Runner
    SRFI-64 Test Results
    SRFI-64 Writing a New Test Runner
  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.
  SRFI-119 Wisp: simpler indentation-sensitive Scheme.
  Transducers
  - SRFI-171 General Discussion
    Applying Transducers
    Reducers
    Transducers
    Helper functions for writing transducers
  SRFI-197: Pipeline Operators
  - Acknowledgements
  SRFI-207 String-notated bytevectors
  - External Notation
    Constructors
    Conversion
    Selection
    Replacement
    Comparison
    Searching
    Joining And Splitting
    I/O
    Exceptions
    Acknowledgements
  SRFI-244 - Multiple-value Definitions
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 the “Rest” of a Nodeset
  Matching the Unmatched Attributes
  Default Values in Attribute Patterns
  Guards in Patterns
  Catamorphisms
  Named-Catamorphisms
  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
  method* and define-method*
  - Advanced argument handling in method and define-method
    Type dispatch and redefinition for advanced argument handling
    next-method call in method*
    Advanced argument handling design choices
  Generic Function and Method Examples
  Handling Invocation Errors
Inheritance
- Class Precedence List
  Sorting Methods
  Inheritance and accessors
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 Behavior
  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

On this page

R6RS Support

See R6RS Libraries, for more information on how to define R6RS libraries, and their integration with Guile modules.

Incompatibilities with the R6RS
R6RS Standard Libraries

Pager

Previous pageSRFI-244 - Multiple-value Definitions
Multiple-value Definitions

Next pageIncompatibilities with the R6RS
Guile mostly implements R6RS.

Docs

Emacs
Elisp
Gallery
Elisp Docs

Sites

GNU
Org Mode
FSF

More

Other Manuals
Q & A
License(s)
Codeberg