/* 

 *   Copyright (c) 1998, 2002 Michael J. Roberts.  All Rights Reserved.

 *   

 *   Please see the accompanying license file, LICENSE.TXT, for information

 *   on using and copying this software.  

 */

/*

Name

  vmtype.h - VM types

Function

Notes

Modified

  10/21/98 MJRoberts  - Creation

*/

#ifndef VMTYPE_H

#define VMTYPE_H

#include <string.h>

#include <stdlib.h>

#include "t3std.h"

#include "vmerr.h"

#include "vmerrnum.h"

#include "vmglob.h"

/*

 *   Constant pool/code offset.  This is an address of an object in the

 *   pool.  Pool offsets are 32-bit values.  

 */

typedef uint32 pool_ofs_t;

/*

 *   Savepoint ID's are stored in a single byte; since we store many

 *   copies of savepoint ID's (since they need to be stored with each undo

 *   list head), we want to save some space on this type.  This limits us

 *   to 256 simultaneous savepoints, but this should be more than we

 *   actually want to keep around anyway, because of the amount of memory

 *   it would consume to try to keep more than that around.  

 */

typedef uchar vm_savept_t;

const vm_savept_t VM_SAVEPT_MAX = 255;

/* 

 *   Object ID type.  VM_INVALID_OBJ is a distinguished value that serves

 *   as an invalid object ID (a null pointer, effectively); no object can

 *   ever have this ID.  

 */

typedef uint32 vm_obj_id_t;

const vm_obj_id_t VM_INVALID_OBJ = 0;

/*

 *   Property ID.  Property ID's are 16-bit values.  VM_INVALID_PROP is a

 *   distinguished value that serves as an invalid property ID, which can

 *   be used to indicate the absence of a property value.  

 */

typedef uint16 vm_prop_id_t;

const vm_prop_id_t VM_INVALID_PROP = 0;

/*

 *   Maximum recursion depth for recursive equality tests and hash

 *   calculations.

 *   

 *   When we're comparing or hashing a tree of references by value, such as

 *   when we're comparing two vectors or hashing a vector, we'll keep track

 *   of the recursion depth of our tree traversal.  If we reach this depth,

 *   we'll throw an error on the assumption that the tree contains cycles and

 *   thus cannot be hashed or compared by value.  This depth is chosen to be

 *   large enough that it's unlikely we'll exceed it with acyclical trees,

 *   but small enough that we probably won't blow the C++ stack before we

 *   reach this depth.  

 */

const int VM_MAX_TREE_DEPTH_EQ = 256;

/*

 *   Datatypes

 */

enum vm_datatype_t

{

    /* nil - doubles as a null pointer and a boolean false */

    VM_NIL = 1,

    /* true - boolean true */

    VM_TRUE,

    /* 

     *   Stack pointer (this is used to store a pointer to the enclosing

     *   frame in a stack frame).  This is a native machine pointer.  

     */

    VM_STACK,

    /* 

     *   Code pointer (this is used to store a pointer to the return

     *   address in a stack frame, for example).  This is a native machine

     *   pointer.  This differs from VM_CODEOFS in that this is a native

     *   machine pointer.  

     */

    VM_CODEPTR,

    /* object reference */

    VM_OBJ,

    /* property ID */

    VM_PROP,

    /* 32-bit signed integer */

    VM_INT,

    /* 

     *   string constant value - the value is an offset into the constant

     *   pool of the string descriptor 

     */

    VM_SSTRING,

    /* 

     *   self-printing string value - the value is an offset into the

     *   constant pool of the string descriptor 

     */

    VM_DSTRING,

    /* 

     *   list constant - the value is an offset into the constant pool of

     *   the list descriptor 

     */

    VM_LIST,

    /* 

     *   byte-code constant offset - this is an offset into the byte-code

     *   pool.  This differs from VM_CODEPTR in that this is an offset in

     *   the byte-code constant pool rather than a native machine pointer.

     *   

     */

    VM_CODEOFS,

    /*

     *   function pointer - this is represented as an offset into the

     *   byte-code pool.  This differs from VM_CODEOFS in that the code

     *   referenced by a VM_CODEOFS value is generally invoked directly

     *   whenever the value is evaluated, whereas VM_FUNCPTR values are

     *   used to convey function pointers, so the underlying code is not

     *   executed implicitly on evaluation of such a value but must be

     *   explicitly invoked. 

     */

