class RulesState

class RulesState {
    
    /**
     * Globally keeps the ids of rules blocked due to recursion prevention.
     *
     * @var array
     */
    protected static $blocked = array();
    
    /**
     * The known variables.
     *
     * @var array
     */
    public $variables = array();
    
    /**
     * Holds info about the variables.
     *
     * @var array
     */
    protected $info = array();
    
    /**
     * Keeps wrappers to be saved later on.
     */
    protected $save;
    
    /**
     * Holds the arguments while an element is executed.
     *
     * May be used by the element to easily access the wrapped arguments.
     */
    public $currentArguments;
    
    /**
     * Variable for saving currently blocked configs for serialization.
     */
    protected $currentlyBlocked;
    
    /**
     * Constructs a RulesState object.
     */
    public function __construct() {
        // Use an object in order to ensure any cloned states reference the same
        // save information.
        $this->save = new ArrayObject();
        $this->addVariable('site', FALSE, self::defaultVariables('site'));
    }
    
    /**
     * Adds the given variable to the given execution state.
     */
    public function addVariable($name, $data, $info) {
        $this->info[$name] = $info + array(
            'skip save' => FALSE,
            'type' => 'unknown',
            'handler' => FALSE,
        );
        if (empty($this->info[$name]['handler'])) {
            $this->variables[$name] = rules_wrap_data($data, $this->info[$name]);
        }
    }
    
    /**
     * Runs post-evaluation tasks, such as saving variables.
     */
    public function cleanUp() {
        // Make changes permanent.
        foreach ($this->save
            ->getArrayCopy() as $selector => $wrapper) {
            $this->saveNow($selector);
        }
        unset($this->currentArguments);
    }
    
    /**
     * Block a rules configuration from execution.
     */
    public function block($rules_config) {
        if (empty($rules_config->recursion) && $rules_config->id) {
            self::$blocked[$rules_config->id] = TRUE;
        }
    }
    
    /**
     * Unblock a rules configuration from execution.
     */
    public function unblock($rules_config) {
        if (empty($rules_config->recursion) && $rules_config->id) {
            unset(self::$blocked[$rules_config->id]);
        }
    }
    
    /**
     * Returns whether a rules configuration should be blocked from execution.
     */
    public function isBlocked($rule_config) {
        return !empty($rule_config->id) && isset(self::$blocked[$rule_config->id]);
    }
    
    /**
     * Get the info about the state variables or a single variable.
     */
    public function varInfo($name = NULL) {
        if (isset($name)) {
            return isset($this->info[$name]) ? $this->info[$name] : FALSE;
        }
        return $this->info;
    }
    
    /**
     * Returns whether the given wrapper is saveable.
     */
    public function isSavable($wrapper) {
        return $wrapper instanceof EntityDrupalWrapper && entity_type_supports($wrapper->type(), 'save') || $wrapper instanceof RulesDataWrapperSavableInterface;
    }
    
    /**
     * Returns whether the variable with the given name is an entity.
     */
    public function isEntity($name) {
        $entity_info = entity_get_info();
        return isset($this->info[$name]['type']) && isset($entity_info[$this->info[$name]['type']]);
    }
    
    /**
     * Gets a variable.
     *
     * If necessary, the specified handler is invoked to fetch the variable.
     *
     * @param string $name
     *   The name of the variable to return.
     *
     * @return
     *   The variable or a EntityMetadataWrapper containing the variable.
     *
     * @throws RulesEvaluationException
     *   Throws a RulesEvaluationException in case we have info about the
     *   requested variable, but it is not defined.
     */
    public function &get($name) {
        if (!array_key_exists($name, $this->variables)) {
            // If there is handler to load the variable, do it now.
            if (!empty($this->info[$name]['handler'])) {
                $data = call_user_func($this->info[$name]['handler'], rules_unwrap_data($this->variables), $name, $this->info[$name]);
                $this->variables[$name] = rules_wrap_data($data, $this->info[$name]);
                $this->info[$name]['handler'] = FALSE;
                if (!isset($data)) {
                    throw new RulesEvaluationException('Unable to load variable %name, aborting.', array(
                        '%name' => $name,
                    ), NULL, RulesLog::INFO);
                }
            }
            else {
                throw new RulesEvaluationException('Unable to get variable %name, it is not defined.', array(
                    '%name' => $name,
                ), NULL, RulesLog::ERROR);
            }
        }
        return $this->variables[$name];
    }
    
