/* 

 *   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

  tcprs.h - TADS 3 Compiler - parser

Function

Notes

Modified

  04/29/99 MJRoberts  - Creation

*/

#ifndef TCPRS_H

#define TCPRS_H

#include <assert.h>

#include "vmtype.h"

#include "t3std.h"

#include "tcglob.h"

#include "tctok.h"

#include "tctargty.h"

#include "tcprstyp.h"

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

/*

 *   Object ID type 

 */

typedef ulong tc_obj_id;

/*

 *   Property ID type 

 */

typedef uint tc_prop_id;

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

/*

 *   scope data structure 

 */

struct tcprs_scope_t

{

    /* local symbol table */

    class CTcPrsSymtab *local_symtab;

    /* enclosing scope's local symbol table */

    class CTcPrsSymtab *enclosing_symtab;

    /* number of locals allocated in scope */

    int local_cnt;

};

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

/*

 *   Code body parsing types.  Each type of code body is essentially the

 *   same with minor variations, so we use a common code body parser that

 *   checks the parsing type to apply the variations.  

 */

enum tcprs_codebodytype

{

    /* a standard function or method code body */

    TCPRS_CB_NORMAL,

    /* anonymous function */

    TCPRS_CB_ANON_FN,

    /* short-form anonymous function */

    TCPRS_CB_SHORT_ANON_FN

};

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

/*

 *   the saved method context is always at index 1 in local variable context

 *   arrays, when we're using local variable context arrays 

 */

#define TCPRS_LOCAL_CTX_METHODCTX  1

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

/*

 *   Parser 

 */

class CTcParser

{

public:

    CTcParser();

    ~CTcParser();

    /* initialize - call this after the code generator is set up */

    void init();

    /*

     *   Set the module information.  This tells us the module's name (as

     *   it's given in the makefile (.t3m) or library (.tl) file) and its

     *   sequence number (an ordinal giving its position in the list of

     *   modules making up the overall program build).  We use this

     *   information in generating the sourceTextGroup object.  

     */

    void set_module_info(const char *name, int seqno);

    /*

     *   Write an exported symbol file.  An exported symbol file

     *   facilitates separate compilation by providing a listing of the

     *   symbols defined in another module.  If module A depends on the

     *   symbols from module B, the user can first create an exported

     *   symbol file for module B, then can compile module A in the

     *   presence of B's symbol file, without actually loading B, and

     *   without manually entering a set of external definitions in module

     *   A's source code. 

     */

    void write_symbol_file(class CVmFile *fp, class CTcMake *make_obj);

    /*

     *   Seek to the start of the build configuration information in a symbol

     *   file.  The return value is the number of bytes stored in the build

     *   configuration block; on return, the file object will have its seek

     *   offset set to the first byte of the build configuration data.

     *   Returns zero if the symbol file is invalid or does not contain any

     *   configuration data.  

     */

    static ulong seek_sym_file_build_config_info(class CVmFile *fp);

    /* 

     *   Write the global table to an object file. 

     */

    void write_to_object_file(class CVmFile *fp);

    /*

     *   Read an object file and load it into the global symbol table.  We

     *   will fill in the object and property ID translation tables

     *   provided with the translated values for the object and property

     *   symbols that we find in the object file.

     *   

     *   Returns zero on success; logs error messages and returns non-zero

     *   on error.  Note that a non-zero value should be returned only

     *   when the file appears to be corrupted or an I/O error occurs;

     *   errors involving conflicting symbols, or other problems that do

     *   not prevent us from continuing to read the file in an orderly

     *   fashion, should not return failure but should simply log the

     *   error and continue; this way, we can detect any additional symbol

     *   conflicts or other errors.  This routine should return failure

     *   only when it is not possible to continue reading the file.  

     */

    int load_object_file(class CVmFile *fp,

                         const textchar_t *fname,

                         tctarg_obj_id_t *obj_xlat,

                         tctarg_prop_id_t *prop_xlat,

                         ulong *enum_xlat);

    /*

     *   Apply internal object/property ID fixups.  This traverses the

     *   symbol table and calls each symbol's apply_internal_fixups()

     *   method.  This can be called once after loading all object files.  

     */

    void apply_internal_fixups();

