DEFINITION MODULE Dictman; 

(*
    Title    :  Dictionary management routines
    LastEdit :  Thu Apr 19 16:24:53 1984
    Author   :  Graham Toal
    Acorn Computers VLSI Design Aids Group
*)

(*------------------------------------------------------------------------*)
(*  These procedures provide a clean interface to a symbol table          *)
(*  manager.  The implementation of the symbol table is a PDL; this can   *)
(*  be assumed by any callers.  Three specific interfaces are offered:    *)
(*                                                                        *)
(*    1) Strings 2) Integers & 3) PROCs.                                  *)
(*                                                                        *)
(*  These were found to be the most commonly accessed items in the trial  *)
(*  implementation.  Special entries can be made by using type WORD,      *)
(*  and performing explicit type-casts on insertion and removal.          *)
(*                                                                        *)
(*     This package offers a simple way of writing command interpreters,  *)
(*  information-passing between modules, and simple database lookup.      *)
(*                                                                        *)
(*  The package can be used for data vetting by entering the names        *)
(*  of valid data items, but with no corresponding value field, and       *)
(*  merely testing the success of the lookup.                             *)
(*                                                                        *)
(*     A RESERVED ENTRY "***Default" may be entered in any dictionary     *)
(*  which will be returned in the event that a lookup fails.  If there    *)
(*  is no default entry, an error will be returned when searching for     *)
(*  a key which does not exist.                                           *)
(*                                                                        *)
(*     Errors go via the Utils error package, and set the variables       *)
(*  Utils.Error and Utils.Warning. The printing of error messages may be  *)
(*  suppressed by setting Utils.SuppressError to TRUE.                    *)
(*                                                                        *)
(*------------------------------------------------------------------------*)


(*------------------------------------------------------------------------*)
(*  An example use of the package is:                                     *)
(*                                                                        *)
(*  Dictman.NewDict ("commands");                                         *)
(*     Dictman.EnterProc ("commands", "help",    HelpProc)                *)
(*     Dictman.EnterProc ("commands", "doodle",  DoodleProc)              *)
(*     Dictman.EnterProc ("commands", "***Default", ERRORproc)            *)
(*                                                                        *)
(*  LOOP                                                                  *)
(*     Utils.Readln ("Command: ", CommandLine)                         *)
(*     AnyProc := Dictman.FindItem (CommandLine)                          *)
(*     AnyProc ()                                                         *)
(*  END                                                                   *)
(*                                                                        *)
(*------------------------------------------------------------------------*)


(*------------------------------------------------------------------------*)
(*  The ForAll procedures are accessed as would be expected:              *)
(*                                                                        *)
(*     Dictman.NewDict ("help");                                          *)
(*        Dictman.EnterItem ("help", "doodle", "A Doodle procedure")      *)
(*        Dictman.EnterItem ("help", "help",   "Give this information")   *)
(*                                                                        *)
(*  PROCEDURE GiveHelp (Dict, Command, Info :ARRAY OF CHAR);              *)
(*  BEGIN                                                                 *)
(*     WriteF2 ("%S: %S*N", H(Command), H(Info))                          *)
(*  END GiveHelp                                                          *)
(*                                                                        *)
(*  PROCEDURE HelpProc ();                                                *)
(*  BEGIN                                                                 *)
(*     WriteS ("Help info 1 Apr 1984*N);                                  *)
(*     Dictman.ForAllStrings (GiveHelp)                                   *)
(*  END HelpProc;                                                         *)
(*------------------------------------------------------------------------*)



FROM SYSTEM IMPORT WORD;

IMPORT Utils;

EXPORT QUALIFIED

   FuzzySearch,

   NewDict,

   Swap,
   
   EnterString, EnterInteger, EnterProc, EnterWord,

   FindString, FindInteger, FindProc, FindWord,

   DeleteString, DeleteInteger, DeleteProc, DeleteWord,
   
   ForAllStrings, ForAllIntegers, ForAllProcs, ForAllWords;

TYPE
   StringPROC  = PROCEDURE (ARRAY OF CHAR, ARRAY OF CHAR, ARRAY OF CHAR)
                 :BOOLEAN;
   IntegerPROC = PROCEDURE (ARRAY OF CHAR, ARRAY OF CHAR, INTEGER)
                 :BOOLEAN;
   ProcPROC    = PROCEDURE (ARRAY OF CHAR, ARRAY OF CHAR, PROC)
                 :BOOLEAN;
   WordPROC    = PROCEDURE (ARRAY OF CHAR, ARRAY OF CHAR, WORD)
                 :BOOLEAN;

VAR
   FuzzySearch :BOOLEAN;

PROCEDURE NewDict (Dict :ARRAY OF CHAR);

PROCEDURE Swap (Dict, Entry1, Entry2 :ARRAY OF CHAR);

PROCEDURE EnterString  (Dict, Name :ARRAY OF CHAR; Value :ARRAY OF CHAR);
PROCEDURE EnterInteger (Dict, Name :ARRAY OF CHAR; Value :INTEGER);
PROCEDURE EnterProc    (Dict, Name :ARRAY OF CHAR; Value :PROC);
PROCEDURE EnterWord    (Dict, Name :ARRAY OF CHAR; Value :WORD);

PROCEDURE FindString  (Dict, Name :ARRAY OF CHAR) :Utils.STRptr;
PROCEDURE FindInteger (Dict, Name :ARRAY OF CHAR) :INTEGER;
PROCEDURE FindProc    (Dict, Name :ARRAY OF CHAR) :WORD;
PROCEDURE FindWord    (Dict, Name :ARRAY OF CHAR) :WORD;
                 
PROCEDURE DeleteString  (ExactDict, ExactName :ARRAY OF CHAR);
PROCEDURE DeleteInteger (ExactDict, ExactName :ARRAY OF CHAR);
PROCEDURE DeleteProc    (ExactDict, ExactName :ARRAY OF CHAR);
PROCEDURE DeleteWord    (ExactDict, ExactName :ARRAY OF CHAR);

PROCEDURE ForAllStrings  (Dict : ARRAY OF CHAR; Apply: StringPROC);
PROCEDURE ForAllIntegers (Dict : ARRAY OF CHAR; Apply: IntegerPROC);
PROCEDURE ForAllProcs    (Dict : ARRAY OF CHAR; Apply: ProcPROC);
PROCEDURE ForAllWords    (Dict : ARRAY OF CHAR; Apply: WordPROC);

END Dictman.
