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, including the names of libraries currently available for import. 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)
     ...)

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 R7RS), 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.