    /*

     *   Read an exported symbol file.  Reads the file and loads the

     *   global symbol table with the symbols in the file, with each

     *   symbol marked as external.

     *   

     *   This can be used for separate compilation.  If module A depends

     *   on symbols in module B, first create a symbol file for module B,

     *   then module A can be compiled simply be pre-loading B's symbol

     *   file.  Any symbol files that a module depends upon must be loaded

     *   before the module is compiled - symbol file loading must precede

     *   parsing.

     *   

     *   If any errors occur, we'll log the errors and return non-zero.

     *   We'll return zero on success.  

     */

    int read_symbol_file(class CVmFile *fp);

    /* get the global symbol table */

    class CTcPrsSymtab *get_global_symtab() const { return global_symtab_; }

    /* get the current local symbol table */

    class CTcPrsSymtab *get_local_symtab() const { return local_symtab_; }

    /* get the 'goto' symbol table */

    class CTcPrsSymtab *get_goto_symtab() const { return goto_symtab_; }

    /* set the current pragma C mode */

    void set_pragma_c(int mode);

    /* turn preprocess expression mode on or off */

    void set_pp_expr_mode(int f) { pp_expr_mode_ = f; }

    /* get the current preprocess expression mode flag */

    int get_pp_expr_mode() const { return pp_expr_mode_; }

    /* set/get the sourceTextGroup mode */

    void set_source_text_group_mode(int f);

    int get_source_text_group_mode() const { return src_group_mode_; }

    /* get/set the syntax-only mode flag */

    int get_syntax_only() const { return syntax_only_; }

    void set_syntax_only(int f) { syntax_only_ = f; }

    /* 

     *   Get the constructor and finalize property ID's - all constructors

     *   and finalizers have these property ID's respectively 

     */

    tc_prop_id get_constructor_prop() const { return constructor_prop_; }

    tc_prop_id get_finalize_prop() const { return finalize_prop_; }

    /* get the constructor property symbol */

    class CTcSymProp *get_constructor_sym() const { return constructor_sym_; }

    /* get the object-call property */

    tc_prop_id get_objcall_prop() const { return objcall_prop_; }

    /*

     *   Check for unresolved external symbols.  Scans the global symbol

     *   table and logs an error for each unresolved external.  Returns

     *   true if any unresolved externals exist, false if not.  

     */

    int check_unresolved_externs();

    /* 

     *   build the dictionaries - scans the global symbol table, and

     *   inserts each object symbol's dictionary words into its

     *   corresponding dictionary 

     */

    void build_dictionaries();

    /* build the grammar productions */

    void build_grammar_productions();

    /*

     *   Top-level parser.  Parse functions, objects, and other top-level

     *   definitions and declarations. 

     */

    class CTPNStmProg *parse_top();

    /* 

     *   Parse a required semicolon.  If the semicolon is present, we'll

     *   simply skip it.  If it's missing, we'll log an error and try to

     *   resynchronize.  If we find something that looks like it should go

     *   at the end of an expression, we'll try to skip up to the next

     *   semicolon; otherwise, we'll simply stay put.

     *   

     *   Returns zero if the caller should proceed, non-zero if we're at

     *   end of file, in which case there's nothing more for the caller to

     *   parse.  

     */

    static int parse_req_sem();

    /* 

     *   Skip to the next semicolon, ignoring any tokens up to that point.

     *   This can be used when the caller encounters an error that makes

     *   it impossible to process the current statement further, and wants

     *   to find the next semicolon in the hope that it will be a good

     *   place to start again with the next statement.

     *   

     *   Returns zero if the caller should proceed, non-zero if we reach

     *   the end of the file.  

     */

    static int skip_to_sem();

    /* 

     *   Parse an expression.  This parses a top-level "comma" expression. 

     */

    class CTcPrsNode *parse_expr();

    /*

     *   Parse a condition expression.  This parses a top-level "comma"

     *   expression, but displays a warning if the outermost operator in

     *   the expression is an assignment, because such expressions are

     *   very frequently meant as comparisons, but the '=' operator was

     *   inadvertantly used instead of '=='. 

     */

    class CTcPrsNode *parse_cond_expr();

    /* 

     *   Parse a value expression or a double-quoted string expression

     *   (including a double-quoted string with embedded expressions).  If

     *   allow_comma_expr is true, we'll parse a comma expression;

     *   otherwise, we'll parse an assignment expression.  (A comma

     *   expression is broader than an assignment expression, since the

     *   comma separates assignment expressions.)  

     */

