Evaluate terms before extracting documentation #1463
Merged
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
With this change,
nickel doc
evaluates a term before trying to extractdocumentation. The evaluation mode needed here is somewhat between evaluating to
WHNF and a full deep evaluation. Namely, we first evaluate the term to WHNF. If
it isn't a record then there is no documentation to extract and we're done. If
it is, we iterate through all fields with a defined value and call the evaluator
recursively.
The result will be a tree of records in WHNF which our previous documentation
extraction procedure knows how to handle. In fact, the only difference to a full
deep evaluation is that we do not descend into arrays. Consequently, this change
will incur a performance penalty compared to the previous
nickel doc
. Fornow, we're willing to accept this penalty for two reasons. First, documentation
extraction is expected to be rarer than fully evaluating a Nickel configuration.
Second, the evaluation algorithm presented here does strictly less work than a
full evaluation and therefore shouldn't be any slower.
There is another caveat with this implementation. For simplicity, I've
implemented an explicitly recursive version of the algorithm described above.
This means that we're using the Rust callstack when descending into deeply
nested records and we might encounter stack overflows for particularly deep
records. The Nickel evaluator itself uses a custom stack stored in the heap to
circumvent this problem. If we ever encounter stack overflows in
nickel doc
inthe wild, we should do the same here.
Fixes #1462.