contributing to tcl/parrot

a brief overview on how to help out, if you're interested. In general, it's ok to send patches for tcl to the RT system for anything that isn't "BIG STUFF" - those, please bounce off me first. I'd prefer diff -u patches, but am happy to take complete files as well.

Most of this is mentioned in the TODO - in fact, this document probably should merge with the TODO to avoid redundancy.

BIG STUFF

interperter -> compiler

Right now, partcl is an interpreter. The parser generates an AST of sorts, which the interpreter then walks through the ast, finds the command to execute, (e.g., Tcl::puts), gets the values for each of the args (Evaluation is deferred until just before the function is called.)

To switch to a compiler, we need to basically use the same interpreter loop, but generate it specifically for the series of commands being invoked. Once we have the PIR, we can then compile it, and return that anonymous PIR sub. Then, instead of calling "interpret", we can just invoke that sub.

Some optimizations we can do:

TclWord (which we call to get the PMC for the various arguments), has an "is_const" method - If we look up the value and it's constant, we can hardcode it right into the PIR. Same goes for the commands.

A non-tcl option we can provide is a command line option to just dump the generated PIR/bytecode. (e.g. tclsh -o foo.pir or tclsh -o foo.pbc)

One algorithm to cache the builtins - keep a global counter (in some places, called epoch) - every time [rename] is called, epoch is bumped up and we have to re-fetch the method. But, if it hasn't changed, we're allowed to cheat. And if we can cheat on something like puts foo, we can translate that *in place* to a simple print "foo\n" and not have to go through all the overhead.

speed

We're currently quite slow, compared to tclsh. Switching over to a compiler instead of an interpreter might help here, though I'm having a hard time envisioning a compiler that doesn't have to do all the things we already do as an interpreter.

We could rewrite parse/interpret/compile in C, either as an NCI or behind a PMC object - this would possibly give us an improvement in speed also.

features

We're currently missing a lot of stuff that requires support from parrot before we can continue, like Unicode for the \u escapes. I've tried to start documenting these in the TODO with sections like given Unicode, then listing the things that we can do once we have that.

DOCUMENTATION

pod

Every PIR .sub that's defined should probably have some POD to go along with it to document the arguments and return values.

big picture docs.

Are the docs in docs/ useful? Could use someone to proof them, and verify that there are no missing chunks (if missing, write them, or get them added to the TODO), and that they are coherent.

PIR

Missing Commands

Every builtin command corresponds to a file with an appropriately named sub in lib/commands - Each of these subs takes some number of PMCs as arguments. For those commands that take a fixed number of parameters, we declare them with .param. For those that take a variable number, we use the foldup opcode.

Note that there are two return values for each command, an int and a PMC. The integer contains the Tcl return value for that command (OK, BREAK, RETURN, etc.). The PMC is usually a string at this point, but could be any valid PMC. Note - right now, if there's an error condition, create a new string-like PMC and put the error condition in it. Eventually this will be some kind of structure.

Once you write a command (or add a subcommand), you need to add a test file ( or a test in an existing) file in t/ - tests for puts, for example, go in t/cmd_puts.t - we use the Test::Harness framework, via Parrot::Test. To run your test, just say make test in the top level tcl directory. Be sure to test each of the subcommands. While our eventual goal is to pass the tcl test suite, we really need to maintain a good one on our own in the meantime.

To find a command to work on, just check out the TODO - several commands are currently not implemented, and others are missing various subcommands.