    VM_FUNCPTR,

    /*

     *   This is a special pseudo-type used to indicate that a value is

     *   not present.  This differs from nil, in that nil is a null

     *   reference or false value, whereas this indicates that there's no

     *   specified value at all.  This is used, for example, to indicate

     *   in an undo record that a property did not previously exist. 

     */

    VM_EMPTY,

    /*

     *   This is a special pseudo-type used to indicate that evaluating an

     *   expression requires executing system code.  The value stored is a

     *   pointer to a constant CVmNativeCodeDesc object, which describes a

     *   native code method.  

     */

    VM_NATIVE_CODE,

    /*

     *   Enumerated constant 

     */

    VM_ENUM,

    /*

     *   First invalid type ID.  Tools (such as compilers and debuggers)

     *   can use this ID and any higher ID values to flag their own

     *   internal types.  

     */

    VM_FIRST_INVALID_TYPE

};

/* macro to create a private type constant for internal use in a tool */

#define VM_MAKE_INTERNAL_TYPE(idx) \

    ((vm_datatype_t)(((int)VM_FIRST_INVALID_TYPE) + (idx)))

/*

 *   Value container.  Local variables, stack locations, and other value

 *   holders use this structure to store a value and its type.  

 */

struct vm_val_t

{

    vm_datatype_t typ;

    union

    {

        /* stack/code pointer */

        void *ptr;

        /* object reference */

        vm_obj_id_t obj;

        /* property ID */

        vm_prop_id_t prop;

        /* 32-bit integer */

        int32 intval;

        /* enumerated constant */

        uint32 enumval;

        /* sstring/dstring/list constant pool offset/pcode pool offset */

        pool_ofs_t ofs;

        /* native code descriptor */

        const class CVmNativeCodeDesc *native_desc;

    } val;

    /* set various types of values */

    void set_empty() { typ = VM_EMPTY; }

    void set_nil() { typ = VM_NIL; }

    void set_true() { typ = VM_TRUE; }

    void set_stack(void *ptr) { typ = VM_STACK; val.ptr = ptr; }

    void set_codeptr(void *ptr) { typ = VM_CODEPTR; val.ptr = ptr; }

    void set_obj(vm_obj_id_t obj) { typ = VM_OBJ; val.obj = obj; }

    void set_nil_obj() { typ = VM_NIL; val.obj = VM_INVALID_OBJ; }

    void set_propid(vm_prop_id_t prop) { typ = VM_PROP; val.prop = prop; }

    void set_int(int32 intval) { typ = VM_INT; val.intval = intval; }

    void set_enum(uint32 enumval) { typ = VM_ENUM; val.enumval = enumval; }

    void set_sstring(pool_ofs_t ofs) { typ = VM_SSTRING; val.ofs = ofs; }

    void set_dstring(pool_ofs_t ofs) { typ = VM_DSTRING; val.ofs = ofs; }

    void set_list(pool_ofs_t ofs) { typ = VM_LIST; val.ofs = ofs; }

    void set_codeofs(pool_ofs_t ofs) { typ = VM_CODEOFS; val.ofs = ofs; }

    void set_fnptr(pool_ofs_t ofs) { typ = VM_FUNCPTR; val.ofs = ofs; }

    void set_native(const class CVmNativeCodeDesc *desc)

        { typ = VM_NATIVE_CODE; val.native_desc = desc; }

    /* 

     *   set an object or nil value: if the object ID is VM_INVALID_OBJ,

     *   we'll set the type to nil 

     */

    void set_obj_or_nil(vm_obj_id_t obj)

    {

        /* set the object value initially */

        typ = VM_OBJ;

        val.obj = obj;

        /* if the object is invalid, set the type to nil */

        if (obj == VM_INVALID_OBJ)

            typ = VM_NIL;

    }

    /* set to an integer giving the datatype of the given value */

    void set_datatype(VMG_ const vm_val_t *val);

    /* set to nil if 'val' is zero, true if 'val' is non-zero */

    void set_logical(int v) { typ = (v != 0 ? VM_TRUE : VM_NIL); }

    /* determine if the value is logical (nil or true) */

    int is_logical() const { return (typ == VM_NIL || typ == VM_TRUE); }

    /* 

     *   Get a logical as numeric TRUE or FALSE.  This does not perform

     *   any type checking; the caller must ensure that the value is

     *   either true or nil, or this may return meaningless results.  

     */

