Affects Version/s: None
Fix Version/s: PUP 4.3.0
Sprint:Language 2015-09-02, Language 2015-09-16, Language 2015-09-30
Release Notes:New Feature
Release Notes Summary:As part of the 'data in modules' feature - the lookup command line tool can now explain how a looked up value was resolved by using the option --explain.
In order to enable explaining how a particular looked up key gets its value (or no value (not found) the API of a DataProvider should accept an additional argument - an ÉxplanationAcceptor.
By default a NullExplanationAcceptor is used.
This acceptor should be passed throughout the calls:
The acceptor should be based on an API that requires very little overhead when a NullExplainerAcceptor is used - i.e. avoiding formatting messages to add to the explainer.
- LookupExplainerAcceptor.accept(&block) where the block is called by an acceptor that actually produces explanations seems like an adequate solution. The acceptor should pass itself as an argument to the block.
- The block should call back to method(s) on the acceptor to log an explanation
- Since lookup calls can nest (interpolation, delegation, merge) - the explainers also nest
- An explainer has an outcome of: found, not_found (and its content describes how it arrived at that outcome) - if found it also has the value/result.
- The resulting explainer tree should be serializeable as JSON (most likely presentation format).
The puppet lookup function cannot easily support explain - it would need to return a generic data structure instead of the value - therefore this functionality is only available to command line utilities (or possible a a function added in the future with a signature similar to lookup but that returns the data structure).
As an example (pseudo explanation):
(The above is only an illustration)
The first implementation should focus on the major branch points/results. New tickets should be added for more advanced/detailed explanations.