ConditionPresetEvaluator.h

Go to the documentation of this file.

/**
 * @file ConditionPresetEvaluator.h
 * @brief Stateless runtime evaluator for ConditionPreset expressions.
 * @author Olympe Engine
 * @date 2026-03-17
 *
 * @details
 * ConditionPresetEvaluator is a fully stateless utility class.  All methods are
 * static.  It evaluates a ConditionPreset by:
 *
 *   1. Resolving the left Operand to a float (via the RuntimeEnvironment).
 *   2. Resolving the right Operand to a float (via the RuntimeEnvironment).
 *   3. Applying the ComparisonOp to produce a bool result.
 *
 * Operand resolution strategy:
 *   - Variable  -> query RuntimeEnvironment::GetBlackboardVariable()
 *   - Const     -> use Operand::constValue directly (no environment access)
 *   - Pin       -> query RuntimeEnvironment::GetDynamicPinValue()
 *
 * All errors are reported through the outErrorMsg parameter; the return value
 * is always false when an error occurs.
 *
 * C++14 compliant — no std::optional, structured bindings, std::filesystem.
 */
 
#pragma once
 
#include <string>
#include <vector>
#include "../Editor/ConditionPreset/ConditionPreset.h"
#include "../Editor/ConditionPreset/NodeConditionRef.h"
#include "../Editor/ConditionPreset/Operand.h"
#include "RuntimeEnvironment.h"
 
namespace Olympe {
 
// Forward declaration
class ConditionPresetRegistry;
 
/**
 * @class ConditionPresetEvaluator
 * @brief Evaluates a ConditionPreset against a RuntimeEnvironment.
 *
 * @details
 * Typical usage:
 * @code
 *   RuntimeEnvironment env;
 *   env.SetBlackboardVariable("mHealth", 1.0f);
 *
 *   ConditionPreset preset("p1",
 *       Operand::CreateVariable("mHealth"),
 *       ComparisonOp::LessEqual,
 *       Operand::CreateConst(2.0));
 *
 *   std::string error;
 *   bool result = ConditionPresetEvaluator::Evaluate(preset, env, error);
 *   // result == true, error == ""
 * @endcode
 *
 * For multiple conditions with logical operators:
 * @code
 *   std::vector<NodeConditionRef> conditions;
 *   // (populated with NodeConditionRef entries referencing presets)
 *
 *   bool result = ConditionPresetEvaluator::EvaluateConditionChain(
 *       conditions, env, outErrorMsg);
 * @endcode
 */
class ConditionPresetEvaluator {
public:
 
    /**
     * @brief Evaluates a single ConditionPreset and returns the boolean result.
     *
     * @param preset      The condition preset to evaluate.
     * @param env         Runtime environment providing variable and pin values.
     * @param outErrorMsg Receives a human-readable error description on failure.
     *                    Empty on success.
     * @return true when the condition holds; false on failure or when the
     *         comparison evaluates to false.
     */
    static bool Evaluate(
        const ConditionPreset& preset,
        RuntimeEnvironment&    env,
        std::string&           outErrorMsg);
 
    /**
     * @brief Evaluates a chain of conditions combined with logical operators (AND/OR).
     *
     * @details
     * Implements short-circuit evaluation:
     *   - For AND chains: stops and returns false at the first false condition
     *   - For OR chains:  stops and returns true at the first true condition
     *
     * The first condition's LogicalOp is ignored (treated as Start).
     *
     * @param conditions  Vector of NodeConditionRef objects referencing presets.
     *                    Each preset ID is resolved via the provided registry.
     * @param registry    Registry containing the ConditionPreset objects.
     * @param env         Runtime environment providing variable and pin values.
     * @param outErrorMsg Receives a human-readable error description on failure.
     *                    Empty on success.
     * @return true when the combined condition chain evaluates to true;
     *         false on evaluation failure or when conditions are empty.
     *
     * @pre conditions vector must not be empty.
     * @pre registry must be valid (non-null).
     */
    static bool EvaluateConditionChain(
        const std::vector<NodeConditionRef>& conditions,
        const ConditionPresetRegistry&       registry,
        RuntimeEnvironment&                  env,
        std::string&                         outErrorMsg);
 
private:
 
    /**
     * @brief Resolves an Operand to its runtime float value.
     *
     * @param operand     Operand to resolve.
     * @param env         RuntimeEnvironment used for Variable / Pin lookup.
     * @param outErrorMsg Receives an error description when resolution fails.
     * @param outValue    Receives the resolved float value on success.
     * @return true on success; false when the variable / pin is not found.
     */
    static bool ResolveOperand(
        const Operand&      operand,
        RuntimeEnvironment& env,
        std::string&        outErrorMsg,
        float&              outValue);
 
    /**
     * @brief Applies a ComparisonOp to two float values.
     *
     * @param left        Left-hand side value.
     * @param op          Operator to apply.
     * @param right       Right-hand side value.
     * @param outErrorMsg Receives an error description for unknown operators.
     * @return Result of the comparison, or false on unknown operator.
     */
    static bool EvaluateOperator(
        float        left,
        ComparisonOp op,
        float        right,
        std::string& outErrorMsg);
};
 
} // namespace Olympe