    class CTcPrsNode *parse_expr_or_dstr(int allow_comma_expr);

    /* 

     *   Parse an assignment expression - this is the next precedence

     *   level down from comma expressions.  In certain contexts, a

     *   top-level comma expression is not allowed because a comma has a

     *   separate meaning (in the initializer clause of a 'for' statement,

     *   for example, or in a list element). 

     */

    class CTcPrsNode *parse_asi_expr();

    /* parse an 'enum' top-level statement */

    void parse_enum(int *err);

    /* parse a 'dictionary' top-level statement */

    class CTPNStmTop *parse_dict(int *err);

    /* parse a 'grammar' top-level statement */

    class CTPNStmTop *parse_grammar(int *err, int replace, int modify);

    /* parse and flatten a set of grammar rules */

    class CTcPrsGramNode *flatten_gram_rule(int *err);

    /* parse a 'grammar' OR node */

    class CTcPrsGramNode *parse_gram_or(int *err, int level);

    /* parse a 'grammar' CAT node */

    class CTcPrsGramNode *parse_gram_cat(int *err, int level);

    /* parse a 'grammar' qualifier int value */

    int parse_gram_qual_int(int *err, const char *qual_name, int *stm_end);

    /* skip to the end of a mal-formed grammar qualifier */

    void parse_gram_qual_skip(int *err, int *stm_end);

    /* 

     *   Parse a 'function' top-level statement.  If 'is_extern' is true,

     *   the function is being defined externally, so it should have no

     *   code body defined here (just the prototype).  If 'replace' is

     *   true, we're replacing an existing function.

     *   

     *   If 'func_kw_present' is true, the 'function' keyword is present

     *   and must be skipped; otherwise, the function definition elides

     *   the 'function' keyword and starts directly with the function name

     *   symbol.  

     */

    class CTPNStmTop *parse_function(int *err, int is_extern,

                                     int replace, int modify,

                                     int func_kw_present);

    /* parse an 'intrinsic' top-level statement */

    class CTPNStmTop *parse_intrinsic(int *err);

    /* parse an 'intrinsic class' top-level statement */

    class CTPNStmTop *parse_intrinsic_class(int *err);

    /* parse an 'extern' top-level statement */

    void parse_extern(int *err);

    /* 

     *   parse an object or function defintion (this is called when the

     *   first thing in a statement is a symbol; we must check what

     *   follows to determine what type of definition it is) 

     */

    class CTPNStmTop *parse_object_or_func(int *err, int replace,

                                           int suppress_error,

                                           int *suppress_next_error);

    /* parse a template definition statement */

    class CTPNStmTop *parse_template_def(int *err,

                                         const class CTcToken *class_tok);

    /* add a template definition */

    void add_template_def(class CTcSymObj *class_sym,

                          class CTcObjTemplateItem *item_head,

                          size_t item_cnt);

    /* add inherited template definitions */

    void add_inherited_templates(class CTcSymObj *sc_sym,

                                 class CTcObjTemplateItem *item_head,

                                 size_t item_cnt);

    /* 

     *   expand the 'inherited' keyword in a template for the given

     *   superclass template and add the result to the template list for the

     *   class 

     */

    void expand_and_add_inherited_template(class CTcSymObj *sc_sym,

                                           class CTcObjTemplateItem *items,

                                           class CTcObjTemplate *sc_tpl);

    /* 

     *   build a list of superclass templates, for expanding an 'inherited'

     *   token in a template definition 

     */

    void build_super_template_list(struct inh_tpl_entry **list_head,

                                   struct inh_tpl_entry **list_tail,

                                   class CTcSymObj *sc_sym);

    /* parse an 'object' statement */

    class CTPNStmTop *parse_object_stm(int *err, int is_transient);

    /* 

     *   parse an object definition that starts with a '+' string; this

     *   also parses '+ property' statements 

     */

    class CTPNStmTop *parse_plus_object(int *err);

    /* 

     *   Parse an object definition.  If 'replace' is true, this

     *   definition is to replace a previous definition of the same

     *   object; if 'modify' is true, this definition is to modify a

     *   previous definition.  If 'is_class' is true, the definition is

     *   for a class, otherwise it's for a static instance.

     *   

     *   If the definition uses the '+' notation to set the location,

     *   plus_cnt gives the number of '+' signs preceding the object

     *   definition.  

     */

