iinterpreter

The Engine Internals: BASIC Interpreter

This module has become fairly large and will probably be split into multiple modules in the future.

Enumerations

:::C
enum {
    // commands
    KW_QUIT = 1001, KW_EXIT,
    KW_LOAD, KW_SAVE, KW_EDIT, KW_NEW,
    KW_RUN, KW_STOP, KW_END,
    KW_PRINT, KW_WHY, KW_LOCATE, 
    KW_INPUT, KW_OPEN, KW_CLOSE,
    KW_READ, KW_DATA, KW_RESTORE,
    KW_IF, KW_UNLESS, KW_THEN, KW_ELSE, KW_ENDIF,
    KW_WHILE, KW_WEND, KW_REPEAT, KW_UNTIL,
    KW_FOR, KW_TO, KW_DOWNTO, KW_STEP, KW_NEXT,
    KW_SWITCH, KW_CASE, KW_DEFAULT, KW_ENDSWITCH,
    KW_GOTO, KW_GOSUB, KW_RETURN, KW_LABEL,
    KW_ON, KW_ERROR, KW_OFF,
    KW_EVERY,
    KW_LET,
    KW_RANDOMIZE, KW_TIMER,
    // functions
    KW_VAL = 1101, KW_ASC, KW_RND,
    KW_STR, KW_LEFT, KW_RIGHT, KW_MID,
    KW_HEX, KW_OCT, KW_BIN, KW_DEC,
    KW_TI, KW_TIME, KW_DATE,
    // operators
    KW_COLON = 1201, KW_SEMICOLON, KW_LPAREN, KW_RPAREN, KW_STAR, 
    KW_AT, KW_LBRACKET, KW_RBRACKET, KW_LBRACE, KW_RBRACE,
    KW_DOT, KW_EQ, KW_NE, KW_LE, KW_GE, KW_LT, KW_GT, 
    KW_QUERY, KW_COMMA, KW_COLUMN, KW_SLASH, KW_AMP,
    KW_SPACE, KW_BKSLASH, KW_CARET, KW_TILDE, KW_MINUS, KW_PLUS, 
    KW_PLING, KW_HASH, KW_DOLLAR, KW_BACKTICK,
    // textual operators
    KW_SHL, KW_SHR, KW_AND, KW_OR, KW_XOR, KW_NOT, KW_MOD
};

This enumeration specifies various token IDs. In The Engine's BASIC, everything is a token ID. A string of tokens consists of a series of token IDs (int), terminated by 0.

User-defined tokens begin at ID 2001, and are counted by the varCode variable.

:::C
typedef enum _vartype_t {
    VT_FLOAT,
    VT_STRING,
    VT_COMMENT,
    VT_FLOAT_ARRAY,
    VT_STRING_ARRAY
} vartype_t;

This specifies the type for variables. Note that a VT_FLOAT variable can be a label.

:::C
typedef enum _labmode_t {   // label mode
    LM_NONE,            // not a label or unset/unused
    LM_CMDLINE,         // a temporary (command line) label
    LM_PROGRAM          // a program label
} labmode_t;

This specifies the label mode for a variable.

:::C
typedef enum _istokres_t {
    ISTOK_SPACE,
    ISTOK_KEYWORD,
    ISTOK_VARIABLE,
    ISTOK_JUMP_CMD,
    ISTOK_JUMP_TGT,
    ISTOK_NUMBER,
    ISTOK_STRING,
    ISTOK_COMMENT,
    ISTOK_SEPARATOR,
    ISTOK_OPERATOR,
    ISTOK_UNKNOWN,
    ISTOK_END
} istokres_t;

This specifies the syntax highlighting code for syntax highlighting (token type analysis).

:::C
enum {
    // error codes
    EC_OK,
    EC_INTERR,
    EC_SYNERR,
    EC_DIVZERO,
    EC_SUBERR,
    EC_RETERR,
    EC_MAX
};

Error codes used by the report() function.

Data Structures

:::C
typedef struct _kwent_t {
    int code; const char* name;
} kwent_t;

Keyword entry data structure, used in keyword table.

:::C
#define VHTF_NAME   1   // registered in varByName hash
#define VHTF_CODE   2   // registered in varByCode hash
#define VHTF_VALD   4   // registered in varByValD hash
#define VHTF_VALS   8   // registered in varByValS hash
#define VHTF_VALC   16  // registered in varByValC hash

typedef struct _var_t {
    node_t      node;
    char*       name;
    int         code;   // token code
    int         rcnt;   // reference counter
    int         hash;   // hash table flags
    size_t      asiz;   // array size (or 0 for none)
    void*       labl;   // label line (for LM_PROGRAM)
    const int*  labp;   // label position (if label)
    labmode_t   labm;   // label mode (or LM_NONE)
    vartype_t   type;
    union {
        double      val_f;
        char*       val_s;
        double*     val_af;
        char**      val_as;
    };
} var_t;

Data structure for variables.

:::C
// identify label record
typedef struct _ilrec_t {
    int     start;  // start position of token in color data
    int     end;    // end   position of token in color data
    int     type;   // token type
} ilrec_t;

Used by syntax highlighting.

:::C
typedef struct _intp_callarg_t {
    node_t      node;
    vartype_t   type;   // VT_FLOAT, VT_STRING
    union {
        double      val_f;
        char*       val_s;
    };
} intp_callarg_t;

Used while evaluating function calls.

:::C
typedef struct _intp_numfunc_t {
    int         kw;     // keyword
    const char* title;  // title
    const char* format; // argument format
    void        (*func)( intp_callarg_t**, int, double* );
} intp_numfunc_t;

typedef struct _intp_strfunc_t {
    int         kw;     // keyword
    const char* title;  // title
    const char* format; // argument format
    void        (*func)( intp_callarg_t**, int, char** );
} intp_strfunc_t;

Used for function tables.

:::C
typedef struct _intp_stmtfunc_t {
    int         kw;     // keyword
    const char* title;  // title
    bool        (*func)( const int** );
} intp_stmtfunc_t;

Used for statement tables.

:::C
typedef struct _err_t {
    node_t      node;
    int         code;
    char*       text;
} err_t;

Error stack item data structure, used by WHY and WHY$.

:::C
typedef struct _intp_locrec_t {
    node_t      node;
    void*       line;   // editline_t* -- program line
    const int*  tok;    // token address within program line
} intp_locrec_t;

Location record used to record a program position. If line is 0, a position in the currently executed direct mode command is specified.

:::C
typedef struct _intp_forrec_t {
    intp_locrec_t   lr;     // location record for loop body
    var_t*          v;      // loop variable
    double          from;   // "from" value
    double          to;     // "to"   value
    double          step;   // "step" value
} intp_forrec_t;

Record for FOR loops (currently unused).

External Functions

:::C
void setCommand( const char* newcmd );

Set a command to be executed by the interpreter in direct mode. Used by the ENTER key handler to send the text line under the cursor in the output window to the interpreter.

:::C
void startInterpreter( void );

Launch interpreter thread. Thread will automatically be stopped when the program exit(3)'s (facilitated by atexit(3) handler).

:::C
void colorizeLine( const char* line, istokres_t out[256], int* outn );

Colorize line (returns token identification information).

:::C
void requestHalt( void );

Request that the currently executed user program be halted.

Internal Functions

to be documented