Tcl Library Source Code

Bounty program for improvements to Tcl and certain Tcl packages.

[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]


wip - Word Interpreter

Table Of Contents


package require Tcl 8.4
package require wip ?2.2?
package require snit ?1.3?
package require struct::set

::wip wipName engine arg...
def name
def name method_prefix
wipName option ?arg arg ...?
wip::dsl ?suffix?
wipName def name ?method_prefix?
wipName defl names
wipName defd dict
wipName deflva name...
wipName defdva (name method_prefix)...
wipName undefl names
wipName undefva name...
wipName unknown cmdprefix
wipName runl wordlist
wipName run word...
wipName run_next
wipName run_next_while acceptable
wipName run_next_until rejected
wipName run_next_if acceptable
wipName run_next_ifnot rejected
wipName next
wipName peek
wipName peekall
wipName insertl at wordlist
wipName replacel wordlist
wipName pushl wordlist
wipName addl wordlist
wipName insert at word...
wipName replace word...
wipName push word...
wipName add word...


This package provides a micro interpreter for lists of words. Domain specific languages based on this will have a bit of a Forth feel, with the input stream segmented into words and any other structuring left to whatever the language desired. Note that we have here in essence only the core dispatch loop, and no actual commands whatsoever, making this definitely only a Forth feel and not an actual Forth.

The idea is derived from Colin McCormack's treeql processor, modified to require less boiler plate within the command implementations, at the expense of, likely, execution speed. In addition the interface between processor core and commands is more complex too.


Word interpreters have a mappping from the names of the language commands they shall recognize to the methods in the engine to invoke for them, and possibly fixed arguments for these methods. This mapping is largely static, however it is possible to change it during the execution of a word list (= program).

At the time a language command is defined the word interpreter will use snit's introspection capabilities to determine the number of arguments expected by the method of the egnine, and together with the number of fixed arguments supplied in the method prefix of the mapping it then knows how many arguments the language command is expecting. This is the command's arity. Variable-argument methods (i.e. with the last argument named args) are not allowed and will cause the word interpreter to throw an error at definition time.

Note that while I said snit's abilities the engine object can be written in any way, as long as it understands the method info args, which takes a method name and returns the list of arguments for that method.

When executing a list of words (aka program) the first word is always taken as the name of a language command, and the next words as its arguments, per the arity of the command. Command and argument words are removed from the list and then associated method of the engine is executed with the argument words. The process then repeats using the then-first word of the list.

Note that the methods implementing the language commands may have full access to the list of words and are allowed to manipulate as they see fit.

  1. This means, for example, that while we cannot specify variable-argument methods directly they can consume words after their fixed arguments before returning to the execution loop. This may be under the control of their fixed arguments.

  2. Another possibility is the use of method run_next and its variants to execute commands coming after the current command, changing the order of execution.

  3. Execution can be further changed by use of the program accessor methods which allow a command implementation to modify the remaining list of words (insert, replace, prepend, append words) without executing them immediately.

  4. At last the basic run methods save and restore an existing list of words when used, enabling recursive use from within command implementations.


The main command of the package is:

The package additionally exports the command:


The following commands are possible for word interpreter objects:


No examples yet.

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category wip of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.


interpreter, list, word


Programming tools


Copyright © 2007-2010 Andreas Kupries