    /**
     * Apply permanent changes provided the wrapper's data type is saveable.
     *
     * @param $selector
     *   The data selector of the wrapper to save or just a variable name.
     * @param $wrapper
     * @param bool $immediate
     *   Pass FALSE to postpone saving to later on. Else it's immediately saved.
     */
    public function saveChanges($selector, $wrapper, $immediate = FALSE) {
        $info = $wrapper->info();
        if (empty($info['skip save']) && $this->isSavable($wrapper)) {
            $this->save($selector, $wrapper, $immediate);
        }
        elseif (empty($info['skip save']) && isset($info['parent']) && !$wrapper instanceof EntityDrupalWrapper) {
            // Cut of the last part of the selector.
            $selector = implode(':', explode(':', $selector, -1));
            $this->saveChanges($selector, $info['parent'], $immediate);
        }
        return $this;
    }
    
    /**
     * Remembers to save the wrapper on cleanup or does it now.
     */
    protected function save($selector, EntityMetadataWrapper $wrapper, $immediate) {
        // Convert variable names and selectors to both use underscores.
        $selector = strtr($selector, '-', '_');
        if (isset($this->save[$selector])) {
            if ($this->save[$selector][0]
                ->getIdentifier() == $wrapper->getIdentifier()) {
                // The entity is already remembered. So do a combined save.
                $this->save[$selector][1] += self::$blocked;
            }
            else {
                // The wrapper is already in there, but wraps another entity. So first
                // save the old one, then care about the new one.
                $this->saveNow($selector);
            }
        }
        if (!isset($this->save[$selector])) {
            // In case of immediate saving don't clone the wrapper, so saving a new
            // entity immediately makes the identifier available afterwards.
            $this->save[$selector] = array(
                $immediate ? $wrapper : clone $wrapper,
                self::$blocked,
            );
        }
        if ($immediate) {
            $this->saveNow($selector);
        }
    }
    
    /**
     * Saves the wrapper for the given selector.
     */
    protected function saveNow($selector) {
        // Add the set of blocked elements for the recursion prevention.
        $previously_blocked = self::$blocked;
        self::$blocked += $this->save[$selector][1];
        // Actually save!
        $wrapper = $this->save[$selector][0];
        $entity = $wrapper->value();
        // When operating in hook_entity_insert() $entity->is_new might be still
        // set. In that case remove the flag to avoid causing another insert instead
        // of an update.
        if (!empty($entity->is_new) && $wrapper->getIdentifier()) {
            $entity->is_new = FALSE;
        }
        rules_log('Saved %selector of type %type.', array(
            '%selector' => $selector,
            '%type' => $wrapper->type(),
        ));
        $wrapper->save();
        // Restore the state's set of blocked elements.
        self::$blocked = $previously_blocked;
        unset($this->save[$selector]);
    }
    
    /**
     * Merges info from the given state into the existing state.
     *
     * Merges the info about to-be-saved variables from the given state into the
     * existing state. Therefore we can aggregate saves from invoked components.
     * Merged-in saves are removed from the given state, but not-mergeable saves
     * remain there.
     *
     * @param $state
     *   The state for which to merge the to be saved variables in.
     * @param $component
     *   The component which has been invoked, thus needs to be blocked for the
     *   merged in saves.
     * @param $settings
     *   The settings of the element that invoked the component. Contains
     *   information about variable/selector mappings between the states.
     */
    public function mergeSaveVariables(RulesState $state, RulesPlugin $component, $settings) {
        // For any saves that we take over, also block the component.
        $this->block($component);
        foreach ($state->save
            ->getArrayCopy() as $selector => $data) {
            $parts = explode(':', $selector, 2);
            // Adapt the selector to fit for the parent state and move the wrapper.
            if (isset($settings[$parts[0] . ':select'])) {
                $parts[0] = $settings[$parts[0] . ':select'];
                $this->save(implode(':', $parts), $data[0], FALSE);
                unset($state->save[$selector]);
            }
        }
        $this->unblock($component);
    }
    
