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.2?
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 unknown cmdprefix
44
45       wipName runl wordlist
46
47       wipName run word...
48
49       wipName run_next
50
51       wipName run_next_while acceptable
52
53       wipName run_next_until rejected
54
55       wipName run_next_if acceptable
56
57       wipName run_next_ifnot rejected
58
59       wipName next
60
61       wipName peek
62
63       wipName peekall
64
65       wipName insertl at wordlist
66
67       wipName replacel wordlist
68
69       wipName pushl wordlist
70
71       wipName addl wordlist
72
73       wipName insert at word...
74
75       wipName replace word...
76
77       wipName push word...
78
79       wipName add word...
80
81______________________________________________________________________________
82

DESCRIPTION

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

GENERAL BEHAVIOUR

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
103       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
112       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
116       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
123       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
127       [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
132       [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
136       [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
141       [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

CLASS API

146       The main command of the package is:
147
148       ::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
154              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
159              The recognized language of this word list is
160
161              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
165              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
169       The  returned  command  may be used to invoke various operations on the
170       object.  It has the following general form:
171
172              wipName option ?arg arg ...?
173                     Option and the args determine the exact behavior  of  the
174                     command.
175
176       The package additionally exports the command:
177
178       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
184              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
191              Note  that  this  does and cannot install the language to inter‐
192              pret, i.e. the mapping from words to engine methods.
193
194              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

OBJECT API

201       The following commands are possible for word interpreter objects:
202
203       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
208       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
213       wipName defd dict
214              Defines a series of language  commands,  specified  through  the
215              dictionary dict of names and method prefixes.
216
217       wipName deflva name...
218              As  method  defl, however the list of names is specified through
219              multiple arguments.
220
221       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
225       wipName undefl names
226              Removes the named series of language commands from the mapping.
227
228       wipName undefva name...
229              As method undefl, however the list of names is specified through
230              multiple arguments.
231
232       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
239       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
244              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
250       wipName run word...
251              As method runl, however the list of words to execute  is  speci‐
252              fied through multiple arguments.
253
254       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
259              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
263       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
269              Exposed for use within command  implementations  to  change  the
270              order of execution.
271
272       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
278              Exposed for use within command  implementations  to  change  the
279              order of execution.
280
281       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
287              Exposed for use within command  implementations  to  change  the
288              order of execution.
289
290       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
296              Exposed for use within command  implementations  to  change  the
297              order of execution.
298
299       wipName next
300              Returns the next word in the programm. The word is also removed.
301
302       wipName peek
303              Returns the next word in the programm without removing it
304
305       wipName peekall
306              Returns the remaining programm in toto.
307
308       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
313       wipName replacel wordlist
314              Basic  programm  accessor method. Replaces the whole stored pro‐
315              gram with the specified wordlist.
316
317       wipName pushl wordlist
318              Program accessor method. The specified wordlist is added to  the
319              front of the remaining program. Equivalent to
320
321
322              $wip insertl 0 $wordlist
323
324       wipName addl wordlist
325              Program  accessor  method. The specified wordlist is appended at
326              the end of the remaining program. Equivalent to
327
328
329              $wip insertl end $wordlist
330
331       wipName insert at word...
332              Like method insertl, except the words are specified through mul‐
333              tiple arguments.
334
335       wipName replace word...
336              Like  method setl, except the words are specified through multi‐
337              ple arguments.
338
339       wipName push word...
340              Like method pushl, except the words are specified through multi‐
341              ple arguments.
342
343       wipName add word...
344              Like  method addl, except the words are specified through multi‐
345              ple arguments.
346

EXAMPLES

348       No examples yet.
349

BUGS, IDEAS, FEEDBACK

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
357       When proposing code changes, please provide unified diffs, i.e the out‐
358       put of diff -u.
359
360       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

KEYWORDS

366       interpreter, list, word
367

CATEGORY

369       Programming tools
370
372       Copyright (c) 2007-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>
373
374
375
376
377tcllib                                2.2                               wip(n)
Impressum