                                   L3P QUICK TUTORIAL
                                   -------------------

WELCOME to the L3P Tutorial

This is a quick tour which will show you some typical ways of operating with
the L3P programming environment. We advice you to print this file before
following instructions. Printing of MANUAL.TXT might also be helpful.


0) PRELIMINARIES

Be sure you are in the L3P directory, that is, the directory where you have
uncompressed L3P?????.ZIP shareware package (e.g. C:\LANG\L3P ).
In order to follow this tutorial you have to check the existence of just two
files: L3P.EXE and TUTORIAL.L3P.


1) HOW TO LOAD AN EXISTING FILE.

Let's start L3P, the Integrated Programming Environment. Type F3 and then
TUTORIAL, or type <enter> and choose TUTORIAL.L3P by moving the green
bar on this name (with the arrows) and then by giving <enter>.
You can get the same result writing the command:

     l3p tutorial

at the DOS prompt.

2) HOW TO COMPILE A WORK AND HOW TO GET THE GLOBAL ENTITIES LIST

What you can see is a <global-declaration-sequence> (see MANUAL.TXT).
Let us report it here for your convenience:

(*  Sample L3P-work to be used in connection with TUTORIAL.TXT *)

const NMAX=20
var A: ARRAY[1..NMAX] of numeric
    S: real

function fact(N)                          (* LISP-like,  untyped function *)
return if N=0 then 1 else N*fact(N-1) endif
end fact

procedure Polygon(N: integer; L: real)    (* LOGO-like, typed procedure *)
begin
  for N times do
    Left(360/N)
    Forwd(L)
  endfor
end Polygon

predic                                    (* L3P-PROLOG section *)
  sum(0,X,X).
  sum(s(X),Y,s(Z)):-sum(X,Y,Z).
  factlist([],[]).
  factlist([X|L],[FX|FL]):-factlist(L,FL),FX val fact(?X). (*INTEGRATION!*)
endpredic

 By compiling it (press F4) you will get the "Compilation SUCCESSFUL"
 message on the top line.
Now you have created some entities: i.e. constants, variables, arrays,
 functions, procedures and predicates. You can list them typing the shortcut
 <Alt-G> .
Remember: entities start to exist only after compilation.

3) HOW TO TEST A FUNCTION: THE EVALUATION ENVIRONMENT

Let us test the classical 'fact' function. For this purpose the best thing
 to do is entering the evaluation environment by the shortcut <Alt-v>.
This is a classical expression evaluation loop. Each expression is first
compiled and then evaluated:

? 1+1
= 2
? NMAX
= 20
? fact(5)
= 120
? fact(10)
= 3628800
? fact(13)
=

The last evaluation will rise a RUN-TIME ERROR message on the lower right
 corner. Integer representations are on 32 bits but you can work with real
 numbers by asking:

? fact(13.0)
= 6.227021E+09
? fact('a')
=
This evaluation will cause an 'Expected numeric operand' RUN-TIME ERROR.
If you wish, you can force a static type checking by redefining fact as:

function fact(N:numeric):numeric         (* LISP-like,  typed function *)

Let us look at more examples:

? "White" conc "House"
= WhiteHouse
? if TRUE then 1 else 2 endif
= 1
? if FALSE then 1 else 2 endif
= 2
? [1,2,3,4] & [3,4,5,6]
= [1,2,3,4,3,4,5,6]
? A.UppBnd(1)
= 20

The evaluation environment is side-effect-free, provided that functions used
 are side-effect-free.

4) HOW TO TEST STATEMENTS AND PROCEDURES: THE IMPERATIVE ENVIRONMENT

Someone might ask to produce a table of the factorials, say from 1 to 10.
 The easiest way to do it is moving to the IMPERATIVE ENVIRONMENT with the
<Alt-I> shortcut:

! for i from to N do write i,fact(i); nl endfor
 1 1
 2 2
 3 6
 4 24
...
 10 3628800

Now, you can also test the procedure Polygon. For instance, try:

! TurtleMode; Polygon(4,100)
! TurtleMode; TurtleDelay(100); for i from 1 to 10 do Polygon(i,100);
SetColor(i) endfor
! TurtleMode; for 360 times do Polygon(10,100); Left(1) endfor

You will probably interrupt the current computation. You can do it by
 <Ctrl-Break> -ing.

The imperative environment is also suitable for working on global arrays.
 Let us load a portion of array A with some values read from keyboard.

WARNING: each number has to be terminated by the enter key! This might seem
tedious but permits an immediate validation of last input data.

! for i from 1 to 10 do read A[i] endfor
 1 2.5 3 4.5 7 7.5 5 6.5 8 8.5
! for i from 1 to 10 do write A[i] endfor(* check *)
 1 2.5 3 4.5 7 7.5 5 6.5 8 8.5

Now, let us solve the problem "compute their mean value" :

! for i from 1 to 10 do S:=S+ A[i] endfor; write S/10

The above line will cause the following RUN-TIME ERROR:
"S" NOT INITIALIZED.
In fact, we forgot to set S:=0 before looping. Insert it helping yourself with
the editing keys:

! S:=0; for i from 1 to 10 do S:=S+ A[i] endfor; write S/10
5.35

Many common mistakes can be discovered by means of this L3P-feature.
Array elements are also initially undefined.
Moreover array index are always checked against bounds:

! write A[11]    (* will cause:  "A[11] NOT INITIALIZED" *)
! write A[21]    (* will cause: A[21] index out of bounds *)

Arrays can be dynamically resized. For instance, this command double-sizes
 array A:

! A.Dim(1,2*A.UppBnd(1)); write A.UppBnd(1)
40

5) HOW TO TEST PREDICATES: THE LOGIC ENVIRONMENT

As you can see, you are provided with two predicates: sum/3 and factlist/2.
You can test them moving to the LOGIC ENVIRONMENT with the shortcut <Alt-L>:

?- sum(0,0,s(0)).
 NO
?- sum(X,Y,s(s(0))).
 X = 0,  Y = s(s(0))
More ? (Y/N) Y
? X = s(0), Y = s(0)
More ? (Y/N) N

It looks much like an interpreted PROLOG environment. You can also assert or
retract clauses, listing, tracing, etc.:
Let us test the factlist/2 predicate:

?- factlist([4,6,10],A).
 A = [24,720,3628800]
More ? (Y/N) Y
 NO

You have reached the end of this preliminary Tutorial. You might want to
experiment many changes or add new declarations. You can leave the original
file TUTORIAL.L3P unmodified by the 'Save as' command (for instance you
might call MYTUTOR.L3P the new file).

You can exit L3P from almost any environment by typing <Alt-X>.

----------------------------------------------------------------------------
END of L3P Tutorial
