class RulesDataInputEvaluator

abstract class RulesDataInputEvaluator extends RulesDataProcessor {
    
    /**
     * Overridden to invoke prepare().
     */
    protected function __construct($setting, $param_info, $var_info = array(), $processor = NULL) {
        $this->setting = TRUE;
        $this->processor = $processor;
        $this->prepare($setting, $var_info, $param_info);
    }
    
    /**
     * Overridden to generate evaluator $options and invoke evaluate().
     */
    public function process($value, $info, RulesState $state, RulesPlugin $element, $options = NULL) {
        $options = isset($options) ? $options : $this->getEvaluatorOptions($info, $state, $element);
        $value = isset($this->processor) ? $this->processor
            ->process($value, $info, $state, $element, $options) : $value;
        return $this->evaluate($value, $options, $state);
    }
    
    /**
     * Generates the evaluator $options.
     */
    protected function getEvaluatorOptions($info, $state, $element) {
        $cache = rules_get_cache();
        $languages = language_list();
        $info += array(
            'cleaning callback' => isset($cache['data info'][$info['type']]['cleaning callback']) ? $cache['data info'][$info['type']]['cleaning callback'] : FALSE,
            'sanitize' => FALSE,
        );
        $options = array_filter(array(
            'language' => $info['#langcode'] != LANGUAGE_NONE && isset($languages[$info['#langcode']]) ? $languages[$info['#langcode']] : NULL,
            'callback' => $info['cleaning callback'],
            'sanitize' => $info['sanitize'],
        ));
        return $options;
    }
    
    /**
     * Overridden to prepare input evaluator processors.
     *
     * The setting is expected to be the input value to be evaluated later on
     * and is replaced by the suitable processor.
     */
    public static function prepareSetting(&$setting, $param_info, $var_info = array()) {
        $processor = NULL;
        foreach (self::evaluators($param_info, FALSE) as $name => $info) {
            $object = new $info['class']($setting, $param_info, $var_info, $processor);
            $processor = $object->getPreparedValue();
        }
        $setting = $processor;
    }
    protected function getPreparedValue() {
        return isset($this->setting) ? $this : $this->processor;
    }
    
    /**
     * Overrides RulesDataProcessor::attachForm().
     *
     * Overridden to just attach the help() of evaluators.
     */
    public static function attachForm(&$form, $settings, $param_info, $var_info, $access_check = TRUE) {
        foreach (self::evaluators($param_info, $access_check) as $name => $info) {
            $form['help'][$name] = call_user_func(array(
                $info['class'],
                'help',
            ), $var_info, $param_info);
            $form['help'][$name]['#weight'] = $info['weight'];
        }
    }
    
    /**
     * Returns all input evaluators that can be applied to the parameters type.
     */
    public static function evaluators($param_info = NULL, $access_check = TRUE) {
        return parent::processors($param_info, $access_check, 'evaluator_info');
    }
    
    /**
     * Overrides RulesDataProcessor::processors().
     *
     * Overridden to default to our hook, thus being equivalent to
     * self::evaluators().
     */
    public static function processors($param_info = NULL, $access_check = TRUE, $hook = 'evaluator_info') {
        return parent::processors($param_info, $access_check, $hook);
    }
    
    /**
     * Prepares the evaluation.
     *
     * For example, to determine whether the input evaluator has been used.
     * If this evaluator should be skipped just unset $this->setting.
     *
     * @param string $text
     *   The text to evaluate later on.
     * @param array $variables
     *   An array of info about available variables.
     * @param array $param_info
     *   (optional) An array of information about the handled parameter value.
     *   For backward compatibility, this parameter is not required.
     */
    public abstract function prepare($text, $variables);
    
    /**
     * Apply the input evaluator.
     *
     * @param string $text
     *   The text to evaluate.
     * @param array $options
     *   A keyed array of settings and flags to control the processing.
     *   Supported options are:
     *   - language: A language object to be used when processing.
     *   - callback: A callback function that will be used to post-process
     *     replacements that might be incorporated, so they can be cleaned in a
     *     certain way.
     *   - sanitize: A boolean flag indicating whether incorporated replacements
     *     should be sanitized.
     * @param RulesState $state
     *   The rules evaluation state.
     *
     * @return
     *   The evaluated text.
     */
    public abstract function evaluate($text, $options, RulesState $state);
    
    /**
     * Provide some usage help for the evaluator.
     *
     * @param array $variables
     *   An array of info about available variables.
     * @param array $param_info
     *   (optional) An array of information about the handled parameter value.
     *   For backward compatibility, this parameter is not required.
     *
     * @return array
     *   A renderable array.
     */
    public static function help($variables) {
        return array();
    }

}