\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename marst.info
@settitle GNU MARST 2.1 User's Guide
@c %**end of header

@ifinfo
@format
START-INFO-DIR-ENTRY
* marst: (marst).       GNU Algol-to-C Translator
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@ifinfo
This file is a part of GNU MARST package.

Copyright (C) 2000 Andrew Makhorin <mao@@mai2.rcnet.ru>, Department for
Applied Informatics, Moscow Aviation Institute, Moscow, Russia. All rights
reserved.

GNU MARST package is a part of the GNU project, released under the aegis of
GNU.

This code is free software; you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This software is distributed "as is" in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHATABILITY or
FITNESS FOR A PRTICULAR PURPOSE. See the GNU General Public License for more
details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, 59 Temple Place,
Suite 330, Boston, MA 02111-1307 USA.
@end ifinfo

@titlepage
@title GNU MARST
@subtitle GNU Algol-to-C Translator
@subtitle Version 2.1
@subtitle User's Guide
@subtitle December 2000
@author Andrew Makhorin
@page
@vskip 0pt plus 1filll
GNU MARST package is a part of the GNU project, released under the aegis of
GNU.

Copyright @copyright{} 2000 Andrew Makhorin, Department for Applied
Informatics, Moscow Aviation Institute, Moscow, Russia. All rights reserved.

Free Software Foundation, Inc., 59 Temple Place --- Suite 330, Boston, MA
02111, USA.

Permission is granted to make and distribute verbatim copies of this manual
provided the copyright notice and this permission notice are preserved on all
copies.

Permission is granted to copy and distribute modified versions of this manual
under the conditions for verbatim copying, provided also that the entire
resulting derived work is distributed under the terms of a permission notice
identical to this one.

Permission is granted to copy and distribute translations of this manual into
another language, under the above conditions for modified versions.
@end titlepage

@ifinfo
@node Top, , , (dir)
@top GNU MARST 2.1 User's Guide

@menu
* Introduction::        Introduction
* Installation::        Installation
* Invocation::          Program Invocation
* Example::             Usage Example
* Language::            Input Language
* Io::                  Input/Output
* Extensions::          Language Extensions
* Converter::           Converter Utility
* Thanks::              Acknowledgements
@end menu
@end ifinfo

@contents

@node Thanks, , , Top
@unnumbered Acknowledgements

The author thanks Erik Sch@"onfelder <@email{schoenfr@@gaertner.de}> for a lot
of useful advices and especially for testing MARST with real Algol 60 programs.
The author also thanks Bernhard Treutwein
<@email{Bernhard.Treutwein@@Verwaltung.Uni-Muenchen.DE}> for great help in
preparing MARST documentation.

@node Introduction, Installation, , Top
@chapter Introduction

GNU MARST is an Algol-to-C translator. It automatically translates programs
written in the algorithmic language @w{Algol 60} into the ANSI C programming
language.

Processing scheme can be understood as the following:

@sp 1
@example
                Algol-60 source program
                           |
                           V
                    +-------------+
                    |    MARST    |
                    +-------------+
                           |
                           V
                     C source code
                           |
                           V
                    +-------------+
     algol.h ------>| C compiler  |<------ Standard headers
                    +-------------+
                           |
                           V
                      Object code
                           |
                           V
                    +-------------+
      ALGLIB ------>|   Linker    |<------ Standard libraries
                    +-------------+
                           |
                           V
                    +-------------+
  Input data ------>| Executable  |-------> Output data
                    +-------------+
@end example
@sp 1

@noindent
where:

@table @asis
@item Algol 60 source program
a text file that contains a program written in the algorithmic language
@w{Algol 60} (see below about coding requirements);
@item MARST
the MARST translator, a program that converts source Algol program to the C
programming language. This program is a part of the MARST package;
@item C source code
a text file that contains the C source code generated by the MARST translator;
@item @code{algol.h}
the header file that contains declarations of all objects used by every 
program generated by the MARST translator. This file includes some standard
headers (@code{stdio.h}, @code{stdlib.h}, etc.), however, no other headers are 
used explicitly in the generated code. This file is a part of the MARST
package;
@item Standard headers
standard header files (they are used only in the header file @code{algol.h});
@item C compiler
C compiler;
@item Object code
a binary file that contains object code produced by the C compiler;
@item ALGLIB
the library (archive) file that contains object code for all standard and 
library routines used by Algol programs. Some of these routines, which 
correspond to standard Algol procedures (@i{ininteger}, @i{outreal}, etc.) are
written in @w{Algol 60} and translated to the C programming language by means
of the MARST translator. Source code of all library routines is a part of the
MARST package. Note that the name of this library depends on a particular
distribution. In this distribution the library has the name @code{libalgol.a};
@item Standard libraries
standard C run-time libraries;
@item Linker
external references resolving program;
@item Executable
a binary file that contains ready-to-run Algol 60 program in the loadable
(executable) form;
@item Input data
input text file(s) read by Algol program;
@item Output data
output text file(s) written by Algol program.
@end table

@node Installation, Invocation, Introduction, Top
@chapter Installation

In order to install the MARST package under GNU/Linux the standard installation
procedure should be used. For details see the file @code{INSTALL} included into
the distribution.

As a result of installation the following four components will be installed:

