\font\ninerm=cmr9
\let\mc=\ninerm % medium caps for names like PASCAL
\def\MWEB{{\tt MWEB}}
\def\PASCAL{{\mc PASCAL}}
\def\[{\ifhmode\ \fi$[\![$}
\def\]{$]\!]$\ }
\def\<{$\langle\,$}
\def\>{$\,\rangle$}
\def\sec{{\tensy x}}
\def\title{Tablehandler Definition Module}

@* Table Handler.
This module is a general-purpose symbol table handler. 
It is based on the TableHandler module in
Niklaus Wirth's {\it Programming in Modula-2}. 
It allows a calling program to build a table of symbols with a cardinal value
associated with each.
This is the definition module; the
implementation module is in a separate source file.
@p 
definition @+module table_handler ;
@<Export List@>@;
const @<Constants of the module@>@;
type @<Global types@>@;

@ These are the symbols we are exporting. They are the only ones visible 
outside of the module.
@<Export List@>=

export qualified
	symbol_length ,
        undefined_symbols_in_table,
        symbol_string_ptr,
        symbol_string,
        search_symbol_table,
        delete_symbol_table,
        create_symbol_table,
        set_error_handler,
        table_proc,
        error_proc,
        symbol_table_error_code,
        symbol_table  ,
        symbol_is_defined,
        set_value_of_symbol,
        get_value_of_symbol;


@ @<Constants of the module@>=
@!symbol_length = 200 ;

@ The following types are defined here, rather than in the implementation
module, because they are either needed for the procedure definitions which
follow or are to be exported or both. |symbol_table| is defined as an
{\it opaque} type, since the details of its structure are hidden. The complete
definition appears in the implementation module.
@<Global types@>=
@!symbol_table  ; @/
@!symbol_table_error_code = 
      (@!undefined_symbol,@!duplicate_symbol,@!memory_exhausted);@/
@!symbol_string = array [0..symbol_length-1] of char ;@/
@!symbol_string_ptr = pointer to  symbol_string ;@/

@ This procedure is used to create a symbol table. 
An error procedure can be
supplied by the user in case errors occur during symbol manipulation.
Case-sensitivity is optional for table keys. If |case_sens=true| then JUNK and
junk are considered different symbols.
@p
procedure create_symbol_table(var @!the_table: symbol_table  ; 
       @!case_sens : boolean; @!user_error_routine :error_proc);
@ An error procedure can be
supplied by the user in case errors occur during symbol manipulation.
This procedure is used to change the error handler for a particular table
after it has been created.
@p
procedure set_error_handler(@!the_table: symbol_table ; 
       @!user_error_routine :error_proc);
@ This function procedure checks the integrity of 
the table by searching for entries that have been referenced, 
but never defined.  If undefined symbols are found,
the user-supplied error routine is called for each one and a value of |true|
is returned for the procedure.
@p
procedure undefined_symbols_in_table(@!the_table: symbol_table; 
      @!undefined_symbol_handling_routine :error_proc) : boolean;
@ Modula-2 allows a mechanism whereby a procedure, complete with parameters,
can be defined as a data type and stored in memory or passed like any other 
parameter to another procedure. We define a procedure type |table_proc|,
which is used in the definition of |search_symbol_table| below. The user
is allowed to specify his own procedure to perform some action on each entry
in the table. The value store in the entry, a pointer to the symbol, and a 
boolean variable indicating the symbol is defined are passed as parameters
@<Global types@>=
@!table_proc = @+procedure(cardinal,symbol_string_ptr,boolean);
@ This procedure performs a
user-provided operation on every entry in the table.
As each entry is processed, a user-provided procedure is called, and the 
value stored with this name is passed as a parameter.  The 
user procedure is free to
perform any operation it wishes.  
The nodes are processed alphabetically.
@p
procedure search_symbol_table(@!the_table: symbol_table;
     @+@!user_action_routine : table_proc) ;

@ We define a error handler procedure type, which is called whenever an error
occurs. When one of these procedures is called, the type of error and the 
symbol involved are passed as parameters.
@<Global types@>=
@!error_proc = @+procedure(symbol_table_error_code,array of char);
@ This is the main symbol table lookup procedure, the one visible to the
calling program. If the entry does not exist it is created.
@p
procedure get_value_of_symbol ( @!the_table: symbol_table;
@!target_symbol : array of char ; 
@+@!this_is_a_definition : boolean ; 
@+var@+ @+@!string_ptr : symbol_string_ptr) : cardinal ;

@ We provide a procedure to set the table entry to a specific value.
@p
procedure set_value_of_symbol ( @!the_table: symbol_table;
@!target_symbol : array of char ; 
@+@!this_is_a_definition : boolean ; 
@+var@+ @+@!string_ptr : symbol_string_ptr;the_val : cardinal) ;

@ We provide a function procedure to determine if a particular symbol has been
defined.
@p
procedure symbol_is_defined ( @!the_table: symbol_table;
@!target_symbol : array of char ) : boolean ;
@ 
This procedure is used to delete the
table and free the memory allocated to it.
@p
procedure delete_symbol_table(var @!the_table: symbol_table);
@ Here is the end of the definition module.
@p
end table_handler.

@* Index.