<?php

declare(strict_types=1);

namespace Drupal\flowdrop\Plugin\ExpressionEvaluator;

use Drupal\Component\Plugin\PluginInspectionInterface;

/**
 * Interface for ExpressionEvaluator plugins.
 *
 * Expression evaluators provide a unified interface for evaluating expressions
 * against a data context. Different implementations support different syntax:
 * - PropertyPath: Symfony PropertyAccessor bracket notation
 * - JSONPath: RFC 9535 JSONPath expressions
 * - ExpressionLanguage: Symfony ExpressionLanguage
 * - Twig: Drupal Twig template rendering.
 *
 * Site builders choose the evaluator per node instance to match their needs.
 *
 * @see \Drupal\flowdrop\Attribute\ExpressionEvaluator
 * @see \Drupal\flowdrop\Service\ExpressionEvaluatorPluginManager
 *
 * @api
 */
interface ExpressionEvaluatorInterface extends PluginInspectionInterface {

  /**
   * Evaluate an expression against a data context.
   *
   * @param string $expression
   *   The expression to evaluate. Syntax depends on the implementation.
   * @param mixed $context
   *   The data context. For extraction evaluators (jsonpath, property_path),
   *   this is the source data to query. For transformation evaluators
   *   (expression_language, twig), this is an associative array of variables.
   *
   * @return mixed
   *   The evaluation result.
   *
   * @throws \RuntimeException
   *   If the expression cannot be evaluated.
   */
  public function evaluate(string $expression, mixed $context): mixed;

  /**
   * Validate expression syntax without evaluating.
   *
   * @param string $expression
   *   The expression to validate.
   *
   * @return bool
   *   TRUE if the expression is syntactically valid.
   */
  public function validate(string $expression): bool;

  /**
   * Get a human-readable syntax hint for the UI.
   *
   * @return string
   *   Example expression showing the expected syntax.
   */
  public function getSyntaxHint(): string;

}