    class CTPNStmTop *parse_object(int *err, int replace, int modify,

                                   int is_class, int plus_cnt,

                                   int is_transient);

    /* find or define an object symbol */

    CTcSymObj *find_or_def_obj(const char *tok_txt, size_t tok_len,

                               int replace, int modify, int *is_class,

                               class CTcSymObj **mod_orig_sym,

                               class CTcSymMetaclass **meta_sym,

                               int *is_transient);

    /* parse an anonymous object */

    class CTPNStmObject *parse_anon_object(int *err, int plus_cnt,

                                           int is_nested,

                                           struct tcprs_term_info *term_info,

                                           int is_transient);

    /* 

     *   Parse an object body.  We start parsing from the colon that

     *   introduces the class list, and parse the class list and the

     *   property list for the object.

     *   

     *   If 'is_anon' is true, this is an anonymous object.  'obj_sym'

     *   should be null in this case.

     *   

     *   If 'is_nested' is true, this is a nested object defined in-line in

     *   an object's property list.  Note that is_nested implies is_anon,

     *   since nested objects are always anonymous.

     *   

     *   If this is a 'modify' definition, 'mod_orig_tok' should be set up

     *   with the synthesized symbol for the modified base object;

     *   otherwise, 'mod_orig_tok' should be null.

     *   

     *   If 'meta_sym' is non-null, we're modifying an intrinsic class.

     *   This imposes certain restrictions; in particular, we cannot modify

     *   a method defined in the native interface to the class.  

     */

    class CTPNStmObject *parse_object_body(int *err, class CTcSymObj *obj_sym,

                                           int is_class, int is_anon,

                                           int is_grammar,

                                           int is_nested, int modify,

                                           class CTcSymObj *mod_orig_sym,

                                           int plus_cnt,

                                           class CTcSymMetaclass *meta_sym,

                                           struct tcprs_term_info *term_info,

                                           int is_transient);

    /* parse an object template instance in an object body */

    void parse_obj_template(int *err, class CTPNStmObject *obj_stm);

    /* search a superclass list for a template match */

    const class CTcObjTemplate

        *find_class_template(const class CTPNSuperclass *first_sc,

                             class CTcObjTemplateInst *src,

                             size_t src_cnt, const CTPNSuperclass **def_sc,

                             int *undescribed_class);

    /* find a match for a given template in the given list */

    const class CTcObjTemplate

        *find_template_match(const class CTcObjTemplate *first_tpl,

                             class CTcObjTemplateInst *src,

                             size_t src_cnt);

    /*

     *   Match a template to a given actual template parameter list.  Returns

     *   true if we match, false if not.  We'll fill in the actual list with

     *   the property symbols that we matched; these values are only

     *   meaningful if we return true to indicate a match.  

     */

    int match_template(const class CTcObjTemplateItem *tpl_head,

                       class CTcObjTemplateInst *src, size_t src_cnt);

    /* parse property definition within an object */

    void parse_obj_prop(int *err, class CTPNStmObject *obj_stm, int replace,

                        class CTcSymMetaclass *meta_sym,

                        struct tcprs_term_info *term_info,

                        struct propset_def *propset_stack, int propset_depth,

                        int enclosing_obj_is_nested);

    /* parse a class definition */

    class CTPNStmTop *parse_class(int *err);

    /* parse a 'modify' definition */

    class CTPNStmTop *parse_modify(int *err);

    /* parse a 'replace' definition */

    class CTPNStmTop *parse_replace(int *err);

    /* parse a 'property' statement */

    void parse_property(int *err);

    /* parse an 'export' statement */

    void parse_export(int *err);

    /* add an export for the given symbol; returns the new export record */

    class CTcPrsExport *add_export(const char *sym, size_t sym_len);

    /* add an export record to our list */

    void add_export_to_list(class CTcPrsExport *exp);

    /* get the head of the export list */

    class CTcPrsExport *get_exp_head() const { return exp_head_; }

    /*

     *   Parse a function or method body, starting with the formal parameter

     *   list.  If 'eq_before_brace' is set, we expect an '=' before the

     *   opening brace of the code body, and we allow the expression syntax,

     *   where an expression enclosed in parentheses can be used.

     *   'self_valid' indicates whether or not 'self' is valid in the context

     *   of the code being compiled; for an object method, 'self' is usually

     *   valid, while for a stand-alone function it isn't.  

     */

