.TH MIRA 1 "November 2019" .SH NAME mira \- the Miranda(tm) functional programming system .SH SYNOPSIS .B mira [options] [file] .fi .SH DESCRIPTION Miranda is a functional programming system with lazy evaluation, polymorphic strong typing and function definition by pattern matching. .PP The \fBmira\fP 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 "\fBscript.m\fP" is assumed. The names of files containing miranda scripts must end in ".m" and \fBmira\fP 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. .PP 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. ."For example .".nf ." Miranda \fBproduct [1..40] ." 815915283247897734345611269596115894272000000000\fP .".fi ."There is a `standard environment' of predefined functions, such as ."product, which are always in scope. The interpreter also accepts certain commands (mostly beginning with a `\fB/\fP' character) - these include \fB/help\fP or \fB/h\fP which prints a summary of the available commands, and \fB/man\fP or \fB/m\fP 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 \fBmira -man\fP. .SH OPTIONS .TP .B -lib pathname Specifies location of the miralib directory. For default see \fBFILES\fP. Can also be done by setting environment variable \fBMIRALIB\fP. The location of the miralib directory can be interrogated (but not changed) from within the miranda session by the command `/miralib'. .TP .B -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'. .TP .B -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'. .TP .B -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'. .TP .B -nostrictif Enables the compiler to accept old Miranda scripts with no `\fBif\fP' after the guard comma. .TP .B -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'. .TP .B -dic SIZE Causes the dictionary, used by the compiler to store identifiers etc., to be SIZE bytes (default 100k). This can be interrogated (but not changed) from within the miranda session by the command `/dic'. .TP .B -heap SIZE Causes the heap to be SIZE cells (default 2500k). This can changed within the miranda session by the command `/heap SIZE'. A cell is 9 bytes (2 words of 32 bits, and a tag field). .TP .B -editor prog Causes the resident editor (usual default `\fBvi\fP') to be \fBprog\fP instead. This can also be done from within the miranda session by the command \fB/editor prog\fP. Any occurrences of \fB!\fP and \fB%\fP in \fBprog\fP 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. .TP .B -UTF-8 (-noUTF-8) Assume the current locale is (is not) UTF-8 overriding environment vars (version 2.044 and later). .TP .B -stdenv Run mira without loading the standard environment. Any script needing functions from will then have to explicitly %include , or define the required functions itself. Not recommended as normal practise and may have unexpected consequences. .TP .B -object Used for debugging the compiler. Modifies the behaviour of ?identifier(s) to show the associated combinator code, which may or may not be comprehensible as there is no documentation other than the source code. .SH SPECIAL CALLS The following special calls to \fBmira\fP do not start a Miranda session but accomplish another purpose. .TP .B mira -man Enter Miranda online manual from the UNIX shell. From within a Miranda session this is done by the command `/man' or `/m'. .TP .B mira -version Prints version information. This information can be obtained within a Miranda session by the command `/version' or `/v'. .TP .B mira -V More detailed version information. Can be obtained within a Miranda session by the command `/V'. .PP The remaining special calls are discussed in more detail in the online manual - we list them here for completeness. .TP .B mira -exec Special call permitting the use of miranda script as a stand-alone program. See online manual subsection 31/4 for details. .TP .B mira -exec2 As \fB-exec\fP except that it redirects stderr to a log file. See online manual subsection 31/4 for details. .PP These three relate to separate compilation and Miranda's built in `make' facility. See online manual section 27 (\fBthe library mechanism\fP):- .TP .B mira -make [files] Checks that all the miranda source files listed have up-to-date .x (intermediate code) files, triggering compilation processes if necessary. .TP .B 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). .TP .B 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 \fB%include\fP or \fB%insert\fP statements), excluding the standard environment \fB\fP. .TP .B mira -version Gives version information. This information can also be obtained from within a Miranda session by the command `/version'. .TP .B mira -V More detailed version information. .SH ENVIRONMENT .TP .B MIRALIB Specifies the location of the miralib directory. A \fB-lib\fP flag, if present, overrides this. For default location see \fBFILES\fP. .TP .B 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 `\fBvi\fP' is assumed. Chosen editor can be changed from within a Miranda session by the command \fB/editor prog\fP. Any occurrences of \fB!\fP and \fB%\fP in \fBprog\fP 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. .TP .B LC_CTYPE, LANG At startup (version 2.044 and later) the miranda system inspects \fBLC_TYPE\fP, or if that is empty \fBLANG\fP, to determine if it is running in a UTF-8 locale. On Windows/Cygwin this information is taken from the \fBuser-default ANSI code page\fP. An explicit \fB-UTF-8\fP or \fB-noUTF-8\fP flag, if present, overrides. .TP .B 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 `\fB/e\fP' commands and `\fB!\fP' escapes. This can also be controlled from within a Miranda session by the commands `/recheck', `/norecheck'. .TP .B SHELL Determines what shell is used in `!' escapes. This will normally contain the name of the user's login shell. If no \fBSHELL\fP is present in the environment, \fB/bin/sh\fP is assumed. .TP .B MIRAPROMPT Sets a string to be used as session prompt instead of the default prompt "Miranda " (version 2.044 and later). .TP .B NOSTRICTIF If this is set to any non-empty string Miranda accepts old scripts with no `\fBif\fP' after the guard comma. Equivalent to calling mira with option \fB-nostrictif\fP. Deprecated - you should put the `\fBif\fP's in. .PP The behaviour of the menudriver program that displays pages of the online manual can be modified using three environment variables:- .TP .B VIEWER The program used for displaying pages of the online manual. If this variable is not set the default is normally `\fBmore -d\fP' or (roughly equivalent) `\fBless -EX\fP'. If you set \fBVIEWER\fP to something, you may also need to set an environment variable \fBRETURNTOMENU\fP. .TP .B RETURNTOMENU=YES Prevents another prompt being given after displaying each section, causing instead an immediate return to contents page. Appropriate if \fBVIEWER\fP is a program that pauses for input at end of file (e.g. `\fBless\fP'). It should be `\fBNO\fP' if \fBVIEWER\fP is a program that quits silently at end of file (e.g. `\fBmore -d\fP', `\fBless -EX\fP'). .TP .B MENUVIEWER Can be used to specify the program used to display manual contents pages (default is usually `\fBcat\fP' or `\fBmore\fP'). .PP To find the current settings of the online manual enter \fB???\fP to the "next selection" prompt of the manual system. .SH FILES .TP .B /usr/lib/miralib A directory containing files which \fBmira\fP needs - by default it looks for this at \fB/usr/lib/miralib\fP, then \fB/usr/local/lib/miralib\fP, and lastly at \fB./miralib\fP. 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 \fB-lib\fP option or by setting the environment variable \fBMIRALIB\fP. .TP .B $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 \fBmira\fP using a peculiar format, not intended to be edited by humans. The settings can be interrogated within a Miranda session by the command \fB/settings\fP or \fB/s\fP, and changed by various session commands (use \fB/aux\fP or \fB/a\fP to list these). The only setting which cannot be changed in a session is dictionary size - this is done using the \fB-dic\fP option when mira is invoked. This rarely needs to be changed, however. .PP If a \fB.mirarc\fP is copied to \fBmiralib/.mirarc\fP the settings it records will be picked up by new users, who will not yet have their own \fB.mirarc\fP file. This allows an administrator to change the default settings, e.g. to have a default editor other than \fBvi\fP. The \fB$HOME/.mirarc\fP once created will override the global one, however, allowing users to make individual choices. .SH SEE ALSO .PP .B http://miranda.org.uk the Miranda home page. .PP D.A.Turner \fBAn Overview of Miranda\fP, SIGPLAN Notices, 21(12), December 1986. A convenient summary of the main features of Miranda. .PP \fBMiranda System Manual\fP. Accessed by \fBmira -man\fP or \fB/man\fP from within a Miranda session. .SH COPYRIGHT The Miranda system is Copyright (c) Research Software Limited 1985-2019. For distribution terms see the file "COPYING" included in the distribution.