@table @code
@item marst
as a rule, into @code{usr/local/bin};
@item macvt
as a rule, into @code{usr/local/bin};
@item algol.h
as a rule, into @code{usr/local/include} and/or @code{usr/include};
@item libalgol.a
as a rule, into @code{usr/local/lib}.
@end table

@node Invocation, Example, Installation, Top
@chapter Program Invocation

In order to invoke the MARST translator the following syntax should be used:

@sp 1
@code{marst} [@i{options} ...] [@i{filename}]
@sp 1

Options:

@table @asis
@item @code{-d}, @code{--debug}
run translator in debug mode

If this option is set, the translator emits elementary syntactic units of 
source Algol program to the output C code in the form of comments.

This option is useful for localizing syntax error more precisely. For example,
@w{Algol 60} allows comments of three kinds: ordinary comments,
@w{@b{end}-@b{end}} comments, and extended parameter delimiters. Therefore, it
is easy to make a mistake, for example, forgetting a comma between the @b{end}
bracket and the next statement.

@item @code{-e} @i{nnn}, @code{--error-max} @i{nnn}
maximal error allowance

This option sets maximal error allowance. The translator stops processing after
the specified number of errors has been detected. The value of @i{nnn} should
be in the range from 0 to 255. If this option is not specified, the default
option @code{@w{-e 0}} is used and means that the translation is continued
until the end of the input file.

@item @code{-h}, @code{--help}
display help information and @code{exit(0)}

@item @code{-l} @i{nnn}, @code{--linewidth} @i{nnn}
desirable output line width

This option sets desirable line width for the output C code produced by the
translator. The value @i{nnn} should be in the range from 50 to 255. If this
option is not specified, the default option @code{@w{-l 72}} is used.

Note that actual line width may happen to be greater than @i{nnn}, because the
translator is not able to break the output text at any place. However, this 
happens relatively seldom.

@item @code{-o} @i{filename}, @code{--output} @i{filename}
the name of output text file, to which the translator sends the produced C code

If this option is not set, the translator uses the standard output by default.

@item @code{-t}, @code{--notimestamp}
don't write the time stamp to the output C code

By default the translator writes date and time of translation to the output C
code as a comment.

@item @code{-v}, @code{--version}
display translator version and @code{exit(0)}

@item @code{-w}, @code{--nowarn}
don't display warning messages

By default the translator displays warning messages that reflect potential 
errors and non-standard features used in the source Algol program.
@end table

In order to translate a program written in @w{Algol 60}, it should be prepared
as a plain text file, and the name of this file should be specified in the
command line. If the name of the input text file is not specified, the
translator uses the standard input by default.

Note that the translator reads the input file @emph{twice}, therefore this file
should be only regular file, but not a pipe, terminal input, etc. Thus, if the
standard input is used, it should be redirected to a regular file.

For one run the translator is able to process only one input text file.

@node Example, Language, Invocation, Top        
@chapter Usage Example

The following example shows how the MARST translator may be used in most cases.

At first we prepare source @w{Algol 60} program, say, in the text file named
@samp{sample.alg}:

@sp 1
@example
begin
   outstring(1, "Hello, world\n")
end
@end example
@sp 1

Now we translate this program to the C programming language:

@sp 1
@example
marst sample.alg -o sample.c
@end example
@sp 1

@noindent
and get the text file named @samp{sample.c}, which then we compile and link in
the usual way (we should remember about Algol and math libraries):

@sp 1
@example
gcc sample.c -lalgol -lm
@end example
@sp 1

Finally, we run executable

@sp 1
@example
./sample
@end example
@sp 1

@noindent
and see what we get. That's all.

@node Language, Io, Example, Top
@chapter Input Language

