1wip(n) Word Interpreter wip(n)
2______________________________________________________________________________
6
8 wip - Word Interpreter
9
11 package require Tcl 8.4
12 package require wip ?2.2?
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 unknown cmdprefix
44 wipName runl wordlist
46 wipName run word...
48 wipName run_next
50 wipName run_next_while acceptable
52 wipName run_next_until rejected
54 wipName run_next_if acceptable
56 wipName run_next_ifnot rejected
58 wipName next
60 wipName peek
62 wipName peekall
64 wipName insertl at wordlist
66 wipName replacel wordlist
68 wipName pushl wordlist
70 wipName addl wordlist
72 wipName insert at word...
74 wipName replace word...
76 wipName push word...
78 wipName add word...
80______________________________________________________________________________
82
84 This package provides a micro interpreter for lists of words. Domain
85 specific languages based on this will have a bit of a Forth feel, with
86 the input stream segmented into words and any other structuring left to
87 whatever the language desired. Note that we have here in essence only
88 the core dispatch loop, and no actual commands whatsoever, making this
89 definitely only a Forth feel and not an actual Forth.
90 The idea is derived from Colin McCormack's treeql processor, modified
92 to require less boiler plate within the command implementations, at the
93 expense of, likely, execution speed. In addition the interface between
94 processor core and commands is more complex too.
95
97 Word interpreters have a mappping from the names of the language com‐
98 mands they shall recognize to the methods in the engine to invoke for
99 them, and possibly fixed arguments for these methods. This mapping is
100 largely static, however it is possible to change it during the execu‐
101 tion of a word list (= program).
102 At the time a language command is defined the word interpreter will use
104 snit's introspection capabilities to determine the number of arguments
105 expected by the method of the egnine, and together with the number of
106 fixed arguments supplied in the method prefix of the mapping it then
107 knows how many arguments the language command is expecting. This is the
108 command's arity. Variable-argument methods (i.e. with the last argument
109 named args) are not allowed and will cause the word interpreter to
110 throw an error at definition time.
111 Note that while I said snit's abilities the engine object can be writ‐
113 ten in any way, as long as it understands the method info args, which
114 takes a method name and returns the list of arguments for that method.
115 When executing a list of words (aka program) the first word is always
117 taken as the name of a language command, and the next words as its
118 arguments, per the arity of the command. Command and argument words are
119 removed from the list and then associated method of the engine is exe‐
120 cuted with the argument words. The process then repeats using the then-
121 first word of the list.
122 Note that the methods implementing the language commands may have full
124 access to the list of words and are allowed to manipulate as they see
125 fit.
126 [1] This means, for example, that while we cannot specify variable-
128 argument methods directly they can consume words after their
129 fixed arguments before returning to the execution loop. This may
130 be under the control of their fixed arguments.
131 [2] Another possibility is the use of method run_next and its vari‐
133 ants to execute commands coming after the current command,
134 changing the order of execution.
135 [3] Execution can be further changed by use of the program accessor
137 methods which allow a command implementation to modify the
138 remaining list of words (insert, replace, prepend, append words)
139 without executing them immediately.
140 [4] At last the basic run methods save and restore an existing list
142 of words when used, enabling recursive use from within command
143 implementations.
144
146 The main command of the package is:
147 ::wip wipName engine arg...
149 The command creates a new word interpreter object with an asso‐
150 ciated global Tcl command whose name is wipName. If however the
151 string %AUTO% was used as object name the package will generate
152 its own unique name for the object.
153 The engine is the object the word interpreter will dispatch all
155 recognized commands to, and the arguments are a word list which
156 defines an initial mapping from language words to engine meth‐
157 ods.
158 The recognized language of this word list is
160 def name
162 Defines name as command of the language, to be mapped to
163 a method of the engine having the same name.
164 def name method_prefix
166 Defines name as command of the language, to be mapped to
167 the method of the engine named in the method_prefix.
168 The returned command may be used to invoke various operations on the
170 object. It has the following general form:
171 wipName option ?arg arg ...?
173 Option and the args determine the exact behavior of the
174 command.
175 The package additionally exports the command:
177 wip::dsl ?suffix?
179 This command is for use within snit types which wish to use one
180 or more wip interpreters as a component. Use within the type
181 definition installs most of the boilerplate needed to setup and
182 use a word interpreter.
183 It installs a component named wip, and a method wip_setup for
185 initializing it. This method has to be called from within the
186 constructor of the type using the word interpreter. If further
187 installs a series of procedures which make the object API of the
188 word interpreter directly available to the type's methods, with‐
189 out having to specify the component.
190 Note that this does and cannot install the language to inter‐
192 pret, i.e. the mapping from words to engine methods.
193 It is possible to instantiate multiple word interpreter compo‐
195 nents within a type by using different suffices as arguments to
196 the command. In that case the name of the component changes to
197 ´wip_$suffix', the setup command becomes ´wip_$suffix_setup' and
198 all the procedures also get the suffix ´_$suffix'.
199
201 The following commands are possible for word interpreter objects:
202 wipName def name ?method_prefix?
204 Defines a language command name and maps it to the method named
205 in the engine's method_prefix. If the method_prefix name is not
206 specified it is simply the name of the language command.
207 wipName defl names
209 Defines a series of language commands, specified through the
210 list of names, all of which are mapped to engine methods of the
211 same name.
212 wipName defd dict
214 Defines a series of language commands, specified through the
215 dictionary dict of names and method prefixes.
216 wipName deflva name...
218 As method defl, however the list of names is specified through
219 multiple arguments.
220 wipName defdva (name method_prefix)...
222 As method defd, however the dictionary of names and method pre‐
223 fixes is specified through multiple arguments.
224 wipName undefl names
226 Removes the named series of language commands from the mapping.
227 wipName undefva name...
229 As method undefl, however the list of names is specified through
230 multiple arguments.
231 wipName unknown cmdprefix
233 Sets the handler for unknown words to cmdprefix. This command
234 prefix takes one argument, the current word, and either throws
235 some error, or returns the result of executing the word, as
236 defined by the handler. The default handler simply throws an
237 error.
238 wipName runl wordlist
240 Treats the list of words in wordlist as a program and executes
241 the contained command one by one. The result of the command exe‐
242 cuted last is returned as the result of this command.
243 The wordlist is stored in the object for access by the other
245 run-methods, and the general program accessor methods (see
246 below). A previously stored wordlist is saved during the execu‐
247 tion of this method and restored before it returns. This enables
248 the recursive execution of word lists within word lists.
249 wipName run word...
251 As method runl, however the list of words to execute is speci‐
252 fied through multiple arguments.
253 wipName run_next
255 Low-level method. Determines the next word in the list of words,
256 and its arguments, and then executes it. The result of the exe‐
257 cuted word is the result of this method.
258 Exposed for use within command implementations. The methods run
260 and runl use it to execute words until their word list is
261 exhausted.
262 wipName run_next_while acceptable
264 Low-level method. Invokes the method run_next as long as the
265 next word is in the set of acceptable words, and the program is
266 not empty. The result of the command executed last is returned
267 as the result of this command.
268 Exposed for use within command implementations to change the
270 order of execution.
271 wipName run_next_until rejected
273 Low-level method. Invokes the method run_next until the next
274 word is in the set of rejected words, and the program is not
275 empty. The result of the command executed last is returned as
276 the result of this command.
277 Exposed for use within command implementations to change the
279 order of execution.
280 wipName run_next_if acceptable
282 Low-level method. Invokes the method run_next if the next word
283 is in the set of acceptable words, and the program is not empty.
284 The result of the command executed last is returned as the
285 result of this command.
286 Exposed for use within command implementations to change the
288 order of execution.
289 wipName run_next_ifnot rejected
291 Low-level method. Invokes the method run_next if the next word
292 is not in the set of rejected words, and the program is not
293 empty. The result of the command executed last is returned as
294 the result of this command.
295 Exposed for use within command implementations to change the
297 order of execution.
298 wipName next
300 Returns the next word in the programm. The word is also removed.
301 wipName peek
303 Returns the next word in the programm without removing it
304 wipName peekall
306 Returns the remaining programm in toto.
307 wipName insertl at wordlist
309 Basic programm accessor method. Inserts the specified wordlist
310 into the program, just before the word at position at. Positions
311 are counted from zero.
312 wipName replacel wordlist
314 Basic programm accessor method. Replaces the whole stored pro‐
315 gram with the specified wordlist.
316 wipName pushl wordlist
318 Program accessor method. The specified wordlist is added to the
319 front of the remaining program. Equivalent to
320 $wip insertl 0 $wordlist
323 wipName addl wordlist
325 Program accessor method. The specified wordlist is appended at
326 the end of the remaining program. Equivalent to
327 $wip insertl end $wordlist
330 wipName insert at word...
332 Like method insertl, except the words are specified through mul‐
333 tiple arguments.
334 wipName replace word...
336 Like method setl, except the words are specified through multi‐
337 ple arguments.
338 wipName push word...
340 Like method pushl, except the words are specified through multi‐
341 ple arguments.
342 wipName add word...
344 Like method addl, except the words are specified through multi‐
345 ple arguments.
346
348 No examples yet.
349
351 This document, and the package it describes, will undoubtedly contain
352 bugs and other problems. Please report such in the category wip of the
353 Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also
354 report any ideas for enhancements you may have for either package
355 and/or documentation.
356 When proposing code changes, please provide unified diffs, i.e the out‐
358 put of diff -u.
359 Note further that attachments are strongly preferred over inlined
361 patches. Attachments can be made by going to the Edit form of the
362 ticket immediately after its creation, and then using the left-most
363 button in the secondary navigation bar.
364
366 interpreter, list, word
367
369 Programming tools
370
372 Copyright (c) 2007-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>
373tcllib 2.2 wip(n)