<p>
<h1>Hello, World!</h1>
<p>
In time honoured tradition, this tutorial begins with "Hello, World!".
Here it is, taken from the file <tt>hello_world.m</tt> :
<p>
<center><table border=1 width=90%><tr><td><pre>

:- module hello_world.

:- interface.

:- import_module io.

:- pred main(io__state, io__state).
:- mode main(di, uo) is det.

:- implementation.

main -->
        io__write_string("Hello, World!\n").
</pre></tr></table></center>
<p>
It's obvious what's going to happen when we compile and run this
program.  First, a word of warning.  There are a number of weird and
wonderful things going on here, most of which you can safely ignore
for now.  If something seems cryptic, don't worry, it will all be
explained later on.  Let's take a look at the finer detail.
<p>
First off, the file begins with the line
<p><center><table border=1 width=90%><tr><td><pre>

:- module hello_world.
</pre></tr></table></center><p>
Lines beginning with a "<tt>:-</tt>" are all <em>declarations</em> of one kind or
another.  This line declares the contents of this file to be the
<em>module</em> called <tt>hello_world</tt>.  The current implementation of the
<em>mmc</em> compiler expects modules to be defined in files of the same name.
<p>
Observe that most lines end with a full stop.  The full stop is used to
indicate when a particular declaration or definition finishes.
<p>
The next line is
<p><center><table border=1 width=90%><tr><td><pre>

:- interface.
</pre></tr></table></center><p>
This says that any names declared in what follows, up to the
<p><center><table border=1 width=90%><tr><td><pre>

:- implementation.</pre></tr></table></center><p> declaration (see below), are <em>visible</em> to
other modules that use or import this module.  The module is said to
<em>export</em> these names.
<p>
It is good practice to export the bare minimum of names from a module.
In other words, if users of a module does not need to know a
particular name, then it should be declared in the implementation
section rather than the interface.
<p>
This module uses names defined in the <tt>io</tt> library module.  This is
what the declaration
<p><center><table border=1 width=90%><tr><td><pre>

:- use_module io.
</pre></tr></table></center><p>
means.  All the names declared in the interface section of the <tt>io</tt>
module therefore become visible in the <tt>hello_world</tt> module.
<p>
The fourth line looks pretty complicated, but is really quite
straightforward.
<p><center><table border=1 width=90%><tr><td><pre>

:- pred main(io__state, io__state).
</pre></tr></table></center><p>
This is a declaration that this module defines a <em>predicate</em> called
<tt>main</tt> that takes two arguments.  Each argument is of type
<tt>io__state</tt>.  The prefix "<tt>io__</tt>" says that the type in question is
defined in the <tt>io</tt> module.  In other words, the arguments take the
type called <tt>state</tt> as defined in the <tt>io</tt> module.  The token
"<tt>__</tt>" is used to connect module names to names defined within a
particular module.
<p>
<em>Note:</em> the predicate defined here will often be referred to using the
shorthand <tt>main/2</tt>, referring to its name and number of arguments
(its <em>arity</em>).  If you're unfamiliar with the term, just think of a
predicate as a procedure or function, some of whose arguments are
inputs, and some of which are outputs.
<p>
The fifth line looks even stranger than the fourth.
<p><center><table border=1 width=90%><tr><td><pre>

:- mode main(di, uo) is det.
</pre></tr></table></center><p>
This says that the first of <tt>main/2</tt>'s arguments is an
input argument that must be a unique reference which will be
destroyed by the call: "<tt>di</tt>" for <em>destructive input</em>.  It also
specifies that the second is an output argument which will be a unique
reference: "<tt>uo</tt>" for <em>unique output</em>.  Finally, "<tt>is det</tt>" says
that the predicate is deterministic.  Don't be too concerned about
what these terms mean for now -- all will become clear soon enough.
<p>
Then comes the declaration that what follows is all implementation.
<p><center><table border=1 width=90%><tr><td><pre>

:- implementation.
</pre></tr></table></center><p>
New names introduced in the implementation section will not be visible
to any modules importing <tt>hello_world</tt>.  However, it happens that we
don't introduce anything new in this example (indeed, we don't even
intend anyone to import this module).
<p>
The last two lines define the predicate itself.
<p><center><table border=1 width=90%><tr><td><pre>