The input language of the MARST translator is hardware representation of the
reference language @w{Algol 60} as described in the following IFIP document
@footnote{The verbatim reprint of this document may be obtained from the
author's page dedicated to the MARST package at
<@url{http://mai2.rcnet.ru/~mao/marst/index.htm}>.}:

Modified Report on the Algorithmic Language @w{ALGOL 60}.
@i{The Computer Journal}, @w{Vol. 19}, @w{No. 4}, @w{Nov. 1976},
@w{pp. 364---79}. (This document is an official IFIP standard. It is @emph{not}
a part of the MARST package.)

Source @w{Algol 60} program is coded as a plain text file using ASCII character
set.

Basic symbols should be coded as shown in the following table:

@ifinfo
@example
Basic symbol            Hardware representation
-----------------------------------------------
a, b, ..., z            a, b, ..., z
A, B, ..., Z            A, B, ..., Z
0, 1, ..., 9            0, 1, ..., 9
+                       +
-                       -
x                       *
/                       /
integer division        %
exponentiation          ^ (or **)
<                       <
not greater             <=
=                       =
not less                >=
>                       >
not equal               !=
equivalence             ==
implication             ->
or                      |
and                     &
not                     !
,                       ,
.                       .
ten (10)                # (pound sign)
:                       :
;                       ;
:=                      :=
(                       (
)                       )
[                       [
]                       ]
opening quote           "
closing quote           "
array                   array
begin                   begin
Boolean                 Boolean (or boolean)
code                    code
comment                 comment
do                      do
else                    else
end                     end
false                   false
for                     for
go to                   go to (or goto)
if                      if
integer                 integer
label                   label
own                     own
procedure               procedure
real                    real
step                    step
string                  string
switch                  switch
then                    then
true                    true
until                   until
value                   value
while                   while
@end example
@end ifinfo

@tex
$$\vbox
{
\settabs 5 \columns
\+ Basic symbol & Representation & Basic symbol & Representation & \cr
\+ \hrulefill & \hrulefill & \hrulefill & \hrulefill & \cr
\+ $a, b, \dots, z$ & \tt{a}, \tt{b}, \dots, \tt{z} & ] & \tt{]}  & \cr
\+ $A, B, \dots, Z$ & \tt{A}, \tt{B}, \dots, \tt{Z} & ` & \tt{"}  & \cr
\+ $0, 1, \dots, 9$ & \tt{0}, \tt{1}, \dots, \tt{9} & ' & \tt{"}  & \cr
\+ $+$       & \tt{+}           & \bf{array}     & \tt{array}     & \cr
\+ $-$       & \tt{-}           & \bf{begin}     & \tt{begin}     & \cr
\+ $\times$  & \tt{*}     & \bf{Boolean}   & \tt{Boolean} (\tt{boolean})& \cr
\+ $/$       & \tt{/}           & \bf{code}      & \tt{code}      & \cr
\+ $\div$    & \tt{\%}          & \bf{comment}   & \tt{comment}   & \cr
\+ $\uparrow$ & \tt{\^{}} (\tt{**})  & \bf{do}        & \tt{do}        & \cr
\+ $<$       & \tt{<}           & \bf{else}      & \tt{else}      & \cr
\+ $\leq$    & \tt{<=}          & \bf{end}       & \tt{end}       & \cr
\+ $=$       & \tt{=}           & \bf{false}     & \tt{false}     & \cr
\+ $\geq$    & \tt{>=}          & \bf{for}       & \tt{for}       & \cr
\+ $\neq$    & \tt{!=}          & \bf{go to}     & \tt{go to} (\tt{goto})& \cr
\+ $\equiv$  & \tt{==}          & \bf{if}        & \tt{if}        & \cr
\+ $\supset$ & \tt{->}          & \bf{integer}   & \tt{integer}   & \cr
\+ $\vee$    & \tt{|}           & \bf{label}     & \tt{label}     & \cr
\+ $\wedge$  & \tt{\&}          & \bf{own}       & \tt{own}       & \cr
\+ $\neg$    & \tt{!}           & \bf{procedure} & \tt{procedure} & \cr
\+ $,$       & \tt{,}           & \bf{real}      & \tt{real}      & \cr
\+ $.$       & \tt{.}           & \bf{step}      & \tt{step}      & \cr
\+ $_{10}$   & \tt{\#}          & \bf{string}    & \tt{string}    & \cr
\+ $:$       & \tt{:}           & \bf{switch}    & \tt{switch}    & \cr
\+ $;$       & \tt{;}           & \bf{then}      & \tt{then}      & \cr
\+ $:=$      & \tt{:=}          & \bf{true}      & \tt{true}      & \cr
\+ $($       & \tt{(}           & \bf{until}     & \tt{until}     & \cr
\+ $)$       & \tt{)}           & \bf{value}     & \tt{value}     & \cr
\+ $[$       & \tt{[}           & \bf{while}     & \tt{while}     & \cr
}
$$
@end tex

Any symbol can be surrounded by any number of white-space characters (i.e. by
spaces, @code{HT}, @code{CR}, @code{LF}, @code{FF}, and @code{VT}). However,
any multi-character symbol should contain no white-space characters. Moreover,
a letter sequence is recognized as a keyword if and only if there is no letter
or digit that immediately precedes or follows the sequence (except the keyword
@samp{@w{go to}} that may contain zero or more spaces between @samp{go} and
@samp{to}).

For example:

@table @code
@item ... 123 then abc ...
@samp{then} will be recognized as @b{then} symbol
@item ... 123then abc ...
@item ... 123 thenabc ...
@samp{then} will be recognized as letters @i{t}, @i{h}, @i{e}, @i{n}, but not
as @b{then} symbol
@item ... 123 th en abc ...
@samp{th en} will be recognized as letters @i{t}, @i{h}, @i{e}, @i{n}
@end table

Note that identifiers and numbers can contain white-space characters. This
feature may be used in that case if an identifier is the same as keyword. For
example, identifier @i{label} should be coded as @samp{@w{la bel}} or
@samp{@w{lab el}}. Note also that white-space characters are not significant
(except their use within character strings), so @samp{abc} and
@samp{@w{a b c}} denote the same identifier @i{abc}.

All letters are case sensitive (except the first "b" in the keyword
@b{Boolean}). This means that @samp{abc} and @samp{ABC} are different
identifiers, and @samp{Then} will not be recognized as the keyword @b{then}.

Each identifier or number can contain up to 100 characters (except internal
white-space characters).

Quoted character string are coded in the C style. For example:

@sp 1
@example
outstring(1, "This\tis a string\n");

outstring(1, "This\tis a st"   "ring\n");

outstring(1, "This\tis all one st"
   "ring\n");
@end example                  
@sp 1

Within a string (i.e. between double quotes that enclose the string body)
escape sequences may be used (as @samp{\t} and @samp{\n} in the example
above). Double quote and backslash within string should be coded as @samp{\"}
and @samp{\\} respectively. Between parts of a string any number of
white-space characters is allowed.

Except coding character strings and limitation on length of identifiers and
numbers, there are no other differences between the syntax of the reference
language and the syntax of the MARST input language.

Note that there are some differences between the Revised Report on @w{Algol 60}
and the Modified Report on @w{Algol 60}, because the latter is a result of
application of the following IFIP document to the former:

@i{@w{R. M. De Morgan}, @w{I. D. Hill}, and @w{B. A. Whichman.}} A Supplement
to the @w{ALGOL 60} Revised Report. @i{The Computer Journal}, @w{Vol. 19},
@w{No. 3}, 1976, @w{pp. 276---88}. (This document is an official IFIP standard.
It is @emph{not} a part of the MARST package.)

@ifnotinfo

In order to illustrate what is the input language of the MARST translator let's
consider the following procedure, which is written in the reference language:

@sp 1
@tex
{
\parskip 0 pt
\parindent 0 pt
\leftskip 12 pt
\bf{real} \bf{procedure} \it{euler}\rm{(}\it{fct}\rm{,} \it{eps}\rm{,}
\it{tim}\rm{);}

\leftskip 24 pt
\bf{value} \it{eps}\rm{,} \it{tim}\rm{;}

\leftskip 24 pt
\bf{real} \bf{procedure} \it{fct}\rm{;} \bf{real} \it{eps}\rm{;}
\bf{integer} \it{tim}\rm{;}

\bf{comment} \it{euler computes the sum of fct}\rm{(}\it{i}\rm{)} \it{for i
from zero up to infinity by means of a suitably refined euler transformation.
The summation is stopped as soon as tim times in succession the absolute
value of the terms of the transformed series are found to be less than eps.
Hence one should provide a function fct with one integer argument}\rm{,}
\it{an upper bound eps}\rm{,} \it{and an integer tim. euler is particularly
efficient in the case of a slowly convergent or divergent alternating
series}\rm{;}

\bf{begin}

\bf{integer} \it{i}\rm{,} \it{k}\rm{,} \it{n}\rm{,} \it{t}\rm{;}

\bf{array} \it{m}\rm{[0:15];}

\bf{real} \it{mn}\rm{,} \it{mp}\rm{,} \it{ds}\rm{,} \it{sum}\rm{;}

\it{n} \rm{:=} \it{t} \rm{:= 0;}

\it{m}\rm{[0] :=} \it{fct}\rm{(0);} \it{sum} \rm{:=} \it{m}\rm{[0]/2;}

\bf{for} \it{i} \rm{:= 1,} \it{i} \bf{+ 1} \bf{while} \it{t} \rm{$<$} \it{tim}
\bf{do}

\leftskip 36 pt
\bf{begin}

\it{mn} \rm{:=} \it{fct}\rm{(}\it{i}\rm{);}

\bf{for} \it{k} \rm{:= 0} \bf{step} \rm{1} \bf{until} \it{n} \bf{do}

\leftskip 48 pt
\bf{begin}

\it{mp} \rm{:= (}\it{mn} \rm{+} \it{m}\rm{[}\it{k}\rm{])/2;}

\it{m}\rm{[}\it{k}\rm{] :=} \it{mn}\rm{;} \it{mn} \rm{:=} \it{mp}

\bf{end} \it{means}\rm{;}

\leftskip 36 pt
\bf{if} \it{abs}\rm{(}\it{mn}\rm{)} \rm{$<$}
\it{abs}\rm{(}\it{m}\rm{[}\it{n}\rm{]) $\wedge$} \it{n} \rm{$<$ 15} \bf{then}

\leftskip 48 pt
\bf{begin}

\it{ds} \rm{:=} \it{mn}\rm{/2;} \it{n} \rm{:=} \it{n} \rm{+ 1;}

\it{mn}\rm{[}\it{n}\rm{] :=} \it{mn}

\bf{end} \it{accept}\rm{;}

\leftskip 36 pt
\bf{else}

\leftskip 48 pt
\it{ds} \rm{:=} \it{mn}\rm{;}

\leftskip 36 pt
\it{sum} \rm{:=} \it{sum} \rm{+} \it{ds}\rm{;}

\it{t} \rm{:=} \bf{if} \it{abs}\rm{(}\it{ds}\rm{) $<$} \it{eps} \bf{then}
\it{t} \rm{+ 1} \bf{else} \rm{0}

\bf{end}\rm{;}

\leftskip 24 pt
\it{euler} \rm{:=} \it{sum}

\bf{end} \it{euler}\rm{;}

}
@end tex
@sp 1

This procedure may be coded using MARST representation as the following:

@sp 1
@example
real procedure euler(fct, eps, tim);
   value eps, tim;
   real procedure fct; real eps; integer tim;
   comment euler computes the sum of fct(i) for i from zero up to
   infinity by means of a suitably refined euler transformation. The
   summation is stopped as soon as times in succession the absolute
   value of the terms of the transformed series are found to be less
   than eps. Hence one should provide a function fct with one integer
   argument, an upper bound eps, and an integer tim. euler is
   particularly efficient in the case of a slowly convergent or
   divergent alternating series;
   begin
   integer i, k, n, t;
   array m[0:15];
   real mn, mp, ds, sum;
   n := t := 0;
   m[0] := fct(0); sum := m[0] / 2;
   for i := 1, i+1 while t < tim do
      begin
      mn := fct(i);
      for k := 0 step 1 until n do
         begin
         mp := (mn + m[k]) / 2;
         m[k] := mn; mn := mp
      end means;
   if abs(mn) < abs(m[n]) & n < 15 then
      begin
      ds := mn / 2; n := n + 1;
      m[n] := mn
      end accept
   else
      ds := mn;
   sum := sum + ds;
   t := if abs(ds) < eps then t + 1 else 0
   end;
euler := sum
end euler;   
@end example
@sp 1

@end ifnotinfo

@node Io, Extensions, Language, Top
@chapter Input/Output

All input/output is performed by standard @w{Algol 60} procedures.

The MARST implementation provides up to 16 input/output channels, which have
numbers 0, 1, @dots{}, 15. The channel number 0 is always connected to
@code{stdin}, so only input from this channel is allowed. Analogously, the
channel number 1 is always connected to @code{stdout}, so only output to this
channel is allowed. Other channels allow both input and output.

(The standard procedure @i{fault} uses the channel number
@tex
$\Sigma,$
@end tex
which is not available to the programmer. This latent channel is always
connected to @code{stderr}.)

Before Algol program startup all channels (except channels number 0 and 1) are
disconnected, i.e. no files are assigned to them.

If input (output) is required by the Algol program from (to) the channel number
@i{n}, the following actions are taken:

@enumerate a
@item
if the channel number @i{n} is connected for output (input), the I/O routine
closes the file assigned to this channel, making it be disconnected;
@item
if the channel number @i{n} is disconnected, the I/O routine opens the
corresponding file in read (write) mode and assigns this file to the channel,
making it be connected;
@item
finally, the I/O routine performs an input (an output) operation on the channel
number @i{n}. If an end-of-file has been detected, the I/O routine signals an
error condition.
@end enumerate

In order to determine the name of file, which should be assigned to the channel
number @i{n}, the I/O routine checks for environment variable named
@samp{FILE_n}. If such variable exists, its value is used as filename.
Otherwise, its name (i.e. the character string @code{"FILE_n"}) is used as
filename.

@node Extensions, Converter, Io, Top
@chapter Language Extensions

The MARST translator provides some extensions of the reference language in
order to make the package be more convenient for the programmer.

@section Modular programming

The feature of modular programming can be illustrated by the following example:

@ifinfo
@example
First file                    Second file
----------------------------------------------------
procedure one(a, b);          procedure one(a, b);
value a, b; real a, b;        value a, b; real a, b;
begin                         code;
      ...
end;                          procedure two(x, y);
                              value x, y; real x, y;
procedure two(x, y);          code;
value x, y; real x, y;
begin                         begin
      ...                           <main program>
end;                          end
@end example
@end ifinfo

@tex
$$\vbox
{
\settabs 3 \columns
\+ First file & Second file & \cr
\+ \hrulefill & \hrulefill & \cr
\+ \tt{procedure one(a, b);}       & \tt{procedure one(a, b);}       & \cr
\+ \tt{value a, b; real a, b;}     & \tt{value a, b; real a, b;}     & \cr
\+ \tt{begin}                      & \tt{code;}                      & \cr
\+ \tt{. . . . . .}                &                                 & \cr
\+ \tt{end;}                       & \tt{procedure two(x, y);}       & \cr
\+                                 & \tt{value x, y; array x, y;}    & \cr
\+ \tt{procedure two(x, y);}       & \tt{code;}                      & \cr
\+ \tt{value x, y; array x, y;}    &                                 & \cr
\+ \tt{begin}                      & \tt{begin}                      & \cr
\+ \tt{. . . . . .}                & \tt{<main program>}             & \cr
\+ \tt{end;}                       & \tt{end;}                       & \cr
}
$$
@end tex

The procedures @i{one} and @i{two} in the first file are called
@dfn{precompiled procedures}. Declarations of precompiled procedures should be
outside of main program block or compound statement. The procedures @i{one} and
@i{two} in the second file are called @dfn{code procedures}; they have the
keyword @b{code} instead a procedure body statement. Declarations of code
procedures also should be outside of main program block or compound statement.

This mechanism allows translating precompiled procedures independently from the
main program. Moreover, precompiled procedures may be programmed in any other
C compatible programming language. The programmer can consider that directly
before Algol program startup declarations of all precompiled procedures are
substituted into the file, which contains main program (the second file in the
example above), instead declarations of corresponding code procedures.

Each code procedure should have the same procedure heading as the corresponding
precompiled procedure (however, names of parameters may be altered). Note that
mismatched procedure headings can't be detected by the MARST translator,
because they are placed in different files.

@section Pseudo procedure @i{inline}

The pseudo procedure @i{inline} has the following (implicit) heading:

@sp 1
@example
procedure inline(str);
string str;
@end example
@sp 1

A procedure statement that refers to the @i{inline} pseudo procedure is
translated into the code, which is the string @i{str} without enclosing quotes.
For example:

@ifinfo
@example
Source program                  Output C code
------------------------------------------------
. . .                           . . .
a := 1;                         dsa_0->a_5 = 1;
b := 2;                         dsa_0->b_8 = 2;
inline("printf(\"OK\");");      printf("OK");
c := 3;                         dsa_0->c_4 = 3;
. . .                           . . .
@end example
@end ifinfo

@tex
$$\vbox
{
\settabs
\+ \tt(.............................) & \tt(..............) & \cr
\+ Source program & Output C code & \cr
\+ \hrulefill & \hrulefill & \cr
\+ \tt{. . .}                       & \tt{. . .} & \cr
\+ \tt{a := 1;}                     & \tt{dsa\_0->a\_5 = 1;} & \cr
\+ \tt{b := 2;}                     & \tt{dsa\_0->b\_8 = 2;} & \cr
\+ \tt{inline("printf($\backslash$"OK$\backslash$");");}
& \tt{printf("OK");} & \cr
\+ \tt{c := 3;}                     & \tt{dsa\_0->c\_4 = 3;} & \cr
\+ \tt{. . .}                       & \tt{. . .} & \cr
}
$$
@end tex

Procedure statement @i{inline} may be used anywhere in the program as an
oridinary Algol statement.

@section Pseudo procedure @i{print}

The pseudo procedure @i{print} is intended mainly for test printing (because
standard Algol input/output is out of criticism). This procedure has
unspecified heading and variable parameter list. For example:

@sp 1
@example
real a, b; integer c; Boolean d;
array u, v[1:10], w[-5:5,-10:10];
. . .
print(a, b, u);
print(c);
. . .
print("test shot", (a+b)*c, !d & u[1] > v[1], u, v, w);
. . .
@end example
@sp 1

Each actual parameter passed to the pseudo procedure @i{print} is sent to the
channel number 1 (@code{stdout}) using printable format.

@node Converter, , Extensions, Top
@chapter Converter Utility

Algol converter utility is MACVT. It is an auxiliary program, which is intended
for converting @w{Algol 60} programs from some other representation to the
MARST representation. Such conversion is usually needed when existing Algol
programs should be adjusted in order to translate them with MARST.

MACVT is not a translator itself. This program just reads original code of
@w{Algol 60} program from the input text file, converts main symbols to the
MARST representation (see Section 5. Input Language), and writes resulting code
to the output text file. It is assumed that the output code produced by MACVT
will be later translated by MARST in usual way. Note that MACVT performs no 
syntax checking.

Input language understood by MACVT differs from the MARST input language only
in representation of basic symbols. Should note that in this sense the MARST
input language is a subset of the MACVT input language.

Representation of basic symbols implemented in MACVT is based mainly on well
known (in 1960s) @w{Algol 60} compiler developed by IBM first for IBM 7090 and
later for System/360. This representation may be considered as non-official
standard, because it was widely used at that time, when @w{Algol 60} was actual
programming language.

In order to invoke the MACVT converter the following syntax should be used:

@code{macvt} [@i{options} ...] [@i{filename}]

Options:

@table @asis
@item @code{-c}, @code{--classic}
use classic representation

This option is used by default until other representation is chosen. It assumes
that input Algol 60 program is coded using classic representation: all
white-space characters are non-significant (except within quoted character
strings) and keywords should be enclosed by apostrophes. For details see below.

@item @code{-f}, @code{--free-coding}
use free representation

If this option is set, it is allowed not to enclose keywords by apostrophes. 
But in this case white-space characters should not be used within
multi-character basic symbols. See below for details.

@item @code{-h}, @code{--help}
display help information and @code{exit(0)}

@item @code{-i}, @code{--ignore-case}
convert letters to lower case

If this option is set, all letters (except within comments and character 
strings) are converted to lower case, i.e. conversion is case-insensitive.

@item @code{-m}, @code{--more-free}
use more free representation

This option is the same as @code{--free-coding}, but additionally keywords for
arithmetic, logical, and relational operators can be coded without apostrophes.
For details see below.

@item @code{-o} @i{filename}, @code{--output} @i{filename}
the name of output text file, to which the converter sends the converted 
@w{Algol 60} program

If this option is not set, the converter uses the standard output by default.

@item @code{-s}, @code{--old-sc}
use old (classic) semicolon representation

This option allows the converter recognizing diphthong ., (point and comma) as
semicolon (including its usage for terminating comment sequence).

@item @code{-t}, @code{--old-ten}
use old (classic) ten symbol representation

This option allows the converter recognizing single apostrophe (when it is
followed by @code{+}, @code{-}, or digit) as ten symbol.

@item @code{-v}, @code{--version}
display the converter version and @code{exit(0)}
@end table

In order to convert an Algol 60 program, it should be prepared as a plain text
file, and the name of this file should be specified in the command line. If the
name of the input text file is not specified, the converter uses the standard
input by default.

For one run the converter is able to process only one input text file.

In the table shown on the next page one or more valid representation are given
for each basic symbol. Thereto the following additional rules are assumed:

@enumerate 1
@item
Classic (apostrophized) form of keywords and some other basic symbols are
allowed for any (i.e. for classic as well as free) representation.
@item
In case of classic representation all white-space characters (except their
usage within comments and quoted strings) are ignored anywhere.
@item
Basic symbol enclosed by apostrophes may contain white-space characters, which
are ignored. Besides, all letters are case-insensitive.
@item
Basic symbols may be coded in the free form (without apostrophes) only if the
free representation (@code{--free-coding} or @code{--more-free}) is used.
@item
In case of free representation any multi-character basic symbol should contain
no white-space characters.
@item
Free form of keywords that denote arithmetic, logical, and relational operators
(i.e. @code{greater} instead @code{'greater'}) is allowed only if the option
@code{--more-free} is used.
@item
Single apostrophe is recognized as ten symbol only if the option
@code{--old-ten} is used. Note that in this case the sequence @code{'10'} is
not recognized as ten symbol.
@item
Diphthong ., (point and comma) is recognized as semicolon only in the case if
the option @code{--old-sc} is used.
@item
If an opening quote is coded as @code{"} (double quote), the corresponding
closing quote should be coded as @code{"} (double quote). If an opening quote
is coded as @code{`} (diacritic mark), the corresponding closing quote should
be coded as @code{'} (single apostrophe).
@end enumerate

@ifinfo
@example
   Basic symbol            Extended hardware representation
   -----------------------------------------------------------
   a, b, ..., z            a, b, ..., z
   A, B, ..., Z            A, B, ..., Z
   0, 1, ..., 9            0, 1, ..., 9
   +                       +
   -                       -
   x                       *
   /                       /
   integer division        %                    '/'      'div'
   exponentiation          ^     **             'power'  'pow'
   <                       <                    'less'
   not greater             <=                   'notgreater'
   =                       =                    'equal'
   not less                >=                   'notless'
   >                       >                    'greater'
   not equal               !=                   'notequal'
   equivalence             ==                   'equiv'
   implication             ->                   'impl'
   or                      |                    'or'
   and                     &                    'and'
   not                     !                    'not'
   ,                       ,
   .                       .
   ten (10)                #     '              '10'
   :                       :     ..
   ;                       ;     .,
   :=                      :=    .=    ..=
   (                       (
   )                       )
   [                       [     (/
   ]                       ]     /)
   opening quote           "     `
   closing quote           "     '
   array                                        'array'
   begin                                        'begin'
   Boolean                                      'boolean'
   code                                         'code'
   comment                                      'comment'
   do                                           'do'
   else                                         'else'
   end                                          'end'
   false                                        'false'
   for                                          'for'
   go to                                        'goto'
   if                                           'if'
   integer                                      'integer'
   label                                        'label'
   own                                          'own'
   procedure                                    'procedure'
   real                                         'real'
   step                                         'step'
   string                                       'string'
   switch                                       'switch'
   then                                         'then'
   true                                         'true'
   until                                        'until'
   value                                        'value'
   while                                        'while'
@end example
@end ifinfo

@tex
$$\vbox
{
\settabs
\+ \tt{............} & \tt{.......................} & \tt{.............} &
   \tt{............} & \cr
\+ Basic symbol & Representation & Basic symbol & Representation & \cr
\+ \hrulefill & \hrulefill & \hrulefill & \hrulefill & \cr
\+ $a, b, \dots, z$ & \tt{a}, \tt{b}, \dots, \tt{z}
   & ] & \tt{]\ \ \ \ \ \ /)} & \cr
