## type-package-language.api
# Compiled by:
# src/lib/compiler/front/typer/typer.sublib# This module is the core of the typechecker.
#
# Typechecking is essentially a matter of converting the raw syntax tree,
# which contains both declarative and executable content, into a deep
# syntax tree containing the executable content and a symbol table
# containing the declarative content.
#
# The two return values from our (sole) type_declaration() entrypoint
# are that deep sytax tree and that symbol table.
#
# We get called by
#
# src/lib/compiler/front/typer/main/translate-raw-syntax-to-deep-syntax-g.pkg#
# after it has finished its special-casing of
# toplevel stuff (see file-top comments in it
# for a broader overview), and we in turn hand
# off such subtasks as typechecking of apis,
# types and core language stuff to
#
# src/lib/compiler/front/typer/main/type-api.pkg# src/lib/compiler/front/typer/main/type-type.pkg# src/lib/compiler/front/typer/main/type-core-language.pkg# src/lib/compiler/front/typer/main/typer-junk.api# src/lib/compiler/front/typer/main/typer-junk.pkg# src/lib/compiler/front/typer/modules/api-match-g.pkg# src/lib/compiler/front/typer/modules/generics-expansion-junk-g.pkg# src/lib/compiler/front/typer/modules/expand-generic-g.pkg# src/lib/compiler/front/typer/modules/expand-type.pkg# src/lib/compiler/front/typer-stuff/modules/module-junk.api# src/lib/compiler/front/typer-stuff/modules/module-junk.pkg# src/lib/compiler/front/typer/types/type-core-language-declaration-g.pkg# src/lib/compiler/front/typer/types/unify-typoids.pkg#
# The main package-level constructs in the language are:
# o Package definitions.
# o Api definitions.
# o Generic (package-valued compile-time function) definitions.
# o Generic api definitions.
# o Generic invocations.
#
# For typechecking purposes, the first four just amount
# to laundry lists of elements to save in the symbol table,
# so for our purposes here, most of the interest -- and
# work -- centers on generic invocation.
#
# A generic is in essence a typed macro, so generic invocation
# amounts to typed macro expansion. In order to typecheck a
# program, we must do macro expansion on each generic invocation
# in the program, so that we can examine and type-check (and
# eventually do code generation for) the results of each invocation.
#
# To keep track of the macro expansion process and its products, we
# create a shadow-world counterpart of our regular symbols, symbol
# tables, symbol paths etc. We call these shadow components
# module_stamps, macroExpansionDictionaries, macroExpansionPaths,
# packageMacroExpansions and so forth.
#
# The package body constituting the body of a generic definition
# gets expanded into a packageMacroExpansion which is given a
# module_stamp as a name, and stored in a typerstore.
#
# Nested packages in the generic definition body expand into
# nested typechecked_packages which are accessed via lists of typechecked_package
# stamps called macroExpansionPaths, just as components in regular
# nested packages are accessed via lists of symbols called
# symbol paths.
#
# These typechecked_package datastructures are temporaries internal to the
# typechecker: the 'type_declaration' entrypoint function in
# this file passes an empty typerstore and an empty
# stamppath_context down the call hierarchy, and discards the
# corresponding populated ones that are returned to it, since at
# that point their job is done.
#
# The bulk of the typechecked_package datastructure stuff is implemented in:
#
# src/lib/compiler/front/typer-stuff/modules/module-level-declarations.api# src/lib/compiler/front/typer-stuff/modules/module-level-declarations.pkg#
# src/lib/compiler/front/typer-stuff/modules/stamppath.pkg#
# src/lib/compiler/front/typer-stuff/modules/typerstore.pkg# src/lib/compiler/front/typer-stuff/modules/typerstore.api#
# src/lib/compiler/front/typer-stuff/modules/stamppath-context.pkg# src/lib/compiler/front/typer/modules/generics-expansion-junk-g.pkg#
# The major routines in this file (occupying about
# the indicated percentages of the file) are:
#
# 10% extract_symbolmapstack_contents
# 15% type_package
# 20% type_generic
# 10% type_named_packages
# 30% type_declaration'
#
# with the latter four being mutually recursive.
### "You are in a maze of twisty tunnels, all different."
### "The tar pit of software engineering will continue to be sticky for a long time
### to come. One can expect the human race to continue attempting systems just
### within or just beyond our reach; and software systems are perhaps the most
### intricate and complex of man's handiworks. The management of this complex
### craft will demand our best use of new languages and systems, our best
### adaptation of proven engineering management methods, liberal doses of common
### sense, and ... humility to recognize our fallibility and limitations.
###
### -- Frederick Brooks, Jr., The Mythical Man Month
### "First quantization is a mystery, but second quantization is a functor!"
###
### -- Edward Nelson
#
stipulate
package ds = deep_syntax; # deep_syntax is from src/lib/compiler/front/typer-stuff/deep-syntax/deep-syntax.pkg package ip = inverse_path; # inverse_path is from src/lib/compiler/front/typer-stuff/basics/symbol-path.pkg package lnd = line_number_db; # line_number_db is from src/lib/compiler/front/basics/source/line-number-db.pkg package mld = module_level_declarations; # module_level_declarations is from src/lib/compiler/front/typer-stuff/modules/module-level-declarations.pkg package spc = stamppath_context; # stamppath_context is from src/lib/compiler/front/typer-stuff/modules/stamppath-context.pkg package raw = raw_syntax; # raw_syntax is from src/lib/compiler/front/parser/raw-syntax/raw-syntax.pkg package syx = symbolmapstack; # symbolmapstack is from src/lib/compiler/front/typer-stuff/symbolmapstack/symbolmapstack.pkg package ts = typer_junk; # typer_junk is from src/lib/compiler/front/typer/main/typer-junk.pkgherein
api Type_Package_Language {
# Typecheck module-level declarations:
#
type_declaration:
{
raw_declaration: raw::Declaration, # Actual raw syntax to typecheck.
symbolmapstack: syx::Symbolmapstack, # Symbol table containing info from all .compiled files we depend on.
typerstore: mld::Typerstore,
#
syntactic_typechecking_context: ts::Syntactic_Typechecking_Context, # TOPLEVEL/API/PKG/GENERIC
level: Bool, # TRUE iff top-level declaration.
stamppath_context: spc::Context,
path: ip::Inverse_Path,
source_code_region: lnd::Source_Code_Region,
per_compile_stuff: ts::Per_Compile_Stuff
}
->
{ deep_syntax_declaration: ds::Declaration, # Typechecked version of raw_declaration.
symbolmapstack: syx::Symbolmapstack # Contains (only) stuff from raw_declaration.
};
debugging: Ref( Bool );
};
end;