[Commit] nickle/doc/tutorial/tour tour.sgml,NONE,1.1

[Bart Massey]

Committed by: bart

Update of /local/src/CVS/nickle/doc/tutorial/tour
In directory home.keithp.com:/tmp/cvs-serv15809/doc/tutorial/tour

Added Files:
	tour.sgml 
Log Message:
docbook version of Nickle tutorial



--- NEW FILE: tour.sgml ---
<sect1><title>Nickle Tour</title>
<para>
<screen>
$ nickle
</screen>
Arithmetic works as expected, with a rich set of operators.
<screen>
> 1+1
2
> 2 ** (2+2)
16
> 5!
120
</screen>
Rationals are represented exactly, but printed in decimal.
Math is done with infinite precision.
Notice that integer division (//) is different from rational division (/).
Nickle provides some conveniences, such as <literal>.</literal> denoting the last value printed.
<screen>
> 1/3
0.{3}
> . * 3
1
> 1 // 3
0
</screen>
Variables can be declared implicitly at the top level, as well as explicitly with type.
The results of statements are not printed; terminating an expression with a semicolon makes it a simple statement.
C-like control structures may also be used at the top level; the <literal>+</literal> prompt indicates an incomplete line to be continued.
<screen><![CDATA[
> x = .
0
> int y = x;
> ++y;
> for(int i=0; i<25; ++i)
+   x+=0;
> x
0
> for(int i=1; i<9; i+=2)
+   x+=i;
> x
16
]]></screen>
When performing square roots, Nickle will stay exact when possible.
If the result is irrational, however, it will be stored as an inexact real.
Imprecision is contagious; if a rational operator combines an imprecise variable with a precise one, the result will be imprecise.
<screen>
> sqrt(x)
4
> sqrt(2)
1.414213562373095
> .**2
2
> sqrt(5)
2.236067977499789
> .**2
4.999999999999999
> ./5
0.999999999999999
</screen>
Functions can also be typed at the top level.
Since functions, as most things, are first-class in Nickle, they may be declared and assigned as below.
<screen>
> real foo(real x,real y) {
+   return x*y;
+ }
> foo(2,3)
6
> foo(4,2)
8
> real(real,real) bar = foo;
> bar(4,2)
8
> 
</screen>
Nickle is gauranteed never to dump core; it has a simple yet powerful exception system it uses to handle all errors.
An unhandled exception leads to the debugger, which uses a <literal>-</literal> prompt.
The debugger can be used to trace the stack, move up and down on it, and check values of variables.
<screen>
> (-1) ** (1/2) 
Unhandled exception "invalid_argument" at /u/p186/share/nickle/math.5c:13
        "sqrt of negative number"
        0
        -1
- trace
    raise invalid_argument ("sqrt of negative number", 0, v);
sqrt (-1)
    result = sqrt (a);
pow (-1, (1/2))
    -1 ** (1 / 2)
- done
> quit
$
</screen>
Large chunks of code can be placed in a seperate text file and loaded when needed.
The <literal>print</literal> command can be used to inspect variables, functions, namespaces, and other names.
<literal>import</literal> brings the names in a namespace into scope.
The <literal>::</literal> operator can be used to view those names without importing them.
(These can also be used with several namespaces built in to Nickle, such as Math and File.)
<screen>
$ nickle
> load "cribbage.5c"
> print Cribbage
namespace Cribbage {
    public void handprint (int[*] hand);
    public int scorehand (int[*] hand);
}
> print Cribbage::handprint
public void handprint (int[*] hand)
{
    printf ("hand { ");
    for (int i = 0; i < dim (hand); ++i)
        switch (hand[i]) {
        case 1:
            printf ("A ");
            break;
        case 11:
            printf ("J ");
            break;
        case 12:
            printf ("Q ");
            break;
        case 13:
            printf ("K ");
            break;
        default:
            printf ("%d ", hand[i]);
        }
    printf ("} ");
}
> import Cribbage;
> int[5] hand = { 7, 8, 12, 10, 5 };
> handprint(hand); printf(" has %d points.\n", scorehand(hand));
hand { 7 8 Q 10 5 }  has 6 points.
> quit
$ 
</screen>
</para>
</sect1>