\+ $A, B, \dots, Z$ & \tt{A}, \tt{B}, \dots, \tt{Z}
   & ` & \tt{"\ \ \ \ \ \ `} & \cr
\+ $0, 1, \dots, 9$ & \tt{0}, \tt{1}, \dots, \tt{9}
   & ' & \tt{'\ \ \ \ \ \ '} & \cr
\+ $+$       & \tt{+}           & \bf{array}     & \tt{'array'}   & \cr
\+ $-$       & \tt{-}           & \bf{begin}     & \tt{'begin'}   & \cr
\+ $\times$  & \tt{*}           & \bf{Boolean}   & \tt{'boolean'} & \cr
\+ $/$       & \tt{/}           & \bf{code}      & \tt{'code'}    & \cr
\+ $\div$    & \tt{\%\ \ \ \ \ \ '/'\ \ \ \ \ \ 'div'}
   & \bf{comment}   & \tt{'comment'} & \cr
\+ $\uparrow$ & \tt{\^{}\ \ **\ \ 'power'\ \ 'pow'}
   & \bf{do}        & \tt{'do'} & \cr
\+ $<$       & \tt{<\ \ \ \ \ \ 'less'}
   & \bf{else}      & \tt{'else'} & \cr
\+ $\leq$    & \tt{<=\ \ \ \ \ 'notgreater'}
   & \bf{end}       & \tt{'end'} & \cr
