1wip(n) Word Interpreter wip(n)
2______________________________________________________________________________
6
8 wip - Word Interpreter
9
11 package require Tcl 8.4
12 package require wip ?2.1.1?
14 package require snit ?1.3?
16 package require struct::set
18 ::wip wipName engine arg...
20 def name
22 def name method_prefix
24 wipName option ?arg arg ...?
26 wip::dsl ?suffix?
28 wipName def name ?method_prefix?
30 wipName defl names
32 wipName defd dict
34 wipName deflva name...
36 wipName defdva (name method_prefix)...
38 wipName undefl names
40 wipName undefva name...
42 wipName runl wordlist
44 wipName run word...
46 wipName run_next
48 wipName run_next_while acceptable
50 wipName run_next_until rejected
52 wipName next
54 wipName peek
56 wipName peekall
58 wipName insertl at wordlist
60 wipName replacel wordlist
62 wipName pushl wordlist
64 wipName addl wordlist
66 wipName insert at word...
68 wipName replace word...
70 wipName push word...
72 wipName add word...
74_________________________________________________________________
76
78 This package provides a micro interpreter for lists of words. Domain
79 specific languages based on this will have a bit of a Forth feel, with
80 the input stream segmented into words and any other structuring left to
81 whatever the language desired. Note that we have here in essence only
82 the core dispatch loop, and no actual commands whatsoever, making this
83 definitely only a Forth feel and not an actual Forth.
84 The idea is derived from Colin McCormack's treeql processor, modified
86 to require less boiler plate within the command implementations, at the
87 expense of, likely, execution speed. In addition the interface between
88 processor core and commands is more complex too.
89
91 Word interpreters have a mappping from the names of the language com‐
92 mands they shall recognize to the methods in the engine to invoke for
93 them, and possibly fixed arguments for these methods. This mapping is
94 largely static, however it is possible to change it during the execu‐
95 tion of a word list (= program).
96 At the time a language command is defined the word interpreter will use
98 snit's introspection capabilities to determine the number of arguments
99 expected by the method of the egnine, and together with the number of
100 fixed arguments supplied in the method prefix of the mapping it then
101 knows how many arguments the language command is expecting. This is the
102 command's arity. Variable-argument methods (i.e. with the last argument
103 named args) are not allowed and will cause the word interpreter to
104 throw an error at definition time.
105 Note that while I said snit's abilities the engine object can be writ‐
107 ten in any way, as long as it understands the method info args, which
108 takes a method name and returns the list of arguments for that method.
109 When executing a list of words (aka program) the first word is always
111 taken as the name of a language command, and the next words as its
112 arguments, per the arity of the command. Command and argument words are
113 removed from the list and then associated method of the engine is exe‐
114 cuted with the argument words. The process then repeats using the then-
115 first word of the list.
116 Note that the methods implementing the language commands may have full
118 access to the list of words and are allowed to manipulate as they see
119 fit.
120 [1] This means, for example, that while we cannot specify variable-
122 argument methods directly they can consume words after their
123 fixed arguments before returning to the execution loop. This may
124 be under the control of their fixed arguments.
125 [2] Another possibility is the use of method run_next and its vari‐
127 ants to execute commands coming after the current command,
128 changing the order of execution.
129 [3] Execution can be further changed by use of the program accessor
131 methods which allow a command implementation to modify the
132 remaining list of words (insert, replace, prepend, append words)
133 without executing them immediately.
134 [4] At last the basic run methods save and restore an existing list
136 of words when used, enabling recursive use from within command
137 implementations.
138
140 The main command of the package is:
141 ::wip wipName engine arg...
143 The command creates a new word interpreter object with an asso‐
144 ciated global Tcl command whose name is wipName. If however the
145 string %AUTO% was used as object name the package will generate
146 its own unique name for the object.
147 The engine is the object the word interpreter will dispatch all
149 recognized commands to, and the arguments are a word list which
150 defines an initial mapping from language words to engine meth‐
151 ods.
152 The recognized language of this word list is
154 def name
156 Defines name as command of the language, to be mapped to
157 a method of the engine having the same name.
158 def name method_prefix
160 Defines name as command of the language, to be mapped to
161 the method of the engine named in the method_prefix.
162 The returned command may be used to invoke various operations on the
164 object. It has the following general form:
165 wipName option ?arg arg ...?
167 Option and the args determine the exact behavior of the
168 command.
169 The package additionally exports the command:
171 wip::dsl ?suffix?
173 This command is for use within snit types which wish to use one
174 or more wip interpreters as a component. Use within the type
175 definition installs most of the boilerplate needed to setup and
176 use a word interpreter.
177 It installs a component named wip, and a method wip_setup for
179 initializing it. This method has to be called from within the
180 constructor of the type using the word interpreter. If further
181 installs a series of procedures which make the object API of the
182 word interpreter directly available to the type's methods, with‐
183 out having to specify the component.
184 Note that this does and cannot install the language to inter‐
186 pret, i.e. the mapping from words to engine methods.
187 It is possible to instantiate multiple word interpreter compo‐
189 nents within a type by using different suffices as arguments to
190 the command. In that case the name of the component changes to
191 ´wip_$suffix', the setup command becomes ´wip_$suffix_setup' and
192 all the procedures also get the suffix ´_$suffix'.
193
195 The following commands are possible for word interpreter objects:
196 wipName def name ?method_prefix?
198 Defines a language command name and maps it to the method named
199 in the engine's method_prefix. If the method_prefix name is not
200 specified it is simply the name of the language command.
201 wipName defl names
203 Defines a series of language commands, specified through the
204 list of names, all of which are mapped to engine methods of the
205 same name.
206 wipName defd dict
208 Defines a series of language commands, specified through the
209 dictionary dict of names and method prefixes.
210 wipName deflva name...
212 As method defl, however the list of names is specified through
213 multiple arguments.
214 wipName defdva (name method_prefix)...
216 As method defd, however the dictionary of names and method pre‐
217 fixes is specified through multiple arguments.
218 wipName undefl names
220 Removes the named series of language commands from the mapping.
221 wipName undefva name...
223 As method undefl, however the list of names is specified through
224 multiple arguments.
225 wipName runl wordlist
227 Treats the list of words in wordlist as a program and executes
228 the contained command one by one. The result of the command exe‐
229 cuted last is returned as the result of this command.
230 The wordlist is stored in the object for access by the other
232 run-methods, and the general program accessor methods (see
233 below). A previously stored wordlist is saved during the execu‐
234 tion of this method and restored before it returns. This enables
235 the recursive execution of word lists within word lists.
236 wipName run word...
238 As method runl, however the list of words to execute is speci‐
239 fied through multiple arguments.
240 wipName run_next
242 Low-level method. Determines the next word in the list of words,
243 and its arguments, and then executes it. The result of the exe‐
244 cuted word is the result of this method.
245 Exposed for use within command implementations. The methods run
247 and runl use it to execute words until their word list is
248 exhausted.
249 wipName run_next_while acceptable
251 Low-level method. Invokes the method run_next as long as the
252 next word is in the set of acceptable words. The result of the
253 command executed last is returned as the result of this command.
254 Exposed for use within command implementations to change the
256 order of execution.
257 wipName run_next_until rejected
259 Low-level method. Invokes the method run_next until the next
260 word is in the set of rejected words. The result of the command
261 executed last is returned as the result of this command.
262 Exposed for use within command implementations to change the
264 order of execution.
265 wipName next
267 Returns the next word in the programm. The word is also removed.
268 wipName peek
270 Returns the next word in the programm without removing it
271 wipName peekall
273 Returns the remaining programm in toto.
274 wipName insertl at wordlist
276 Basic programm accessor method. Inserts the specified wordlist
277 into the program, just before the word at position at. Positions
278 are counted from zero.
279 wipName replacel wordlist
281 Basic programm accessor method. Replaces the whole stored pro‐
282 gram with the specified wordlist.
283 wipName pushl wordlist
285 Program accessor method. The specified wordlist is added to the
286 front of the remaining program. Equivalent to
287 $wip insertl 0 $wordlist
289 wipName addl wordlist
291 Program accessor method. The specified wordlist is appended at
292 the end of the remaining program. Equivalent to
293 $wip insertl end $wordlist
295 wipName insert at word...
297 Like method insertl, except the words are specified through mul‐
298 tiple arguments.
299 wipName replace word...
301 Like method setl, except the words are specified through multi‐
302 ple arguments.
303 wipName push word...
305 Like method pushl, except the words are specified through multi‐
306 ple arguments.
307 wipName add word...
309 Like method addl, except the words are specified through multi‐
310 ple arguments.
311
313 No examples yet.
314
316 This document, and the package it describes, will undoubtedly contain
317 bugs and other problems. Please report such in the category wip of the
318 Tcllib SF Trackers [http://sourceforge.net/tracker/?group_id=12883].
319 Please also report any ideas for enhancements you may have for either
320 package and/or documentation.
321
323 interpreter, list, word
324
326 Copyright (c) 2007-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net>
327wip 2.1.1 wip(n)