/ 
parrot-0.3.0
/ languages::tcl::docs::howto

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 some things that require support from parrot before we can continue, like [info nameofexecutable]. In general, though, a lot of what we need to do is possible with parrot.

If you're looking for something to todo, check one of: TODO tests in t/; RT https://rt.perl.org/rt3/NoAuth/parrot/List.html?Field=Lang&Value=tcl or by their absence: every actual builtin at http://www.tcl.tk/man/tcl8.5/TclCmd/contents.htm should have a corresponding file in lib/commands/

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. Only exceptions to this should be subs which correspond directly to Tcl builtins -- those are already documented elsewhere.

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.

If the return value would be TCL_OK, then simply .return the value from the sub. For any other return type, use one of the macros in lib/returncodes.pir: .throw, etc. the value can be any simple register or a PMC, the calling conventions will autobox as necessary.

Before adding new functionality, add a test (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.

Our final goal will be to pass (most of) the tcl test suite: run make tcl-test to checkout the latest version of of the tcl test suite and run it. Warning: slow...

Long term goal is remove any tests in t/ that are testing things that are already tested in the official tcl suite. Partcl's checked in test suite should just be checking partcl-specific functionaliity.