\+ $=$       & \tt{=\ \ \ \ \ \ 'equal'}
   & \bf{false}     & \tt{'false'} & \cr
\+ $\geq$    & \tt{>=\ \ \ \ \ 'notless'}
   & \bf{for}       & \tt{'for'} & \cr
\+ $\neq$    & \tt{!=\ \ \ \ \ 'notequal'}
   & \bf{go to}     & \tt{'goto'} & \cr
\+ $\equiv$  & \tt{==\ \ \ \ \ 'equiv'}
   & \bf{if}        & \tt{'if'} & \cr
\+ $\supset$ & \tt{->\ \ \ \ \ 'impl'}
   & \bf{integer}   & \tt{'integer'} & \cr
\+ $\vee$    & \tt{|\ \ \ \ \ \ 'or'}
   & \bf{label}     & \tt{'label'} & \cr
\+ $\wedge$  & \tt{\&\ \ \ \ \ \ 'and'}
   & \bf{own}       & \tt{'own'} & \cr
\+ $\neg$    & \tt{!\ \ \ \ \ \ 'not'}
   & \bf{procedure} & \tt{'procedure'} & \cr
\+ $,$       & \tt{,}           & \bf{real} & \tt{'real'} & \cr
\+ $.$       & \tt{.}           & \bf{step} & \tt{'step'} & \cr
\+ $_{10}$   & \tt{\#\ \ \ \ \ \ '\ \ \ \ \ \ \ \ '10'}
   & \bf{string}    & \tt{'string'} & \cr
\+ $:$       & \tt{:\ \ \ \ \ \ ..}
   & \bf{switch}    & \tt{'switch'} & \cr
\+ $;$       & \tt{;\ \ \ \ \ \ .,}
   & \bf{then}      & \tt{'then'} & \cr
\+ $:=$      & \tt{:=\ \ \ \ \ .=\ \ \ \ \ \ \ ..=}
   & \bf{true}      & \tt{'true'} & \cr
\+ $($       & \tt{(}           & \bf{until} & \tt{'until'} & \cr
\+ $)$       & \tt{)}           & \bf{value} & \tt{'value'} & \cr
\+ $[$       & \tt{[\ \ \ \ \ \ (/}
   & \bf{while}     & \tt{'while'} & \cr
}
$$
@end tex

In order to illustrate what the MACVT converter does, let us consider the
following @w{Algol 60} procedure, which is coded using old (classic)
representation:

@sp 1
@example
'PROCEDURE'EULER(FCT,SUM,EPS,TIM).,'VALUE'EPS,TIM.,
'INTEGER' TIM., 'REAL' 'PROCEDURE' FCT., 'REAL' SUM, EPS.,
'COMMENT' EULER COMPUTES THE SUM OF FCT (I) FOR I
 FROM ZERO UP TO INFINITY BY MEANS OF A SUITABLY
 REFINED EULER TRANSFORMATION. THE SUMMATION IS
 STOPPED AS SOON AS TIM TIMES IN SUCCESSION THE ABSOLUTE
 VALUE OF THE TERMS OF THE TRANSFORMED SERIES IS
 FOUND TO BE LESS THAN EPS, HENCE ONE SHOULD PROVIDE
 A FUNCTION FCT WITH ONE INTEGER ARGUMENT, AN UPPER
 BOUND EPS, AND AN INTEGER TIM. THE OUTPUT IS THE SUM SUM.
 EULER IS PARTICULARLY EFFICIENT IN THE CASE OF A SLOWLY
 CONVERGENT OR DIVERGENT ALTERNATING SERIES.,
 'BEGIN''INTEGER' I,K,N,T.,'ARRAY' M(/0..15/).,
 'REAL' MN, MP, DS.,
  I.=N.=T.=0.,M(/0/).=FCT(0).,SUM.=M(/0/)/2.,
  NEXTTERM..I.=I+1.,MN.=FCT(1).,
    'FOR' K.=0'STEP'1'UNTIL'N'DO'
         'BEGIN' MP.=(MN+M(/K/))/2.,M(/K/).=MN.,
            MN.=MP'END'MEANS.,
    'IF' (ABS(MN)'LESS' ABS (M(/N/))'AND'N'LESS'15)'THEN'
         'BEGIN'DS.=MN/2.,N.=N+1.,
            M(/N/).=MN'END' ACCEPT
         'ELSE' DS.=MN.,
          SUM.=SUM+DS.,
         'IF' ABS(DS)'LESS'EPS'THEN'T.=T+1'ELSE'T.=0.,
         'IF'T'LESS'TIM'THEN''GOTO'NEXTTERM
         'END'EULER;
@end example
@sp 1

We can convert this code to the MARST input language by means of the following
command:

@example
macvt -i -s euler.alg -o euler1.alg
@end example

The verbatim result of conversion is the following:

@sp 1
@example
procedure euler(fct,sum,eps,tim);value eps,tim;
integer tim; real procedure fct; real sum, eps;
comment EULER COMPUTES THE SUM OF FCT (I) FOR I
 FROM ZERO UP TO INFINITY BY MEANS OF A SUITABLY
 REFINED EULER TRANSFORMATION .THE SUMMATION IS
 STOPPED AS SOON AS TIM TIMES IN SUCCESSION THE ABSOLUTE
 VALUE OF THE TERMS OF THE TRANSFORMED SERIES IS
 FOUND TO BE LESS THAN EPS, HENCE ONE SHOULD PROVIDE
 A FUNCTION FCT WITH ONE INTEGER ARGUMENT, AN UPPER
 BOUND EPS, AND AN INTEGER TIM .THE OUTPUT IS THE SUM SUM
 .EULER IS PARTICULARLY EFFICIENT IN THE CASE OF A SLOWLY
 CONVERGENT OR DIVERGENT ALTERNATING SERIES;
 begin integer i,k,n,t;array m[0:15];
 real mn, mp, ds;
  i:=n:=t:=0;m[0]:=fct(0);sum:=m[0]/2;
  nextterm:i:=i+1;mn:=fct(1);
    for k:=0 step 1 until n do
         begin mp:=(mn+m[k])/2;m[k]:=mn;
            mn:=mp end means;
    if (abs(mn)< abs (m[n])&n<15)then
         begin ds:=mn/2;n:=n+1;
            m[n]:=mn end accept
         else ds:=mn;
          sum:=sum+ds;
         if abs(ds)<eps then t:=t+1 else t:=0;
         if t<tim then go to nextterm
         end euler;
@end example
@sp 1

@bye
