There are two main varieties of Larceny.

Native Larceny is the fastest and most convenient variety of Larceny. It compiles directly to native machine code for Intel x86 microprocessors running Linux, Apple OS X, or Windows operating systems.

Petit Larceny compiles to C instead of machine code. It can be made to run on most Unix machines.

Binary distributions of native Larceny are available for just about any Intel x86-compatible microprocessor running a Linux, Apple OS X, or Windows operating system. Although Larceny still uses 32-bit pointers, it will run on 64-bit machines provided the appropriate 32-bit libraries have been installed.

Binary distributions of Petit Larceny are available for x86 machines running Linux. Petit Larceny requires the gcc compiler as well as the appropriate 32-bit libraries.

For more details, see doc/HOWTO-INSTALL. If you want to build Larceny or Petit Larceny from source code, see doc/HOWTO-BUILD.

The current versions of Larceny are available for download at Larceny's main web page.

Larceny is distributed in two forms: as a precompiled binary, or as source code that can be used to reconstruct any of the precompiled binary distributions. Unless you intend to modify Larceny yourself, you do not need to download the source code.

Unpack the distribution files with an appropriate command such as one of the following, substituting the version number (such as 0.98) for "X.Y":

tar -xzf larceny-X.Y-bin-native-ia32-linux86.tar.gz
tar -xzf larceny-X.Y-bin-native-ia32-macosx.tar.gz
tar -xzf larceny-X.Y-bin-native-ia32-win32.tar.gz
tar -xzf larceny-X.Y-bin-petit-stdc-macosx.tar.gz
tar -xzf larceny-X.Y-src.tar.gz

That will create a directory with a similar name (but without the .tar.gz suffix) in your current working directory. That is the Larceny root directory, which you may rename to something shorter, such as larceny; the rest of this section will refer to it by that name.

Assuming you have unpacked a binary distribution for Linux or OS X, the larceny directory will contain the following files:

larceny.bin         Run-time system
larceny.heap        Heap image with preloaded libraries and compiler
larceny             Shell script that runs the two files listed above
scheme-script       Shell script that runs Scheme scripts
compile-stale       Scheme script that compiles R7RS/R6RS libraries
startup.sch         Pathnames for the autoload and require features

If you unpacked a binary distribution, then you should be able to run it immediately by making the larceny directory your current working directory and invoking ./larceny. (If that does not work, you may need to install some 32-bit libraries on your machine. See doc/HOWTO-INSTALL.)

Binary distributions for Windows will include a larceny.bat file in addition to the files listed above, so you can run Larceny by invoking larceny. (If that does not work, you may need to tell the DEP feature to let Larceny opt out.)

If you unpacked the source code there will be many other files and directories, but larceny.bin and larceny.heap will not be present.

You may add the larceny directory to your standard path, or you may install Larceny into a directory that is already part of your standard path.

Suppose, for example, that you want to install Larceny in /usr/local/bin and /usr/local/lib/larceny. Copy the larceny and scheme-script files to /usr/local/bin and edit the definition of LARCENY_ROOT at the head of each file to point to the correct directory:

LARCENY_ROOT=/usr/local/lib/larceny

Then move the entire larceny directory to /usr/local/lib/larceny.

You should now be able to run Larceny from any directory by typing "larceny" at a prompt.

If you are installing Petit Larceny, then you will have to compile the R7RS/R6RS runtime and standard libraries before you can run Larceny in R7RS or R6RS modes.

This step is also required if you are building any variety of Larceny from source code. With the prebuilt native varieties of Larceny, however, this step should not be necessary unless you change one of the files in lib/R7RS, lib/R6RS, or lib/SRFI.

