Chez Scheme Version 9 User's Guide Cisco Systems, Inc. www.cisco.com c 2020 Cisco Systems, Inc. Licensed under the Apache License Version 2.0 http://www.apache.org/licenses/LICENSE-2.0 Revised August 2020 for Chez Scheme Version 9.5.4. Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affil- iates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: http://www.cisco.com/go/trademarks. Third-party trademarks mentioned are the prop- erty of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R) Contents Preface ix 1. Introduction 1 1.1. Chez Scheme Syntax 2 1.2. Notational Conventions 4 1.3. Parameters 5 1.4. More Information 5 2. Using Chez Scheme 7 2.1. Interacting with Chez Scheme 7 2.2. Expression Editor 11 2.3. The Interaction Environment 14 2.4. Using Libraries and Top-Level Programs 17 2.5. Scheme Shell Scripts 20 2.6. Optimization 22 2.7. Customization 24 2.8. Building and Distributing Applications 24 2.9. Command-Line Options 30 3. Debugging 33 3.1. Tracing 33 3.2. The Interactive Debugger 40 3.3. The Interactive Inspector 41 3.4. The Object Inspector 47 iv Contents 3.5. Locating objects 53 3.6. Nested object size and composition 54 4. Foreign Interface 57 4.1. Subprocess Communication 57 4.2. Calling out of Scheme 59 4.3. Calling into Scheme 70 4.4. Continuations and Foreign Calls 73 4.5. Foreign Data 74 4.6. Providing Access to Foreign Procedures 89 4.7. Using Other Foreign Languages 93 4.8. C Library Routines 94 4.9. Example: Socket Operations 105 5. Binding Forms 113 5.1. Definitions 113 5.2. Multiple-value Definitions 114 5.3. Recursive Bindings 115 5.4. Fluid Bindings 116 5.5. Top-Level Bindings 117 6. Control Structures 123 6.1. Conditionals 123 6.2. Mapping and Folding 125 6.3. Continuations 125 6.4. Engines 127 7. Operations on Objects 133 7.1. Missing R6RS Type Predicates 133 7.2. Pairs and Lists 133 7.3. Characters 137 7.4. Strings 139 Contents v 7.5. Vectors 141 7.6. Fixnum-Only Vectors 143 7.7. Bytevectors 146 7.8. Boxes 150 7.9. Symbols 152 7.10. Void 156 7.11. Sorting 157 7.12. Hashtables 158 7.13. Record Types 167 7.14. Record Equality and Hashing 167 7.15. Legacy Record Types 171 7.16. Procedures 187 8. Numeric Operations 189 8.1. Numeric Type Predicates 190 8.2. Fixnum Operations 191 8.3. Flonum Operations 195 8.4. Inexact Complex Operations 197 8.5. Bitwise and Logical Operators 200 8.6. Random Number Generation 208 8.7. Miscellaneous Numeric Operations 208 9. Input/Output Operations 213 9.1. Generic Ports 213 9.2. File Options 215 9.3. Transcoders 217 9.4. Port Operations 218 9.5. String Ports 227 9.6. File Ports 229 9.7. Custom Ports 230 9.8. Input Operations 230 vi Contents 9.9. Output Operations 238 9.10. Input/Output Operations 243 9.11. Non-Unicode Bytevector/String Conversions 244 9.12. Pretty Printing 245 9.13. Formatted Output 249 9.14. Input/Output Control Operations 251 9.15. Fasl Output 258 9.16. File System Interface 260 9.17. Generic Port Examples 265 10. Libraries and Top-level Programs 275 10.1. Built-in Libraries 275 10.2. Running Top-level Programs 277 10.3. Library and Top-level Program Forms 278 10.4. Standalone import and export forms 279 10.5. Explicitly invoking libraries 287 10.6. Library Parameters 287 10.7. Library Inspection 290 11. Syntactic Extension and Modules 293 11.1. Fluid Keyword Bindings 293 11.2. Syntax-Rules Transformers 295 11.3. Syntax-Case Transformers 295 11.4. Compile-time Values and Properties 300 11.5. Modules 305 11.6. Standalone import and export forms 311 11.7. Built-in Modules 311 11.8. Meta Definitions 312 11.9. Conditional expansion 313 11.10. Aliases 314 11.11. Annotations 315 Contents vii 11.12. Source Tables 321 12. System Operations 325 12.1. Exceptions 325 12.2. Interrupts 329 12.3. Environments 332 12.4. Compilation, Evaluation, and Loading 336 12.5. Source Directories and Files 356 12.6. Compiler Controls 357 12.7. Profiling 364 12.8. Waiter Customization 374 12.9. Transcript Files 379 12.10. Times and Dates 380 12.11. Timing and Statistics 388 12.12. Cost Centers 392 12.13. Parameters 394 12.14. Virtual registers 396 12.15. Environmental Queries and Settings 398 12.16. Subset Modes 400 13. Storage Management 401 13.1. Garbage Collection 401 13.2. Weak Pairs, Ephemeron Pairs, and Guardians 405 13.3. Locking Objects 413 14. Expression Editor 415 14.1. Expression Editor Parameters 415 14.2. Key Binding 417 14.3. Editing Commands 417 14.4. Creating New Editing Commands 425 viii Contents 15. Thread System 427 15.1. Thread Creation 428 15.2. Mutexes 428 15.3. Conditions 430 15.4. Locks 431 15.5. Locked increment and decrement 432 15.6. Reference counting with ftype guardians 433 15.7. Thread Parameters 435 15.8. Buffered I/O 435 15.9. Example: Bounded Queues 436 16. Compatibility Features 439 16.1. Hash Tables 439 16.2. Extend-Syntax Macros 441 16.3. Structures 446 16.4. Compatibility File 450 References 451 Summary of Forms 455 Index 493 Preface Chez Scheme is both a general-purpose programming language and an implementation of that language, with supporting tools and documentation. As a superset of the language described in the Revised6 Report on Scheme (R6RS), Chez Scheme supports all stan- dard features of Scheme, including first-class procedures, proper treatment of tail calls, continuations, user-defined records, libraries, exceptions, and hygienic macro expansion. Chez Scheme supports numerous non-R6RS features. A few of these are local and top-level modules, local import, foreign datatypes and procedures, nonblocking I/O, an interactive top-level, compile-time values and properties, pretty-printing, and formatted output. The implementation includes a compiler that generates native code for each processor upon which it runs along with a run-time system that provides automatic storage management, foreign-language interfaces, source-level debugging, profiling support, and an extensive run- time library. The threaded versions of Chez Scheme support native threads, allowing Scheme programs to take advantage of multiprocessor or multiple-core systems. Nonthreaded versions are also available and are faster for single-threaded applications. Both 32-bit and 64-bit versions are available for some platforms. The 64-bit versions support larger heaps, while the 32-bit versions are faster for some applications. Chez Scheme's interactive programming system includes an expression editor that, like many shells, supports command-line editing, a history mechanism, and command comple- tion. Unlike most shells that support command-line editing, the expression editor properly supports multiline expressions. Chez Scheme is intended to be as reliable and efficient as possible, with reliability taking precedence over efficiency if necessary. Reliability means behaving as designed and docu- mented. While a Chez Scheme program can always fail to work properly because of a bug in the program, it should never fail because of a bug in the Chez Scheme implementation. Efficiency means performing at a high level, consuming minimal CPU time and memory. Performance should be balanced across features, across run time and compile time, and across programs and data of different sizes. These principles guide Chez Scheme language and tool design as well as choice of implementation technique; for example, a language fea- ture or debugging hook might not exist in Chez Scheme because its presence would reduce reliability, efficiency, or both. The compiler has been rewritten for Version 9 and generates substantially faster code than the earlier compiler at the cost of greater compile time. This is the primary difference between Versions 8 and 9. x Preface This book (CSUG) is a companion to The Scheme Programming Language, 4th Edition (TSPL4). TSPL4 serves as an introduction to and reference for R6RS, while CSUG de- scribes Chez Scheme features and tools that are not part of R6RS. For the reader's con- venience, the summary of forms and index at the back of this book contain entries from both books, with each entry from TSPL4 marked with a \t" in front of its page number. In the online version, the page numbers given in the summary of forms and index double as direct links into one of the documents or the other. Additional documentation for Chez Scheme includes release notes, a manual page, and a number of published papers and articles that describe various aspects of the system's design and implementation. Thank you for using Chez Scheme. 1. Introduction This book describes Chez Scheme extensions to the Revised6 Report on Scheme [28] (R6RS). It contains as well a concise summary of standard and Chez Scheme forms and procedures, which gives the syntax of each form and the number and types of arguments ac- cepted by each procedure. Details on standard R6RS features can be found in The Scheme Programming Language, 4th Edition (TSPL4) [11] or the Revised6 Report on Scheme. The Scheme Programming Language, 4th Edition also contains an extensive introduction to the Scheme language and numerous short and extended examples. Most of this document also applies equally to Petite Chez Scheme, which is fully com- patible with the complete Chez Scheme system but uses a high-speed interpreter in place of Chez Scheme's incremental native-code compiler.