/* 

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

 *   

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

 *   on using and copying this software.  

 */

/*

Name

  tcpn.h - Parse Node - base class

Function

  Defines the target-independent base class for parse nodes

Notes

  All expression parse nodes are derived from the target-specific

  subclass of this class.  The target-independent base class is

  CTcPrsNodeBase; the target-specific class is CTcPrsNode.

Modified

  05/10/99 MJRoberts  - Creation

*/

#ifndef TCPN_H

#define TCPN_H

#include "vmhash.h"

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

/*

 *   Parse Tree Allocation Object.  This is a base class that can be used

 *   for tree objects that are to be allocated from the parser node pool. 

 */

class CTcPrsAllocObj

{

public:

    /*

     *   Override operator new() - allocate all parse node objects out of

     *   the parse node pool.  

     */

    void *operator new(size_t siz);

};

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

/*

 *   adjust_for_debug() information structure 

 */

struct tcpn_debug_info

{

    /* true -> speculative evaluation mode */

    int speculative;

    /* 

     *   stack level - 0 is the active level, 1 is the first enclosing

     *   level, and so on 

     */

    int stack_level;

};

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

/*

 *   Parse Tree Expression Node - base class.  As we parse an expression,

 *   we build a tree of these objects to describe the source code.

 *   

 *   This class is subclassed for each type of parsing node: each type of

 *   statement has a node type, some statements have helper node types for

 *   parts of statements, and each expression operator has a node type.

 *   These subclasses contain the information specific to the type of

 *   parsing construct represented.

 *   

 *   Each parsing subclass is then further subclassed for each target

 *   architecture.  This final subclass contains the code generator for

 *   the node in the target architecture.

 *   

 *   The target-independent base version of each subclass is called

 *   CTPNXxxBase.  The target-specific subclass derived from this base

 *   class is CTPNXxx.  For example, the final subclass for constant

 *   nodes, which is derived from the target-independent base class

 *   CTPNConstBase, is CTPNConst.  (Note that each target uses the same

 *   name for the final subclass, so we can only link one target

 *   architecture into a given build of the compiler.  Each additional

 *   target requires a separate compiler executable with the appropriate

 *   CTPNConst classes linked in.)  

 */

class CTcPrsNodeBase: public CTcPrsAllocObj

{

public:

    /* 

     *   Generate code for the expression for the target architecture.

     *   This method is defined only by the final target-specific

     *   subclasses.

     *   

     *   This method is used to generate code to evaluate the expression

     *   as an rvalue.

     *   

     *   If 'discard' is true, it indicates that any value yielded by the

     *   expression will not be used, in which case the generated code

     *   need not leave the result of the expression on the stack.  We can

     *   generate code more efficiently for certain types of expressions

     *   when we know that we're evaluating them only for side effects.

     *   For example, an assignment expression has a result value, but

     *   this value need not be pushed onto the stack if it will simply be

     *   discarded.  Also, an operator like "+" that has no side effects

     *   of its own can merely evaluate its operands for their side

     *   effects, but need not compute its own result if that result would

     *   simply be discarded.

     *   

     *   If 'for_condition' is true, it indicates that the result of the

     *   expression will be used directly for a conditional of some kind

     *   (for a "?:" operator, an "if" statement, a "while" statement, or

     *   the like).  In some cases, we can avoid extra conversions to some

     *   values when they're going to be used directly for a comparison;

     *   for example, the "&&" operator must return a true/nil value, but

     *   the code generator may be able to avoid the extra conversion when

     *   the value will be used for an "if" statement's conditional value.

     */

    virtual void gen_code(int discard, int for_condition) = 0;

    /*

     *   Get the constant value of the parse node, if available.  Most

     *   parse nodes have no constant value, so by default this returns

     *   null.  Only constant parse nodes can provide a constant value, so

     *   they should override this.  

     */

    virtual class CTcConstVal *get_const_val() { return 0; }

