File: comterp.h

package info (click to toggle)
ivtools 1.2.11a2-4
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 13,364 kB
  • sloc: cpp: 174,988; ansic: 12,717; xml: 5,359; perl: 2,164; makefile: 831; sh: 326
file content (483 lines) | stat: -rw-r--r-- 17,925 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
/*
 * 
 * Copyright (c) 2001-2007 Scott E. Johnston
 * Copyright (c) 2000 IET Inc.
 * Copyright (c) 1994-1999 Vectaport Inc.
 *
 * Permission to use, copy, modify, distribute, and sell this software and
 * its documentation for any purpose is hereby granted without fee, provided
 * that the above copyright notice appear in all copies and that both that
 * copyright notice and this permission notice appear in supporting
 * documentation, and that the names of the copyright holders not be used in
 * advertising or publicity pertaining to distribution of the software
 * without specific, written prior permission.  The copyright holders make
 * no representations about the suitability of this software for any purpose.
 * It is provided "as is" without express or implied warranty.
 *
 * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
 * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
 * IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL,
 * INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 * 
 */

/*
 * ComTerp is a command interpreter derived from the Parser
 */

#if !defined(_comterp_h)
#define _comterp_h

// #define POSTEVAL_EXPERIMENT

#include <ComTerp/parser.h>

#include <OS/table.h>
declareTable(ComValueTable,int,void*)


class AttributeList;
class AttributeValue;
class AttributeValueList;
class ComFunc;
class ComFuncState;
class ComTerpState;
class ComValue;
#include <iosfwd>

class ComterpHandler;

//: extendable command interpreter.
// ComTerp is an extendable command interpreter with a simple C-like expression
// syntax and support for commands with fixed-location and keyword-prefixed 
// arguments.  The underlying architecture of this interpreter is patterned
// after Fischer and LeBlanc's "Crafting a Compiler with C", with their pipeline
// of scanner --> parser --> code_conversion --> code_generation retrofitted into 
// one of scanner --> parser --> code_conversion --> interpreter.
// <p>
// You use a ComTerp by first constructing one with a default set of commands
// and operators, then add any commands (derived ComFunc objects) needed for a
// particular application, then start it running on either stdin or 
// some alternate input file described by arguments to the constructor.
// To embed a ComTerp in another application you'll probably want to use
// a ComTerpServ, which has extensions to ComTerp for passing input and output
// strings from/to the interpreter by buffers.
class ComTerp : public Parser {
public:
    ComTerp();
    // construct with default set of ComFunc objects.
    ComTerp(const char* path);
    // construct and run on commands read from 'path'.
    ComTerp(void*, char*(*)(char*,int,void*), int(*)(void*), int(*)(void*));
    // construct with IO system based on a void* pointer and three function
    // pointers to receive that void* as their first argument, with
    // signatures that match fgets, feof, and ferror.
    ~ComTerp();

    void init();
    // initialize memory for the regular stack, the ComFuncState stack,
    // and the symbol tables.

    boolean read_expr();
    // read expression from the input, return true if all ok.
    boolean eof();
    // return true when end-of-file found on the input.
    void increment_linenum();
    // increment line number when empty line is read

    virtual int eval_expr(boolean nested=false);
    // evaluate topmost expression on the stack, with a flag to
    // indicate if this call to eval_expr() is nested inside
    // another, so that initialization doesn't get repeated.
    virtual int eval_expr(ComValue* pfvals, int npfvals);
    // evaluate postfix expression stored in ComValue objects.
    virtual int post_eval_expr(int tokcnt, int offtop, int pedepth 
#ifdef POSTEVAL_EXPERIMENT
			       , int nolookup=false
#endif
);
    // copy unevaluated expression to the stack and evaluate.
    void print_post_eval_expr(int tokcnt, int offtop, int pedepth);
    // print unevaluated expression
    postfix_token* copy_post_eval_expr(int tokcnt, int offtop);
    // copy unevaluated expression
    boolean top_expr();
    // return true if the topmost expression is currently being evaluated

