1. Manuals
  2. Tumbleweed
  3. tcllib
  4. wip(n)

Scroll to navigation

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








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

  







  

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

  

  
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:





  

  
Option and the args determine the exact behavior of the
      command.






The package additionally exports the command:



  

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

  








OBJECT API


The following commands are possible for word interpreter
  objects:



  

  
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.

  

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

  

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

  

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

  

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

  

  
Removes the named series of language commands from the mapping.

  

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

  

  
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.

  

  
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.

  

  

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

  

  
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.

  

  

  
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.

  

  

  
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.

  

  

  
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.

  

  

  
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.

  

  

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

  

  
Returns the next word in the programm without removing it

  

  
Returns the remaining programm in toto.

  

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

  

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

  

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

  






$wip insertl 0 $wordlist





  

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

  






$wip insertl end $wordlist





  

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

  

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

  

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

  

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






KEYWORDS


interpreter, list, word






CATEGORY


Programming tools






COPYRIGHT


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








  

    2.2
    tcllib