wip - Word Interpreter

       This document, and the package it describes, will undoubtedly contain bugs and  other  problems.   Please
       report  such  in  the category wip of the TcllibTrackers [http://core.tcl.tk/tcllib/reportlist].  Please
       also report any ideas for enhancements you may have for either package and/or documentation.

       When proposing code changes, please provide unifieddiffs, 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.

       Programming tools

       The main command of the package is:

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

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

              defnamemethod_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:

              wipNameoption ?argarg...?
                     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 definition 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 constructor 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'.

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

tcllib                                                 2.3                                             wip(3tcl)

       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.

       No examples yet.

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

       interpreter, list, word

       wip - Word Interpreter

       The following commands are possible for word interpreter objects:

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

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

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

       wipNamedeflvaname...
              As method defl, however the list of names is specified through multiple arguments.

       wipNamedefdva (namemethod_prefix)...
              As method defd, however the dictionary of names and method prefixes is specified through  multiple
              arguments.

       wipNameundeflnames
              Removes the named series of language commands from the mapping.

       wipNameundefvaname...
              As method undefl, however the list of names is specified through multiple arguments.

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

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

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

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

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

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

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

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

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

       wipNamepeek
              Returns the next word in the programm without removing it

       wipNamepeekall
              Returns the remaining programm in toto.

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

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

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

              $wip insertl 0 $wordlist

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

              $wip insertl end $wordlist

       wipNameinsertatword...
              Like method insertl, except the words are specified through multiple arguments.

       wipNamereplaceword...
              Like method setl, except the words are specified through multiple arguments.

       wipNamepushword...
              Like method pushl, except the words are specified through multiple arguments.

       wipNameaddword...
              Like method addl, except the words are specified through multiple arguments.

       package require Tcl8.59

       package require wip?2.3?

       package require snit?1.4?

       package require struct::set::wipwipNameenginearg...

       defnamedefnamemethod_prefixwipNameoption ?argarg...?

       wip::dsl ?suffix?

       wipNamedefname ?method_prefix?

       wipNamedeflnameswipNamedefddictwipNamedeflvaname...

       wipNamedefdva (namemethod_prefix)...

       wipNameundeflnameswipNameundefvaname...

       wipNameunknowncmdprefixwipNamerunlwordlistwipNamerunword...

       wipNamerun_nextwipNamerun_next_whileacceptablewipNamerun_next_untilrejectedwipNamerun_next_ifacceptablewipNamerun_next_ifnotrejectedwipNamenextwipNamepeekwipNamepeekallwipNameinsertlatwordlistwipNamereplacelwordlistwipNamepushlwordlistwipNameaddlwordlistwipNameinsertatword...

       wipNamereplaceword...

       wipNamepushword...

       wipNameaddword...

________________________________________________________________________________________________________________