    int print_stack_top() const;
    // print the top of the stack to stdout.
    int print_stack_top(ostream& out) const;
    // print the top of the stack to an ostream.
    int print_stack() const;
    // print the entire stack to stdout.
    int print_stack(std::ostream& out) const;
    // print the entire stack to stdout.
    int stack_height() { return _stack_top+1; }
    // return current height of the stack.
    boolean brief() const;
    // return brief mode flag.
    void brief(boolean flag) { _brief = flag; }
    // set brief mode flag.

    int add_command(const char* name, ComFunc*, const char* alias = nil, const char* docstring2 = nil);
    // add a derived ComFunc to be known by 'name'.
    void list_commands(ostream& out, boolean sorted = false);
    // print an optionally sorted list of commands to an ostream.
    int* get_commands(int &ncommands, boolean sorted = false);
    // return an optionally sorted list of command names.

    ComValue pop_stack(boolean lookupsym=true);
    // return a reference (on the stack) to what was the top of the stack,
    // if 'lookupsym' is false, don't look up ComValue objects in 
    // the local or global symbol table to replace a symbol, just
    // return the symbol itself.
    ComValue& lookup_symval(ComValue&);
    // look up a ComValue associated with a symbol (specified in the
    // input ComValue) in the local or global symbol tables.
    AttributeValue* lookup_symval(ComValue*);
    // look up a pointer to an AttributeValue associated with a symbol
    // (specified in the input ComValue) in the local or global symbol
    // tables.  Do not alter the input ComValue.
    ComValue& lookup_symval(int symid);
    // look up a ComValue associated with a symbol (specified with a
    // symbol id) in the local or global symbol tables.

    ComValue& stack_top(int n=0);
    // return reference to top of the stack, offset by 'n' (usually negative).
    ComValue& pop_symbol();
    // return a reference (on the stack) to what was the top of the stack,
    void push_stack(ComValue&);
    // copy the state of a ComValue onto the stack, incrementing the
    // reference count of any AttributeValueList, otherwise replicating data.
    void push_stack(AttributeValue&);
    // copy the state of an AttributeValue into a ComValue on the stack, 
    // incrementing the reference count of any AttributeValueList, 
    // otherwise replicating data.
    boolean stack_empty();

    ComValue& expr_top(int n=0);
    // top of currently evaluating expression buffer.

    static ComTerp& instance();
    // instance of ComTerp for global use.

    void quit(boolean quitflag=true);
    // set flag that will cause a quit to happen as soon as possible.
    void quitflag(boolean flag);
    // set flag that will cause a quit to happen as soon as possible.
    boolean quitflag();
    // return value of flag that will cause a quit to happen as soon as possible.
    virtual void exit(int status=0);
    // call _exit().

    virtual int run(boolean one_expr=false, boolean nested=false);
    // run interpreter until end-of-file or quit command, unless 
    // 'one_expr' is true.  Leave 'one_expr' false when using a ComTerpServ.
    // Return Value:  -1 if eof, 0 if normal operation, 1 if 
    // partial expression parsed, 2 if no result computed, 3 if error in parsing.  
    // 'nested' indicates contents of stack should be preserved.

    virtual int runfile(const char* filename, boolean popen_flag=0);
    // run interpreter on contents of 'filename'.
    void add_defaults();
    // add default commands (ComFunc objects).

    ComValueTable* localtable() const { return _localtable; }
    // local symbol table associated with an individual ComTerp.
    ComValueTable* globaltable() const 
      { if (!_globaltable) _globaltable = new ComValueTable(100); return _globaltable; }
    // global symbol table associated with every ComTerp.
    ComValue* localvalue(int symid);
    // value associated with a symbol id in the local symbol table.
    ComValue* globalvalue(int symid);
    // value associated with a symbol id in the global symbol table.
    ComValue* eithervalue(int symid, boolean globalfirst=false);
    // value associated with a symbol id in either symbol table.

    const char* errmsg() { return _errbuf; }
    // current error message buffer.

    void set_attributes(AttributeList*);
    // set AttributeList to be used as an additional local symbol table.
    AttributeList* get_attributes();
    // return pointer to AttributeList being used as an additional 
    // local symbol table.

    void handler(ComterpHandler* h );
    // set handler for invoking ComFunc execute methods.
    ComterpHandler* handler();
    // return pointer to handler that can read_expressions from
    // a connection and interpret them.

