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

speed

We're currently a bit 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.

TODO

Clean up the TODO formatting, esp. the "given" sections, and come up with a list of any other missing features that aren't listed there.

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, RETRUN, 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.