# Data types

The file `quadcode/types.tcl` contains code that manages data types.
Internally to the quadcode engine (the code issuer has a simpler
model), the data type of quadcode values is identified by a bitmask
of type codes that are OR-ed together to represent the possible set
of strings that the value may contain. These code appear at the top
of the `types.tcl` file and will not be repeated here.

There are a few special bits that do not actually represent value types.

`IMPURE` -

  The value may have a noncanonical string representation, which
  must be preserved.
	
`BOTTOM` - 

  Represents a data inconsistency, a value whose origin is
  unknown, a value assigned in unreachable code, or the result of an
  unanalyzed procedure. It's a bug if BOTTOM shows up after all
  quadcode analysis is complete.
	
   

# The quadcode specializer

The *specializer* (`quadcode/specializer.tcl`) is the top-level class
that orchestrates generation of optimized quadcode from Tcl
procedures. It's ordinarily a singleton, instantiated once per
compilation.

The ordinary sequence of operation with the specializer is:

0. Instantiate the specializer.
1. For each procedure that the caller intends to compile, call
   the `register` method, passing the name of the procedure. Internally,
   the name will be fully qualified, and the origin will be resolved.
2. For each cluster of argument types that is needed to any invocation
   of a procedure, call the `require` method giving the procedure and
   the cluster of argument types. For procedures that are to be exported
   to Tcl through thunk generation, all the argument types will be
   `$::quadcode::dataType::STRING`.
3. Once all invocations have been registered, call `computeTypes`. (This
   method is badly named. Its function had once been only to compute
   the parameter and return types of procedures, but it now does the
   bulk of the work of quadcode optimization.)
4. Call the `instancesNeeded` method to retrieve the list of typed
   procedure instances that are being compiled.
5. For each instance returned, the `makeInstance` method will complete
   the quadcode analysis and return a four-element list:
      * the return type of the procedure - a type code as above
	  * a list of argument types of the procedure - again, as type codes
	  * a dictionary whose keys are value names in the quadcode and
	    whose values are the typecodes for the types of the named values.
	  * a list of quadcode instructions for the code issuer.
	  
In addition to the methods above, the specializer exports a collection
of service methods:

* `compiling`

   Accepts a procedure name and returns 1 if the procedure has been
   registered and 0 otherwise.

* `diagnostic`

   Accepts a long list of parameters: procedure name, argument type list,
   source file name, source line number, severity (`fatal`, `error`,
   `warning`, `caution`, `observe`, `note`, or `debug`), error message
   (with possible % substituents) and arguments for the % substituents.
   Records the diagnostic message for later display. On `error` or `fatal`
   problems, also marks the procedure as `failed`, which will keep it and
   its dependents from being returned by `instancesNeeded.`
   
* `frameEffect`

  Accepts a procedure and the list of its argument types. Returns a
  list describing the procedure's effect on the call frame and global
  state.

* `printDiagnostics`

  Prints to the standard error (or to a channel passed as a parameter)
  the diagnostic messages accumulated by the `diagnostic` method.

* `resultType`

  Accepts a procedure and the list of its argument types. Returns a list
  describing the procedure's result type as currently known. (The result
  type may be incomplete.) May also add an interprocedural dependency,
  and schedule the dependent procedure for analysis.