    int get_logical() const { return (typ == VM_TRUE); }

    /*

     *   Get the underlying string constant value.  If the value does not

     *   have an underlying string constant (because it is of a type that

     *   does not store a string value), this will return null. 

     */

    const char *get_as_string(VMG0_) const;

    /*

     *   Get the underlying list constant value.  If the value does not

     *   have an underlying list constant (because it is of a type that

     *   does not store list data), this returns null. 

     */

    const char *get_as_list(VMG0_) const;

    /*

     *   Get the effective number of elements from this value when the

     *   value is used as the right-hand side of a '+' or '-' operator

     *   whose left-hand side implies that the operation involved is a set

     *   operation (this is the case is the left-hand side is of certain

     *   collection types, such as list, array, or vector); and get the

     *   nth element in that context.  Most types of values contribute

     *   only one element to these operations, but some collection types

     *   supply their elements individually, rather than the collection

     *   itself, for these operations.  'idx' is the 1-based index of the

     *   element to retrieve.  

     */

    size_t get_coll_addsub_rhs_ele_cnt(VMG0_) const;

    void get_coll_addsub_rhs_ele(VMG_ size_t idx, vm_val_t *result) const;

    /*

     *   Convert a numeric value to an integer value.  If the value isn't

     *   numeric, throws an error. 

     */

    void num_to_logical()

    {

        /* check the type */

        if (typ == VM_INT)

        {

            /* it's an integer - treat 0 as nil, all else as true */

            typ = (val.intval == 0 ? VM_NIL : VM_TRUE);

        }

        else

        {

            /* it's not a number - throw an error */

            err_throw(VMERR_NO_LOG_CONV);

        }

    }

    /* determine if the value is some kind of number */

    int is_numeric() const { return (typ == VM_INT); }

    /*

     *   Convert a numeric value to an integer.  If the value is not

     *   numeric, we'll throw an error. 

     */

    int32 num_to_int() const

    {

        /* check the type */

        if (typ == VM_INT)

        {

            /* it's an integer already - return the value directly */

            return val.intval;

        }

        else

        {

            /* 

             *   other types are not numeric and can't be directly

             *   converted to integer by arithmetic conversion

             */

            err_throw(VMERR_NUM_VAL_REQD);

            /* the compiler might not know we'll never get here */

            AFTER_ERR_THROW(return 0;)

        }

    }

    /* 

     *   determine if the numeric value is zero; throws an error if the

     *   value is not numeric 

     */

    int num_is_zero() const

    {

        /* check the type */

        if (typ == VM_INT)

        {

            /* check the integer value to see if it's zero */

            return (val.intval == 0);

        }

        else

        {

            /* it's not a number */

            err_throw(VMERR_NUM_VAL_REQD);

            /* in case the compiler doesn't know we'll never get here */

            AFTER_ERR_THROW(return 0;)

        }

    }

    /*

     *   Determine if this value equals a given value.  The nature of the

     *   match depends on the type of this value:

     *   

     *   integers, property ID's, code offsets: the types and values must

     *   match exactly.

     *   

     *   string and list constants: the other value must either be the same

     *   type of constant, or an object that has an underlying value of the

     *   same type; and the contents of the strings or lists must match.

     *   

     *   objects: the match depends on the type of the object.  We invoke the

     *   object's virtual equals() routine to make this determination.

     *   

     *   'depth' has the same meaning as in calc_hash().  

     */

    int equals(VMG_ const vm_val_t *v) const { return equals(vmg_ v, 0); }

    int equals(VMG_ const vm_val_t *val, int depth) const;

    /*

     *   Calculate a hash for the value.  The meaning of the hash varies by

     *   type, but is stable for a given value.  'depth' is a recursion depth

     *   counter, with the same meaning as in CVmObject::calc_hash().  

     */

    uint calc_hash(VMG0_) const { return calc_hash(vmg_ 0); }

    uint calc_hash(VMG_ int depth) const;

    /*

     *   Compare this value to the given value.  Returns a value greater than

     *   zero if this value is greater than 'val', a value less than zero if

     *   this value is less than 'val', or 0 if the two values are equal.

     *   Throws an error if the two values are not comparable.

     *   

     *   By far the most common type of comparison is between integers, so we

     *   test in-line to see if we have two integer values, and if so, use a

     *   fast in-line comparison.  If we don't have two integers, we'll use

     *   our full out-of-line test, which will look at other more interesting

     *   type combinations.  

     */

