Refine addTopDecls
This suggested refactoring/documentation task is spurred on by #10486 (closed). Readers do not have to read that ticket to understand this task.
Currently, addTopDecls
is restricted in what it can add. In an email exchange with Geoff Mainland (the original implementor of addTopDecls
), it was unclear exactly why this restriction is in place. So, I propose lifting the restriction.
We do have to be careful about ordering. As it is currently implemented, here is what happens:
-- region A, including everything up to but not including a top-level splice
$( {- region B, the contents of a top-level splice -} )
-- region C, everything after the splice
In addition to those regions, we also have
-- region D, consisting of all declarations added with `addTopDecls`,
-- as called from splices in region A
By reading the code (TcRnDriver.tc_rn_src_decls
), it seems that the expected behavior should be this:
- Rename region A. Anything defined in other regions is not in scope.
- Rename region D, with declarations from region A in scope.
- Type-check regions A and D together.
- When running TH code in region B, all declarations from A and D are in scope and can be accessed via
reify
and friends. - Combine regions B and C together, and recur to step 1 (where the combined B and C is now a new region A).
This all means that A and D are mutually recursive w.r.t. the type-checker but not the renamer. This is a bit peculiar, but not terrible. For example, this means that there could be a function whose definition is in A and type signature in D. Proper mutual recursion would be hard (impossible?) without better renaming support.
In any case, I don't see a reason to restrict what's allowed in addTopDecls
.
So, at a minimum, I propose:
- Remove restrictions in
addTopDecls
- Document
addTopDecls
generally - Document the above behavior, detailing the interaction between these regions
Perhaps better, we could do:
- Remove restrictions in
addTopDecls
- Rejigger the implementation of
addTopDecls
to lump region D in with B and C. This looks quite straightforward, and it makes for a simpler story about mutual recursion. This is a potentially-breaking change, if existing code has, say, a function defined in A with its type signature in D. - Document the new, simpler behavior
Regardless of which proposal we go with, some testing is in order, to make sure that this is all correct. I've done no testing in formulating this ticket, just reading code.
EDIT: Clarify that region D is created from splices from region A