Parser structures

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.

name
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 comp.property 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

ENUM WEEKDAYS
   MONDAY
   TUESDAY
   ...
END ENUM

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

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 comp.property 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 ...)

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

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