    /* determine if the node has a constant value */

    int is_const() { return get_const_val() != 0; }

    /* determine if I have a given constant integer value */

    int is_const_int(int val)

    {

        return (is_const()

                && get_const_val()->get_type() == TC_CVT_INT

                && get_const_val()->get_val_int() == val);

    }

    /*

     *   Set the constant value of the parse node from that of another

     *   node.  The caller must already have checked that this node and

     *   the value being assigned are both valid constant values.  

     */

    void set_const_val(class CTcPrsNode *src)

    {

        /* set my constant value from the source's constant value */

        get_const_val()->set(((CTcPrsNodeBase *)src)->get_const_val());

    }

    /*

     *   Check to see if this expression can possibly be a valid lvalue.

     *   Return true if so, false if not.  This check is made before

     *   symbol resolution; when it is not certain whether or not a symbol

     *   expression can be an lvalue, assume it can be at this point.  By

     *   default, we'll return false; operator nodes whose result can be

     *   used as an lvalue should override this to return true.  

     */

    virtual int check_lvalue() const { return FALSE; }

    /*

     *   Check to see if this expression is an valid lvalue, after

     *   resolving symbols in the given scope.  Returns true if so, false

     *   if not. 

     */

    virtual int check_lvalue_resolved(class CTcPrsSymtab *symtab) const

        { return FALSE; }

    /*

     *   Check to see if this expression can possibly be a valid address

     *   value, so that the address-of ("&") operator can be applied.

     *   Returns true if it is possible, false if not.  The only type of

     *   expression whose address can be taken is a simple symbol.  The

     *   address of a symbol can be taken only if the symbol is a function

     *   or property name, but we won't know this at parse time, so we'll

     *   indicate that any symbol is acceptable.  By default, this returns

     *   false, since the address of most expressions cannot be taken.  

     */

    virtual int has_addr() const { return FALSE; }

    /*

     *   Check to see if this expression is an address expression of some

     *   kind (i.e., of class CTPNAddrBase, or of a class derived from

     *   CTPNAddrBase).  Returns true if so, false if not.  

     */

    virtual int is_addr() const { return FALSE; }

    /*

     *   Determine if this node is of type double-quoted string (dstring).

     *   Returns true if so, false if not.  By default, we return false.

     */

    virtual int is_dstring() const { return FALSE; }

    /*

     *   Determine if this is a simple assignment operator node.  Returns

     *   true if so, false if not.  By default, we return false. 

     */

    virtual int is_simple_asi() const { return FALSE; }

    /*

     *   Determine if this node yields a value when evaluated.  Returns

     *   true if so, false if not.  When it cannot be determined at

     *   compile-time whether or not the node has a value (for example,

     *   for a call to a pointer to a function whose return type is not

     *   declared), this should indicate that a value is returned.

     *   

     *   Most nodes yield a value when executed, so we'll return true by

     *   default.  

     */

    virtual int has_return_value() const { return TRUE; }

    /*

     *   Determine if this node yields a return value when called as a

     *   function.  We assume by default that it does. 

     */

    virtual int has_return_value_on_call() const { return TRUE; }

    /*

     *   Get the text of the symbol for this node, if any.  If the node is

     *   not some kind of symbol node, this returns null.  

     */

    virtual const textchar_t *get_sym_text() const { return 0; }

    virtual size_t get_sym_text_len() const { return 0; }

    /*

     *   Fold constant expressions, given a finished symbol table.  We do

     *   most of our constant folding during the initial parsing, but some

     *   constant folding must wait until the symbol table is finished; in

     *   particular, we can't figure out what to do with symbols until we

     *   know what the symbols mean.

     *   

     *   For most nodes, this function should merely recurse into subnodes

     *   and fold constants.  Nodes that are affected by symbol

     *   resolution, directly or indirectly, should override this.

     *   

     *   For example, a list can change from unknown to constant during

     *   this operation.  If the list contains a symbol, the list will

     *   initially be set to unknown, since the symbol could turn out to

     *   be a property evaluation, which would be non-constant, or an

     *   object name, which would be constant.

     *   

     *   Returns the folded version of the node, or simply 'this' if no

     *   folding takes place.  

     */

