An `eval` that tells me why the predicate failed

[epage]

In using this with assertions, like assert_cli, it'd be a very big help for debuggability to tell people why the assertion failed.

Requirements

Some possible requirements include (yes, some will be contradictory)

• low overhead in the success case
• be clear about what all the values shown mean
  • e.g. is_close has several params. If do we inline substitution, it might not be clear
• don't overwhelm the user
• show me all of the failures because the first might not be the root cause (particularly when doing dir-diffing)
• show me all of the successes because a later failure might be rooted in the wrong thing succeeding
• Make things clear in the formatting
• Programmatically report the result so assert_cmd and friends can decide whether to panic (return error, etc)

Example of odd cases to watch for

• is_close taking several parameters
• from_utf8, trim, a potential normalize_newlines, from_file_path transform the data being passed down
  • Some of these also changes item's type
• name shifts the child predicate into an equivalent of a named field
• not flips what case we are looking for

Open Questions

• Is this feature important enough and Debug implementations common enough that we can justify requiring Predicate<Item: Debug>?
  • atm we're leaning towards this being acceptable

API Design Options

cases_iter(item, yes: bool) -> Iterator

This returns an iterator of examples of cases for why yes. Each case in the iterator can show the full expression tree and what each part evaluates to.

The yes is needed to flip what we are looking for when evaluating not.

tree_eval(item) -> (bool, tree)

Returns the result of eval plus a renderable tree using the treeline crate.

Requires the following Predicate methods

• stringify: like Display but substitutes the Item in
• make_tree: creates the renderabvle tree
• tree_eval: the actual function, a default trait implementation exists

See #39

table_eval(item) -> (bool, table)

Like tree_eval but render a table using term-table

See #39

prove(&'a self, item, yes:bool) -> Option<Tree<'a>>

Creates a Tree of the predicates and their intermediate values using references, owned values, and Cow. Different render implementations can be written against this, whether tree, table, or something else.

Only return those parts for support yes.

If None is returned, then nothing supports yes.

[epage]

This should include a name predicate that let's you give names to sub-expressions.

[epage]

Given:

let between_5_and_10 = predicate::ge(5).and(predicate::le(10));
assert_eq!(true, between_5_and_10.eval(&7));
assert_eq!(false, between_5_and_10.eval(&11));
assert_eq!(false, between_5_and_10.eval(&4));

ideally the output would be

item > 5 && item < 10
with
    item: 7

And because of not, we need to always build this up because a predicate that might be "fine" can be turned into the "failure case".

So API requirements

• Build up expression and values separately
• Allow user to pass in the variable name to meet the current application
• Allow predicate transforms to define new variables (taking a path predicate and turning it into a str predicate by reading its contents)
• Might get recursive if we allow naming sub-expressions, which would be ideal for files

[epage]

In giving this some time to think over, my thought is that the expression would come from implementing Display. The values would come from cases_iter(yes: bool) that would look for all cases that prove yes.