=head1 HISTORY

This was originally written as a perl5 script. Rather than doing bootstrapping,
I foolishly decided it would be fun to write the parser IN parrot assembly,
esp. as this would help implementing "eval" and "proc" (Of course, in
retrospect, I really wish I had kept with the bootstrapping effort, as I think
it would have generated usable results sooner.

=head1 OVERVIEW 

This is a from-scratch implementation, based primarily on the tcl man page(s),
and the cvs-current test suite for tcl.

Another interesting project would have been to modify the tcl source and 
have it generate parrot directly. Many people smarter than I am have
declared this I<hard>, so I'm rather happy I'm working on it this way.  
(Apparently Tcl's bytecode engine is very optimized for Tcl (big surprise).
So, converting the tcl-specific bytecodes there to parrot would be a big deal.)

=head1 RUNNING TCL

=head2 Generated Files

When you make tcl, you're generating several files:

=over 4

=item lib/tcllib.pbc

This file is used to load all the various commands, ops, etc. into
the appropriate namespaces, as well as declare and register the TCL
compiler for the C<compile> opcode.

This file is actually built in two steps. The first step uses C<tcl.pl>
to generate C<lib/tcllib.pir>, using C<tcl.pir_template> as a template.
The file is basically passed through unchanged, except for a few C<${ }>
-style substitutions. C<INCLUDES> make sure all the required C<.pir> files
are included properly. It adds a C<HEADER>, and removes any C<XXX> comments.

=item tcl.pbc

This is roughly equivalent to C<tclsh> - It takes the command line arguments
(currently, the name of the file you wish to parse), and reads in the file,
and uses the tcl library to parse those contents as tcl. You can also specify
command line options to be used with this bytecode file.

=back

=head2 Classes

The classes are not user-visible, but are internal helper classes designed
to simplify the parser/interpreter. They are written in PIR and are in
C<lib>. All the helper classes provide a C<compile> method, which can be
invoked by the top level compiler, or by a container class. For example, in
C<TclConst>, the compilation is a very straightforward register load, while
C<TclCommandList> compiles each of the C<TclCommand>s it contains, which in
turn compile their arguments, and their method name, and setup an invocation
of the PIR subroutine that corresponds to the tcl proc or builtin.

=over 4

=item TclCommand

A class representing a Tcl command made up of a name and arguments.

=item TclCommandList

A list of TclCommands used to represent a body of code. This returns the value
of the last command.

=item TclConst

A constant Tcl value created during parsing.

=item TclVar

A class representing Tcl variables.

=item TclWord

A TclWord handles the concatenation of arguments. For instance, given

  puts ab$c

the parser will generate a C<TclWord> containing an C<TclConst>==C<ab> 
and a C<TclVar>==C<c>. When compiled, a C<TclWord> compiles each of its
elements and concatenates the results.

=back

=head2 PMCS

The Tcl PMCs (Parrot Magic Cookies) are the user visible data types. These
live in the C<*.pmc> files in C<classes/>. They are compiled into a
dynamically loadable library which is loaded with the C<.HLL> directive
(HLL stands for High Level Language). Most of the functionality associated
with these PMCS is derived from the base parrot classes, except as noted below.

=over 4

=item TclString

Scalar string, with an override for the boolean truth values.

=item TclInt

Scalar integer, with an override for various math. (For example, parrot
Integers automatically promote to float division, while Tcl does not.)

=item TclFloat

Scalar float, with an override of the stringification: Tcl floats are
somewhat unusual compared to other parrot HLLs in that integer-valued floats
stringify with a trailing C<.0>.

=item TclList

Ordered container, corresponding to values generated by the C<[list]> builtin.
Overrides the default stringification provided by parrot Arrays.

=item TclArray

Hash like container, corresponding to values created with the C<[array]>
builtin.

=item TclObject

A virtual type, which is used to provide some shimmer (aka morph) methods
common to all the scalar value types.

=back

=head1 TESTS

To run the test suite, C<make test>. If you want to also get output from the
TODO tests, C<make devtest> instead. This is NOT the tcl test suite.
No failures are expected.

To run the tcl test suite, type "make tcl-test". This will checkout the latest
cvs copy of the tests from the tcl repository and run them. Warning:

=over 4

=item 1 Slow

There are a lot of tests, and we setup and breakdown an instance of
parrot for *each* test we try to run.

=item 2 Incomplete

We convert the tests to use Perl's TAP instead of running
them natively. The conversion process is flawed, and we don't claim to
implement 100% of Tcl yet anyway. Expect a low pass rate.

=back

=head1 EXAMPLES

There are examples in the C<examples> directory that are vaguely more
interesting. Change to that directory and type C<make> for directions.
