Skip to main content

explain

Function explain 

Source
pub fn explain(
    ctx: &Context,
    input: ExplainInput,
) -> Result<Explanation, CapabilityError>
Expand description

Why one identifier is or is not in the context a request compiles to.

It compiles the request and then looks the identifier up in the result, which is the only honest way to answer the question: the standing of a thing is a property of a particular answer, not of the thing. The cost is one compile per question, and the benefit is that “excluded for budget” is measured against the budget the reply carries rather than one inferred afterwards.

An identifier this repository does not hold is Standing::Unknown — an answer, not an error — because “the index holds nothing under that name” is exactly the fact the caller asked for. The only refusal is an empty identifier, which is not a question.

use majordomus_cli::capability::CapabilityError;
use majordomus_cli::devcontext::{compile, explain, CompileInput, ExplainInput, Standing};
use majordomus_cli::synthetic::SyntheticRepository;

let repo = SyntheticRepository::small().unwrap();
let ctx = repo.context().unwrap();

// the standing is about one compiled answer, so it moves with the request
let generous = compile(&ctx, CompileInput::default()).unwrap();
let uri = generous.selected.last().unwrap().uri.clone();
let selected = explain(&ctx, ExplainInput { uri: uri.clone(), ..Default::default() }).unwrap();
assert_eq!(selected.standing, Standing::Selected);
assert_eq!(selected.entry.as_ref().unwrap().uri, uri);

// an identifier nothing answers: reported as unknown rather than refused
let unknown = explain(
    &ctx,
    ExplainInput { uri: "majordomus://rule/nothing-like-this@1".into(), ..Default::default() },
)
.unwrap();
assert_eq!(unknown.standing, Standing::Unknown);
assert!(!unknown.detail.is_empty(), "it says so in words too");

// and the one thing that is not a question
assert!(matches!(
    explain(&ctx, ExplainInput { uri: "   ".into(), ..Default::default() }),
    Err(CapabilityError::InvalidInput(_)),
));