6. Package for work with source code positions

The compilers often use internal representation which stores source code positions. Here package `position' which serves to support information about source positions of compiled files taking into account all included files is suggested.

The strategy of the package usage can be follows. Function `initiate_positions' is called by the first. After that function `start_file_position' is called when a file is opened for compilation as source or included file. Members `line_number' and `column_number' of variable `current_position' are modified correspondingly during given file compilation. The value of `current_position' can be stored into internal representation for usage for output messages on the following passes. Function `finish_file_position' is called when a processed file is closed. Function `finish_positions' may be called after all processing a source file.

The package uses packages `vlobject' and `objstack' which use package `allocate'. The interface part of the package is file `position.h'. The implementation part is file `position.c'. The interface contains the following external definitions:

Type `position_t'

is structure which describes a file position. The structure has the following members:

Member `file_name'

is name of file to which given position belongs.

Members `line_number', `column_number'

are source line and column corresponding to given position.

Member `path'

is pointer to another position structure representing position of include-clause which caused immediately given file compilation.

Variable `no_position'

has value of type `position_t' has members with values equals to zero or `NULL'. The value does not correspond to concrete file position.

Variable `current_position'

has value which is current file position.

Function `initiate_positions'

        `void initiate_positions (void)'
        

initiates the package. Value of variable `current_position' becomes equal to `no_position'.

Function `finish_position'

        `void finish_positions (void)'
        

frees all memory allocated during package work.

Function `position_file_inclusion_level'

        `int position_file_inclusion_level (position_t position)'
        

returns level of inclusion of file of position given as the function parameter. The level numbers are started with zero for positions corresponding non-included files and for positions which does not correspond to concrete file.

Function `start_file_position'

        `void start_file_position (const char *file_name)'
        

copys position structure (by dynamic memory allocation) in variable `current_position' and sets up new values of members of `current_position'. Values of members `file_name', `line_number', `column_number', and `path' become equal to the function parameter value, 1, 0, and pointer to the copied structure. Values of `current_position' during different calls of the function must be different (e.g. different columns or lines), i.e. positions of different include-clauses must be different.

Function `finish_file_position'

        `void finish_file_position (void)'
        

recovers previous value of variable `current_position', more exactly sets up the variable by structure to which the variable member `path' refers.

Function `compare_positions'

        `int compare_positions (position_t position_1,
                                position_t position_2)'
        

compares two positions given by parameters of type `position_t' and returns -1 (if the first position is less than the second), 0 (if the first position is equal to the second) or 1 (if the first position is greater than the second). The order of positions is lexicographic.