1wip(n)                         Word Interpreter                         wip(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       wip - Word Interpreter
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require wip  ?2.1.1?
14
15       package require snit  ?1.3?
16
17       package require struct::set
18
19       ::wip wipName engine arg...
20
21       def name
22
23       def name method_prefix
24
25       wipName option ?arg arg ...?
26
27       wip::dsl ?suffix?
28
29       wipName def name ?method_prefix?
30
31       wipName defl names
32
33       wipName defd dict
34
35       wipName deflva name...
36
37       wipName defdva (name method_prefix)...
38
39       wipName undefl names
40
41       wipName undefva name...
42
43       wipName runl wordlist
44
45       wipName run word...
46
47       wipName run_next
48
49       wipName run_next_while acceptable
50
51       wipName run_next_until rejected
52
53       wipName next
54
55       wipName peek
56
57       wipName peekall
58
59       wipName insertl at wordlist
60
61       wipName replacel wordlist
62
63       wipName pushl wordlist
64
65       wipName addl wordlist
66
67       wipName insert at word...
68
69       wipName replace word...
70
71       wipName push word...
72
73       wipName add word...
74
75_________________________________________________________________
76

DESCRIPTION

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

GENERAL BEHAVIOUR

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
97       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
106       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
110       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
117       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
121       [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
126       [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
130       [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
135       [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

CLASS API

140       The main command of the package is:
141
142       ::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
148              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
153              The recognized language of this word list is
154
155              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
159              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
163       The  returned  command  may be used to invoke various operations on the
164       object.  It has the following general form:
165
166              wipName option ?arg arg ...?
167                     Option and the args determine the exact behavior  of  the
168                     command.
169
170       The package additionally exports the command:
171
172       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
178              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
185              Note  that  this  does and cannot install the language to inter‐
186              pret, i.e. the mapping from words to engine methods.
187
188              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

OBJECT API

195       The following commands are possible for word interpreter objects:
196
197       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
202       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
207       wipName defd dict
208              Defines a series of language  commands,  specified  through  the
209              dictionary dict of names and method prefixes.
210
211       wipName deflva name...
212              As  method  defl, however the list of names is specified through
213              multiple arguments.
214
215       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
219       wipName undefl names
220              Removes the named series of language commands from the mapping.
221
222       wipName undefva name...
223              As method undefl, however the list of names is specified through
224              multiple arguments.
225
226       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
231              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
237       wipName run word...
238              As method runl, however the list of words to execute  is  speci‐
239              fied through multiple arguments.
240
241       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
246              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
250       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
255              Exposed  for  use  within  command implementations to change the
256              order of execution.
257
258       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
263              Exposed for use within command  implementations  to  change  the
264              order of execution.
265
266       wipName next
267              Returns the next word in the programm. The word is also removed.
268
269       wipName peek
270              Returns the next word in the programm without removing it
271
272       wipName peekall
273              Returns the remaining programm in toto.
274
275       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
280       wipName replacel wordlist
281              Basic  programm  accessor method. Replaces the whole stored pro‐
282              gram with the specified wordlist.
283
284       wipName pushl wordlist
285              Program accessor method. The specified wordlist is added to  the
286              front of the remaining program. Equivalent to
287
288              $wip insertl 0 $wordlist
289
290       wipName addl wordlist
291              Program  accessor  method. The specified wordlist is appended at
292              the end of the remaining program. Equivalent to
293
294              $wip insertl end $wordlist
295
296       wipName insert at word...
297              Like method insertl, except the words are specified through mul‐
298              tiple arguments.
299
300       wipName replace word...
301              Like  method setl, except the words are specified through multi‐
302              ple arguments.
303
304       wipName push word...
305              Like method pushl, except the words are specified through multi‐
306              ple arguments.
307
308       wipName add word...
309              Like  method addl, except the words are specified through multi‐
310              ple arguments.
311

EXAMPLES

313       No examples yet.
314

BUGS, IDEAS, FEEDBACK

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

KEYWORDS

323       interpreter, list, word
324
326       Copyright (c) 2007-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net>
327
328
329
330
331wip                                  2.1.1                              wip(n)
Impressum