    void disable_prompt();
    // disable '>' prompting sent in response to an unfinished input expression.
    void enable_prompt();
    // enable '>' prompting sent in response to an unfinished input expression.

    unsigned int& pfnum() { return _pfnum; }
    // number of arguments in the input postfix buffer of a tokenized 
    // tree like expression ready to be evaluated, but not yet
    // converted to ComValue objects.

    virtual boolean is_serv() { return false; } 
    // flag to test if ComTerp or ComTerpServ

    void func_for_next_expr(ComFunc* func);
    // set ComFunc to use on subsequent expression
    ComFunc* func_for_next_expr();
    // get ComFunc to use on subsequent expression

    void val_for_next_func(ComValue& val);
    // set ComValue to pass to subequent command
    ComValue& val_for_next_func();
    // get ComValue to pass to subequent command
    void clr_val_for_next_func();
    // clear out ComValue to pass to subequent command

    unsigned int& linenum() { return _linenum; }
    // count of lines processed

    ComTerpState* top_servstate();
    // return pointer to top state on ComTerpServ state stack

    void push_servstate();
    // push ComTerpServ state for later retrieval

    void pop_servstate();
    // pop ComTerpServ state that was saved earlier

    void trace_mode(int mode) { _trace_mode = mode; }
    // set trace mode

    int trace_mode() { return _trace_mode; }
    // return trace mode

    int& npause() { return _npause; }
    // return (reference to) number of pauses

    int& stepflag() { return _stepflag; }
    // return flag that controls stepwise execution

    void echo_postfix(boolean flag) { _echo_postfix = flag; }
    // set flag that indicates whether to echo postfix or not

    boolean echo_postfix() const { return _echo_postfix; }
    // return flag that indicates whether to echo contents of postfix buffer

    void postfix_echo();
    // echo the postfix tokens
    void postfix_echo(postfix_token* pfbuf, int pfnum);
    // echo the postfix tokens

    void delim_func(boolean flag) { _delim_func = flag; }
    // set flag that indicates whether to run a delimiter-selected func.
 
    boolean delim_func() const { return _delim_func; }
    // return flag that indicates whether to run a delimiter-selected func.

    void ignore_commands(boolean flag) { _ignore_commands = flag; }
    // set flag that indicates whether to ignore all built-in commands
 
    boolean ignore_commands() const { return _ignore_commands; }
    // return flag that indicates whether to ignore all built-in commands

    void autostream(boolean flag) { _autostream = flag; }
    // set flag that indicates whether to run a delimiter-selected func.
 
    boolean autostream() const { return _autostream; }
    // return flag that indicates whether to run a delimiter-selected func.

    void running(boolean flag) { _running = flag; }
    // set flag that indicates whether to run a delimiter-selected func.
 
    boolean running() const { return _running; }
    // return flag that indicates whether to run a delimiter-selected func.

    void muted(boolean flag) { _muted = flag; }
    // set flag that indicates whether to mute output
 
    boolean muted() const { return _muted; }
    // return flag that indicates whether to mute output

    void force_nested(boolean flag) { _force_nested = flag; }
    // set flag to ensure subsequent calls are nested

    boolean force_nested() { return _force_nested; }
    // get flag to ensure subsequent calls are nested

    int arg_str(int n);
    // return nth command line argument

    int narg_str();
    // return number of command line argument

    void set_args(int argc, char** argv);
    // set command line arguments

    void set_args(const char* argstr);
    // set command line arguments

    void clear_top_commands(); 
    // clear list used to collect list of top-level commands

    AttributeValueList* top_commands() { return _top_commands; }
    // list of top-most commands for this derived interpreter


protected:
    void incr_stack();
    void incr_stack(int n);
    void decr_stack(int n=1);

    boolean skip_func(ComValue* topval, int& offset, int offlimit);
    boolean skip_key(ComValue* topval, int& offset, int offlimit, int& argcnt);
    boolean skip_arg(ComValue* topval, int& offset, int offlimit, int& argcnt);

    void push_stack(postfix_token*);
    void token_to_comvalue(postfix_token*, ComValue*);
    const ComValue* stack(unsigned int &top) const;
    void load_sub_expr();
    void load_postfix(postfix_token*, int toklen, int tokoff);
    void eval_expr_internals(int pedepth=0);