    virtual class CTcPrsNode *fold_constants(class CTcPrsSymtab *symtab) = 0;

    /* 

     *   generate a constant value node for the address of this node;

     *   returns null if the symbol has no address 

     */

    virtual class CTcPrsNode *fold_addr_const(class CTcPrsSymtab *)

    {

        /* by default, we have no address */

        return 0;

    }

    /*

     *   Adjust the expression for use as a debugger expression.  Code

     *   generation for debugger expressions is somewhat different than

     *   for normal expressions; this routine should allocate a new node,

     *   if necessary, for debugger use.  Returns the current node if no

     *   changes are necessary, or a new node if changes are needed.

     *   

     *   If 'speculative' is true, the expression is being evaluated

     *   speculatively by the debugger.  This means that the user hasn't

     *   explicitly asked for the expression to be evaluated, but rather

     *   the debugger is making a guess that the expression might be of

     *   interest to the user and is making an unsolicited attempt to

     *   offer it to the user.  Because the debugger is only guessing that

     *   the expression is interesting, the expression must not be

     *   evaluated if it has any side effects at all.  

     */

    virtual class CTcPrsNode *adjust_for_debug(const tcpn_debug_info *info);

};

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

/*

 *   Symbol Table Entry.  Each symbol has an entry in one of the symbol

 *   tables:

 *   

 *   - The global symbol table contains object, property, and built-in

 *   functions from the default function set.

 *   

 *   - Local symbol tables contain local variables and parameters.  Local

 *   tables have block-level scope.

 *   

 *   - Label symbol tables contain code labels (for "goto" statements).

 *   Label tables have function-level or method-level scope.  

 */

/*

 *   Basic symbol table entry.  The target 

 */

class CTcSymbolBase: public CVmHashEntryCS

{

public:

    CTcSymbolBase(const char *str, size_t len, int copy, tc_symtype_t typ)

        : CVmHashEntryCS(str, len, copy)

    {

        typ_ = typ;

    }

    /* allocate symbol entries from the parser memory pool */

    void *operator new(size_t siz);

    /* get the symbol type */

    tc_symtype_t get_type() const { return typ_; }

    /* get the symbol text and length */

    const char *get_sym() const { return getstr(); }

    size_t get_sym_len() const { return getlen(); }

    /*

     *   Generate a constant value node for this symbol, if possible;

     *   returns null if the symbol does not evaluate to a compile-time

     *   constant value.  An object name, for example, evaluates to a

     *   compile-time constant equal to the object reference; a property

     *   name, in contrast, is (when not qualified by another operator) an

     *   invocation of the property, hence must be executed at run time,

     *   hence is not a compile-time constant.  

     */

    virtual class CTcPrsNode *fold_constant()

    {

        /* by default, a symbol's value is not a constant */

        return 0;

    }

    /* 

     *   generate a constant value node for the address of this symbol;

     *   returns null if the symbol has no address 

     */

    virtual class CTcPrsNode *fold_addr_const()

    {

        /* by default, a symbol has no address */

        return 0;

    }

    /* determine if this symbol can be used as an lvalue */

    virtual int check_lvalue() const { return FALSE; }

    /* determine if this symbol can have its address taken */

    virtual int has_addr() const { return FALSE; }

    /* determine if I have a return value when evaluated */

    virtual int has_return_value_on_call() const { return TRUE; }

