Output to UNIX files etc.

Since Miranda is a functional language, the evaluation of an  expression
cannot  in  itself  cause  a side effect on the state of the world.  The
side effects occur when the value of the  expression  is  printed.   The
value  of  a  command  level  expression is a list of `system messages',
where the possible forms of message are  shown  by  the  following  type
declaration,

  sys_message ::= Stdout [char] | Stderr [char] | Tofile [char] [char] |
                  Closefile [char] | Appendfile [char] | System [char] |
                  Exit num

The  system `prints' such a list of messages by reading it in order from
left to right, evaluating and obeying each message  in  turn  as  it  is
encountered.  The effect of the various messages is as follows.

        Stdout string
The  list  of characters `string' is transmitted to the standard output,
which will normally be connected to the user's screen.  So  for  example
the effect of obeying
        [Stdout "!!!"]
is that three exclamation marks appear on the screen.

        Stderr string
The  list  of  characters `string' is sent to the standard error output.
[Explanation to those unfamiliar with UNIX stream philosophy: all normal
UNIX processes come into existence with a standard input stream, and two
output streams, called standard out  and  standard  error  respectively.
Under  normal  circumstances  standard  error  and standard out are both
connected to the users screen, but in principle they could be  connected
to different places.]

        Tofile fil string
The characters of the string are transmitted to the file or device whose
UNIX pathname is given by `fil'.  Successive `Tofile'  messages  to  the
same  destination  are  appended  together  (i.e. the first such message
causes the file to be opened for writing, and it remains open until  the
end  of  the  whole  message list).  Note that opening a file for output
destroys its previous  contents  (unless  preceded  by  an  `Appendfile'
message, see below).

        Closefile fil
The  stream  which  has  been  opened  to the file `fil' (presumably the
subject of some previous `Tofile' messages) is closed.  If `fil' was not
in  fact  open  this  command  has  no  effect  (i.e. is harmless).  All
open-for-output streams  are  automatically  closed  at  the  end  of  a
message-list  evaluation,  so it is only necessary to invoke `Closefile'
explicitly if you wish to  terminate  output  to  given  file  during  a
message-list  evaluation.   (One reason why you might want to do this is
so as not to have too many output files open at  one  time,  since  many
UNIX  systems place a limit on the number of streams which a process can
have.)

        Appendfile fil
If obeyed before any `Tofile' messages to destination `fil', causes  the
file  to  be opened in `append-mode', so its previous contents are added
to, instead of being replaced.

        System string
Causes `string' to be executed as a shell command (by `/bin/sh') at this
point  in  time.   Enables  arbitrary  UNIX  commands to be invoked from
within a Miranda output list.  The shell process comes into  being  with
its  streams (standard input, standard output, standard error) inherited
from the Miranda process.

        Exit num
Causes the UNIX process evaluating the message list to terminate at this
point  with  exit  status  `num'  (an  integer  between 0 and 127).  The
remaining messages in the list (if any) are discarded.  The exit  status
of  a  Miranda  evaluation which terminates other than by a call to Exit
will be 0 if it terminates successfully or 1 if it encounters a  runtime
error.   The  exit  status  is only relevant if you are using Miranda to
implement a stand-alone UNIX command (see  separate  manual  page  about
this).

[Explanation: the exit status of a UNIX command is a one  byte  quantity
which  is communicated back to the calling shell and can be tested by it
- the usual convention is that 0 exit status means all ok, anything else
means  something  was  amiss.  If you are not into shell programming you
can safely ignore the whole issue.]

The default message wrapper

We have stated above that the value of a  command  level  expression  is
expected  to be of type `[sys_message]'.  Otherwise it is converted to a
list of messages by applying the default message wrapper,

        wrap x = [Stdout x]
This requires that x be a string  -  if  not,  the  operator  `show'  is
applied to x to convert it into a printable representation.

This explains how the Miranda system is able to function in its standard
`desk-calculator' mode.  When you type, say `2+3', the compiler  notices
that this is not of type [sys_message] and silently converts it to
        [Stdout (show(2+3))]
before obeying it.

Output redirection

A Miranda command of the form
        exp &> pathname
causes  a  background  process to be set up for the evaluation of `exp',
with both the standard output and  the  standard  error  output  of  the
process  redirected  to  `pathname'.  The expression is coerced to be of
type [sys_message] using exactly the same rules as in the standard case.
If  the  value of `exp' is an explicit list of messages, the destination
of `Tofile' messages are unaffected  by  the  global  redirection  (only
messages  which  would  otherwise  have  gone  to the screen are sent to
`pathname').

If two (blank separated) pathnames are given after  the  `&>',  standard
output is redirected to the first file and standard error to the second.
Thus:
        exp &> outfil errfil

If the `&>' is replaced by a `&>>', instead of overwriting the  previous
contents, the relevant output is appended to the end of the file.  Thus:
        exp &>> pathname(s)
As  with  the  `&>'  command,  either one or two pathnames can be given,
depending on whether you wish standard error to be merged with  standard
out, or separated from it.

Note that a background process created by a `&>' or `&>>' command has no
standard input - if  the  expression  contains  `$-',  the  latter  will
evaluate to `[]'.

Implementation Restrictions
 Arguments representing pathnames (to Tofile, Appendfile, Closefile) are
restricted  to  1024  characters  in length - pathnames longer than this
cause an error message.  The shell command supplied to  System  is  also
restricted to 1024 characters in length.