automapper_validation/eval/
evaluator.rs

1//! Core condition evaluation traits.
2
3use super::context::EvaluationContext;
4
5/// Three-valued result of evaluating a single condition.
6///
7/// Unlike the C# implementation which uses `bool`, we use three-valued logic
8/// to support partial evaluation when external conditions are unavailable.
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
10pub enum ConditionResult {
11    /// The condition is satisfied.
12    True,
13    /// The condition is not satisfied.
14    False,
15    /// The condition cannot be determined (e.g., external condition without a provider).
16    Unknown,
17}
18
19impl ConditionResult {
20    /// Returns `true` if this is `ConditionResult::True`.
21    pub fn is_true(self) -> bool {
22        matches!(self, ConditionResult::True)
23    }
24
25    /// Returns `true` if this is `ConditionResult::False`.
26    pub fn is_false(self) -> bool {
27        matches!(self, ConditionResult::False)
28    }
29
30    /// Returns `true` if this is `ConditionResult::Unknown`.
31    pub fn is_unknown(self) -> bool {
32        matches!(self, ConditionResult::Unknown)
33    }
34
35    /// Three-valued AND: `False` if either is, `True` if both are, else `Unknown`.
36    pub fn and(self, other: ConditionResult) -> ConditionResult {
37        match (self, other) {
38            (ConditionResult::False, _) | (_, ConditionResult::False) => ConditionResult::False,
39            (ConditionResult::True, ConditionResult::True) => ConditionResult::True,
40            _ => ConditionResult::Unknown,
41        }
42    }
43
44    /// Three-valued OR: `True` if either is, `False` if both are, else `Unknown`.
45    pub fn or(self, other: ConditionResult) -> ConditionResult {
46        match (self, other) {
47            (ConditionResult::True, _) | (_, ConditionResult::True) => ConditionResult::True,
48            (ConditionResult::False, ConditionResult::False) => ConditionResult::False,
49            _ => ConditionResult::Unknown,
50        }
51    }
52
53    /// Three-valued NOT.
54    pub fn negate(self) -> ConditionResult {
55        match self {
56            ConditionResult::True => ConditionResult::False,
57            ConditionResult::False => ConditionResult::True,
58            ConditionResult::Unknown => ConditionResult::Unknown,
59        }
60    }
61
62    /// Converts to `Option<bool>`: True -> Some(true), False -> Some(false), Unknown -> None.
63    pub fn to_option(self) -> Option<bool> {
64        match self {
65            ConditionResult::True => Some(true),
66            ConditionResult::False => Some(false),
67            ConditionResult::Unknown => None,
68        }
69    }
70}
71
72impl From<bool> for ConditionResult {
73    fn from(value: bool) -> Self {
74        if value {
75            ConditionResult::True
76        } else {
77            ConditionResult::False
78        }
79    }
80}
81
82impl std::fmt::Display for ConditionResult {
83    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
84        match self {
85            ConditionResult::True => write!(f, "True"),
86            ConditionResult::False => write!(f, "False"),
87            ConditionResult::Unknown => write!(f, "Unknown"),
88        }
89    }
90}
91
92/// Evaluates individual AHB conditions by number.
93///
94/// Implementations are typically generated from AHB XML schemas (one per
95/// message type and format version). Each condition number maps to a
96/// specific business rule check.
97pub trait ConditionEvaluator: Send + Sync {
98    /// Evaluate a single condition by number.
99    ///
100    /// Returns `ConditionResult::Unknown` for unrecognized condition numbers
101    /// or conditions that require unavailable external context.
102    fn evaluate(&self, condition: u32, ctx: &EvaluationContext) -> ConditionResult;
103
104    /// Returns `true` if the given condition requires external context
105    /// (i.e., cannot be determined from the EDIFACT message alone).
106    fn is_external(&self, condition: u32) -> bool;
107
108    /// Returns `true` if this evaluator has an implementation for the given
109    /// condition number (whether internal or external). Conditions that fall
110    /// through to the `_ => Unknown` wildcard return `false`.
111    ///
112    /// This allows distinguishing "implemented but returned Unknown because
113    /// the relevant data isn't present in the message" from "not implemented
114    /// at all".
115    fn is_known(&self, _condition: u32) -> bool {
116        false
117    }
118
119    /// Returns the message type this evaluator handles (e.g., "UTILMD").
120    fn message_type(&self) -> &str;
121
122    /// Returns the format version this evaluator handles (e.g., "FV2510").
123    fn format_version(&self) -> &str;
124}
125
126impl<T: ConditionEvaluator + ?Sized> ConditionEvaluator for std::sync::Arc<T> {
127    fn evaluate(&self, condition: u32, ctx: &EvaluationContext) -> ConditionResult {
128        (**self).evaluate(condition, ctx)
129    }
130
131    fn is_external(&self, condition: u32) -> bool {
132        (**self).is_external(condition)
133    }
134
135    fn is_known(&self, condition: u32) -> bool {
136        (**self).is_known(condition)
137    }
138
139    fn message_type(&self) -> &str {
140        (**self).message_type()
141    }
142
143    fn format_version(&self) -> &str {
144        (**self).format_version()
145    }
146}
147
148/// Provider for external conditions that depend on context outside the EDIFACT message.
149///
150/// External conditions are things like:
151/// - [1] "Wenn Aufteilung vorhanden" (message splitting status)
152/// - [14] "Wenn Datum bekannt" (whether a date is known)
153/// - [30] "Wenn Antwort auf Aktivierung" (response to activation)
154///
155/// These cannot be determined from the EDIFACT content alone and require
156/// business context from the calling system.
157pub trait ExternalConditionProvider: Send + Sync {
158    /// Evaluate an external condition by name.
159    ///
160    /// The `condition_name` corresponds to the speaking name from the
161    /// generated external conditions constants (e.g., "MessageSplitting",
162    /// "DateKnown").
163    fn evaluate(&self, condition_name: &str) -> ConditionResult;
164}
165
166/// A no-op external condition provider that returns `Unknown` for everything.
167///
168/// Useful when no external context is available — conditions will propagate
169/// as `Unknown` through the expression evaluator.
170pub struct NoOpExternalProvider;
171
172impl ExternalConditionProvider for NoOpExternalProvider {
173    fn evaluate(&self, _condition_name: &str) -> ConditionResult {
174        ConditionResult::Unknown
175    }
176}
177
178/// The number of a message type's bare "Wenn vorhanden" condition, if it has one.
179///
180/// The condition is self-referential: its value is whether the element or
181/// group it annotates is present. `Soll [166]` on a group means "send it if
182/// you have it", which only the sender knows, so an absent group annotated
183/// with it is never missing. The generated evaluators answer it with `True`
184/// ("the rule applies wherever it is evaluated"), which is right for a present
185/// element and wrong for an absent one — see [`AbsentTarget`].
186///
187/// The numbers are stable across every format version in
188/// `xml-migs-and-ahbs/` (FV2410–FV2610); keyed by [`ConditionEvaluator::message_type`]
189/// rather than by evaluator so aliased and regenerated evaluators need no edit.
190pub fn presence_condition(message_type: &str) -> Option<u32> {
191    match message_type {
192        "UTILMD_Strom" | "UTILMD_Gas" => Some(166),
193        "INVOIC" => Some(22),
194        "ORDERS" => Some(12),
195        _ => None,
196    }
197}
198
199/// Every condition of a message type that answers "does the annotated thing
200/// exist?", which an absent element or group answers with no.
201///
202/// The [`presence_condition`], plus conditions that ask for one repetition per
203/// real-world object the message cannot see. UTILMD_Strom [2003] ("Einmal für
204/// jede ruhende Marktlokation, die der Marktlokation »Kundenanlage« …
205/// untergeordnet ist", FV2504–FV2610, absent in Gas) is `Soll` on the ruhende
206/// Marktlokation: zero ruhende MaLos means zero groups, and only the sender
207/// knows how many exist. The generated evaluators cannot decide it and answer
208/// `Unknown`, which reported every message without a ruhende MaLo.
209pub fn presence_conditions(message_type: &str) -> &'static [u32] {
210    match message_type {
211        "UTILMD_Strom" => &[166, 2003],
212        "UTILMD_Gas" => &[166],
213        "INVOIC" => &[22],
214        "ORDERS" => &[12],
215        _ => &[],
216    }
217}
218
219/// The condition of a message type that allows a group or segment once per
220/// transaction, and the transaction group: UTILMD's `[2061]` "Segment bzw.
221/// Segmentgruppe ist genau einmal je SG4 IDE (Vorgang) anzugeben" (Strom and
222/// Gas, FV2504–FV2610). The conditions evaluate it as `True` wherever there is
223/// a transaction, so what it limits — the count — is checked on its own; see
224/// [`binds_once`].
225pub fn once_per_transaction(message_type: &str) -> Option<(u32, &'static str)> {
226    transaction_group(message_type).map(|group| (2061, group))
227}
228
229/// The group a message type repeats once per transaction, whose conditions the
230/// AHB states per transaction: UTILMD's SG4 (`IDE+24`, Vorgang). The validator
231/// evaluates each repetition against the message as that transaction sees it
232/// (`mig_assembly::transaction_view`, #337).
233pub fn transaction_group(message_type: &str) -> Option<&'static str> {
234    match message_type {
235        "UTILMD_Strom" | "UTILMD_Gas" => Some("SG4"),
236        _ => None,
237    }
238}
239
240/// Whether `status` limits what it annotates to once per transaction: the
241/// condition `once` is a conjunct of every line (`Muss [483] ∧ [2061]`). Where
242/// it sits in one branch only (`Soll [165] ∧ (([2061] ∧ [583]) ∨ [584])`), the
243/// other branch allows more.
244pub fn binds_once(status: &str, once: u32) -> bool {
245    fn conjunct(expr: &crate::expr::ConditionExpr, once: u32) -> bool {
246        match expr {
247            crate::expr::ConditionExpr::Ref(id) => *id == once,
248            crate::expr::ConditionExpr::And(exprs) => exprs.iter().any(|e| conjunct(e, once)),
249            _ => false,
250        }
251    }
252    let lines: Vec<&str> = status
253        .lines()
254        .map(str::trim)
255        .filter(|l| !l.is_empty())
256        .collect();
257    !lines.is_empty()
258        && lines.iter().all(|line| {
259            matches!(
260                crate::expr::ConditionParser::parse(line),
261                Ok(Some(expr)) if conjunct(&expr, once)
262            )
263        })
264}
265
266/// Evaluates conditions for an element or group that is known to be absent.
267///
268/// Identical to the wrapped evaluator except that the message type's
269/// [`presence_conditions`] are `False`: whatever the condition annotates is not
270/// there. Use it wherever a status is evaluated to decide whether something
271/// missing is required.
272pub struct AbsentTarget<'a, E: ConditionEvaluator + ?Sized>(pub &'a E);
273
274impl<E: ConditionEvaluator + ?Sized> ConditionEvaluator for AbsentTarget<'_, E> {
275    fn evaluate(&self, condition: u32, ctx: &EvaluationContext) -> ConditionResult {
276        if presence_conditions(self.0.message_type()).contains(&condition) {
277            return ConditionResult::False;
278        }
279        self.0.evaluate(condition, ctx)
280    }
281
282    fn is_external(&self, condition: u32) -> bool {
283        self.0.is_external(condition)
284    }
285
286    fn is_known(&self, condition: u32) -> bool {
287        self.0.is_known(condition)
288    }
289
290    fn message_type(&self) -> &str {
291        self.0.message_type()
292    }
293
294    fn format_version(&self) -> &str {
295        self.0.format_version()
296    }
297}
298
299/// Evaluates conditions for an element or group that is known to be present,
300/// to decide whether it is allowed there.
301///
302/// The message type's [`presence_conditions`] are `True`: whatever the
303/// condition annotates is there. Only the AHB's conditions proper (`[1]` to
304/// `[499]`) decide; notes (`[500]`–`[899]`), formats (`[900]`–`[999]`) and
305/// repetition rules (`[2000]` and up: "genau einmal je SG8 …") say nothing about
306/// whether something may be sent, and are `Unknown` — so `[197] ∧ [2308]` is
307/// false when `[197]` is, and `[2317] ⊻ [2318]` is never.
308pub struct PresentTarget<'a, E: ConditionEvaluator + ?Sized>(pub &'a E);
309
310impl<E: ConditionEvaluator + ?Sized> ConditionEvaluator for PresentTarget<'_, E> {
311    fn evaluate(&self, condition: u32, ctx: &EvaluationContext) -> ConditionResult {
312        if presence_conditions(self.0.message_type()).contains(&condition) {
313            return ConditionResult::True;
314        }
315        if !(1..500).contains(&condition) {
316            return ConditionResult::Unknown;
317        }
318        self.0.evaluate(condition, ctx)
319    }
320
321    fn is_external(&self, condition: u32) -> bool {
322        self.0.is_external(condition)
323    }
324
325    fn is_known(&self, condition: u32) -> bool {
326        self.0.is_known(condition)
327    }
328
329    fn message_type(&self) -> &str {
330        self.0.message_type()
331    }
332
333    fn format_version(&self) -> &str {
334        self.0.format_version()
335    }
336}
337
338/// Whether something present under `status` is not allowed where `ctx` is: a
339/// `Muss`/`X` status with a condition that evaluates to false through
340/// [`PresentTarget`]. `Soll`/`Kann`, an unconditional status, an undecidable
341/// condition, a package (`[19P1..1]`, judged by its own check) and a status of
342/// several lines refuse nothing.
343pub fn refuses_presence<E: ConditionEvaluator + ?Sized>(
344    status: &str,
345    evaluator: &E,
346    ctx: &EvaluationContext,
347    ub_definitions: &std::collections::BTreeMap<String, crate::expr::ConditionExpr>,
348) -> bool {
349    let status = status.trim();
350    let package = status.split('[').skip(1).any(|term| {
351        term.trim_start_matches(|c: char| c.is_ascii_digit())
352            .starts_with('P')
353    });
354    if status.contains('\n') || !status.contains('[') || package {
355        return false;
356    }
357    let keyword = &status[..status
358        .find(|c: char| !c.is_alphabetic())
359        .unwrap_or(status.len())];
360    if !matches!(keyword, "Muss" | "X") {
361        return false;
362    }
363    let present = PresentTarget(evaluator);
364    super::ConditionExprEvaluator::new(&present).evaluate_status_with_ub(
365        status,
366        ctx,
367        ub_definitions,
368    ) == ConditionResult::False
369}
370
371#[cfg(test)]
372mod tests {
373    use super::*;
374
375    struct AlwaysTrue(&'static str);
376
377    impl ConditionEvaluator for AlwaysTrue {
378        fn evaluate(&self, _: u32, _: &EvaluationContext) -> ConditionResult {
379            ConditionResult::True
380        }
381        fn is_external(&self, _: u32) -> bool {
382            false
383        }
384        fn message_type(&self) -> &str {
385            self.0
386        }
387        fn format_version(&self) -> &str {
388            "FV2604"
389        }
390    }
391
392    #[test]
393    fn once_per_transaction_binds_where_every_line_has_it() {
394        assert!(binds_once("Muss [483] ∧ [2061]", 2061));
395        assert!(binds_once("Muss [2061]", 2061));
396        assert!(binds_once(
397            "Muss ([77] ∧ [78]) ∧ [347] ∧ [2061]\r\nKann [2061]",
398            2061
399        ));
400        assert!(!binds_once("Soll [165] ∧ (([2061] ∧ [583]) ∨ [584])", 2061));
401        assert!(!binds_once(
402            "Muss ([32] ∧ [2061] ∧ [651]) ⊻ ([200] ∧ [601])",
403            2061
404        ));
405        assert!(!binds_once("Muss [483]", 2061));
406        assert!(!binds_once("", 2061));
407    }
408
409    #[test]
410    fn absent_target_answers_only_the_presence_condition_with_false() {
411        let external = NoOpExternalProvider;
412        let ctx = EvaluationContext::new("55043", &external, &[]);
413        let inner = AlwaysTrue("UTILMD_Strom");
414        let absent = AbsentTarget(&inner);
415        assert_eq!(absent.evaluate(166, &ctx), ConditionResult::False);
416        assert_eq!(absent.evaluate(674, &ctx), ConditionResult::True);
417        // [2003]: one group per ruhende Marktlokation the sender knows of.
418        assert_eq!(absent.evaluate(2003, &ctx), ConditionResult::False);
419
420        // [166] of another message type is an unrelated condition.
421        let invoic = AlwaysTrue("INVOIC");
422        assert_eq!(
423            AbsentTarget(&invoic).evaluate(166, &ctx),
424            ConditionResult::True
425        );
426        assert_eq!(
427            AbsentTarget(&invoic).evaluate(22, &ctx),
428            ConditionResult::False
429        );
430    }
431
432    #[test]
433    fn test_condition_result_is_methods() {
434        assert!(ConditionResult::True.is_true());
435        assert!(!ConditionResult::True.is_false());
436        assert!(!ConditionResult::True.is_unknown());
437
438        assert!(!ConditionResult::False.is_true());
439        assert!(ConditionResult::False.is_false());
440
441        assert!(ConditionResult::Unknown.is_unknown());
442    }
443
444    #[test]
445    fn three_valued_and_or_not() {
446        use ConditionResult::{False as F, True as T, Unknown as U};
447        assert_eq!(T.and(T), T);
448        assert_eq!(T.and(U), U);
449        assert_eq!(U.and(F), F);
450        assert_eq!(F.or(F), F);
451        assert_eq!(F.or(U), U);
452        assert_eq!(U.or(T), T);
453        assert_eq!(U.negate(), U);
454        assert_eq!(T.negate(), F);
455    }
456
457    #[test]
458    fn test_condition_result_to_option() {
459        assert_eq!(ConditionResult::True.to_option(), Some(true));
460        assert_eq!(ConditionResult::False.to_option(), Some(false));
461        assert_eq!(ConditionResult::Unknown.to_option(), None);
462    }
463
464    #[test]
465    fn test_condition_result_from_bool() {
466        assert_eq!(ConditionResult::from(true), ConditionResult::True);
467        assert_eq!(ConditionResult::from(false), ConditionResult::False);
468    }
469
470    #[test]
471    fn test_condition_result_display() {
472        assert_eq!(format!("{}", ConditionResult::True), "True");
473        assert_eq!(format!("{}", ConditionResult::False), "False");
474        assert_eq!(format!("{}", ConditionResult::Unknown), "Unknown");
475    }
476
477    #[test]
478    fn test_noop_external_provider() {
479        let provider = NoOpExternalProvider;
480        assert_eq!(
481            provider.evaluate("MessageSplitting"),
482            ConditionResult::Unknown
483        );
484        assert_eq!(provider.evaluate("anything"), ConditionResult::Unknown);
485    }
486}
automapper_validation/eval/evaluator.rs

automapper_validation/eval/
evaluator.rs