    /* 

     *   Write the symbol to a symbol export file.  By default, we'll

     *   write the type and symbol name to the file.  Some subclasses

     *   might wish to override this to write additional data, or to write

     *   something different or nothing at all (for example, built-in

     *   function symbols are not written to a symbol export file).

     *   

     *   When a subclass does override this, it must write the type as a

     *   UINT2 value as the first thing written to the file.  The generic

     *   file reader switches on this type code to determine what to call

     *   to load the entry, then calls the subclass-specific loader to do

     *   the actual work.

     *   

     *   Returns true if we wrote the symbol to the file, false if not.

     *   (False doesn't indicate an error - it indicates that we chose not

     *   to store the symbol because the symbol is not of a type that we

     *   want to put in the export file.)  

     */

    virtual int write_to_sym_file(class CVmFile *fp);

    /* write the symbol name (with a UINT2 length prefix) to a file */

    int write_name_to_file(class CVmFile *fp);

    /*

     *   Write the symbol to an object file.  By default, we'll write the

     *   type and symbol name to the file.  Some subclasses might wish to

     *   override this to write additional data, or to write something

     *   different or nothing at all (for example, built-in function

     *   symbols are not written to an object file).

     *   

     *   When a subclass does override this, it must write the type as a

     *   UINT2 value as the first thing written to the file.  The generic

     *   file reader switches on this type code to determine what to call

     *   to load the entry, then calls the subclass-specific loader to do

     *   the actual work.

     *   

     *   Returns true if we wrote the symbol to the file, false if not.

     *   (False doesn't indicate an error - it indicates that we chose not

     *   to store the symbol because the symbol is not of a type that we

     *   want to put in the export file.)  

     */

    virtual int write_to_obj_file(class CVmFile *fp);

    /*

     *   Write the symbol's cross references to the object file.  This can

     *   write references to other symbols by storing the other symbol's

     *   index in the object file.  Most symbols don't have any cross

     *   references, so this does nothing by default.

     *   

     *   If this writes anything, the first thing written must be a UINT4

     *   giving the object file index of this symbol.  On loading, we'll

     *   read this and look up the loaded symbol.  

     */

    virtual int write_refs_to_obj_file(class CVmFile *) { return FALSE; }

    /* 

     *   perform basic writing to a file - this performs common work that

     *   can be used for object or symbol files 

     */

    int write_to_file_gen(CVmFile *fp);

    /*

     *   Read a symbol from a symbol file, returning the new symbol 

     */

    static class CTcSymbol *read_from_sym_file(class CVmFile *fp);

    /*

     *   Load a symbol from an object file.  Stores the symbol in the

     *   global symbol table, and fills in the appropriate translation

     *   mapping table when necessary.  Returns zero on success; logs

     *   error messages and return non-zero on failure.  

     */

    static int load_from_obj_file(class CVmFile *fp,

                                  const textchar_t *fname,

                                  tctarg_obj_id_t *obj_xlat,

                                  tctarg_prop_id_t *prop_xlat,

                                  ulong *enum_xlat);

    /*

     *   Load references from the object file - reads the information that

     *   write_refs_to_obj_file() wrote, except that the caller will have

     *   read the first UINT4 giving the symbol's object file index before

     *   calling this routine. 

     */

    virtual void load_refs_from_obj_file(class CVmFile *,

                                         const textchar_t * /*obj_fname*/,

                                         tctarg_obj_id_t * /*obj_xlat*/,

                                         tctarg_prop_id_t * /*prop_xlat*/)

    {

        /* by default, do nothing */

    }

    /*

     *   Log an object file loading conflict with this symbol.  The given

     *   type is the new type found in the object file of the given name. 

     */

    void log_objfile_conflict(const textchar_t *fname, tc_symtype_t new_type)

        const;

    /*

     *   Get a pointer to the head of the fixup list for this symbol.

     *   Symbols such as functions that keep a list of fixups for

     *   references to the symbol must override this to provide a fixup

     *   list head; by default, symbols keep no fixup list, so we'll just

     *   return null. 

     */

