wip(n)								 Word Interpreter							    wip(n)

__________________________________________________________________________________________________________________________________________________

NAME

       wip - Word Interpreter

SYNOPSIS

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

_________________________________________________________________

DESCRIPTION

       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.

GENERAL BEHAVIOUR

       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 execu-
       tion 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  argu-
       ments 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.

CLASS API

       The main command of the package is:

       ::wip wipName engine arg...
	      The command creates a new word interpreter object with an associated global Tcl command whose name is wipName. If however the string
	      %AUTO% was used as object name the package will generate its own unique name for the object.

	      The engine is the object the word interpreter will dispatch all recognized commands to, and the arguments  are  a  word  list  which
	      defines an initial mapping from language words to engine methods.

	      The recognized language of this word list is

	      def name
		     Defines name as command of the language, to be mapped to a method of the engine having the same name.

	      def name method_prefix
		     Defines name as command of the language, to be mapped to the method of the engine named in the method_prefix.

       The returned command may be used to invoke various operations on the object.  It has the following general form:

	      wipName option ?arg arg ...?
		     Option and the args determine the exact behavior of the command.

       The package additionally exports the command:

       wip::dsl ?suffix?
	      This command is for use within snit types which wish to use one or more wip interpreters as a component. Use within the type defini-
	      tion installs most of the boilerplate needed to setup and use a word interpreter.

	      It installs a component named wip, and a method wip_setup for initializing it. This method has to be called  from  within  the  con-
	      structor	of  the type using the word interpreter.  If further installs a series of procedures which make the object API of the word
	      interpreter directly available to the type's methods, without having to specify the component.

	      Note that this does and cannot install the language to interpret, i.e. the mapping from words to engine methods.

	      It is possible to instantiate multiple word interpreter components within a type by using different suffices  as	arguments  to  the
	      command.	In that case the name of the component changes to 'wip_$suffix', the setup command becomes 'wip_$suffix_setup' and all the
	      procedures also get the suffix '_$suffix'.

OBJECT API

       The following commands are possible for word interpreter objects:

       wipName def name ?method_prefix?
	      Defines a language command name and maps it to the method named in the engine's method_prefix. If  the  method_prefix  name  is  not
	      specified it is simply the name of the language command.

       wipName defl names
	      Defines  a  series  of language commands, specified through the list of names, all of which are mapped to engine methods of the same
	      name.

       wipName defd dict
	      Defines a series of language commands, specified through the dictionary dict of names and method prefixes.

       wipName deflva name...
	      As method defl, however the list of names is specified through multiple arguments.

       wipName defdva (name method_prefix)...
	      As method defd, however the dictionary of names and method prefixes is specified through multiple arguments.

       wipName undefl names
	      Removes the named series of language commands from the mapping.

       wipName undefva name...
	      As method undefl, however the list of names is specified through multiple arguments.

       wipName unknown cmdprefix
	      Sets the handler for unknown words to cmdprefix. This command prefix takes one argument, the current word, and  either  throws  some
	      error, or returns the result of executing the word, as defined by the handler. The default handler simply throws an error.

       wipName runl wordlist
	      Treats  the list of words in wordlist as a program and executes the contained command one by one. The result of the command executed
	      last is returned as the result of this command.

	      The wordlist is stored in the object for access by the other run-methods, and the general program accessor methods  (see	below).  A
	      previously  stored  wordlist is saved during the execution of this method and restored before it returns. This enables the recursive
	      execution of word lists within word lists.

       wipName run word...
	      As method runl, however the list of words to execute is specified through multiple arguments.

       wipName run_next
	      Low-level method. Determines the next word in the list of words, and its arguments, and then executes it. The result of the executed
	      word is the result of this method.

	      Exposed  for  use  within  command  implementations.   The  methods  run	and  runl use it to execute words until their word list is
	      exhausted.

       wipName run_next_while acceptable
	      Low-level method. Invokes the method run_next as long as the next word is in the set of acceptable words, and  the  program  is  not
	      empty. The result of the command executed last is returned as the result of this command.

	      Exposed for use within command implementations to change the order of execution.

       wipName run_next_until rejected
	      Low-level method. Invokes the method run_next until the next word is in the set of rejected words, and the program is not empty. The
	      result of the command executed last is returned as the result of this command.

	      Exposed for use within command implementations to change the order of execution.

       wipName run_next_if acceptable
	      Low-level method. Invokes the method run_next if the next word is in the set of acceptable words, and the program is not empty.  The
	      result of the command executed last is returned as the result of this command.

	      Exposed for use within command implementations to change the order of execution.

       wipName run_next_ifnot rejected
	      Low-level  method.  Invokes  the method run_next if the next word is not in the set of rejected words, and the program is not empty.
	      The result of the command executed last is returned as the result of this command.

	      Exposed for use within command implementations to change the order of execution.

       wipName next
	      Returns the next word in the programm. The word is also removed.

       wipName peek
	      Returns the next word in the programm without removing it

       wipName peekall
	      Returns the remaining programm in toto.

       wipName insertl at wordlist
	      Basic programm accessor method. Inserts the specified wordlist into the program, just before the word at position at. Positions  are
	      counted from zero.

       wipName replacel wordlist
	      Basic programm accessor method. Replaces the whole stored program with the specified wordlist.

       wipName pushl wordlist
	      Program accessor method. The specified wordlist is added to the front of the remaining program. Equivalent to

	      $wip insertl 0 $wordlist

       wipName addl wordlist
	      Program accessor method. The specified wordlist is appended at the end of the remaining program. Equivalent to

	      $wip insertl end $wordlist

       wipName insert at word...
	      Like method insertl, except the words are specified through multiple arguments.

       wipName replace word...
	      Like method setl, except the words are specified through multiple arguments.

       wipName push word...
	      Like method pushl, except the words are specified through multiple arguments.

       wipName add word...
	      Like method addl, except the words are specified through multiple arguments.

EXAMPLES

       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 SF Trackers [http://sourceforge.net/tracker/?group_id=12883].  Please also report any ideas for enhancements you  may  have  for
       either package and/or documentation.

KEYWORDS

       interpreter, list, word

CATEGORY

       Programming tools

COPYRIGHT

       Copyright (c) 2007-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>

wip									2.2								    wip(n)