Compiling the R7RS/R6RS runtime and standard libraries is accomplished as follows:

    $ ./larceny
    Larceny v0.98 "General Ripper" (...)
    > (require 'r7rsmode)
    > (larceny:compile-r7rs-runtime)
    > (exit)

When you start Larceny in R5RS mode (the default), you will be presented with a banner message and the read-eval-print loop's prompt:

    % larceny
    Larceny vX.Y "<version_name>" (MMM DD YYYY HH:MM:SS, ...)
    larceny.heap, built ...

    >

You can enter a Scheme expression at the prompt. After a complete expression has been read, it will be evaluated and its results printed.

To execute a top-level R6RS program that is contained within a file named pgm, type:

    larceny -r6rs -program pgm

The -program option can be omitted, in which case Larceny will read the top-level program from standard input:

    larceny -r6rs < pgm

If you omit the -program option and do not redirect standard input, then Larceny will wait patiently for you to type a complete top-level program into standard input, terminating it with an end-of-file.

You probably don't want to do that. Had you wanted to type R6RS code at Larceny, you'd be using Larceny's R7RS read/eval/print loop instead.

To execute a top-level R7RS/R6RS program that is contained within a file named pgm, type:

    larceny -r7rs -program pgm

To interact with Larceny's R7RS read/eval/print loop, omit the -program option:

    % larceny -r7rs
    Larceny v0.98 "General Ripper" (...)

The (scheme base) library has already been imported, but you may want to import other libraries as well. For example:

    > (import (scheme read)
              (scheme write)
              (scheme file)
              (scheme cxr)
              (scheme inexact)
              (scheme complex)
              (scheme char)
              (scheme load))

If you'd rather have Larceny import all of the standard R7RS and R6RS libraries at startup, along with a few Larceny-specific procedures, you can use the -r7r6 option instead of r7rs:

    % larceny -r7r6
    Larceny v0.98 "General Ripper" (...)

Using the -r7r6 option is equivalent to using the -r7rs option and then importing the (larceny r7r6) library.

The features procedure will return a list of all cond-expand features and libraries available to you. That procedure reads the source code for all library files found in your current Larceny library path, so don't be surprised if it takes a few seconds.

    > (features)
    (r7rs r6rs larceny larceny-0.98
     exact-closed ratios exact-complex complex ieee-float
     full-unicode full-unicode-strings unicode-7
     posix unix gnu-linux i386 ilp32 little-endian
     ...
     (rnrs arithmetic bitwise (6))
     (rnrs arithmetic fixnums (6))
     (rnrs arithmetic flonums (6))
     (rnrs bytevectors (6))
     ...
     (rnrs (6))
     (scheme base)
     (scheme case-lambda)
     (scheme char)
     (scheme complex)
     (scheme cxr)
     (scheme eval)
     (scheme file)
     (scheme inexact)
     (scheme lazy)
     (scheme load)
     (scheme process-context)
     (scheme r5rs)
     (scheme read)
     (scheme repl)
     (scheme time)
     (scheme write)
     (srfi 1)
     (srfi 1 lists)
     ...)

    > (import (scheme load))

    > (load "lib/R6RS/larceny/benchmarking.sls")
    > (import (larceny benchmarking))
    > (time (vector-for-each + (make-vector 1000000 0)))
    Words allocated: 3053286
    Elapsed time...: 25 ms (User: 25 ms; System: 0 ms)
    Elapsed GC time: 3 ms (CPU: 2 in 2 collections (1 minor).)

(larceny r7r6)                         ; all R7RS/R6RS standard libraries

(scheme base)
(scheme case-lambda)
(scheme char)
(scheme complex)
(scheme cxr)
(scheme eval)
(scheme file)
(scheme inexact)
(scheme lazy)
(scheme load)
(scheme process-context)
(scheme r5rs)
(scheme read)
(scheme repl)
(scheme time)
(scheme write)

(rnrs base (6))                        ; R6RS chapter 9
(rnrs unicode (6))                     ; R6RS library chapter 1
(rnrs bytevectors (6))                 ; R6RS library chapter 2
(rnrs lists (6))                       ; R6RS library chapter 3
(rnrs sorting (6))                     ; R6RS library chapter 4
(rnrs control (6))                     ; R6RS library chapter 5
(rnrs exceptions (6))                  ; R6RS library section 7.1
(rnrs conditions (6))                  ; R6RS library sections 7.2 and 7.3
(rnrs io ports (6))                    ; R6RS library sections 8.1 and 8.2
(rnrs io simple (6))                   ; R6RS library sections 8.1 and 8.3
(rnrs files (6))                       ; R6RS library chapter 9
(rnrs programs (6))                    ; R6RS library chapter 10
(rnrs arithmetic fixnums (6))          ; R6RS library section 11.2
(rnrs arithmetic flonums (6))          ; R6RS library section 11.3
(rnrs arithmetic bitwise (6))          ; R6RS library section 11.4
(rnrs syntax-case (6))                 ; R6RS library chapter 12
(rnrs hashtables (6))                  ; R6RS library chapter 13
(rnrs enums)                           ; R6RS library chapter 14
(rnrs (6))                             ; R6RS library chapter 15
(rnrs eval (6))                        ; R6RS library chapter 16
(rnrs mutable-pairs (6))               ; R6RS library chapter 17
(rnrs mutable-strings (6))             ; R6RS library chapter 18
(rnrs r5rs (6))                        ; R6RS library chapter 19

(rnrs records procedural (6))          ; R6RS library section 6.3
(rnrs records inspection (6))          ; R6RS library section 6.4
(rnrs records syntactic (6))           ; R6RS library section 6.2

(srfi 1 lists)                         ; list library
(srfi 2 and-let*)                      ; extended `and` and `let*`
(srfi 5 let)                           ; extended version of `let`
(srfi 6 basic-string-ports)            ; basic string ports
(srfi 8 receive)                       ; binding to multiple values
(srfi 9 records)                       ; defining record types
(srfi 11 let-values)                   ; syntax for multiple values
(srfi 13 strings)                      ; string libraries
(srfi 14 char-sets)                    ; character-set library (default)
(srfi 14 unicode)                      ;   for all Unicode characters
(srfi 14 bmp)                          ;   for the Basic Multilingual Plane
(srfi 14 latin-1)                      ;   for ISO 8859-1 (Latin-1)
(srfi 16 case-lambda)                  ; syntax for variable arity
(srfi 17 generalized-set!)             ; generalized set!
(srfi 19 time)                         ; time data types and procedures
(srfi 23 error)                        ; error reporting mechanism
(srfi 25 multi-dimensional-arrays)     ; multi-dimensional array primitives
(srfi 26 cut)                          ; specializing without currying
(srfi 27 random-bits)                  ; sources of random bits
(srfi 28 basic-format-strings)         ; basic format strings
(srfi 29 localization)                 ; localization
(srfi 38 with-shared-structure)        ; i/o for data with shared structure
(srfi 39 parameters)                   ; parameter objects
(srfi 41 streams)                      ; streams
(srfi 42 eager-comprehensions)         ; eager comprehensions
(srfi 43 vectors)                      ; vector library
(srfi 45 lazy)                         ; iterative lazy algorithms
(srfi 48 intermediate-format-strings)  ; format
(srfi 51 rest-values)                  ; rest values hackery
(srfi 54 cat)                          ; still more formatting
(srfi 59 vicinities)                   ; vicinity
(srfi 61 cond)                         ; a more general cond clause
(srfi 63 arrays)                       ; homogeneous, heterogeneous arrays
(srfi 64 testing)                      ; an API for test suites
(srfi 67 compare-procedures)           ; three-way comparison procedures
(srfi 78 lightweight-testing)          ; lightweight testing
(srfi 87 case)                         ; a more general case clause
(srfi 98 os-environment-variables)     ; environment variables
(srfi 99 records)                      ; (composite library)
(srfi 99 records procedural)           ; (procedural API)
(srfi 99 records inspection)           ; (inspection API)
(srfi 99 records syntactic)            ; (syntactic API)
(srfi 101 random-access-lists)         ; fast and purely functional lists
(srfi 111 boxes)                       ; boxes
(srfi 112)                             ; environment inquiry
(srfi 113 sets)                        ; sets and bags
(srfi 114 comparators)                 ; comparators
(srfi 115 regexp)                      ; regular expressions
(srfi 116 ilists)                      ; immutable lists

(srfi 60 integer-bits)                 ; integers as bits
(srfi 66 octet-vectors)                ; octet vectors
(srfi 69 basic-hash-tables)            ; basic hash tables
(srfi 71 let)                          ; extensions of let, let*, letrec
(srfi 74 blobs)                        ; octet-addressed binary blocks
(srfi 95 sorting-and-merging)          ; sorting and merging

(err5rs records procedural)            ; ERR5RS records (procedural API)
(err5rs records inspection)            ; ERR5RS records (inspection API)
(err5rs records syntactic)             ; ERR5RS records (syntactic API)
(err5rs load)                          ; ERR5RS load procedure

(larceny load)                         ; extension of (err5rs load)
(larceny compiler)                     ; separate compilation (R7RS/R6RS)
(larceny benchmarking)                 ; timing facilities
(larceny profiling)                    ; profiling of Scheme code
(larceny r7r6)                         ; all R7RS/R6RS standard libraries
(larceny records printer)              ; custom printing of records
(larceny shivers-syntax)               ; syntax favored by Olin Shivers
(r5rs)                                 ; approximates the R5RS top level
(explicit-renaming)                    ; macros with explicit renaming

    (import (primitives random current-seconds
                        getenv setenv system
                        current-directory file-modification-time)
            (scheme time))

On most Unix systems (including Linux and Apple's OS X), Larceny's scheme-script will execute Scheme scripts as described in R6RS non-normative appendix D, with or without the optional script header. To make Scheme scripts executable in their own right, without executing scheme-script directly, add Larceny's root directory to your path as described in doc/HOWTO-INSTALL, or edit scheme-script to define LARCENY_ROOT and copy that edited scheme-script to a directory in your path.

Suppose, for example, that /home/myself/hello is an R7RS/R6RS Scheme script whose first line is the optional script header shown below:

#!/usr/bin/env scheme-script

If you do not have execute permission for this script, or Larceny's root directory is not in your path, you can still run the script from Larceny's root directory as follows:

    % ./scheme-script /home/myself/hello

If you have execute permission for the script, and Larceny's root directory is in your path, you can also run the script as follows:

    % /home/myself/hello

If, in addition, the directory that contains the script is in your path, you can run the script as follows:

    % hello

You may also pass command-line arguments to a Scheme script.

On Unix systems, standard input and output can be redirected in the usual way. In Larceny, standard input corresponds to the textual port initially returned by current-input-port, and standard output corresponds to the textual port initially returned by current-output-port.

Suppose hello.sch contains the following R5RS code:

    (display "Hello world!")
    (newline)
    (exit)

You can run hello.sch as a script by executing Larceny as follows:

    % larceny -nobanner -- hello.sch

You can redirect Larceny's standard input, in which case you may want to eliminate the herald announcement and the read/eval/print loop's prompt:

    % larceny -nobanner -- -e "(begin (herald #f) (repl-prompt values))" \
              < hello.sch

For an explanation of why that works, which may suggest other creative uses of Larceny, ask for help:

    % larceny -help

In R6RS mode, which is batch-only, errors should result in an error message followed by a clean exit from the program.

If your program encounters an error in an interactive mode (R5RS or R75RS), it will enter the debugger; this is believed to be a feature.

Despite its crudity, and to some extent because of it, Larceny's debugger works at least as well with optimized compiled code as with interpreted code.

If you type a question mark at the debugger prompt, the debugger will print a help message. That message is more helpful if you understand the Twobit compiler and Larceny's internal representations and invariants, but this manual is not the place to explain those things.

The debugging context is saved so you can exit the debugger and re-enter it from the main read/eval/print loop's prompt:

    > (debug)

The debugger is pretty much a prototype; you don't need to tell us how bad it is.

By default, Larceny's Twobit compiler performs several optimizations that are fully compatible with the R7RS but may not be fully compatible with the older R6RS, R5RS, and IEEE-1178 standards.

When compiling R5RS code, Larceny's Twobit compiler normally makes several assumptions that allow it to generate faster code; for example, the compiler assumes Scheme's standard procedures will not be redefined.

To obtain strict conformance to R5RS semantics at the expense of slower code, use R5RS mode and evaluate the expression

    (compiler-switches 'standard)

To make the compiler generate faster code, you can promise not to redefine standard procedures and not to redefine any top-level procedure while it is running. To make this promise, evaluate

        (compiler-switches 'fast-safe)

To view the current settings of Twobit's numerous compiler switches, evaluate

        (compiler-switches)

All of Twobit's compiler switches are procedures whose setting can be changed by passing the new value of the switch as an argument.

For more information, evaluate

        (help)

To alter the compiler switches from R7RS mode, or to disable certain compiler optimizations that are incompatible with the R6RS, see the section that describes the (larceny compiler) library.

By default, Larceny recognizes several Larceny-specific flags of the form permitted by the R6RS. The flag you are most likely to encounter represents one of Larceny's unspecified values:

    #!unspecified

Certain other flags have special meanings to Larceny's read and get-datum procedures. They are described below.

By default, Larceny is case-sensitive. This global default can be overridden by specifying —foldcase or —nofoldcase on Larceny's command line, or by changing the value of Larceny's case-sensitive? parameter.

The case-sensitivity of a particular textual input port is affected by reading one of the following flags from the port using the read or get-datum procedures:

    #!fold-case
    #!no-fold-case

The #!fold-case flag enables case-folding on data read from the port by the read and get-datum procedures, while the #!no-fold-case flag disables case-folding. The behavior established by one of these flags extends to the next such flag read from the port by read or get-datum.

Both #!fold-case and #!no-fold-case are treated as comments by Larceny's read and get-datum procedures. (This is a change from Larceny v0.97.)

When a port is first opened, the Larceny-specific lexical extensions that are accepted on the port are determined by Larceny's lexical parameters.

The following flags change the case-sensitivity and lexical extensions on the specific port from which they are read:

    #!r7rs         ; implies #!no-fold-case, enables R7RS syntax
    #!r6rs         ; implies #!no-fold-case, negates other flags
    #!r5rs         ; implies #!fold-case, enables R7RS syntax
    #!err5rs       ; enables R7RS/R6RS syntax with extensions
    #!larceny      ; implies #!no-fold-case and #!err5rs

All of those flags are treated as comments by Larceny's read and get-datum procedures. (This is a change from Larceny v0.97.)

When given no argument, these parameters return the current default for some aspects of the lexical syntax that will be accepted on newly created input ports or written to newly created output ports. When given an argument, these procedures change the default as specified by the argument.

The initial values of these parameters are determined by the -r7r6, -r7rs, -r6rs, or -r5rs options on Larceny's command line. The -r6rs option disables non-R6RS lexical syntax; the -r7r6, -r7rs, and -r5rs options allow both R7RS and R6RS syntax.

Procedure case-sensitive?

(case-sensitive? ) => boolean

(case-sensitive? boolean)

If true, newly created textual input ports behave as though they began with !fold-case. If false, newly created textual input ports behave as though they began with !no-fold-case.

Procedure read-r6rs-flags?

(read-r6rs-flags? ) => boolean

(read-r6rs-flags? boolean)

If true, allows flags other than !r6rs to be read from newly created ports. If false, flags other than !r6rs raise exceptions when read.

Procedure read-r7rs-weirdness?

(read-r7rs-weirdness? ) => boolean

(read-r7rs-weirdness? boolean)

If true, newly created textual input ports behave as though they began with #!r7rs, and R7RS lexical syntax will be used when writing external representations to newly created textual output ports. If false, R7RS-specific extensions to R5RS/R6RS lexical syntax may raise exceptions.

Procedure read-r6rs-weirdness?

(read-r6rs-weirdness? ) => boolean

(read-r6rs-weirdness? boolean)

If true, allows all R6RS lexical syntax on newly created ports without disabling other lexical syntax on those ports (so newly created textual input ports do not behave as though they began with #!r6rs). If false, R6RS-specific extensions to R5RS/R7RS lexical syntax may raise exceptions.

If read-r6rs-weirdness? is true and read-r7rs-weirdness? is false, then the R6RS bytevector syntax will be used when writing to newly opened textual output ports. If neither or both are true, then R7RS bytevector syntax will be used.

Procedure read-larceny-weirdness?

(read-larceny-weirdness? ) => boolean

(read-larceny-weirdness? boolean)

Determines whether newly created textual ports allow Larceny's usual extensions to R5RS lexical syntax. In addition, this parameter determines whether newly created ports allow # as an insignificant digit, which is required by the R5RS but disallowed by the R6RS and not required by the R7RS.

Procedure read-traditional-weirdness?

(read-traditional-weirdness? ) => boolean

(read-traditional-weirdness? boolean)

Determines whether newly created textual ports allow certain lexical extensions that are deprecated in Larceny.

In Larceny, file names generally follow Unix conventions, even on Windows. The following suffixes have special meanings to some components of Larceny.

Larceny's root directory should contain the following files:

    larceny
    scheme-script
    larceny.bin
    larceny.heap
    startup.sch

The following subdirectories are also essential for correct operation of some features of some modes in some varieties of Larceny:

    include
    lib
    lib/Base
    lib/Debugger
    lib/Ffi
    lib/MzScheme
    lib/R6RS
    lib/SRFI
    lib/Standard
    lib/TeachPacks

The include subdirectory is used when compiling files with Petit Larceny.

The startup.sch file tells Larceny's require procedure to search some of the lib subdirectories for libraries that are loaded dynamically.

The R7RS and R6RS standards do not specify any mapping from library names to files or other locations at which the code for a library might be found.

R6RS non-normative appendix E emphasizes the arbitrariness of such mappings:

To put it more starkly:

R7RS section 5.1 urges implementations to be reasonable:

Fortunately, de facto standards have been emerging. Larceny supports those de facto standards by providing these Larceny-specific mechanisms:

R7RS programs may use any of those five mechanisms, and may also use a sixth mechanism: An R7RS program can be written as a little configuration program that loads the program's libraries from files before any libraries are imported. This sixth mechanism appears to be portable, but is not available to R6RS programs executing in Larceny's R6RS mode because it mixes execution with macro expansion, which is explicitly forbidden by one of the R6RS standard's "absolute requirements".

Suppose Larceny's -path option is used to specify a certain directory, and the program imports a nonstandard library whose name is of the form (name1 name2 … lastname). Larceny will search for that library in the following files:

The search starts with the first of those file names, continues with the following file names in order, and ends when a file with one of those names is found. The imported library must be one of the libraries defined within the first file found by this search, since the search is not continued after that first file is found (except as noted in the next paragraph).

If the search ends by finding a file whose name ends with .slfasl, then Larceny checks to see whether there is a file in the same directory with the same root name but ending with .sld or .sls instead of .slfasl. If the .sld or .sls file has been modified since the .slfasl file was last modified, then a warning is printed and the .sld or .sls file is loaded instead of the .slfasl file. Otherwise the .slfasl file is loaded.

In R5RS mode, Larceny's -path option and LARCENY_LIBPATH environment variable may be used to specify directories to be searched by the require procedure, which takes a single symbol libname as its argument. The require procedure will search for the following files in every directory that is part of the current require path, starting with the directories specified by LARCENY_LIBPATH and the -path option:

These files are expected to contain R5RS code, not library definitions. Otherwise the search proceeds much the same as when searching for an R7RS/R6RS library.

Procedure require

(require libname)

libname must be a symbol that names an R5RS-compatible library within the current require path.

If the library has not already been loaded, then it is located and loaded. If the library is found and loaded successfully, then require returns true; otherwise an error is signalled.

If the library has already been loaded, then require returns false without loading the library a second time.

Procedure current-require-path

(current-require-path ) => stringlist

(current-require-path stringlist)

The optional argument is a list of directory names (without slashes at the end) that should be searched by require and (in R7RS/R6RS modes) by Larceny's autoload feature. Returns the list of directory names that will be searched.

On Unix machines, the most convenient way to compile a group of R7RS/R6RS libraries and top-level programs is to use the compile-stale script in Larceny's root directory. If Larceny's root directory is in your execution path, then there are just two steps:

For example:

    % cd lib/R7RS
    % compile-stale

On non-Unix machines, you can accomplish the same thing using Larceny's R7RS mode and the (larceny compiler) library:

    % pushd lib\R7RS
    % ../../larceny -r7rs
    Larceny v0.98 "General Ripper"

    > (import (larceny compiler))

    > (compile-stale-libraries)

To compile individual files, use the compile-file or compile-library procedures that are exported by (larceny compiler).

Procedure compile-file

(compile-file sourcefile)

Compiles sourcefile, which must be a string naming a file that contains R5RS source code. If faslfile is supplied as a second argument, then it must be a string naming the file that will contain the compiled code; otherwise the name of the compiled file is obtained from sourcefile by replacing the ".sch" or ".scm" suffix with ".fasl".

For R7RS/R6RS libraries and top-level programs, see above.

Larceny v0.98 does not implement these features of the R7RS standard:

include, include-ci, and cond-expand are fully supported at the top-level declaration and definition levels of R7RS libraries.

To simplify interoperability with R6RS libraries and programs, the integer?, rational?, and real? procedures exported by (scheme base) have R6RS semantics. It is not clear whether that is fully compatible with the R7RS (small) standard, because the R7RS specification of those procedures appears to contradict itself.

If any other R7RS feature is missing or incompatible with the R7RS (small) standard, it's a bug.

R7RS and R6RS modes support all procedures and syntaxes exported by the (rnrs base) library.

Larceny's R5RS mode does not support library, import, or identifier-syntax.

All of Larceny's modes support all features of the (rnrs unicode) library.

Larceny v0.98 tries to conform to The Unicode Standard, Version 7.0.

R7RS and R6RS modes support all procedures and syntaxes exported by (rnrs bytevectors), but the endianness syntax is deprecated because it is redundant with quote. Larceny's R5RS mode does not support endianness.

In Larceny, any symbol names a supported endianness. The symbols big and little have their expected meanings. All other symbols mean (native-endianness) with respect to integer operations, but mean the opposite of (native-endianness) with respect to IEEE-754 operations. For string operations, the endianness must be the symbol big or the symbol little. All of these extensions are permitted by the R6RS standard.

Larceny's utf16->string and utf32->string accept one, two, or three arguments. The R6RS specification of these procedures does not allow them to accept a single argument, but that is believed to be an error in the R6RS.

All of Larceny's modes support all features of the (rnrs lists) library.

All of Larceny's modes support all features of the (rnrs sorting) library.

All of Larceny's modes support all features of the (rnrs control) library.

R7RS and R6RS modes support all procedures and syntaxes exported by (rnrs records procedural), (rnrs records inspection), and (rnrs records syntactic).

Those libraries are deprecated, however; the make-record-constructor-descriptor procedure does not simplify unusually complex cases enough to justify the complexity it adds to typical cases, and the entire syntactic layer is gratuitously incompatible with the procedural layer.

Larceny extends the R7RS define-record-type syntax exported by (scheme base) to accept the deprecated R6RS syntax, and extends the deprecated define-record-type syntax exported by (rnrs records syntactic) to accept R7RS syntax. Larceny's unification of the two syntaxes within a single implementation of define-record-type allows libraries and programs to import both (scheme base) and (rnrs) without having to rename one version of define-record-type.

Larceny also extends its unified R7RS/R6RS define-record-type to support all features of (srfi :99 records syntactic). So long as the deprecated R6RS syntax is not used, Larceny's define-record-type is fully compatible with the procedural layers defined by (srfi :99 records procedural) and by (rnrs records procedural).

Larceny's R5RS mode supports all features of the deprecated (rnrs records procedural) and (rnrs records inspection) libraries. R5RS mode does not support (rnrs records syntactic).

All of Larceny's modes support all features of the (err5rs records procedural) and (err5rs records inspection) libraries. R7RS and R6RS modes also support the (err5rs records syntactic) library. These libraries are equivalent to the (srfi :99 records procedural), (srfi :99 records inspection), and (srfi :99 records syntactic) libraries.

The record definition syntax of SRFI 9 is a proper subset of the syntax provided by the (err5rs records syntactic) library. In R5RS mode, SRFI 9 can be loaded dynamically using the require procedure:

    > (require 'srfi-9)

We recommend the R7RS and/or SRFI 9 libraries be used instead of the corresponding R6RS libraries.

All of Larceny's modes support all features of the (rnrs exceptions) and (rnrs conditions) libraries.

R7RS and R6RS modes support all names exported by the (rnrs io ports), (rnrs io simple), and (rnrs files) libraries.

The buffer-mode, eol-style, and error-handling-mode syntaxes are deprecated because they are redundant with quote. Larceny may provide these deprecated syntaxes in the form of procedures rather than syntax, but this deviation from R6RS semantics cannot be detected by portable R6RS programs.

Larceny's R5RS mode supports all non-deprecated features of those libraries.

Larceny supports four distinct buffer modes: none, line, datum, and block. The R6RS requires the buffer-mode syntax to raise an exception for the datum buffer mode, which is the buffer mode Larceny uses for interactive output ports.

In Larceny, any symbol names a supported end-of-line style. All end-of-line and error-handling-mode symbols whose meanings are not described by the R6RS have locale-dependent meanings, which is an extension permitted by the R6RS standard.

Although Larceny supports the UTF-16 codec, it is not really useful on Windows machines (where it should be most useful) because Larceny's low-level file system mimics a byte-oriented Unix file system even on Windows. This problem should be addressed in some future version of Larceny.

The most up-to-date list of known deviations from R6RS io semantics can be found on the web page that describes the current status of Larceny's R6RS-compatible mode.

R7RS and R6RS modes support the (rnrs programs) library.

Larceny's R5RS mode provides the exit procedure but not the command-line procedure of that library. Larceny's traditional command-line-arguments procedure can be used to implement an approximation to command-line. For a definition, see lib/R6RS/rnrs/programs.sls.

All of Larceny's modes support all features of the (rnrs arithmetic fixnums), (rnrs arithmetic flonums), and (rnrs arithmetic bitwise) libraries.

R7RS and R6RS modes support the (rnrs syntax-case) library. Larceny's R5RS mode does not.

All of Larceny's modes support all features of the (rnrs hashtables) library.

R7RS and R6RS modes support the (rnrs enums) library. Larceny's R5RS mode provides all of the procedures exported by (rnrs enums) but does not provide the define-enumeration syntax.

R7RS and R6RS modes support the (rnrs eval) library. Larceny's R5RS mode provides an R5RS-compatible eval procedure, not an R6RS-compatible eval procedure, and does not provide the environment procedure.

All of Larceny's modes support all features of the (rnrs mutable-pairs) and (rnrs mutable-strings) libraries.

All of Larceny's modes support all features of the (rnrs r5rs) library.

The (larceny load) library exports both the load procedure of (scheme load) and Larceny's r5rs:require procedure, which is a renaming of the require procedure used by Larceny's R5RS mode.

In Larceny's R7RS mode, the load procedure can load R5RS libraries and programs as well as R7RS/R6RS libraries.

The r5rs:require procedure should be used only for dynamic loading of R5RS libraries into Larceny's underlying R5RS system. The variables defined by that library can be imported into an R7RS session or R7RS/R6RS library or program using a primitives clause in an import form.

The (larceny compiler) library exports the load and r5rs:require procedures of (larceny load), the current-require-path procedure, the compile-file, compile-library, and compile-stale-libraries procedures described below, and the compiler-switches procedure.

These procedures can be used to compile R7RS/R6RS libraries and top-level programs before they are imported or executed. This is especially important for Petit Larceny, which would otherwise use an interpreter. For native Larceny, whose just-in-time compiler generates native machine code as source libraries and programs are loaded, imported, or executed, the main advantage of separate compilation is that compiled libraries and programs will load much faster than source libraries and programs.

The main disadvantage of separate compilation is that compiled libraries and programs go stale when their source code is changed or when a library on which they depend is changed or recompiled. Stale libraries and programs can be dangerously inconsistent with libraries on which they depend, so Larceny checks for staleness and refuses to execute a stale library or program. The compile-stale-libraries procedure provides a convenient way to recompile stale libraries and programs.

(compile-file sourcefile [slfaslfile])

Compiles sourcefile, which must be a string naming a file that contains source code for one or more R7RS/R6RS libraries or a top-level program. If slfaslfile is supplied as a second argument, then it must be a string naming the file that will contain the compiled code; otherwise the name of the compiled file is obtained from sourcefile by replacing the ".sld" or ".sls" suffix with ".slfasl".

Procedure compile-library

(compile-library sourcefile [slfaslfile])

Compiles sourcefile, which must be a string naming a file that contains source code for one or more R7RS/R6RS libraries. Apart from its unwillingness to compile top-level programs, compile-library behaves the same as compile-file above.

Procedure compile-stale-libraries

(compile-stale-libraries )

(compile-stale-libraries changedfile)

If no argument is supplied, then all ".sld" and ".sls" files that lie within the current directory or a subdirectory are recompiled.

If changedfile is supplied, then it must be a string giving the absolute pathname of a file. (In typical usage, changedfile is a source file that has been modified, making it necessary to recompile all files that depend upon it.) Compiles all R7RS/R6RS library files that lie within the same directory as changedfile or a subdirectory, and have not yet been compiled or whose compiled files are older than changedfile.

Procedure compiler-switches

(compiler-switches )

(compiler-switches mode)

If no argument is supplied, then the current settings of all compiler switches are displayed. Each of those switches is itself a parameter that is exported by the (larceny compiler) library. Calling any individual compiler switch with no arguments will return its current setting. Calling any individual compiler switch with an argument (usually a boolean) will change its setting to that argument.

The compiler-switches procedure may also be called with one of the following symbols as its argument:

default sets most compiler switches to their default settings.

fast-safe enables all optimizations but continues to generate code to perform all run-time type and range checks that are needed for safety (in the traditional sense, not the R6RS sense).

fast-unsafe enables all optimizations and also disables type and range checking. This setting is deprecated because it compromises safety (in the traditional sense).

slow turns off all optimizations.

standard sets compiler switches for maximal conformance to the R5RS and R6RS standards.

The (larceny benchmarking) library exports the time syntax and run-benchmark procedure described below.

Syntax time

(time expression)

Evaluates expression and returns its result after printing approximations to the storage allocated and time taken during evaluation of expression.

    > (time (fib 30))
    Words allocated: 0
    Words reclaimed: 0
    Elapsed time...: 49 ms (User: 48 ms; System: 0 ms)
    Elapsed GC time: 0 ms (CPU: 0 in 0 collections.)
    832040

(run-benchmark name iterations thunk predicate)

Given the name of a benchmark, the number of iterations to be performed, a zero-argument procedure thunk that runs the benchmark, and a unary predicate that checks the result of thunk, prints approximations to the storage allocated and time taken by iterations calls to thunk.

    > (run-benchmark "fib30"
                     100
                     (lambda () (fib 30))
                     (lambda (x) (= x 832040)))

    --------------------------------------------------------
    fib30
    Words allocated: 0
    Words reclaimed: 0
    Elapsed time...: 4828 ms (User: 4824 ms; System: 4 ms)
    Elapsed GC time: 0 ms (CPU: 0 in 0 collections.)

The (larceny records printer) library exports the two procedures described below. These procedures can be used to override Larceny's usual printing of records and opaque types that were defined using the records libraries.

Procedure rtd-printer

(rtd-printer rtd) => maybe-procedure

Given a record type descriptor, returns its custom print procedure, or returns false if the rtd has no custom print procedure.

Procedure rtd-printer-set!

(rtd-printer-set! rtd printer)

Given a record type descriptor rtd and a printer for instances of that rtd, installs printer as a custom print procedure for rtd. The printer should be a procedure that, given an instance of the rtd and a textual output port, writes a representation of the instance to the port.

The (err5rs load) library has been superseded by the (scheme load) library, and continues to exist only for backward compatibility.

Procedure load

(load filename)

Loads ERR5RS code from filename, evaluating each form as though it had been entered at the interactive read/eval/print loop.

The ERR5RS record facility described below incorporates all optional features of SRFI 99 and is otherwise identical to the facilities described by SRFI 99. SRFI 99 is itself an extension of SRFI 9, whose define-record-type syntax is identical to that defined by the R7RS.

When a procedure is said to be equivalent to an R6RS procedure, the equivalence holds only when all arguments have the properties required of them by the R6RS specification. ERR5RS does not mandate R6RS exception semantics for programs that violate the specification.

    <definition>
      -> <record type definition>           ; addition to 7.1.6 in R5RS

    <record type definition>
      -> (define-record-type <type spec>
           <constructor spec>
           <predicate spec>
           <field spec> ...)

    <type spec>  -> <type name>
                 -> (<type name> <parent>)

    <constructor spec>
                 -> #f
                 -> #t
                 -> <constructor name>
                 -> (<constructor name> <field name> ...)

    <predicate spec>
                 -> #f
                 -> #t
                 -> <predicate name>

    <field spec> -> <field name>
                 -> (<field name>)
                 -> (<field name> <accessor name>)
                 -> (<field name> <accessor name> <mutator name>)

    <parent>           -> <expression>

    <type name>        -> <identifier>
    <constructor name> -> <identifier>
    <predicate name>   -> <identifier>
    <accessor name>    -> <identifier>
    <mutator name>     -> <identifier>
    <field name>       -> <identifier>

Larceny provides Unicode strings with R6RS semantics.

The string-downcase and string-upcase procedures perform Unicode-compatible case folding, which can result in a string whose length is different from that of the original.

Larceny may still provide string-downcase! and string-upcase! procedures, but they are deprecated.

A bytevector is a data structure that stores bytes — exact 8-bit unsigned integers. Bytevectors are useful in constructing system interfaces and other low-level programming. In Larceny, many bytevector-like structures — bignums, for example — are implemented in terms of a lower-level bytevector-like data type. The operations on generic bytevector-like structures are particularly fast but useful largely in code that manipulates Larceny's data representations.

The (rnrs bytevectors) library now provides a large set of procedures that, in Larceny, are defined using the procedures described below.

Integrable procedure make-bytevector

(make-bytevector length) => bytevector

(make-bytevector length fill) => bytevector

Returns a bytevector of the desired length. If no second argument is given, then the bytevector has not been initialized and most likely contains garbage.

Operations on bytevector structures

(bytevector? obj) => boolean

(bytevector-length bytevector) => integer

(bytevector-ref bytevector offset) => byte

(bytevector-set! bytevector offset byte) => unspecified

(bytevector-equal? bytevector1 bytevector2) => boolean

(bytevector-fill! bytevector byte) => unspecified

(bytevector-copy bytevector) => bytevector

These procedures do what you expect. All are integrable, except bytevector-equal? and bytevector-copy. The bytevector-equal? name is deprecated, since the R6RS calls it bytevector=?.

Operations on bytevector-like structures

(bytevector-like? obj) => boolean

(bytevector-like-length bytevector) => integer

(bytevector-like-ref bytevector offset) => byte

(bytevector-like-set! bytevector offset byte) => unspecified

(bytevector-like-equal? bytevector1 bytevector2) => boolean

(bytevector-like-copy bytevector) => bytevector

A bytevector-like structure is a low-level representation for indexed arrays of uninterpreted bytes. Bytevector-like structures are used to represent types such as bignums and flonums.

There is no way to construct a "generic" bytevector-like structure; use the constructors for specific bytevector-like types.

The bytevector-like operations operate on all bytevector-like structures. All are integrable, except bytevector-like-equal? and bytevector-like-copy. All are deprecated because they violate abstraction barriers and make your code representation-dependent; they are useful mainly to Larceny developers, who might otherwise be tempted to write some low-level operations in C or assembly language.

Procedure vector-copy

(vector-copy vector) => vector

Returns a shallow copy of its argument.

Operations on vector-like structures

(vector-like? object) => boolean

(vector-like-length vector-like) => fixnum

(vector-like-ref vector-like k) => object

(vector-like-set! vector-like k object) => unspecified

A vector-like structure is a low-level representation for indexed arrays of Scheme objects. Vector-like structures are used to represent types such as vectors, records, symbols, and ports.

There is no way to construct a "generic" vector-like structure; use the constructors for specific data types.

The vector-like operations operate on all vector-like structures. All are integrable. All are deprecated because they violate abstraction barriers and make your code representation-dependent; they are useful mainly to Larceny developers, who might otherwise be tempted to write some low-level operations in C or assembly language.

Operations on procedures

(make-procedure length) => procedure

(procedure-length procedure) => fixnum

(procedure-ref procedure offset) => object

(procedure-set! procedure offset object) => unspecified

These procedures operate on the representations of procedures and allow user programs to construct, inspect, and alter procedures.

Procedure procedure-copy

(procedure-copy procedure) => procedure

Returns a shallow copy of the procedure.

The rest of this section describes some procedures that reach through abstraction barriers in a more controlled way to extract heuristic information from procedures for debugging purposes.

The procedures that extract heuristic information from procedures are permitted to return any result whatsoever. If the type of a result is not among those listed below, then the result represents an implementation-dependent extension to this interface, which may safely be interpreted as though no information were available from the procedure. Otherwise the result is to be interpreted as described below.

Procedure procedure-arity

(procedure-arity proc)

Returns information about the arity of proc. If the result is #f, then no information is available. If the result is an exact non-negative integer k, then proc requires exactly k arguments. If the result is an inexact non-negative integer n, then proc requires n or more arguments. If the result is a pair, then it is a list of non-negative integers, each of which indicates a number of arguments that will be accepted by proc; the list is not necessarily exhaustive.

Procedure procedure-documentation-string

(procedure-documentation-string proc)

Returns general information about proc. If the result is #f, then no information is available. If the result is a string, then it is to be interpreted as a "documentation string" (see Common Lisp).

Procedure procedure-name

(procedure-name proc)

Returns information about the name of proc. If the result is #f, then no information is available. If the result is a symbol or string, then it represents a name. If the result is a pair, then it is a list of symbols and/or strings representing a path of names; the first element represents an outer name and the last element represents an inner name.

Procedure procedure-source-file

(procedure-source-file proc)

Returns information about the name of a file that contains the source code for proc. If the result is #f, then no information is available. If the result is a string, then the string is the name of a file.

Procedure procedure-source-position

(procedure-source-position proc)

Returns information about the position of the source code for proc whithin the source file specified by procedure-source-file. If the result is #f, then no information is available. If the result is an exact integer k, then k characters precede the opening parenthesis of the source code for proc within that source file.

Procedure procedure-expression

(procedure-expression proc)

Returns information about the source code for proc. If the result is #f, then no information is available. If the result is a pair, then it is a lambda expression in the traditional representation of a list.

Procedure procedure-environment

(procedure-environment proc)

Returns information about the environment of proc. If the result is #f, then no information is available. In any case the result may be passed to any of the environment inquiry functions.

Notes on the Larceny implementation

Twobit does not yet produce data for all of these functions, so some of them always return #f.

The (rnrs lists) library now provides a set of procedures that may supersede some of the procedures described below. If one of Larceny's procedures duplicates the semantics of an R6RS procedure whose name is different, then Larceny's name is deprecated.

Procedure append!

(append! list1 list2 … obj) => object

append! destructively appends its arguments, which must be lists, and returns the resulting list. The last argument can be any object. The argument lists are appended by changing the cdr of the last pair of each argument except the last to point to the next argument.

Procedure every?

(every? procedure list1 list2 …) => object

every? applies procedure to each element tuple of list_s in first-to-last order, and returns #f as soon as _procedure returns #f. If procedure does not return #f for any element tuple of list_s, then the value returned by _procedure for the last element tuple of _list_s is returned.

Procedure last-pair

(last-pair list-structure) => pair

last-pair returns the last pair of the list structure, which must be a sequence of pairs linked through the cdr fields.

Procedure list-copy

(list-copy list-copy) => list

list-copy makes a shallow copy of the list and returns that copy.

Procedure remove

(remove key list) => list

(remq key list) => list

(remv key list) => list

(remp pred? list) => list

Each of these procedures returns a new list which contains all the elements of list in the original order, except that those elements of the original list that were equal to key (or that satisfy pred?) are not in the new list. Remove uses equal? as the equivalence predicate; remq uses eq?, and remv uses eqv?.

Procedure remove!

(remove! key list) => list

(remq! key list) => list

(remv! key list) => list

(remp! pred? list) => list

These procedures are like remove, remq, remv, and remp, except they modify list instead of returning a fresh list.

Procedure reverse!

(reverse! list) => list

reverse! destructively reverses its argument and returns the reversed list.

Procedure some?

(some? procedure list1 list2 …) => object

some? applies procedure to each element tuple of list_s in first-to-last order, and returns the first non-false value returned by _procedure. If procedure does not return a true value for any element tuple of _list_s, then some? returns #f.

The (rnrs sorting) library now provides a small set of procedures that supersede most of the procedures described below. All of the procedures described below are therefore deprecated.

Procedures sort and sort!

(sort list less?) => list

(sort vector less?) => vector

(sort! list less?) => list

(sort! vector less?) => vector

These procedures sort their argument (a list or a vector) according to the predicate less?, which must implement a total order on the elements in the data structures that are sorted.

sort returns a fresh data structure containing the sorted data; sort! sorts the data structure in-place.

The (scheme base), (scheme file), (rnrs io ports), and (rnrs files) libraries now provide a set of procedures that may supersede some of the procedures described below. If one of Larceny's procedures duplicates the semantics of an R7RS or R6RS procedure whose name is different, then Larceny's name is deprecated.

Procedure close-open-files

(close-open-files ) => unspecified

Closes all open files.

Procedure console-input-port

(console-input-port ) => input-port

Returns a character input port such that no read from the port has signalled an error or returned the end-of-file object.

Rationale: console-input-port and console-output-port are artifacts of Unix interactive I/O conventions, where an interactive end-of-file does not mean "quit" but rather "done here". Under these conventions the console port should be reset following an end-of-file. Resetting conflicts with the semantics of ports in Scheme, so console-input-port and console-output-port return a new port if the current port is already at end-of-file.

Since it is convenient to handle errors in the same manner as end-of-file, these procedures also return a new port if an error has been signalled during an I/O operation on the port.

Console-input-port and console-output-port simply call the port generators installed in the parameters console-input-port-factory and console-output-port-factory, which allow user programs to install their own console port generators.

Procedure console-output-port

(console-output-port ) => output-port

Returns a character output port such that no write to the port has signalled an error.

See console-input-port for a full explanation.

Parameter console-input-port-factory

The value of this parameter is a procedure that returns a character input port such that no read from the port has signalled an error or returned the end-of-file object.

See console-input-port for a full explanation.

Parameter console-output-port-factory

The value of this parameter is a procedure that returns a character output port such that no write the port has signalled an error.

See console-input-port for a full explanation.

Parameter current-input-port

The value of this parameter is a character input port.

Parameter current-output-port

The value of this parameter is a character output port.

Procedure delete-file

(delete-file filename) => unspecified

Deletes the named file. No error is signalled if the file does not exist.

Procedure eof-object

(eof-object ) => end-of-file object

Eof-object returns an end-of-file object.

Procedure file-exists?

(file-exists? filename) => boolean

File-exists? returns #t if the named file exists at the time the procedure is called.

Procedure file-modification-time

(file-modification-time filename) => vector or #f

File-modification-time returns the time of last modification of the file as a vector, or #f if the file does not exist. The vector has six elements: year, month, day, hour, minute, second, all of which are exact nonnegative integers. The time returned is relative to the local timezone.

(file-modification-time "larceny") => #(1997 2 6 12 51 13)

(file-modification-time "geekdom") => #f

Procedure flush-output-port

(flush-output-port ) => unspecified

(flush-output-port port) => unspecified

Write any buffered data in the port to the underlying output medium.

Procedure get-output-string

(get-output-string string-output-port) => string

Retrieve the output string from the given string output port.

Procedure open-input-string

(open-input-string string) => input-port

Creates an input port that reads from string. The string may be shared with the caller. A string input port does not need to be closed, although closing it will prevent further reads from it.

Procedure open-output-string

(open-output-string ) => output-port

Creates an output port where any output is written to a string. The accumulated string can be retrieved with get-output-string at any time.

Procedure port?

(port? object) => boolean

Tests whether its argument is a port.

Procedure port-name

(port-name port) => string

Returns the name associated with the port; for file ports, this is the file name.

Procedure port-position

(port-position port) => fixnum

Returns the number of characters that have been read from or written to the port.

Procedure rename-file

(rename-file from to) => unspecified

Renames the file from and gives it the name to. No error is signalled if from does not exist or to exists.

Procedure reset-output-string

(reset-output-string port) => unspecified

Given a port created with open-output-string, deletes from the port all the characters that have been output so far.

Procedure with-input-from-port

(with-input-from-port input-port thunk) => object

Calls thunk with current input bound to input-port in the dynamic extent of thunk. Returns whatever value was returned from thunk.

Procedure with-output-to-port

(with-output-to-port output-port thunk) => object

Calls thunk with current output bound to output-port in the dynamic extent of thunk. Returns whatever value was returned from thunk.

Procedure command-line-arguments

(command-line-arguments ) => vector

Returns a vector of strings: the arguments supplied to the program by the user or the operating system.

Procedure dump-heap

(dump-heap filename procedure) => unspecified

Dump a heap image to the named file that will start up with the supplied procedure. Before procedure is called, command line arguments will be parsed and any init procedures registered with add-init-procedure! will be called.

Note: Currently, heap dumping is only available with the stop-and-copy collector (-stopcopy command line option), although the heap image can be used with all the other collectors.

Procedure dump-interactive-heap

(dump-interactive-heap filename) => unspecified

Dump a heap image to the named file that will start up with the standard read-eval-print loop. Before the read-eval-print loop is called, command line arguments will be parsed and any init procedures registered with add-init-procedure! will be called.

Note: Currently, heap dumping is only available with the stop-and-copy collector (-stopcopy command line option), although the heap image can be used with all the other collectors.

Procedure getenv

(getenv key) => string or #f

Returns the operating system environment mapping for the string key, or #f if there is no mapping for key.

Procedure setenv

(setenv key val) => unspecified

Sets the operating system environment mapping for the string key to val.

Procedure system

(system command) => status

Send the command to the operating system's command processor and return the command's exit status, if any. On Unix, command is a string and status is an exact integer.

Fixnums are small exact integers that are likely to be represented without heap allocation. Larceny never represents a number that can be represented as a fixnum any other way, so programs that can use fixnums will do so automatically. However, operations that work only on fixnums can sometimes be substantially faster than generic operations, and the following primitives are provided for use in those programs that need especially good performance.

The (rnrs arithmetic fixnums) library now provides a large set of procedures, some of them similar to the procedures described below. If one of Larceny's procedures duplicates the semantics of an R6RS procedure whose name is different, then Larceny's name is deprecated within R7RS/R6RS code.

All arguments to the following procedures must be fixnums.

Procedure fixnum?

(fixnum? obj) => boolean

Returns #t if its argument is a fixnum, and #f otherwise.

Procedure fx+

(fx+ fix1 fix2) => fixnum

Returns the fixnum sum of its arguments. If the result is not representable as a fixnum, then an error is signalled (unless error checking has been disabled).

Procedure fx-

Returns the fixnum difference of its arguments. If the result is not representable as a fixnum, then an error is signalled.

Procedure fx—

(fx— fix1) => fixnum

Returns the fixnum negative of its argument. If the result is not representable as a fixnum, then an error is signalled.

Procedure fx*

(fx* fix1 fix2) => fixnum

Returns the fixnum product of its arguments. If the result is not representable as a fixnum, then an error is signalled.

Procedure fx=

(fx= fix1 fix2) => boolean

Returns #t if its arguments are equal, and #f otherwise.

Procedure fx<

(fx< fix1 fix2) => boolean

Returns #t if fix1 is less than fix2, and #f otherwise.

Procedure fx<=

(fx<= fix1 fix2) => boolean

Returns #t if fix1 is less than or equal to fix2, and #f otherwise.

Procedure fx>

(fx> fix1 fix2) => boolean

Returns #t if fix1 is greater than fix2, and #f otherwise.

Procedure fx>=

(fx>= fix1 fix2) => boolean

Returns #t if fix1 is greater than or equal to fix2, and #f otherwise.

Procedure fxnegative?

(fxnegative? fix) => boolean

Returns #t if its argument is less than zero, and #f otherwise.

Procedure fxpositive?

(fxpositive? fix) => boolean

Returns #t if its argument is greater than zero, and #f otherwise.

Procedure fxzero?

(fxzero? fix) => boolean

Returns #t if its argument is zero, and #f otherwise.

Procedure fxlogand

(fxlogand fix1 fix2) => fixnum

Returns the bitwise and of its arguments.

Procedure fxlogior

(fxlogior fix1 fix2) => fixnum

Returns the bitwise inclusive or of its arguments.

Procedure fxlognot

(fxlognot fix) => fixnum

Returns the bitwise not of its argument.

Procedure fxlogxor

(fxlogxor fix1 fix2) => fixnum

Returns the bitwise exclusive or of its arguments.

Procedure fxlsh

(fxlsh fix1 fix2) => fixnum

Returns fix1 shifted left fix2 places, shifting in zero bits at the low end. If the shift count exceeds the number of bits in the machine's word size, then the results are machine-dependent.

Procedure most-positive-fixnum

(most-positive-fixnum ) => fixnum

Returns the largest representable positive fixnum.

Procedure most-negative-fixnum

(most-negative-fixnum ) => fixnum

Returns the smallest representable negative fixnum.

Procedure fxrsha

(fxrsha fix1 fix2) => fixnum

Returns fix1 shifted right fix2 places, shifting in a copy of the sign bit at the left end. If the shift count exceeds the number of bits in the machine's word size, then the results are machine-dependent.

Procedure fxrshl

(fxrshl fix1 fix2) => fixnum

Returns fix1 shifted right fix2 places, shifting in zero bits at the high end. If the shift count exceeds the number of bits in the machine's word size, then the results are machine-dependent.

Larceny has six representations for numbers: fixnums are small, exact integers; bignums are unlimited-precision exact integers; ratnums are exact rationals; flonums are inexact rationals; rectnums are exact complexes; and compnums are inexact complexes.

Number-representation predicates

(fixnum? obj) => boolean

(bignum? obj) => boolean

(ratnum? obj) => boolean

(flonum? obj) => boolean

(rectnum? obj) => boolean

(compnum? obj) => boolean

These predicates test whether an object is a number of a particular representation and return #t if so, #f if not.

Procedure random

(random limit) => exact integer

Returns a pseudorandom nonnegative exact integer in the range 0 through limit-1.

Hashtables represent finite mappings from keys to values. If the hash function is a good one, then the value associated with a key may be looked up in constant time (on the average).

Parameters are procedures that serve as containers for values.

When called with no arguments, a parameter returns its current value. The value of a parameter can be changed temporarily using the parameterize syntax described below.

The effect of passing arguments to a parameter is implementation-dependent. In Larceny, passing one argument to a parameter changes the current value of the parameter to the result of applying a converter procedure to that argument, as described by SRFI 39.

Procedure make-parameter

(make-parameter init) => procedure

(make-parameter init converter) => procedure

(make-parameter name init predicate) => procedure

Creates a parameter.

When make-parameter is called with one argument init, the parameter's initial value is init, and the parameter's converter will be the identity function.

When make-parameter is called with two arguments, converter must be a procedure that accepts one argument, and the parameter's initial value is the result of calling converter on init.

Larceny extends SRFI 39 and the R7RS specification of make-parameter by allowing it to be called with three arguments. The first argument, name, must be a symbol or string giving the print name of the parameter. The second argument, init, will be the initial value of the parameter. The third argument is a predicate from which Larceny constructs a converter procedure that acts like the identity function on arguments that satisfy the predicate but raises an exception on arguments that don't.

(make-parameter name init) => procedure

Larceny's parameter objects predate SRFI 39. For backward compatibility, Larceny's make-parameter will accept two arguments even if the second is not a procedure, provided the first argument is a symbol or string. In that special case, the two arguments will be treated as the name and init arguments to Larceny's three-argument version, with the predicate defaulting to the identity function. This extension is strongly deprecated.

Syntax parameterize

(parameterize ((parameter0 value0) …) expr0 expr1 …)

Parameterize temporarily overrides the values of a set of parameters while the expressions in the body of the parameterize expression are evaluated. (It is like fluid-let for parameters instead of variables.)

The property list of a symbol is an association list that is attached to that symbol. The association list maps properties, which are themselves symbols, to arbitrary values.

Procedure putprop

(putprop symbol property obj) => unspecified

If an association exists for property on the property list of symbol, then its value is replaced by the new value obj. Otherwise, a new association is added to the property list of symbol that associates property with obj.

Procedure getprop

(getprop symbol property) => obj

If an association exists for property on the property list of symbol, then its value is returned. Otherwise, #f is returned.

Procedure remprop

(remprop symbol property) => unspecified

If an association exists for property on the property list of symbol, then that association is removed. Otherwise, this is a no-op.

Procedure gensym

(gensym string) => symbol

Gensym returns a new uninterned symbol, the name of which contains the given string.

Procedure oblist

(oblist ) => list

Oblist returns the list of interned symbols.

Procedure oblist-set!

(oblist-set! list) => unspecified

(oblist-set! list table-size) => unspecified

oblist-set! sets the list of interned symbols to those in the given list by clearing the symbol hash table and storing the symbols in list in the hash table. If the optional table-size is given, it is taken to be the desired size of the new symbol table.

See also: symbol-hash.

Procedure collect

(collect ) => unspecified

(collect generation) => unspecified

(collect generation method) => unspecified

Collect initiates a garbage collection. If the system has multiple generations, then the optional arguments are interpreted as follows. The generation is the generation to collect, where 0 is the youngest generation. The method determines how the collection is performed. If method is the symbol collect, then a full collection is performed in that generation, whatever that means — in a normal multi-generational copying collector, it means that all live objects in the generation's current semispace and all live objects from all younger generations are copied into the generation's other semispace. If method is the symbol promote, then live objects are promoted from younger generations into the target generation — in our example collector, that means that the objects are copied into the target generation's current semispace.

The default value for generation is 0, and the default value for method is collect.

Note that the collector's internal policy settings may cause it to perform a more major type of collection than the one requested; for example, an attempt to collect generation 2 could cause the collector to promote all live data into generation 3.

Procedure gc-counter

(gc-counter ) => fixnum

gc-counter returns the number of garbage collections performed since startup. On a 32-bit system, the counter wraps around every 1,073,741,824 collections.

gc-counter is a primitive and compiles to a single load instruction on the SPARC.

Procedure major-gc-counter

(major-gc-counter ) => fixnum

major-gc-counter returns the number of major garbage collections performed since startup, where a major collection is defined as a collection that may change the address of objects that have already survived a previous collection. On a 32-bit system, the counter wraps around every 1,073,741,824 collections.

major-gc-counter is a primitive and compiles to a single load instruction on the SPARC. Its primary use to implement efficient hashtables that hash on object identity (make-eq-hashtable and make-eqv-hashtable).

Procedure gcctl

(gcctl heap-number operation operand) => unspecified

[GCCTL is largely obsolete in the new garbage collector but may be resurrected in the future. It can still be used to control the non-predictive collector.]

gcctl controls garbage collection policy on a heap-wise basis. The heap-number is the heap to operate on, like for the command line switches: heap 1 is the youngest. If the given heap number does not correspond to a heap, gcctl fails silently.

The operation is a symbol that selects the operation to perform, and the operand is the operand to that operation, always a number. For the non-predictive garbage collector, the following operator/operand pairs are meaningful:

Example: if the non-predictive heap is heap number 2, then the expressions

(gcctl 2 'j-fixed 0)
(gcctl 2 'incr-fixed 1)

makes the non-predictive collector simulate a normal stop-and-copy collector (because j is always set to 0), and grows the heap only one step at a time as necessary. This may be useful for certain kinds of experiments.

Example: ditto, the expressions

(gcctl 2 'j-percent 50)
(gcctl 2 'incr-percent 20)

selects the default policy settings.

Note: The gcctl facility is experimental. A more developed facility will allow controlling heap contraction policy, as well as setting all the watermarks. Certainly one can envision other uses, too. Finally, it needs to be possible to get current values.

Note: Currently the non-predictive heap (np-sc-heap.c) and the standard stop-and-copy "old" heap (old-heap.c) are supported, but not the standard "young" heap (young-heap.c), nor the stop-and-copy collector (sc-heap.c).

Procedure sro

(sro pointer-tag type-tag limit) => vector

SRO ("standing room only") is a system primitive that traverses the entire heap and returns a vector that contains all live objects in the heap that satisfy the constraints imposed by its parameters:

For example, (sro -1 -1 -1) returns a vector that contains all live objects (not including the vector), and (sro 5 2 3) returns a vector containing all live flonums (bytevector-like, with typetag 2) that are referred to in no more than 3 places.

Procedure stats-dump-on

(stats-dump-on filename) => unspecified

Stats-dump-on turns on garbage collection statistics dumping. After each collection, a complete RTS statistics dump is appended to the file named by filename.

The file format and contents are documented in a banner written at the top of the output file. In addition, accessor procedures for the output structure are defined in the program Util/process-stats.sch.

Stats-dump-on does not perform an initial dump when the file is first opened; only at the first collection is the first set of statistics dumped. The user might therefore want to initiate a minor collection just after turning on dumping in order to have a baseline set of data.

Procedure stats-dump-off

(stats-dump-off ) => unspecified

Stats-dump-off turns off garbage collection statistics dumping (which was turned on with stats-dump-on). It does not dump a final set of statistics before closing the file; therefore, the user may wish to initiate a minor collection before calling this procedure.

Procedure system-features

(system-features ) => alist

System-features returns an association lists of system features. Most entries are self-explanatory. The following are a more subtle:

Procedure display-memstats

(display-memstats vector) => unspecified

(display-memstats vector minimal) => unspecified

(display-memstats vector minimal full) => unspecified

Display-memstats takes as its argument a vector as returned by memstats and displays the contents of the vector in human-readable form on the current output port. By default, not all of the values in the vector are displayed.

If the symbol minimal is passed as the second argument, then only a small number of statistics generally relevant to running benchmarks are displayed.

If the symbol full is passed as the second argument, then all statistics are displayed.

Procedure memstats

(memstats ) => vector

Memstats returns a freshly allocated vector containing run-time-system resource usage statistics. Many of these will make no sense whatsoever to you unless you also study the RTS sources. A listing of the contents of the vector is available here.

Procedure run-with-stats

(run-with-stats thunk) => obj

Run-with-stats evaluates thunk, then prints a short summary of run-time statistics, as with

(display-memstats ... 'minimal),

and then returns the result of evaluating thunk.

Procedure run-benchmark

(run-benchmark name k thunk ok?) => obj

Run-benchmark prints a short banner (including the identifying name) to identify the benchmark, then runs thunk k times, and finally tests the value returned from the last call to thunk by applying the predicate ok? to it. If the predicate returns true, then run-benchmark prints summary statistics, as with

([display-memstats][5] ... 'minimal).

If the predicate returns false, an error is signalled.

SRFIs (Scheme Requests For Implementations) describe and implement additional Scheme libraries. The SRFI effort is open to anyone, and is described at http://srfi.schemers.org.

SRFIs are numbered. Importing SRFIs into an R7RS library or program is straightforward:

(import (srfi 19)
        (srfi 27))

The R6RS forbids numbers within library names, so R6RS libraries and programs must import SRFI libraries using the SRFI 97 naming convention in which a colon precedes the number:

(import (srfi :19)
        (srfi :27))

To test whether particular SRFIs are available, use the R7RS cond-expand feature:

(cond-expand
 ((and (library (srfi 19))
       (library (srfi 27)))
  (import (srfi 19))
  (import (srfi 27))))

cond-expand is not available to R6RS libraries or programs.

R5RS programs can use cond-expand as implemented by SRFI 0, "Feature-based conditional expansion construct". (SRFI 0 must be loaded into Larceny before it can be used; see below.) Larceny provides the following nonstandard key for use in SRFI 0:

    larceny

Larceny currently supports many SRFIs, though not as many as it should. Some SRFIs are built into Larceny's R5RS mode, but most must be loaded dynamically using Larceny's require procedure:

    > (require 'srfi-0)

The design documents for SRFI 0 and other SRFIs are available at http://srfi.schemers.org.

SLIB is a large collection of useful libraries that have been written or collected by Aubrey Jaffer.

Larceny supports SLIB via SRFI 96, but SLIB itself is not shipped with Larceny; it must be downloaded separately and then installed. For the most up-to-date information on installing and using SLIB with Larceny, see doc/HOWTO-SLIB.

Larceny provides a general foreign-function interface (FFI) substrate on which other FFIs can be built; see Larceny Note #7. The FFI described in this manual section is a simple example of a derived FFI. It is not yet fully evolved, but it is useful.

enum months { JAN = 1, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC };

TypeDesc ::= CoreAttr | ArrowT | MaybeT | OneOfT

CoreAttr ::= PrimAttr | VoidStar | ---

PrimAttr ::= CurrentPrimAttr | DeprecatedPrimAttr

CurrentPrimAttr
         ::= int | uint | byte | short | ushort | char | uchar
          |  long | ulong | longlong | ulonglong
          |  size_t | float | double |  bool | string | void

DeprecatedPrimAttr
         ::= unsigned | boxed

VoidStar ::= void* | ---

ArrowT   ::= (-> (TypeDesc ...) TypeDesc)

MaybeT   ::= (maybe TypeDesc)

OneOfT   ::= (oneof (Any Fixnum) ... TypeDesc)

gcc -fPIC -shared file1.c file2.c -o my-library.so

gcc -fPIC -shared file1.c file2.c -lc -lm -lsocket -o my-library.so

(define cd
  (let ((chdir (foreign-procedure "chdir" '(string) 'int)))
    (lambda (newdir)
      (if (not (zero? (chdir newdir)))
      (error "cd: " newdir " is not a valid directory name."))
      (unspecified))))

(define pwd
  (let ((getcwd (foreign-procedure "getcwd" '(boxed int) 'int)))
    (lambda ()
      (let ((s (make-bytevector 1024)))
    (getcwd s 1024)
    (ffi/asciiz->string s)))))

(define qsort!
  (foreign-procedure "qsort" '(boxed ushort ushort (-> (void* void*) int)) 'void))

(let ((bv (list->vector '(40 10 30 20 1 2 3 4))))
  (qsort! bv 8 4
          (lambda (x y)
            (let ((x (/ (void*-word-ref x 0) 4))
                  (y (/ (void*-word-ref y 0) 4)))
              (- x y))))
  bv)

(let ((bv (list->bytevector '(40 10 30 20 1 2 3 4))))
  (qsort! bv 8 1
          (lambda (x y)
            (let ((x (void*-byte-ref x 0))
                  (y (void*-byte-ref y 0)))
              (- x y))))
  bv)

<exp>     ::= (define-c-info <c-decl> ... <c-defn> ...)

<c-decl>  ::= (compiler <cc-spec>)
           |  (path <include-path>)
           |  (include <header>)
           |  (include<> <header>)

<cc-spec> ::= cc | cl

<c-defn>  ::= (const <id> <c-type> <c-expr>)
           |  (sizeof <id> <c-type-expr>)
           |  (struct <c-name> <field-clause> ...)
           |  (fields <c-name> <field-clause> ...)
           |  (ifdefconst <id> <c-type> <c-name>)

<c-type>  ::= int | uint | long | ulong

<include-path>
          ::= <string-literal>

<header>  ::= <string-literal>

<field-clause>
          ::= (<offset-id> <c-field>)
           |  (<offset-id> <c-field> <size-id>)

<c-expr>  ::= <string-literal>

<c-type-expr>
          ::= <string-literal>

<c-name>  ::= <string-literal>

<c-field> ::= <string-literal>

<exp>    ::= (define-c-struct (<struct-type> <ctor-id> <c-decl> ...)
                <field-clause> ...)

<field-clause>
         ::= (<c-field> <getter>) | (<c-field> <getter> <setter>)

<getter> ::= (<id>) | (<id> <unmarshal>)

<setter> ::= (<id>) | (<id> <marshal>)

<marshal> ::= <ffi-attr-symbol> | <marshal-proc-exp>

<unmarshal> ::= <ffi-attr-symbol> | <unmarshal-proc-exp>

<struct-type> ::= <string-literal>

<exp> ::= (define-c-enum <enum-id> (<c-decl> ...)
            (<id> <c-name>) ...)

<exp> ::= (define-c-enum-set <enum-id> (<c-decl> ...)
            (<id> <c-name>) ...)

<enum-id> ::= <id>

When Larceny detects an error or a keyboard interrupt, or when it hits a breakpoint, it signals the condition by printing a message on the console. Larceny then enters the debugger, which signals its presence with a short banner and the debugger prompt:

Entering debugger; type "?" for help.
debug>

You can also re-enter the debugger by evaluating (debug).

The debugger is still in an immature state. The following commands are available (commands can be typed in upper or lower case):

B Print backtrace of continuation.

C Print source code of procedure, if available.

D Move down to previous (earlier) activation record.

E n expr Expr is evaluated in the current interaction environment and must evaluate to a procedure. It is passed the contents of slot n from the current activation record, and the result, if not unspecified, is printed.

E (n1 … nk) expr Expr is evaluated in the current interaction environment and must evaluate to a procedure. It is passed the contents of slots n1 through nk from the current activation record, and the result, if not unspecified, is printed.

I n Inspect the procedure in slot n of the current activation record.

I @_ Inspect the active procedure.

Q Quit the debugger and abort the computation.

R Return from the debugger and continue the computation.

S Summarize the contents of the current activation record.

U Up to the next (later) activation record.

X Examine the contents of the current activation record.

The B, D, and U commands can be prefixed with a count, for example, 5 U moves up five activation records, and 10 B displays the next 10 activation records. The default for B is to display all the activations; the default count for D and U is 1.

You can set breakpoints either in program text with the break primitive or interactively at the start of a procedure with the break-entry procedure. When Larceny reaches a breakpoint during execution, the program is suspended and the debugger is entered to allow you to inspect the program.

Procedure larceny-break

(larceny-break )

Invokes the breakpoint handler.

Procedure break-entry

(break-entry procedure)

Set a breakpoint at the start of the procedure.

Procedure unbreak

(unbreak procedure …)

(unbreak )

In the first form, remove any breakpoint set by break-entry at the start of the procedure_s. In the second form, remove all breakpoints set by _break-entry.

Procedure trace-entry

(trace-entry procedure)

Set a trace point on entry to the procedure, removing any other trace points on the procedure. When the procedure is entered, information about the call is printed on the console: the name of the procedure and the actual arguments.

Procedure trace-exit

(trace-exit procedure)

Set a trace point on exit from the procedure, removing any other trace points on the procedure. When the procedure returns, information about the return is printed on the console: the name of the procedure and the returned values.

Note that trace-exit destroys the tail recursion properties of the instrumented procedure. Where the procedure would normally "return" by tail-calling another procedure, the instrumented procedure will call the other procedure by a non-tail call and then return, at which point the procedure name and return values will be printed. Thus use of trace-exit may destroy the space properties of the program.

Procedure trace

(trace procedure)

Set trace points on procedure both at entry and exit.

Procedure untrace

(untrace procedure …)

(untrace )

The first form removes any trace points from the specified procedures. The second form removes all untrace points.

Parameter break-handler

The value of break-handler is a procedure that is called when a breakpoint or tracepoint is encountered. The procedure takes two arguments: the procedure in which the breakpoint was set, and the byte offset within the procedure's code vector of the breakpoint.

IEEE Standard 1178-1990, "IEEE Standard for the Scheme Programming Language", IEEE, 1991. ISBN 1-55937-125-0. May be ordered from IEEE by calling 1-800-678-IEEE or 908-981-1393 or writing IEEE Service Center, 445 Hoes Lane, P.O. Box 1331, Piscataway, NJ 08855-1331, and using order number SH14209.

Richard Kelsey, William Clinger, and Jonathan Rees [editors]. Revised^5 Report on the Algorithmic Language Scheme. Journal of Higher Order and Symbolic Computation, 11(1), 1998, pages 7-105. Also appears in ACM SIGPLAN Notices 33(9), September 1998. Available online in various formats.

Michael Sperber, R Kent Dybvig, Matthew Flatt, and Anton van Straaten [editors]. Revised^6 Report on the Algorithmic Language Scheme, 2007.

Alex Shinn, John Cowan, and Arthur A Gleckler [editors]. Revised^7 Report on the Algorithmic Language Scheme, 2013.

IEEE Standard 754-1985, "IEEE Standard for Binary Floating-Point Arithmetic", IEEE, 1985.

IEEE Standard 754-2008, "IEEE Standard for Floating-Point Arithmetic", IEEE, 2008. (Revision of IEEE Std 754-1985 began in 2000. The IEEE Microprocessor Standards Committee (MSC) accepted a candidate draft on 9 October 2006. The candidate draft 1.2.6 was approved by 79% of 70 votes, which exceeded the required supermajority of 75%. Because there were negative votes and several hundred comments, however, a revised draft 1.3.0 was prepared and approved by 84% of 73 votes. Since there were over a hundred comments on the second candidate draft as well, a third candidate draft 1.4.0 was prepared and another vote taken in April 2007. After a total of eight ballots, with the last four being approved by more than 90% of the voters, the Ballot Review Committee decided in May 2008 that maximum possible timely consensus has been obtained, and the consensus draft was submitted to IEEE-SA RevCom. IEEE-754-2008 was approved on 12 June 2008.)

The Unicode Consortium. The Unicode Standard.