    class CTPNCodeBody *parse_code_body(int eq_before_brace, int is_obj_prop,

                                        int self_valid,

                                        int *p_argc, int *p_varargs,

                                        int *p_varargs_list,

                                        class CTcSymLocal **

                                            p_varargs_list_local,

                                        int *has_retval, int *err,

                                        class CTcPrsSymtab *local_symtab,

                                        tcprs_codebodytype cb_type,

                                        struct propset_def *propset_stack,

                                        int propset_depth,

                                        struct CTcCodeBodyRef *enclosing,

                                        class CTcFormalTypeList **type_list);

    /* parse a nested code body (such as an anonymous function) */

    class CTPNCodeBody *parse_nested_code_body(

        int eq_before_brace,

        int self_valid,

        int *p_argc, int *p_varargs,

        int *p_varargs_list,

        class CTcSymLocal **p_varargs_list_local,

        int *has_retval, int *err,

        class CTcPrsSymtab *local_symtab,

        tcprs_codebodytype cb_type);

    /* parse a formal parameter list */

    void parse_formal_list(int count_only, int opt_allowed,

                           int *argc, int *opt_argc, int *varargs,

                           int *varargs_list,

                           class CTcSymLocal **varargs_list_local,

                           int *err, int base_formal_num,

                           int for_short_anon_func,

                           class CTcFormalTypeList **type_list);

    /*

     *   Parse a compound statement.  The caller must skip the opening

     *   '{'; on return, we'll have skipped the closing '}'.

     *   enclosing_symtab is the enclosing scope's symbol table, and

     *   local_symtab is the symbol table for the new scope within the

     *   compound statement; if the caller has not already allocated a new

     *   symbol table for the inner scope, it should simply pass the same

     *   value for both symbol tables.

     *   

     *   'enclosing_switch' is the immediately enclosing switch statement,

     *   if any.  This is only set when we're parsing the immediate body

     *   of a switch statement.  

     */

    class CTPNStmComp *parse_compound(int *err, int skip_lbrace,

                                      class CTPNStmSwitch *enclosing_switch,

                                      int use_enclosing_scope);

    /* parse a local variable definition */

    class CTPNStm *parse_local(int *err);

    /* parse a local initializer */

    class CTcPrsNode *parse_local_initializer(class CTcSymLocal *lcl,

                                              int *err);

    /*

     *   Parse an individual statement.

     *   

     *   If 'compound_use_enclosing_scope' is true, then if the statement

     *   is a compound statement (i.e., the current token is a left

     *   brace), the compound statement will use the current scope rather

     *   than creating its own scope.  Normally, a compound statement

     *   establishes its own scope, so that local variables can hide

     *   locals and parameters defined outside the braces.  In certain

     *   cases, however, locals defined within the braces should share the

     *   enclosing scope: at the top level of a function or method, for

     *   example, the formal parameters and the locals within the function

     *   body go in the same scope, so the function body's compound

     *   statement doesn't create its own scope.  

     */

    class CTPNStm *parse_stm(int *err, class CTPNStmSwitch *enclosing_switch,

                             int compound_use_enclosing_scope);

    /* parse a 'case' label */

    class CTPNStm *parse_case(int *err,

                              class CTPNStmSwitch *enclosing_switch);

    /* parse a 'default' label */

    class CTPNStm *parse_default(int *err,

                                 class CTPNStmSwitch *enclosing_switch);

    /* parse an 'if' statement */

    class CTPNStm *parse_if(int *err);

    /* parse a 'return' statement */

    class CTPNStm *parse_return(int *err);

    /* parse a 'for' statement */

    class CTPNStm *parse_for(int *err);

    /* parse a 'foreach' statement */

    class CTPNStm *parse_foreach(int *err);

    /* parse a 'break' statement */

    class CTPNStm *parse_break(int *err);

    /* parse a 'continue' statement */

    class CTPNStm *parse_continue(int *err);

    /* parse a 'while' */

    class CTPNStm *parse_while(int *err);

    /* parse a 'do-while' */

    class CTPNStm *parse_do_while(int *err);

    /* parse a 'switch' */

