= Understanding the apply path in the interpreter =

Because the interpreter deals with dynamic type inference and dynamic
overloading resolution, the path for applying a function can be rather
twisty.

Note in particular that the class `DottedMethodApplication` is used to
represent a pending method application (ie a pair of receiver and the
method applied to that receiver); this substantially simplifies the
code to handle e.g. juxtaposition in the interpreter, but it's worth
understanding that these objects are only closures in the sense that
they're waiting to be applied to arguments just as a top-level
function might be.

Most function application in the interpreter goes via
`EvaluatorBase.functionInvocation`, and thence to
`applyPossiblyGeneric`.  This deals with tupling / un-tupling of
arguments and then calls through to `applyInnerPossiblyGeneric`, which
is the method that gets specialized for the various sorts of closure
(overloaded, method, generic, etc.).

A concrete interpreted method or function eventually constructs a new environment
for its arguments using `buildEnvFrom[EnvAnd]Params`.  If the method
or function is built in, it instead calls the built-in version using
`applyToArgs` or `applyMethod` rather than building an env.

A generic function or method undergoes type inference using
`EvaluatorBase.inferAndInstantiateGenericFunction`; this computes the
actual type parameters and creates a non-generic monomorphic `Simple_fcn`
that can be invoked directly.

An overloaded function or method attempts to find the most specific
applicable overloading using `bestMatch` (which in turn calls
`bestMatchInternal`).  This includes instantiating any generic
overloadings that might apply.

A functional method must extract its `self` parameter, then call the
corresponding (specially-named) dotted method to resolve any
overloading or overriding that might have occurred.

== Summary of functions on apply path ==

=== `applyPossiblyGeneric` ===
Uses
      * `Driver.runProgramTask`
      * `Evaluator.invokeGenericMethod` (on `DottedMethodApplication`)
      * `Evaluator.handleException` (construct `forbiddenException`)
      * `EvaluatorBase.functionInvocation` (surrounding `setContext`)
      * `LHSEvaluator.forLValue` (invoke array constructor)
      * `SpawnTask.compute`
      * `DottedMethodApplication.invokeMethod`
      * `GenericFunctionOrConstructor` (after `inferAndInstantiateGenericFunction`)
      * `GenericSingleton.make` (invoke nullary constructor on instantiation)
      * `NonPrimitive.buildEnvFromParams` (invoke varargs factory)
      * `OverloadedFunction.applyInnerPossiblyGeneric` (invoke best match)
      * `Reflect.makeReflectedType` (invoke nullary Reflect constructor after instantiation)
Defs
      * `Fcn`: unwrap, handle `UnificationError`, call `applyInnerPossiblyGeneric`.

=== `applyInnerPossiblyGeneric` ===
Uses
      * `Fcn`: `applyPossiblyGeneric`
Defs
      * `Fcn`: abstract
      * `Dummy_fcn`: NYI (testing only)
      * `Constructor`: call thru to `applyConstructor`
      * `DottedMethodApplication`: `applyMethod` with `setContext`
      * `FunctionalMethod`: pull out self, `DottedMethodApplication.invokeMethod`
      * `FunctionClosure`: `applyToArgs` of native, else eval
      * `GenericFunctionOrConstructor`: `inferAndInstantiate`, then `applyPossiblyGeneric`
      * `MethodClosure`: check for functional-ness, `applyMethod`
      * `OverloadedFunction`: find best match, `applyPossiblyGeneric`

=== `applyMethod` ===
Uses
      * `DottedMethodApplication`: `applyInnerPossiblyGeneric` with `setContext`
      * `MethodClosure.applyInnerPossiblyGeneric`: chain for
      functional method invocation.
      * `OverloadedMethod.applyMethod`: get applicable method, `applyMethod`
      * `IndexedArrayWrapper.put`,get: apply putter,getter
Defs
      * interface `Method`
      * `MethodClosure`: check for native, `applyMethod` or `buildEnvFromEnvAndParams` and eval
      * `OverloadedMethod`: get applicable method, `applyMethod`
      * `TraitMethodInstance`: `buildEnvFromEnvAndParams` and eval (not called?)
      * `NativeMeth`: call thru to `applyMethod` (2 args, no site/`envForInference`)

=== `buildEnvFromEnvAndParams` ===
Uses
      * `Constructor.applyConstructor` (`methodsEnv`)
      * `MethodClosure.applyMethod` (`envForApplication`)
      * `TraitMethodInstance.applyMethod` (`evaluationEnv`)
Defs
      * `NonPrimitive` `(extendAt(getAt())`, pass to `buildEnvFromParams`)

=== `buildEnvFromParams` ===
Uses
      * `FunctionClosure.applyInnerPossiblyGeneric`
Defs
      * `NonPrimitive` (def with, without env; uses within by default)

=== `bestMatch` ===
Uses
      * `OverloadJUTest`
      * `OverloadedFunction.applyInnerPossiblyGeneric`
      * `MethodClosure.getApplicableMethod`
Defs
      * `OverloadedFunction`: calls `bestMatchInternal`, twice if no index is found.

=== `bestMatchInternal` ===
Uses
      * `OverloadedFunction.bestMatch` chains to
Defs
      * `OverloadedFunction`: `inferAndInstantiateGenericFunction` for generic

=== `inferAndInstantiateGenericFunction` ===
Uses
      * `GenericFunctionOrConstructor.applyInnerPossiblyGeneric`
      * `OverloadedFunction.applyInnerPossiblyGeneric` (redundant w/`bestMatchInternal`!)
      * `OverloadedFunction.bestMatchInternal`
Defs
      * `EvaluatorBase` (HUGE wad of code)