=head1 OVERVIEW 

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

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 runtime/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 several steps. First, all the templated commands
(src/builtin/*.tmt) are converted to PIR. Next, runtime/builtins.pir is
generated from all the pir files in src/builtin/ and runtime/builtin. This file
is then included by tcllib.pir and compiled to tcllib.pbc.

=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.

=item src/grammar/expr/pge2past.pir

=item src/grammar/expr/past2pir.pir

=item src/grammar/expr/expression.pir

This C<PIR> files are generated from their corresponding C<.tg> and C<.pg>
files. These grammar files allow us to use PGE's implementation of perl6
rules to more simply specify our parsing rules. We use these rules to handle
both the general parsing for tcl itself, as well as the sub-"language"
used by expressions in [expr] and elsewhere.

=back

=head2 PMCS

The Tcl PMCs (Parrot Magic Cookies) are the user visible data types. These
live in the C<*.pmc> files in F<src/pmc/>. 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 TclDict

Hash like container, corresponding to values created with the C<[dict]>
builtin. Unlike arrays, dictionaries can nest, having dictionaries as
values; Also, dictionaries act more like TclLists in terms of their
conversion to string and back.

=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.
Occasional failures are suspected against svn-head; there should be no
failures in a released version, however.

To run the tcl test suite, type C<make tcl-test>. This will checkout the latest
cvs copy of the tests from the tcl repository and run them.  Warning, this can
be a little slow.

=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.

=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" 

partcl has gone through many iterations since its original beginnings,
requiring many updates as various parts of parrot have changed, and as we
implement features which require extensions to our framework.

=cut
