import Miranda 2.066 from upstream

1 files changed, 175 insertions, 0 deletions

diff --git a/miralib/manual/31/4 b/miralib/manual/31/4
new file mode 100644
index 0000000..5378454
--- /dev/null
+++ b/miralib/manual/31/4
@@ -0,0 +1,175 @@
+_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 `magic string')
+
+Create a file, prog.m say, containing a normal miranda script, but  with
+first line
+	#! /usr/bin/mira -exec
+
+The first two characters must be "#!" followed by an optional space  and
+the absolute pathname of the miranda interpreter.  This may be somewhere
+other than /usr/bin/mira, the UNIX shell  command  "which  mira"  should
+tell  you where it is.  The flag "-exec" is necessary and no other flags
+should be added.  (Note "-exec2" can be  substituted  for  "-exec",  see
+below.)
+
+The remainder of the file can be any legal  miranda  script,  which  may
+%include  other  scripts. Somewhere in the file, or in an included file,
+there must be a definition of `main'.  When `prog.m' is  executed  as  a
+UNIX  command,  the  result  will be that `main' is evaluated, using the
+same rules as if you had entered it in an interactive session,  and  the
+results  sent  to  standard  output.   Remember to give the file execute
+permission (e.g. by saying `chmod +x prog.m').
+
+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.m fig 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.m","fig","23"]
+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 an interpreter to be
+invoked with the name of the file in which it occurs  as  argument  (see
+under  `execve'  in  section  2  of  the UNIX manual).  The flag "-exec"
+instructs the Miranda system to evaluate `main', which  can  be  of  any
+type.   If  main is a string this is sent to stdout, if it is of another
+printable type `show main' is sent to stdout, or  if  main  is  of  type
+[sys-message] the sequence of I/O commands is executed.
+
+Examples
+ Here is the Miranda "hello world" program
+	#! /usr/bin/mira -exec
+	main = "hello world\n"
+	
+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/bin/mira -exec
+
+	main = [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 the manual pages on input from UNIX files and 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" is not
+enforced  for  "magic" scripts, in keeping with the UNIX convention that
+executables require no special suffix.  However  a  magic  script  whose
+name  ends  in  ".m"  can also be made the subject of a miranda session.
+This is advantageous during development, as individual  definitions  can
+be tested.  A first line beginning #! is ignored by the Miranda compiler
+which treats it as a comment.  In this situation $* has  the  value  [],
+since the script was not executed as a command.
+
+Note also that if your Miranda executable file has the  ".m"  suffix,  a
+corresponding  ".x" file will be created at its first call, avoiding the
+need for mira to recompile it on subsequent calls (unless there has been
+an update of the source file).
+
+Notes
+ (1) In some UNIX-like systems `execve' places  a  limit  on  the  total
+length of the `magic string'.
+ (2)  Because in many systems (including Linux) `execve' permits at most
+one flag in a magic string, mira does not understand a `-lib' flag given
+in  conjunction  with  a  `-exec'  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 environment variable MIRALIB, instead of
+using a `-lib' flag.  See manual section on flags  etc.   [To  do:  more
+general mechanism to add other flags to -exec in a magic string - DT]
+ (3) If called from the UNIX command line,
+	mira -exec script.m
+will  find and evaluate `main' in script.m and in this situation you can
+combine -exec with other flags, -lib miralib, -heap N, etc preceding the
+name of the script.  Any additional arguments following script.m will
+be found in $*.
+
+_D_e_b_u_g_g_i_n_g_ _s_t_a_n_d_-_a_l_o_n_e_ _s_c_r_i_p_t_s
+ As an aid to debugging a variant flag is available:
+	#!/usr/bin/mira -exec2
+        definitions...
+The -exec2 flag has the same effect as -exec but runtime  errors  (only,
+not compile time errors) are redirected to file miralog/prog, where prog
+is the name of the script.  The redirection takes  place  if  a  miralog
+directory  exists  in  the  current  working  directory  and the process
+running the script has write permission  to  it.   This  is  useful  for
+debugging  cgi  scripts  written  in  Miranda,  particularly  in the not
+infrequent situation that they compile without errors and seem  to  work
+fine  from the command line but fail when invoked by an http call.  (You
+will need to create a directory miralog  in  cgi-bin  and  chown  it  to
+apache, or whatever personality cgi scripts run as).
+
+SECOND METHOD (using a `here document')
+
+Create a file ("prog' say) containing the following
+
+	mira [script] <<!
+	exp1
+	exp2
+	.
+	.
+	.
+	!
+
+The `!' after << can be replaced by any character sequence  -  the  same
+sequence, on a line by itself, terminates the `here document'.
+
+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.   But  if  the
+delimiter after the >> is in quotation marks, eg
+	mira [script] <<"!"
+	stuff
+        !
+then no substitutions will take place inside the here-document.
+
+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.
+