_U_s_i_n_g_ _M_i_r_a_n_d_a_ _t_o_ _b_u_i_l_d_ _e_x_e_c_u_t_a_b_l_e_ _f_i_l_e_s

FIRST METHOD (using a `here document')

Create a file ("prog' say) containing the following
	mira [script] <<!
	exp1
	exp2
	.
	.
	.
Remember to make the file executable (by saying `chmod +x  prog').   Now
when  `prog'  is executed as a UNIX command, the result will be that the
miranda  expressions  `exp1',  `exp2'  ...  will  be  evaluated  in  the
environment  defined  by  `script', and the results sent to the standard
output.  As usual, if `script' is omitted, a default name `script.m'  is
assumed.   The  text following the special redirection `<<!' is called a
"here-document".  The contents of the here-document are fed to the  mira
command  in place of its standard input.  (So anything you would type to
the miranda system at top level can appear in the here document.)

Here-documents are a normal feature of UNIX, not  something  special  to
miranda.   Miranda's  only  contribution to making this work smoothly is
that it detects when its input is not coming from  a  terminal,  and  in
this  case  suppresses prompts and other extraneous feedback.  Note also
that  lines  beginning  `||'  are  ignored  by   the   Miranda   command
interpreter,  which  gives  a way to include comments in the text of the
here-document.

The program `prog' might be invoked with  one  or  more  arguments,  for
example,
	prog big 23
In  the  here-document,  `$1'  can be used to denote the first argument,
`$2' the second and so on - in this case  `big'  and  `23'  respectively
will  be textually substituted for these before the here-document is fed
to mira as input.  Arguments not present are  replaced  by  empty  text.
Other  replacements  carried  out on the text of the here-document are -
`$*' is replaced by all the arguments together, as  a  single  piece  of
text,  `$#'  is  replaced by the number of arguments present (`2' in the
case shown above), and `$0' is replaced by the name of the program being
executed (in this case `prog').  If the here-document contains instances
of `$' which you don't want replaced by something (for example inside  a
Miranda  string),  you  have  to  escape  them  by preceding them with a
backslash character.

The drawbacks of commands built in this way are two - (a) they  have  no
way  of  taking  information from the terminal during execution (because
the here-document replaces the standard input) and  (b)  the  method  of
access to command line arguments is clumsy.  These problems are overcome
by:

SECOND METHOD (using a `magic string')

Create a file (`prog' say) containing a normal miranda script, but  with
the first two lines in the following form
	#! /usr/local/mira -exp
	<expression>
The  remainder  of  the  file can be any legal miranda script, including
that it can be empty.  Remember to give the file execute permission  (by
saying `chmod +x prog').  Now when `prog' is executed as a UNIX command,
the result  will  be  that  the  miranda  expression  `<expression>'  is
evaluated  in the environment defined by the rest of the script, and the
results sent to the standard output.  Note that only a single expression
is permitted, and it must occur entirely on the second line of the file.
The form of the first line is rigid - the three initial characters  must
be  `#', '!' and space, followed by the absolute pathname of the miranda
interpreter.  The flag "-exp"  is  necessary  and  no  other  flags  are
allowed here.

[Warning: if you omit the `-exp' flag you  can  get  some  very  strange
errors when you try to execute the file, e.g.  a spurious complaint that
the `mira' program has been installed with the wrong permissions.]

A  command  of  this form can take data from the terminal.  The notation
`$-' can be used anywhere in the second and later lines of the  file  to
denote  the  list of characters taken from the standard input.  (That is
`$-' behaves like a Miranda identifier of type [char].)

The command can be invoked with arguments, eg
	prog pig 23
and the notation `$*' can be used in the script as a Miranda  identifier
of  type  [[char]]  denoting the argument list, with the convention that
the initial (zero'th) argument is the name of the command.  So  in  this
case the value of `$*' would be
	["prog","pig","23"]
Of  course,  if  there  are  no arguments, `$*' will be a singleton list
containing just the command name.

_E_x_p_l_a_n_a_t_i_o_n
 The line beginning `#!' is a standard UNIX incantation, called a `magic
string',  indicating  that  the  following  pathname  is to be used as a
command interpreter with the name of the file in which it occurs as  its
argument (see under `execve' in section 2 of the UNIX manual).  The flag
"-exp" advises the Miranda system to expect a  special  script,  of  the
above form, containing an expression to be evaluated as its second line.

[Notes to system administrators:
 (1) In some versions of UNIX `execve'  places  a  limit  (typically  32
chars) on the total length of the `magic string'.
 (2)  Because  the  UNIX  `execve' program permits at most one flag in a
magic string, it is not possible to  give  a  `-lib'  flag  to  mira  in
conjunction with a `-exp' flag.  This is a possible source of difficulty
if you keep the miralib directory at  a  non-standard  place.   One  way
round  this is to set the environment variable MIRALIB, instead of using
a `-lib' flag.  See manual section on flags etc.]

Example
 The  following  script is a Miranda version of the UNIX `cat' command -
if it is invoked without arguments it simply copies its  standard  input
to  its  standard  output, otherwise it concatenates the contents of its
argument files to the standard output.
	#! /usr/local/mira -exp
	output

	output = [Stdout $-], _i_f tl $* = []
               = [Stdout (concat(map read(tl $*)))], _i_f badargs=[]
               = [Stderr (concat(map errmess badargs))], _o_t_h_e_r_w_i_s_e
	badargs = [f|f<-tl $*;~member(filemode f)'r']
	errmess f = f++": cannot access\n"

See also the manual pages on input  from  UNIX  files,  output  to  UNIX
files,  for  the explanation of `read', `filemode', and the constructors
Stdout, Stderr etc.

The rule that Miranda source files must have names ending in  ".m"  does
not  apply  to  scripts  in  this special form (in keeping with the UNIX
convention that the names of  executable  programs  require  no  special
extension).

_E_m_b_a_r_r_a_s_s_i_n_g_ _P_a_u_s_e
 A drawback of the way Miranda #! scripts are currently  implemented  is
that such a script is recompiled each time it is used - if the script is
large this can lead to an irritating delay  each  time  the  program  is
executed.   This  can be minimised by placing as many as possible of the
definitions needed by the #! file in a separate  script  and  %including
them  (see  section on library directives).  These definitions will then
not  be  recompiled  at  each  invocation,  but   retrieved   from   the
corresponding object code file.

