Front End
---------

1. Lexing and Parsing

Parse/
  lexing and parsing, producing ast (concrete syntax trees)

  ast/
    "syntax trees" (really concrete, in contrast to absyn, which is
    the true abstract syntax)
      ast.sig/sml       -- the syntax tree types
      astutil.sig/sml   -- some utility functions

  lex/
    lexical analysis (via ML-Lex)
      ml.lex            -- the lexer spec
      tokentable.sml    --

  parse/
    parsing (via ML-Yacc)
      ml.grm            -- grammar spec

  main/
    control flags and parser driver functions.
    lexer/parser combination translates input stream into ast trees
      parser.sig/sml	-- parser modules initialization, driver function
      parsercontrol.sml -- flags controlling various syntax features
      smlfile.sml	-- top level parsing functions


2. Elaboration
   * abstract syntax
   * static environments
   * translation from ast to abstract syntax and static environment (elaboration)
   * core type checking and inference, overloading resolution
   * modules and signatures, signature matching, functor application
   * code found in directories Semant, ElabData, Elaborator

[***
 What is the distinction between Basics and Semant?  Should these be
 merged?  How about ElabData?  Some of these files (Semant/types) might
 also fit there.

 We have Basics/*, Semant/basics, ElabData/basics, and Elaborator/basics.
 What is the rationale telling us what goes in each of these places?

 This complex organization seems to be partially motivated by the goal
 of separating out any features that are SML/NJ-specific from the generic
 SML stuff.
***]

Basics

  mlcomp/
    basic front-end data structures (e.g. symbols, stamps, ...)
      symbol.sig/sml      -- symbols (should be in ElabData?)
      fastsymbol.sig/sml  -- fast symbols (should be in ElabData?)
      fixity.sml	  -- fixity properties (should be in ElabData)
      persstamps.sig/sml  -- persistant stamps (16 byte vectors)
      persmap.sml	  -- finite maps over pids (persistent stamps)
      pidenv.sig/sml	  -- environments using pid (persistant stamps) as keys
      compileexn.sml	  -- Compile exception (where used?)

  miscutil/  
    some left-over stuff (why not in MiscUtil?  may be redundant)
      intstrmap.sig/sml   -- int/string maps for use in environments;
			     appears redundant with IntStrMapV defined in
			     Env (ElabData/basics/env.sml)
			     used in Tuples, ElabCore, Parse/lex/tokentable.sml.
  errormsg/
    error messages
      errormsg.sig/sml    -- error message interface

  source/
    -- the source abstraction + file pathnames
      pathnames.sig/sml   -- file path names
      source.sig/sml      -- input source datastructure
      sourcemap.sig/sml   -- map character positions in source to line no/column
			     supporting #line "declaration"

  print/
    -- some printing support (more elsewhere?)
      pp-wrapper.sml	  -- implements old PP interface using new SML/NJ Lib PP
      printutil.sig/sml   -- some print utilities (uses Symbol)
      printcontrol.sml    -- print control flags; out, say functions

  stats/
      stats.sml		  -- facilities for defining timed phases

  main/
      basiccontrol.sml    -- printWarning control flag, topregistry
			     uses ControlRegistry, Controls


Semant

  basics/
    -- some "basic" stuff -- why not in Basics?
      inlinfo.sig/sml     -- inlining info (?)

  elaborate/
    -- module level, top level elaboration (why not under Elaborator?)  
      elabmod.sml         -- module level elaboration
      elabtop.sml         -- top-level elaboration

  modules/
    -- mechanisms for module elaboration.  "Entity" is the static-phase
       computation element associated with a module (a kind of expression).
       entity expressions are basically a typed lambda calculus
      evalent.sml         -- evaluation of entity expressions
      instantiate.sml     -- create a free "realization" from a signature
      instantiate-param.sml  -- like instantiate.sml, but different (how?)
      module-plists.sml   -- ???
      sigmatch.sml        -- signature matching (the type-checking of modules)

  pickle/
    -- pickling static environments (the non-"new" variants should go away?)
      pickle-sym-pid.sml
      unpickle-sym-pid.sml
      pickmod-new.sml
      unpickmod-new-sml
      rehash.sml

  statenv/
    -- hand made primitive types, constructors, etc. 
      prim.sml

  types/
    -- some types stuff [why not in ElabData/types?]
      cproto.sml
      tp-var-info.sml
      types-reformat.sml
      typecheck.sml


ElabData
  -- data structures and utilities used in elaboration

  basics/
    -- some basic data structures used in elaboration
      lambdavar.sig/sml
	lambda variables, the abstract representation of variables, used
	as roots of dynamic access chains
      access.sig/sml
	dynamic access paths
      env.sig/sml
	generic environments, mapping symbols to unspecified binding type
      stamps.sig/sml
	static identifiers, used for nominal type equivalence
      stampmap.sml
	generic finite mappings over stamps
      sympaths.sig/sml
	SymPath and InvPath: direct and inverse symbolic paths (selecting
	module components)
      ii.sml [FLINT]
	FLINT related information for inlining (why is this in the elaborator?)
      lambdavar.sig/sml
	lambda variables, the abstract representation of variables
      core-ptnum.sml
	core prim-type numbers (??? -- essentially the same as basic-ptnum.sml) 
      coresym.sml
	defines the special structure symbol "_Core" used to access certain
	special bindings (e.g Match and Bind exceptions)

  syntax/
    -- (typed) abstract syntax
      absyn.sig/sml   -- the abstract syntax types
      varcon.sig/sml  -- variable and data constructor representations
      absynutil.sml   -- utility functions for building tuple patterns and expressions

  types/
    -- representing, constructing and manipulating types
      types.sig/sml      -- the representation of SML types
      typesutil.sig/sml  -- large collection of utility functions for working with types
      tuples.sml         -- fns for constructing tuple and record types
      core-basictypes.sml -- building the primitive types and associated values

  statenv/
    -- representation and mechanism for static environments
      bindings.sig/sml   -- the basic binding forms (values, types, signatures, etc.)
      statenv.sig/sml    -- instantiate generic environments with ML bindings
      lookup.sig/sml     -- accessing symbols in environments
      genmap.sml         -- rapid modmap generation based on modtrees
      coreacc.sml        -- access components of the _Core structure
      browse.sml         -- "browsing" the static environment (???)

  modules/
    -- representation of modules
      modules.sig/sml    -- representation of modules and signatures
      moduleutil.sig/sml -- lots of utility functions for modules
      moduleid.sml       -- module identities used in Modmaps ???
      entpath.sml        -- 
      entityenv.sig/sml  -- enity environments mapping entity variables
      epcontext.sml      -- 

  main/
    -- control flags and contex parameters
      compinfo.sml       -- elaboration context parameter
      edcontrol.sig/sml  -- control flags for ElabData


Elaborator
  -- the actual elaboration

  basics/
    elabcontrol.sml    -- Elaborator control flags
    conrep.sml	       -- inferring conreps for data constructors
    debindex.sig/sml   -- [FLINT] FLINT book-keeping (move back to FLINT)
    ptnum.sml	       -- prim type numbers, augmenting ElabData/basics/core-ptnum.sml

  print/
    pputil.sig/sml     -- prettyprint utilities (generic)  [**MOVE**]
    pptype.sml	       -- prettyprint types
    ppval.sml          -- prettyprint variables and dcons
    ppmod.sml          -- prettyprint modules and signatures
    ppabsyn.sml        -- prettyprint absyn (uses PPUtil(pputil.s??),
	                  PPVal(ppval.sml), PPType(pptype.sml))
  types/
    basictypes.sig/sml -- define basic (built-in) types [MOVE to ElabData?]
    eqtypes.sml        -- equivalence of types
    unify.sml          -- type unification
    overloadlit.sml    -- overloaded numeric literals
    overload.sml       -- overloading resolution
    typecheck.sml      -- typechecking

  modules/
    evalent.sml        -- evaluate "entities" (module and type realizations)
    expandtycon.sml    -- interpret PATHtycs in entity environment
    instantiate.sml    -- free instantiation of signatures
    sigmatch.sml       -- signature matching

  elaborate/
    tyvarset.sml       -- type var sets for keeping track of type var scopes
    specialsyms.sml    -- definition of special symbols for internal use
    

3. Miscellaneous utilities

MiscUtil/
  Contains various kinds of utility programs

  bignums/
    Bignum packages. I have no clue how stable this is.

  library/
    Utility modules that are candidates for eventual
    promotion to general libraries (crc and pickling)
      crc.sml
      pickle-lib.cm
      pickle-util.sml
      unpickle-util.sml

  print/
    Pretty printing 
      ppdec.sml      -- printing top-level declarations
                        (move to Elaborator/print/ ?)
      ppobj.sml      -- print top-level values
      pptable.sml    -- register for user-defined prettyprinters for
                        particular types

  util/
    A couple of miscellaneous leftovers.
      feedback.sml  -- should be part of a graph library (move to ../library?)
      literal-to-num.sml



Middle End
----------

FLINT
  intermediate representation (a form of typed lambda calculus)


Back End
--------

MLRISC
  MLRISC based code generators


Execution Model
---------------

Interactive Top Level
---------------------


======================================================================

Catalog of basic structures
---------------------------

symbols
  Symbol - "Basics/mlcomp/symbol.s??"


ast (syntax trees)
  Ast - Parse/ast/ast.s??

absyn (abstract syntax)
  Absyn     - ElabData/syntax/absyn.s??
  VarCon    - ElabData/syntax/varcon.s??
  AbsynUtil - ElabData/syntax/absynutil.sml
  PPAbsyn   - Elaborator/print/ppabsyn.sml

types
  Types          - ElabData/types/types.s??
  TypesUtil      - ElabData/types/typesutil.s??
  Tuples         - ElabData/types/tuples.sml
  PPType         - Elaborator/print/pptype.sml
  CoreBasicTypes - ElabData/types/core-basictypes.sml
  BasicTypes     - Elaborator/types/basictypes.s??
  EqTypes        - Elaborator/types/eqtypes.sml


environment  (generic environment: 'b env)


static environment


modules (signatures, structures, functors)


control