    ComFuncState* top_funcstate();
    // return top ComFuncState on stack
    virtual void push_funcstate(ComFuncState& funcstate);
    // push ComFuncState onto stack
    virtual void pop_funcstate();
    // pop ComFuncState off stack

    ComValue* _stack;  // stack of multi-value objects, central to the interpreter
    int _stack_top; // current top of stack, -1 indicates empty
    unsigned int _stack_siz; // current maximum stack size
    boolean _quitflag; // flag that can be set to terminate interpreter
    char* _errbuf; // buffer used for rendering error messages
    char* _errbuf2; // ancillary buffer for rendering error messages
    int _pfoff; // current offset in _pfbuf
    boolean _brief; // when used to produce ComValue output
    boolean _just_reset; // flag that gets set after call to ::reset_stack()
    boolean _defaults_added; // flag for base set of commands added 

    ComValueTable* _localtable; // per interpreter symbol table
    static ComValueTable* _globaltable; // interpreter shared symbol table
    AttributeList* _alist; // extends symbol tables with names in an AttributeList

    ComFuncState* _fsstack;  // stack of func-status (nargs/nkeys/...) 
    int _fsstack_top;
    unsigned int _fsstack_siz;

    ComTerpState* _ctsstack;  // stack of ComTerpServ state
    int _ctsstack_top;
    unsigned int _ctsstack_siz;

    ComValue* _pfcomvals; 
    // postfix buffer of ComValue's converted from postfix_token

    static ComTerp* _instance;
    // default instance of a ComTerp

    ComterpHandler* _handler;
    // I/O handler for this ComTerp.

    ComFunc* _func_for_next_expr;
    // ComFunc to run on next expression

    ComValue* _val_for_next_func;
    // ComValue to pass to next command

    int _trace_mode;
    // trace mode

    int _npause;
    // depth of pause

    int _stepflag;
    // true if single-stepping interpreter

    boolean _echo_postfix;
    // echos postfix tokens if true

    boolean _delim_func;
    // use delimiter-selected func, passing symbol in ::command_symid()

    boolean _ignore_commands;
    // ignore any built-in commands.

    boolean _autostream;
    // automatically iterates over stream if left on stack

    boolean _running;
    // flag to inform others this ComTerp in use

    boolean _muted;
    // flag to mute any response from a ComTerp

    boolean _force_nested;
    // flag to ensure subsequent calls are nested

    int _fd;
    // handle for I/O

    int* _arg_strs;
    // array of string ids for command line arguments

    int _narg_strs;
    // size of array of string ids for command line arguments

    AttributeValueList* _top_commands;
    // list of top-most commands for this derived comterp

    friend class ComFunc;
    friend class ComterpHandler;
    friend class ComTerpIOHandler;
};

//: object for holding ComTerp state
// object that holds the state of a ComTerp
// which allows for nested and recursive use of a singular ComTerp
class ComTerpState {
public:
  ComTerpState() {}
  ComTerpState(ComTerpState& ctss) { *this = ctss; }
  // copy constructor.

  postfix_token*& pfbuf() { return _pfbuf; }
  int& pfsiz() { return _pfsiz;; }
  int& pfnum() { return _pfnum; }  
  int& pfoff() { return _pfoff; }
  int& bufptr() { return _bufptr; }
  int& bufsiz() { return _bufsiz; }
  int& linenum() { return _linenum; }
  //  int& just_reset() { return _just_reset; }
  char*& buffer() { return _buffer; }
  ComValue*& pfcomvals() { return _pfcomvals; }
  infuncptr& infunc() { return _infunc; }
  eoffuncptr& eoffunc() { return _eoffunc; }
  errfuncptr& errfunc() { return _errfunc; }
  void*& inptr() { return _inptr; }
  AttributeList*& alist() { return _alist; }

protected:

  postfix_token* _pfbuf;
  int _pfsiz;
  int _pfnum;
  int _pfoff;
  int _bufptr;
  int _linenum;
  // int _just_reset;
  char* _buffer;
  int _bufsiz;
  ComValue* _pfcomvals;
  infuncptr _infunc;
  eoffuncptr _eoffunc;
  errfuncptr _errfunc;
  void* _inptr;
  AttributeList* _alist;

};

#endif /* !defined(_comterp_h) */