Documenting structures created by the parser

During the parser run the HBasic parser creates some information about the HBasic source. This document should describe this structures and list them step by step. You may find the actual definitions of the structures in the file structs.h.

One important documentation tree describes the parts that the compiler has found. It starts with the normal tree of documents that the project manager stores about the current project:
Project group = list of projects
Project = list of documents
Each document creates a pointer to a structure of type FORM_DESC (module_form) which holds the pointer to further information about the source code and the GUI for the form.

FORM_DESC structure

Description of one source module and depending structures.
localvar_offset Offset for the next formlocal variable that will be created.
form_number Unique integer number (zero based) that will be used to identify the form in a table of form descriptions at runtime.
first_formlocal_var (struct VAR_DESC) Pointer to first variable description. This is the start of a list of variable descriptions (see VAR_DESC structure).
first formlocal_sub (struct SUB_DESC) Pointer to first subroutine description. This is the start of a list of subroutine descriptions (see SUBDESC structure).
inherited_form If the current source will be inherited from another source inherited_form points to the description of the base class description.
first_parlist (struct PAR_FORM_LIST) Beside the subroutine declarations described in the list starting with first_formlocal_var the parser uses an additional list of subroutine descriptions in parsing order. This will be stored as pointer in first_parlist.
first_form_event (struct EVENT_DESC) Pointer to first event description. This is the start of a list of event descriptions (see EVENT_DESC structure).
next_form_header Pointer to next form description in list ??
source_ptr (CBasicDocument) This points back to the CBasicDocument class that holds additional information about the depending form and source module.

VAR_DESC structure

The VAR_DESC structure will be generated when the parser find a variable declaration like a "Dim" statement. If the parser finds an identifier it searches through the VAR_DESC structures to find the type of the identifier. In every position in a HBasic source there are at least three lists of VAR_DESC structures.
Global variables valid for all source files
Variables local in the current source Cleared when the parser starts with a new form, source or other module.
Variables and parameter local in the current subroutine. Cleared everytime the compiler starts to parse a new subroutine.

The VAR_DESC structure stores the following information for a variable.
entry_length Used for entries that store additional optional information behind the VAR_DESC structure.
offset Offset of the variable in the memory block of all variables at runtime. Every variable has a unique offset to address the variable memory ar runtime.
typeflag Flags to mark special properties of the variable
type number that describes the type of the variable (integer, double ...). See defines.h for legal values.
subtype used for component access etc. Has been replaced by sub_desc_ptr
sub_desc_ptr Pointer to structures that descibes details of variable type if needed. If for example the identifier is a call to a function the sub_desc_ptr points to the description of the called subroutine.
var_range Describes the range of the variable (global, formlocal, sublocal)
modifier Flags to mark modifiers set with the variable name like PUBLIC, PRIVATE... (currently not used)
call_event_list used ??
subdesc old form of subdescription (used??)
next_var Pointer to next variable declaration in depending list (global, sublocal, parameter ...)

SUB_DESC structure

The SUB_DESC structure is a description for a subroutine definition in the source code. Since there may be more than one subroutine definition for the same subroutine name (polymoph) but different parameter lists there is a substructure (PAR_DESC_LIST) to describe one or more parameter lists for a subroutine name. Each subroutine declaration will be saved with a matching PAR_DESC_LIST. If there are two or more different parameter lists for the same subroutine name there will be two or more PAR_DESC_LIST descriptions.

SUB_DESC structure
name Name of the subroutine
sub_type used ??
par_desc_list Pointer to first parameter description list
next_sub_header Pointer to next subroutine description

PAR_DESC_LIST structure

property_type 0=normal sub 1=property get  2=property let
code_offset code address for interpreter or label number for compiler
localvar_offset Offset for next variable in formlocal variable definitions
sub_ptr Pointer to depending SUB_DESC structure
last_unref_call If a function will be called before the code position of the code is available this is a list of pointer to the addresses where the starting code position of the subroutine must be added later.
par_list Pointer to list of parameters for this function
var_list Pointer to list of sublocal variables for this subroutine
next_parlist Pointer to next PAR_DESC_LIST description.
next_form_parlist Pointer to next PAR_DESC_LIST in parsing order for current form (??)
end_header_code_ptr End of code for current subroutine (used for debuggin purposes)
end_header_line_pos (??)
preread_token (??)
return_value Pointer to variable description for return value of subroutine.

EVENT_DESC structure

If you use events in your HBasic class sourcefiles there must be an event definition at the beginning of the class source and then you may use this event within a RAISE statement later. HBasic stores the information it finds in the event definition in the EVENT_DESC structure.
name Name of the event
par_list List of parameters used when the event will be raised
evt_offset Each event destination will at runtime be stored in the memory block of the component at a unique location. This offset describes the offset of this address within the component memory starting from the beginning of the memory block.
next_event Next event in list of event descriptions for the current form or module

TYPE_DESC structure

The TYPE_DESC structure is used to describe types for variables that have been defined within the sourcecode of the current project. This means if the user has used for example an ENUM definition like


the values MONDAY ... will be stored as constants but the typename WEEKDAYS may be used in further variable declarations like

Dim myvar As WEEKDAYS

Therefore HBasic creates an additional structure of type TYPE_DESC which in this case holds the description of the type WEEKDAYS.
type_id Unique id to identify this type in variable descriptions
type_name Name of the type
type Kind of type (see defines.h (TYPE_*) for list of values)
entry_length Length of memory block that is used to store one entry of this type
description  (??)
next Pointer to next type description in type definition list