mars

mars – interactive interpreter for programs written in the Mars language

Synopsis

mars [-i] [-c command] [--backend=backend] [-m name] [-l library] [-h | --help] [--version] [mars-source-file]

Description

mars is the interpreter / interactive environment for the Mars programming language. It directly interprets the Mars source code, using the specified backend.

By default, it will load the interactive environment, allowing the user to try built-in and prelude functions. It may also be used to load other Mars programs, and either execute them directly, or try their functions at the interactive prompt.

mars takes the following steps to determine how to behave:

1. If mars-source-file is not specified, mars defaults to using the Prelude as the source file (by searching for “prelude.mar” in the Mars search path), and -i is assumed, unless -c is specified.
2. If neither -i nor -c are specified, mars directly executes the main function of the supplied program, mars-source-file, then terminates.
3. Otherwise, if -c is specified, mars executes command on the loaded program, and prints out the result, if any.
4. Then, if -i is specified, mars goes into the interactive prompt, and repeatedly reads commands, one per line, from stdin. Otherwise, it terminates immediately.

Interactive mode

The interactive prompt allows statements and expressions to be evaluated on-the-fly.

Additional commands, specific to the interactive prompt, are available. These commands all begin with a colon (”:”).

Type ”:?” at the prompt for further help.

Options

-i

Start an interactive session. This option is implied if no source file is specified.

-c command

If supplied, executes a command before entering interactive mode. command may be an expression, a statement, or any other interactive-mode command.

--backend=backend

Use a specific backend. This determines what engine will be used to run the Mars program and/or interactive statements. In theory, all backends should produce exactly the same results.

The default backend is llvm.

Backends available: interpret, llvm.

-m name

Specify the name of the main function (program entrypoint). This names the function which will be executed upon program startup. It must have type () -> Num.

Defaults to “main”. Has no effect if -i or -c are specified, or no mars-source-file is given.

-l library

Specify a native library (DLL or shared object) to link to. Multiple libraries may be supplied with separate -l options, and will be searched in the given order.

Mars will search a system-defined set of standard locations (such as those in LD_LIBRARY_PATH for files named liblibrary, with a system-specific extension (such as .so or .dll). It automatically prepends the string “lib” to the front. A file extension may be manually supplied to override the default (such as .so.6, in the case of libc.so.6).

Native libraries are libraries written in C or other low-level languages which may be called by Mars code via the native_import statement. Libraries written in Mars do not need to be specified on the command-line.

-d, --destructive

Perform uniqueness analysis and make certain operations destructive, where possible. This does not change the semantics; it is merely an optimisation. This makes use of functions like array_replace and array_concat use constant time in some cases, rather than linear time.

This is switched on by default. It can be disabled with -d- or --no-destructive.

-h, --help

Display a short help page, then quit.

--version

Display version and copyright information, then quit.

Exit status

mars will exit with a status of 1 if any fatal errors occur, including compiler errors or illegal main functions.

If executing a main function (due to the lack of -i and -c arguments), mars will set its exit status to the result of main.

Otherwise, mars will set its exit status to 0.

Environment

MARSPATH

Colon-separated list of paths to search for Mars source files. Searched when the import statement is used to import Mars modules.

Bugs

A list of known bugs is available at https://bugs.launchpad.net/mars/. Bugs should be reported using the link on that page.