    int compare_to(VMG_ const vm_val_t *b) const

    {

        if (typ == VM_INT && b->typ == VM_INT)

            return (val.intval > b->val.intval

                    ? 1 : val.intval < b->val.intval ? -1 : 0);

        else

            return gen_compare_to(vmg_ b);

    }

    /*

     *   relative value comparisons 

     */

    /* self > b */

    int is_gt(VMG_ const vm_val_t *b) const

    {

        if (typ == VM_INT && b->typ == VM_INT)

            return val.intval > b->val.intval;

        else

            return gen_compare_to(vmg_ b) > 0;

    }

    /* self >= b */

    int is_ge(VMG_ const vm_val_t *b) const

    {

        if (typ == VM_INT && b->typ == VM_INT)

            return val.intval >= b->val.intval;

        else

            return gen_compare_to(vmg_ b) >= 0;

    }

    /* self < b */

    int is_lt(VMG_ const vm_val_t *b) const

    {

        if (typ == VM_INT && b->typ == VM_INT)

            return val.intval < b->val.intval;

        else

            return gen_compare_to(vmg_ b) < 0;

    }

    /* self <= b */

    int is_le(VMG_ const vm_val_t *b) const

    {

        if (typ == VM_INT && b->typ == VM_INT)

            return val.intval <= b->val.intval;

        else

            return gen_compare_to(vmg_ b) <= 0;

    }

private:

    /* out-of-line comparison, used when we don't have two integers */

    int gen_compare_to(VMG_ const vm_val_t *val) const;

};

/* ------------------------------------------------------------------------ */

/*

 *   Native code descriptor.  This describes a native method call of an

 *   intrinsic class object.  

 */

class CVmNativeCodeDesc

{

public:

    /* create a descriptor with an exact number of arguments */

    CVmNativeCodeDesc(int argc)

    {

        /* remember the parameters - there are no optional arguments */

        min_argc_ = argc;

        opt_argc_ = 0;

        varargs_ = FALSE;

    }

    /* create a descriptor with optional arguments (but not varargs) */

    CVmNativeCodeDesc(int min_argc, int opt_argc)

    {

        /* remember the parameters */

        min_argc_ = min_argc;

        opt_argc_ = opt_argc;

        varargs_ = FALSE;

    }

    /* create a descriptor with optional arguments and/or varargs */

    CVmNativeCodeDesc(int min_argc, int opt_argc, int varargs)

    {

        /* remember the parameters */

        min_argc_ = min_argc;

        opt_argc_ = opt_argc;

        varargs_ = varargs;

    }

    /* check the given number of arguments for validity */

    int args_ok(int argc) const

    {

        /* 

         *   the actual parameters must number at least the minimum, and

         *   cannot exceed the maximum (i.e., the minimum plus the

         *   optionals) unless we have varargs, in which case there is no

         *   maximum 

         */

        return (argc >= min_argc_

                && (varargs_ || argc <= min_argc_ + opt_argc_));

    }

    /* minimum argument count */

    int min_argc_;

    /* number of optional named arguments beyond the minimum */

    int opt_argc_;

    /* 

     *   true -> varargs: any number of arguments greater than or equal to

     *   min_argc_ are valid

     */

    int varargs_;

};

/* ------------------------------------------------------------------------ */

/*

 *   String handling - these routines are provided as covers to allow for

 *   easier adjustment for Unicode or other encodings.  Don't include these

 *   if we're compiling interface routines for the HTML TADS environment,

 *   since HTML TADS has its own similar definitions for these, and we don't

 *   need these for interface code.

 *   

 *   NOTE: The purpose of this macro is to indicate that we're being

 *   #included by an HTML TADS source file - that is, the current compile run

 *   is for an htmltads/xxx.cpp file.  Do NOT #define this macro when

 *   compiling tads3/xxx.cpp files.  The tads3/xxx.cpp files have absolutely

 *   no explicit dependencies on the htmltads subsystem and thus don't

 *   #include the htmltads headers that would provide the conflicting

 *   interface definitions for these functions.  The conflict is in the other

 *   direction: some of the htmltads source files explicitly depend on tads3

 *   headers, so they indirectly #include this header.  So, this macro needs

 *   to be defined only when compiling htmltads/xxx.cpp files.  

 */

#ifdef T3_COMPILING_FOR_HTML