main -->
        io__write_string("Hello, World!\n").
</pre></tr></table></center><p>
<p>
So, the <tt>main</tt> predicate calls the <tt>write_string/1</tt> predicate,
defined in the <tt>io</tt> library, with the string argument
<tt>"Hello, World!\n"</tt> (the last pair of characters, "<tt>\n</tt>", denote
the new-line character, as per C).
<p>
But wait!  What happened to our promise to the compiler that <tt>main</tt>
took <em>two</em> arguments -- this one doesn't appear to take <em>any</em>.
<p>
What has happened is that we've defined our predicate using a bit of
syntactic sugar.  Predicates defined using the "<tt>--></tt>" arrow are
using <em>DCG</em> notation.  Essentially, this has the effect of threading
an extra pair of arguments throughout the code behind the scenes.  We
could have defined <tt>main</tt> as
<p><center><table border=1 width=90%><tr><td><pre>

main(IO0, IO) :-
        io__write_string("Hello, World!\n", IO0, IO).
</pre></tr></table></center><p>
and the compiler would have been none the wiser.  It just happens that
<tt>io__state</tt>s have to be threaded through all calls to the <tt>io</tt>
library and that putting them in by hand tends to clutter things up
unnecessarily.  Using "<tt>:-</tt>" rather than "<tt>--></tt>" just means that
extra arguments <em>don't</em> get threaded through the code.
<p>
Now, <tt>IO0</tt> and <tt>IO</tt> are said to be <em>logical variables</em> (you can
detect <em>Mercury</em>'s theory heritage here).  Logical variables are
like names in mathematics: you can bind them to some meaning once, but
you can't change that binding afterwards.  Put another way, you can't
change what a logical variable is bound to after you've bound it to
something.  This is quite different to variables in imperative
languages such as C.  Think mathematically and you'll be fine!
<p>
Logical variables in <em>Mercury</em> always start with a capital letter
(all other names, such as type and predicate names, begin with a
lower case letter or some punctuation symbol).  Henceforth, we'll
simply use the term "<em>variable</em>" and omit the "<em>logical</em>".
<p>
Since the first argument <tt>IO0</tt> is an input argument, this will be
bound to some value when <tt>main</tt> is called.  <tt>io__write_string/3</tt>
takes this argument in turn and destroys it in the process of printing
the string and returns a new, unique <tt>io__state</tt>.  This output gets
bound to <tt>IO</tt> which is "returned" by <tt>main</tt>.  You can check that
all this matches up by looking at the declaration for
<tt>io__write_string/3</tt> in the <tt>io</tt> library interface.
<p>
Enough of all this.  Let's build this thing and start it up:
<p><center><table border=1 width=90%><tr><td><pre>

$ mmake hello_world.depend
--generate-dependencies    hello_world
$ mmake hello_world
rm -f hello_world.c
mmc --compile-to-c --grade asm_fast.gc hello_world.m > hello_world.err 2>&1
mgnuc --grade asm_fast.gc -c hello_world.c -o hello_world.o
c2init --grade asm_fast.gc hello_world.c > hello_world_init.c
mgnuc --grade asm_fast.gc -c hello_world_init.c -o hello_world_init.o
ml --grade asm_fast.gc -o hello_world hello_world_init.o hello_world.o    
$ ./hello_world
Hello, World!
</pre></tr></table></center><p>
Success!  For now, just be aware the <em>mmake</em> is a neat wrapper around
the compiler that hides all sorts of grotty detail from us.  The build
occurs in two stages: first, we tell <em>mmake</em> to find all the module
dependencies for <tt>hello_world</tt>, such as the <tt>io</tt> library module;
secondly we tell <em>mmake</em> to actually build it.  One last thing -- just
as with C, the top-level module of a program has to export a predicate
<tt>main/2</tt> exactly like the one in this example.
<p>
Hopefully you're not feeling anything worse than a mild sense of
bemusement.  Fear not, from now on it's all down hill!
<p>