    class CTPNStm *parse_switch(int *err);

    /* parse a 'goto' */

    class CTPNStm *parse_goto(int *err);

    /* parse a 'try' */

    class CTPNStm *parse_try(int *err);

    /* parse a 'throw' */

    class CTPNStm *parse_throw(int *err);

    /*

     *   Create a symbol node.  We'll look up the symbol in local scope.

     *   If we find the symbol in local scope, we'll return a resolved

     *   symbol node for the local scope item.  If the symbol isn't

     *   defined in local scope, we'll return an unresolved symbol node,

     *   so that the symbol's resolution can be deferred until code

     *   generation. 

     */

    class CTcPrsNode *create_sym_node(const textchar_t *sym, size_t sym_len);

    /*

     *   Get the source file descriptor and line number for the current

     *   source line.  We note this at the start of each statement, so

     *   that a statement node constructed when we finish parsing the

     *   statement can record the location of the start of the statement. 

     */

    class CTcTokFileDesc *get_cur_desc() const { return cur_desc_; }

    long get_cur_linenum() const { return cur_linenum_; }

    /*

     *   Get/set the current enclosing statement.  An enclosing statement

     *   is a 'try' or 'label:' container.  At certain times, we need to

     *   know the current enclosing statement, or one of its enclosing

     *   statements; for example, a 'break' with a label must find the

     *   label in the enclosing statement list to know where to jump to

     *   after the 'break', and must also know about all of the enclosing

     *   'try' blocks our to that point so that it can invoke their

     *   'finally' blocks.  

     */

    class CTPNStmEnclosing *get_enclosing_stm() const

        { return enclosing_stm_; }

    class CTPNStmEnclosing *set_enclosing_stm(class CTPNStmEnclosing *stm)

    {

        class CTPNStmEnclosing *old_enclosing;

        /* remember the current enclosing statement for a moment */

        old_enclosing = enclosing_stm_;

        /* set the new enclosing statement */

        enclosing_stm_ = stm;

        /* 

         *   return the previous enclosing statement - this allows the

         *   caller to restore the previous enclosing statement upon

         *   leaving a nested block, if that's why the caller is setting a

         *   new enclosing statement 

         */

        return old_enclosing;

    }

    /* get the current code body reference object */

    struct CTcCodeBodyRef *get_cur_code_body() const

        { return cur_code_body_; }

    /* determine if 'self' is valid in the current context */

    int is_self_valid() const { return self_valid_; }

    /* 

     *   get/set the 'self' reference status - this indicates whether or not

     *   'self' has been referenced, explicitly via the 'self'

     *   pseudo-variable or implicitly (such as via a property reference or

     *   method call), in the code body currently being parsed 

     */

    int self_referenced() const { return self_referenced_; }

    void set_self_referenced(int f) { self_referenced_ = f; }

    /* 

     *   get/set the full method context reference status - this indicates

     *   whether or not any of the method context variables (self,

     *   targetprop, targetobj, definingobj) have been referenced, explicitly

     *   or implicitly, in the code body currently being parsed 

     */

    int full_method_ctx_referenced() const

        { return full_method_ctx_referenced_; }

    void set_full_method_ctx_referenced(int f)

        { full_method_ctx_referenced_ = f; }

    /* 

     *   Get/set the flag indicating whether or not the local context of the

     *   outermost code body needs 'self'.  The outer code body needs 'self'

     *   in the local context if any lexically nested code body requires

     *   access to 'self'.  

     */

    int local_ctx_needs_self() const { return local_ctx_needs_self_; }

    void set_local_ctx_needs_self(int f) { local_ctx_needs_self_ = f; }

    /* 

     *   Get/set the flag indicating whether or not the local context of the

     *   outermost code body needs the full method context stored in its

     *   local context.  The outer code body needs the full context stored if

     *   any lexically nested code body requires access to any of the method

     *   context variables besides 'self' (targetprop, targetobj,

     *   definingobj).  

     */

    int local_ctx_needs_full_method_ctx() const

        { return local_ctx_needs_full_method_ctx_; }

    void set_local_ctx_needs_full_method_ctx(int f)

        { local_ctx_needs_full_method_ctx_ = f; }

    /*

     *   Add a code label.  This creates a 'goto' symbol table for the

     *   current code body if one doesn't already exist 

     */

