MIRA(1)

NAME
mira - the Miranda(tm) functional programming system

SYNOPSIS
mira [options] [file]

DESCRIPTION
Miranda is a functional programming system with lazy evaluation, polymorphic strong typing and function definition by pattern matching.

The mira program takes a single argument which is the name of a file of definitions (called a "script"). If no argument is given a default name "script.m" is assumed. The names of files containing miranda scripts must end in ".m" and mira will add this if missing. The specified file need not yet exist - in this case you will be starting a Miranda session with an empty current script.

The basic action of the Miranda system is to evaluate expressions in the environment established by the script, so in its simplest mode of use it behaves like a desk calculator. Expressions are typed one per line, terminated by ENTER. The interpreter also accepts certain commands (mostly beginning with a `/' character) - these include /help or /h which prints a summary of the available commands, and /man or /m which gives access to the online manual of the Miranda system (menu driven and self explanatory). This documents all aspects of the Miranda language and system and should be consulted for further details. It is also possible to access the Miranda system manual directly from a UNIX shell by the command mira -man.

OPTIONS

-lib pathname
    Specifies location of the miralib directory. For default see FILES. Can also be done by setting environment variable MIRALIB.

-gc Switches on a flag causing the garbage collector to print information each time a garbage collection takes place. This flag can also be switched on and off from within the miranda session by the commands `/gc', `/nogc'.

-count
    Switches on a flag causing statistics to be printed after each expression evaluation. This flag can also be switched on and off from within the miranda session by the commands `/count', `/nocount'.

-list -nolist
    Switches on (off) a flag causing Miranda scripts to be listed to the screen during compilation. This flag can also be switched on and off from within the miranda session by the commands `/list', `/nolist'.

-nostrictif
    Enables the compiler to accept old Miranda scripts with no `if' after the guard comma.

-hush -nohush
    The miranda system decides whether or not to give prompts and other feedback by testing its standard input with `isatty'. If the standard input does not appear to be a terminal it assumes that prompts would be inappropriate, otherwise it gives them. In either case this behaviour can be overriden by an explicit flag ("-hush" for silence, "-nohush" for prompts etc). This switch is also available from within a miranda session by the commands `/hush', `/nohush'.

-dic SIZE
    Causes the dictionary, used by the compiler to store identifiers etc., to be SIZE bytes instead of the default 60000.

-heap SIZE
    Causes the heap to be SIZE cells instead of the default 250k. This can changed within the miranda session by the command `/heap SIZE'. A cell is 9 bytes (2 words and a tag field).

-editor prog
    Causes the resident editor (usual default `vi') to be prog instead. This can also be done from within the miranda session by the command /editor prog. Any occurrences of ! and % in prog will be replaced by the line number and the name of the file to be edited, respectively. For more detailed discussion see online manual subsection 31/5.

SPECIAL CALLS
The following special calls to mira do not start a Miranda session but accomplish another purpose.

mira -man
    Enter Miranda online manual from the UNIX shell. From within a Miranda session this is done by the command `/man' or `/m'.

mira -version
    Prints version information. This information can be obtained within a Miranda session by the command `/version' or `/v'.

mira -V
    Prints more detailed version information.

The remaining special calls are discussed in more detail in the online manual - we list them here for completeness.

mira -exp
    Special call permitting the use of miranda script as a stand-alone program. See online manual subsection 31/4 for details.

mira -log
    As -exp except that it redirects stderr to a log file. See online manual subsection 31/4 for details.

These three relate to separate compilation and Miranda's built in `make' facility. See online manual section 27 (the library mechanism):-

mira -make [files]
    Checks that all the miranda source files listed have up-to-date .x (intermediate code) files, triggering compilation processes if necessary.

mira -exports [files]
    Sends to stdout a list of the identifiers exported from the given miranda source files, together with their types (may force compilation if needed).

mira -sources [files]
    Send to stdout a list of all the Miranda source files on which the given source files directly or indirectly depend (via %include or %insert statements), excluding the standard environment <stdenv>.

ENVIRONMENT

MIRALIB
    Specifies the location of the miralib directory. A -lib flag, if present, overrides this. For default location see FILES.

EDITOR
    The first time it is called (i.e. if no .mirarc file is present in the home directory or in miralib) the miranda system takes the preferred editor from this environment variable - if not set `vi' is assumed. Chosen editor can be changed from within a Miranda session by the command /editor prog. Any occurrences of ! and % in prog will be replaced by the line number and the name of the file to be edited, respectively. For more detailed discussion see online manual subsection 31/5.

RECHECKMIRA
    If this is set to any non-empty string the Miranda system checks to see if any relevant source file has been updated, and performs any necessary recompilation, before each interaction with the user. This is the appropriate behaviour if an editor window is being kept open during the Miranda session. By default the check is performed only after `/e' commands and `!' escapes. This can also be controlled from within a Miranda session by the commands `/recheck', `/norecheck'.

SHELL
    Determines what shell is used in `!' escapes. This will normally contain the name of the user's login shell. If no SHELL is present in the environment, /bin/sh is assumed.

NOSTRICTIF
    If this is set to any non-empty string Miranda accepts old scripts with no `if' after the guard comma. Equivalent to calling mira with option -nostrictif. Deprecated - you should put the `if's in.

The behaviour of the menudriver program that displays pages of the online manual can be modified using three environment variables:-

VIEWER
    The program used for displaying pages of the online manual. If this variable is not set the default is normally `more -d' or (roughly equivalent) `less -EX'. If you set VIEWER to something, you may also need to set an environment variable RETURNTOMENU.

RETURNTOMENU=YES
    Prevents another prompt being given after displaying each section, causing instead an immediate return to contents page. Appropriate if VIEWER is a program that pauses for input at end of file (e.g. `less'). It should be `NO' if VIEWER is a program that quits silently at end of file (e.g. `more -d', `less -EX').

MENUVIEWER
    Can be used to specify the program used to display manual contents pages (default is usually `cat' or `more').

To find the current settings of the online manual enter ??? to the "next selection" prompt of the manual system.

FILES

/usr/lib/miralib
    A directory containing files which mira needs - by default it looks for this at /usr/lib/miralib, then /usr/local/lib/miralib, and lastly at ./miralib. If it does not find a miralib of the same version number as itself in one of these places it exits with a panic message. This behaviour can be overriden with the -lib option or by setting the environment variable MIRALIB.

$HOME/.mirarc
    Records most recent settings of heap size, dictionary size, editor and various flags which can be toggled during a session. Written and read by mira using a peculiar format, not intended to be edited by humans. The settings can be interrogated within a Miranda session by the command /settings or /s, and changed by various session commands (say /aux or /a to list these). The only setting which cannot be changed in a session is dictionary size - this is done using the -dic option when mira is invoked. This rarely needs to be changed, however.

If a .mirarc is copied to miralib/.mirarc the settings it records will be picked up by new users, who will not yet have their own .mirarc file. This allows an administrator to change the default settings, e.g. to have a default editor other than vi. The $HOME/.mirarc once created will override the global one, however, allowing users to make individual choices.

SEE ALSO

http://miranda.org.uk the Miranda home page.

D.A.Turner An Overview of Miranda, SIGPLAN Notices, 21(12), December 1986. A convenient summary of the main features of Miranda.

Miranda System Manual. Accessed by mira -man or /man from within a Miranda session.

COPYRIGHT
Research Software Limited. Note that the system should be run only on machines for which a license has been obtained. The word "Miranda" is a trademark.