    virtual struct CTcAbsFixup **get_fixup_list_anchor() { return 0; }

    /*

     *   Set my code stream anchor object.  By default, symbols don't keep

     *   track of any stream anchors.  Symbols that refer to code or data

     *   stream locations directly must keep an anchor, since they must

     *   keep track of their fixup list in order to fix up generated

     *   references to the symbol.  This must be overridden by any

     *   subclasses that keep anchors.  

     */

    virtual void set_anchor(struct CTcStreamAnchor *) { }

    /*

     *   Determine if this symbol is external and unresolved.  By default,

     *   a symbol cannot be external at all, so this will return false.

     *   Subclasses for symbol types that can be external should override

     *   this to return true if the symbol is an unresolved external

     *   reference. 

     */

    virtual int is_unresolved_extern() const { return FALSE; }

    /*

     *   Mark the symbol as referenced.  Some symbol types keep track of

     *   whether they've been referenced or not; those types can override

     *   this to keep track.  This method is called each time the symbol

     *   is found in the symbol table via the find() or find_or_def()

     *   methods.  By default, we do nothing.

     */

    virtual void mark_referenced() { }

    /*

     *   Apply internal fixups.  If the symbol keeps its own internal

     *   fixup information, it can translate the fixups here.  By default,

     *   this does nothing.  

     */

    virtual void apply_internal_fixups() { }

    /*

     *   Build dictionary entries for this symbol.  Most symbols do

     *   nothing here; objects which can have associated vocabulary words

     *   should insert their vocabulary into the dictionary.  

     */

    virtual void build_dictionary() { }

    /*

     *   Create a new "context variable" version of this symbol for use in

     *   an anonymous function.  This is only needed for symbols that can

     *   exist in a local scope.  

     */

    virtual class CTcSymbol *new_ctx_var() const { return 0; }

    /*

     *   Apply context variable conversion.  If this symbol has not been

     *   referenced, this should simply remove the symbol from the symbol

     *   table.  Otherwise, this should apply the necessary conversions to

     *   the original symbol from which this symbol was created to ensure

     *   that the original and this symbol share a context variable slot.

     *   

     *   Returns true if a conversion was performed (i.e., the symbol was

     *   referenced), false if not.  

     */

    virtual int apply_ctx_var_conv(class CTcPrsSymtab *,

                                   class CTPNCodeBody *)

        { return FALSE; }

    /*

     *   Finalize context variable conversion.  This should do nothing if

     *   the variable hasn't already been notified that it's a context

     *   variable (how this happens varies by symbol type - see locals in

     *   particular).  This is called with the variable's own scope active

     *   in the parser, so the final variable assignments for the symbol

     *   can be made.  

     */

    virtual void finish_ctx_var_conv() { }

    /*

     *   Check for local references.  For variables that can exist in

     *   local scope, such as locals, this will be called when all of the

     *   code for the scope has been parsed; this should check to see if

     *   the symbol has been referenced in the scope, and display an

     *   appropriate warning message if not.  

     */

    virtual void check_local_references() { }

    /*

     *   Add an entry for this symbol to a "runtime symbol table," which is

     *   a symbol table that we can pass to the interpreter.  This must be

     *   overridden by each symbol type for each target architecture,

     *   because the nature of the runtime symbol table varies by target

     *   architecture.

     *   

     *   By default, this does nothing.  Symbol types that don't need to

     *   generate runtime symbol table entries don't need to override this.  

     */

    virtual void add_runtime_symbol(class CVmRuntimeSymbols *) { }

protected:

    /* 

     *   Base routine to read from a symbol file - reads the symbol name.

     *   Returns a pointer to the symbol name (stored in tokenizer memory

     *   that will remain valid throughout the compilation) on success; on

     *   failure, logs an error and returns null.  

     */

    static const char *base_read_from_sym_file(class CVmFile *fp);

    /* symbol type */

    tc_symtype_t typ_;

};