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