#include "tadshtml.h"

#else

inline size_t get_strlen(const textchar_t *str) { return strlen(str); }

inline void do_strcpy(textchar_t *dst, const textchar_t *src)

    { strcpy(dst, src); }

#endif /* T3_COMPILING_FOR_HTML */

/* ------------------------------------------------------------------------ */

/*

 *   Portable Binary Representations.  When we store certain types of

 *   information in memory, we store it in a format that is identical to

 *   the format we use in portable binary files; using this format allows

 *   us to read and write binary files as byte images, without any

 *   interpretation, which greatly improves I/O performance in many cases.

 */

/*

 *   Portable binary LENGTH indicator.  This is used to store length

 *   prefixes for strings, lists, and similar objects.  We use a UINT2

 *   (16-bit unsigned integer) for this type of value.  

 */

const size_t VMB_LEN = 2;

inline void vmb_put_len(char *buf, size_t len) { oswp2(buf, len); }

inline size_t vmb_get_len(const char *buf) { return osrp2(buf); }

/*

 *   Portable binary unsigned 2-byte integer 

 */

const size_t VMB_UINT2 = 2;

inline void vmb_put_uint2(char *buf, uint16 i) { oswp2(buf, i); }

inline uint16 vmb_get_uint2(const char *buf) { return osrp2(buf); }

/*

 *   Portable binary object ID. 

 */

const size_t VMB_OBJECT_ID = 4;

inline void vmb_put_objid(char *buf, vm_obj_id_t obj) { oswp4(buf, obj); }

inline vm_obj_id_t vmb_get_objid(const char *buf) { return t3rp4u(buf); }

/*

 *   Portable binary property ID 

 */

const size_t VMB_PROP_ID = 2;

inline void vmb_put_propid(char *buf, vm_obj_id_t prop) { oswp2(buf, prop); }

inline vm_prop_id_t vmb_get_propid(const char *buf) { return osrp2(buf); }

/*

 *   Portable data holder.  This is used to store varying-type data items;

 *   for example, this is used to store an element in a list, or the value

 *   of a property in an object.  This type of value stores a one-byte

 *   prefix indicating the type of the value, and a four-byte area in

 *   which the value is stored.  The actual use of the four-byte value

 *   area depends on the type.  

 */

const size_t VMB_DATAHOLDER = 5;

/* offset from a portable data holder pointer to the data value */

const size_t VMB_DH_DATAOFS = 1;

/* store a portable dataholder from a vm_val_t */

void vmb_put_dh(char *buf, const vm_val_t *val);

/* store a nil value in a portable dataholder */

inline void vmb_put_dh_nil(char *buf) { buf[0] = VM_NIL; }

/* store an object value in a portable dataholder */

inline void vmb_put_dh_obj(char *buf, vm_obj_id_t obj)

    { buf[0] = VM_OBJ; vmb_put_objid(buf + 1, obj); }

/* store a property value in a portable dataholder */

inline void vmb_put_dh_prop(char *buf, vm_prop_id_t prop)

    { buf[0] = VM_PROP; vmb_put_propid(buf + 1, prop); }

/* get the value portion of a vm_val_t from a portable dataholder */

void vmb_get_dh_val(const char *buf, vm_val_t *val);

/* get the type from a portable dataholder */

inline vm_datatype_t vmb_get_dh_type(const char *buf)

    { return (vm_datatype_t)buf[0]; }

/* get a vm_val_t from a portable dataholder */

inline void vmb_get_dh(const char *buf, vm_val_t *val)

    { val->typ = vmb_get_dh_type(buf); vmb_get_dh_val(buf, val); }

/* get an object value from a portable dataholder */

inline vm_obj_id_t vmb_get_dh_obj(const char *buf)

    { return (vm_obj_id_t)t3rp4u(buf+1); }

/* get an integer value from a portable dataholder */

inline int32 vmb_get_dh_int(const char *buf)

    { return (int32)osrp4(buf+1); }

/* get a property ID value from a portable dataholder */

inline vm_prop_id_t vmb_get_dh_prop(const char *buf)

    { return (vm_prop_id_t)osrp2(buf+1); }

/* get a constant offset value from a portable dataholder */

inline pool_ofs_t vmb_get_dh_ofs(const char *buf)

    { return (pool_ofs_t)t3rp4u(buf+1); }

#endif /* VMTYPE_H */