    /**
     * Returns an entity metadata wrapper as specified in the selector.
     *
     * @param string $selector
     *   The selector string, e.g. "node:author:mail".
     * @param string $langcode
     *   (optional) The language code used to get the argument value if the
     *   argument value should be translated. Defaults to LANGUAGE_NONE.
     *
     * @return EntityMetadataWrapper
     *   The wrapper for the given selector.
     *
     * @throws RulesEvaluationException
     *   Throws a RulesEvaluationException in case the selector cannot be applied.
     */
    public function applyDataSelector($selector, $langcode = LANGUAGE_NONE) {
        $parts = explode(':', str_replace('-', '_', $selector), 2);
        $wrapper = $this->get($parts[0]);
        if (count($parts) == 1) {
            return $wrapper;
        }
        elseif (!$wrapper instanceof EntityMetadataWrapper) {
            throw new RulesEvaluationException('Unable to apply data selector %selector. The specified variable is not wrapped correctly.', array(
                '%selector' => $selector,
            ));
        }
        try {
            foreach (explode(':', $parts[1]) as $name) {
                if ($wrapper instanceof EntityListWrapper || $wrapper instanceof EntityStructureWrapper) {
                    // Make sure we are using the right language. Wrappers might be cached
                    // and have previous langcodes set, so always set the right language.
                    if ($wrapper instanceof EntityStructureWrapper) {
                        $wrapper->language($langcode);
                    }
                    $wrapper = $wrapper->get($name);
                }
                else {
                    throw new RulesEvaluationException('Unable to apply data selector %selector. The specified variable is not a list or a structure: %wrapper.', array(
                        '%selector' => $selector,
                        '%wrapper' => $wrapper,
                    ));
                }
            }
        } catch (EntityMetadataWrapperException $e) {
            // In case of an exception, re-throw it.
            throw new RulesEvaluationException('Unable to apply data selector %selector: %error', array(
                '%selector' => $selector,
                '%error' => $e->getMessage(),
            ));
        }
        return $wrapper;
    }
    
    /**
     * Magic method. Only serialize variables and their info.
     *
     * Additionally we remember currently blocked configs, so we can restore them
     * upon deserialization using restoreBlocks().
     */
    public function __sleep() {
        $this->currentlyBlocked = self::$blocked;
        return array(
            'info',
            'variables',
            'currentlyBlocked',
        );
    }
    
    /**
     * Magic method. Unserialize variables and their info.
     */
    public function __wakeup() {
        $this->save = new ArrayObject();
    }
    
    /**
     * Restores the before-serialization blocked configurations.
     *
     * Warning: This overwrites any possible currently blocked configs. Thus
     * do not invoke this method if there might be evaluations active.
     */
    public function restoreBlocks() {
        self::$blocked = $this->currentlyBlocked;
    }
    
    /**
     * Defines always-available variables.
     *
     * @param $key
     *   (optional)
     */
    public static function defaultVariables($key = NULL) {
        // Add a variable for accessing site-wide data properties.
        $vars['site'] = array(
            'type' => 'site',
            'label' => t('Site information'),
            'description' => t("Site-wide settings and other global information."),
            // Add the property info via a callback making use of the cached info.
'property info alter' => array(
                'RulesData',
                'addSiteMetadata',
            ),
            'property info' => array(),
            'optional' => TRUE,
        );
        return isset($key) ? $vars[$key] : $vars;
    }

}