    class CTcSymLabel *add_code_label(const class CTcToken *tok);

    /*

     *   Set the debugger local symbol table.  Returns the previous symbol

     *   table so that it can be restored if desired.  

     */

    class CTcPrsDbgSymtab *set_debug_symtab(class CTcPrsDbgSymtab *tab)

    {

        class CTcPrsDbgSymtab *old_tab;

        /* remember the original for later use */

        old_tab = debug_symtab_;

        /* set the new table */

        debug_symtab_ = tab;

        /* return the original */

        return old_tab;

    }

    /*

     *   given a (1-based) object file symbol index, get the symbol 

     */

    class CTcSymbol *get_objfile_sym(uint idx)

        { return (idx == 0 ? 0 : obj_sym_list_[idx - 1]); }

    /* 

     *   given a 1-based object file symbol index, get an object symbol;

     *   if the symbol does not refer to an object, we'll return null 

     */

    class CTcSymObj *get_objfile_objsym(uint idx);

    /* 

     *   given an object file (1-based) object file dictionary index, get

     *   the dictionary entry 

     */

    class CTcDictEntry *get_obj_dict(uint idx)

        { return (idx == 0 ? 0 : obj_dict_list_[idx - 1]); }

    /* add a dictionary object loaded from the object file */

    void add_dict_from_obj_file(class CTcSymObj *sym);

    /* add a symbol object loaded from the object file */

    void add_sym_from_obj_file(uint idx, class CTcSymbol *sym);

    /*

     *   Get the next object file symbol index.  Object file symbol

     *   indices are used to relate symbols stored in the object file to

     *   the corresponding symbol object in memory when the object file is

     *   reloaded.  

     */

    uint get_next_obj_file_sym_idx()

    {

        /* return the next index, consuming the index value */

        return obj_file_sym_idx_++;

    }

    /*

     *   Get the next object file dictionary index.

     */

    uint get_next_obj_file_dict_idx()

    {

        /* return the next index, consuming the index value */

        return obj_file_dict_idx_++;

    }

    /* 

     *   add an anonymous function or other anonymous top-level statement

     *   to our list of nested top-level statements

     */

    void add_nested_stm(class CTPNStmTop *stm);

    /* add an anonymous object to our list */

    void add_anon_obj(class CTcSymObj *obj);

    /* add a non-symbolic object ID */

    void add_nonsym_obj(tctarg_obj_id_t id);

    /* determine if the current code body has a local context */

    int has_local_ctx() const { return has_local_ctx_ != 0; }

    /* get the local context variable number */

    int get_local_ctx_var() const { return local_ctx_var_num_; }

    /* set up a local context */

    void init_local_ctx();

    /* allocate a context variable property ID */

    tctarg_prop_id_t alloc_ctx_var_prop();

    /* 

     *   allocate a context variable index - this assigns an array index

     *   for a context variable within the context object that contains

     *   the shared locals for its scope 

     */

    int alloc_ctx_arr_idx();

    /* allocate a local for use as a local context holder */

    int alloc_ctx_holder_var() { return alloc_local(); }

    /* get the maximum number of locals required in the function */

    int get_max_local_cnt() const { return max_local_cnt_; }

    /* 

     *   find a grammar production symbol, adding a new one if needed,

     *   returning the grammar production list entry for the object 

     */

    class CTcGramProdEntry *declare_gramprod(const char *sym, size_t len);

    /* find a grammar production list entry for a given object */

    class CTcGramProdEntry *get_gramprod_entry(class CTcSymObj *sym);

    /* find a grammar production symbol, adding a new one if needed */

    class CTcSymObj *find_or_def_gramprod(const char *txt, size_t len,

                                          class CTcGramProdEntry **entryp);

    /* allocate a new enumerator ID */

    ulong new_enum_id() { return next_enum_id_++; }

    /* get the number of enumerator ID's allocated */

    ulong get_enum_count() const { return next_enum_id_; }

    /* 

     *   Look up a property symbol, adding it if not yet defined.  If the

     *   symbol is defined as another type, we'll show an error if

     *   show_err is true, and return null.  

     */

    CTcSymProp *look_up_prop(const class CTcToken *tok, int show_err);

    /* get the '+' property for tracking the location graph */

    CTcSymProp *get_plus_prop() const { return plus_prop_; }

    /*