Guile reference manual

Description

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 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 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 the ``Rest'' 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