.. Mars Documentation
   Copyright (C) 2008 Matt Giuca
   11/12/2008

.. This program is free software: you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation, either version 3 of the License, or
   (at your option) any later version.

.. This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

.. You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.

.. _ref-man-mars:

********
``mars``
********

.. sectionauthor:: Matt Giuca <matt.giuca@gmail.com>

:program:`mars` -- interactive interpreter for programs written in the Mars
language

Synopsis
========

.. program:: mars

:program:`mars` [:option:`-i <mars -i>`] [:option:`-c <mars -c>` *command*]
[:option:`--backend <mars --backend>`\ =\ *backend*] [:option:`-m <mars -m>` *name*]
[:option:`-l` *library*]
[:option:`-h <mars -h>` | :option:`--help <mars --help>`] [:option:`--version <mars --version>`]
[*mars-source-file*]

Description
===========

:program:`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.

:program:`mars` takes the following steps to determine how to behave:

1. If *mars-source-file* is not specified, :program:`mars` defaults to
   using the Prelude as the source file (by searching for
   ":file:`prelude.mar`" in the Mars search path), and :option:`-i` is
   assumed, *unless* :option:`-c` is specified.
2. If neither :option:`-i` nor :option:`-c` are specified, :program:`mars`
   directly executes the :func:`main` function of the supplied program,
   *mars-source-file*, then terminates.
3. Otherwise, if :option:`-c` is specified, :program:`mars` executes *command*
   on the loaded program, and prints out the result, if any.
4. Then, if :option:`-i` is specified, :program:`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
=======

.. cmdoption:: -i

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

.. cmdoption:: -c command

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

.. cmdoption:: --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*.

.. cmdoption:: -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
   :type:`() -> Num`.

   Defaults to ":func:`main`". Has no effect if :option:`-i` or :option:`-c`
   are specified, or no *mars-source-file* is given.

.. cmdoption:: -l library

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

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

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

.. cmdoption:: -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 :func:`array_replace` and
   :func:`array_concat` use constant time in some cases, rather than linear
   time.

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

.. cmdoption:: -h, --help

   Display a short help page, then quit.

.. cmdoption:: --version

   Display version and copyright information, then quit.

Exit status
===========

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

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

Otherwise, :program:`mars` will set its exit status to 0.

Environment
===========

.. envvar:: MARSPATH

   Colon-separated list of paths to search for Mars source files. Searched
   when the :keyword:`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.