class RulesContainerPlugin

abstract class RulesContainerPlugin extends RulesPlugin implements IteratorAggregate {
    protected $children = array();
    public function __construct($variables = array()) {
        $this->setUp();
        if (!empty($variables) && $this->isRoot()) {
            $this->info['variables'] = $variables;
        }
    }
    
    /**
     * Returns the specified variables, in case the plugin is used as component.
     */
    public function &componentVariables() {
        if ($this->isRoot()) {
            $this->info += array(
                'variables' => array(),
            );
            return $this->info['variables'];
        }
        // We have to return a reference in any case.
        $return = NULL;
        return $return;
    }
    
    /**
     * Allows access to the children through the iterator.
     *
     * @return RulesRecursiveElementIterator
     */
    public function getIterator() {
        return new RulesRecursiveElementIterator($this->children);
    }
    
    /**
     * @return RulesContainerPlugin
     */
    public function integrityCheck() {
        if (!empty($this->info['variables']) && !$this->isRoot()) {
            throw new RulesIntegrityException(t('%plugin: Specifying state variables is not possible for child elements.', array(
                '%plugin' => $this->getPluginName(),
            )), $this);
        }
        parent::integrityCheck();
        foreach ($this->children as $child) {
            $child->integrityCheck();
        }
        return $this;
    }
    public function dependencies() {
        $modules = array_flip(parent::dependencies());
        foreach ($this->children as $child) {
            $modules += array_flip($child->dependencies());
        }
        return array_keys($modules);
    }
    public function parameterInfo($optional = FALSE) {
        $params = parent::parameterInfo($optional);
        if (isset($this->info['variables'])) {
            foreach ($this->info['variables'] as $name => $var_info) {
                if (empty($var_info['handler']) && (!isset($var_info['parameter']) || $var_info['parameter'])) {
                    $params[$name] = $var_info;
                    // For lists allow empty variables by default.
                    if (entity_property_list_extract_type($var_info['type'])) {
                        $params[$name] += array(
                            'allow null' => TRUE,
                        );
                    }
                }
            }
        }
        return $params;
    }
    public function availableVariables() {
        if (!isset($this->availableVariables)) {
            if ($this->isRoot()) {
                $this->availableVariables = RulesState::defaultVariables();
                if (isset($this->info['variables'])) {
                    $this->availableVariables += $this->info['variables'];
                }
            }
            else {
                $this->availableVariables = $this->parent
                    ->stateVariables($this);
            }
        }
        return $this->availableVariables;
    }
    
    /**
     * Returns available state variables for an element.
     *
     * Returns info about variables available in the evaluation state for any
     * children elements or if given for a special child element.
     *
     * @param $element
     *   The element for which the available state variables should be returned.
     *   If NULL is given, the variables available before any children are invoked
     *   are returned. If set to TRUE, the variables available after evaluating
     *   all children will be returned.
     */
    protected function stateVariables($element = NULL) {
        $vars = $this->availableVariables();
        if (isset($element)) {
            // Add in variables provided by siblings executed before the element.
            foreach ($this->children as $child) {
                if ($child === $element) {
                    break;
                }
                $vars += $child->providesVariables();
                // Take variable info assertions into account.
                if ($assertions = $child->variableInfoAssertions()) {
                    $vars = RulesData::addMetadataAssertions($vars, $assertions);
                }
            }
        }
        return $vars;
    }
    protected function variableInfoAssertions() {
        $assertions = array();
        foreach ($this->children as $child) {
            if ($add = $child->variableInfoAssertions()) {
                $assertions = rules_update_array($assertions, $add);
            }
        }
        return $assertions;
    }
    protected function setUpVariables() {
        return isset($this->info['variables']) ? parent::parameterInfo(TRUE) + $this->info['variables'] : $this->parameterInfo(TRUE);
    }
    
    /**
     * Executes container with the given arguments.
     *
     * Condition containers just return a boolean while action containers return
     * the configured provided variables as an array of variables.
     */
    public function executeByArgs($args = array()) {
        $replacements = array(
            '%label' => $this->label(),
            '@plugin' => $this->itemName,
        );
        rules_log('Executing @plugin %label.', $replacements, RulesLog::INFO, $this, TRUE);
        $this->processSettings();
        $state = $this->setUpState($args);
        // Handle recursion prevention.
        if ($state->isBlocked($this)) {
            return rules_log('Not evaluating @plugin %label to prevent recursion.', array(
                '%label' => $this->label(),
                '@plugin' => $this->plugin(),
            ), RulesLog::INFO);
        }
        // Block the config to prevent any future recursion.
        $state->block($this);
        module_invoke_all('rules_config_execute', $this);
        $result = $this->evaluate($state);
        $return = $this->returnVariables($state, $result);
        $state->unblock($this);
        $state->cleanUp();
        rules_log('Finished executing of @plugin %label.', $replacements, RulesLog::INFO, $this, FALSE);
        return $return;
    }
    public function access() {
        foreach ($this->children as $key => $child) {
            if (!$child->access()) {
                return FALSE;
            }
        }
        return TRUE;
    }
    public function destroy() {
        foreach ($this->children as $key => $child) {
            $child->destroy();
        }
        parent::destroy();
    }
    
    /**
     * By default we do a deep clone.
     */
    public function __clone() {
        parent::__clone();
        foreach ($this->children as $key => $child) {
            $this->children[$key] = clone $child;
            $this->children[$key]->parent = $this;
        }
    }
    
    /**
     * Overrides delete to keep the children alive, if possible.
     */
    public function delete($keep_children = TRUE) {
        if (isset($this->parent) && $keep_children) {
            foreach ($this->children as $child) {
                $child->setParent($this->parent);
            }
        }
        parent::delete();
    }
    public function __sleep() {
        return parent::__sleep() + array(
            'children' => 'children',
            'info' => 'info',
        );
    }
    
    /**
     * Sorts all child elements by their weight.
     *
     * @param bool $deep
     *   If enabled a deep sort is performed, thus the whole element tree below
     *   this element is sorted.
     */
    public function sortChildren($deep = FALSE) {
        // Make sure the array order is kept in case two children have the same
        // weight by ensuring later children would have higher weights.
        foreach (array_values($this->children) as $i => $child) {
            $child->weight += $i / 1000;
        }
        usort($this->children, array(
            'RulesPlugin',
            'compare',
        ));
        // Fix up the weights afterwards to be unique integers.
        foreach (array_values($this->children) as $i => $child) {
            $child->weight = $i;
        }
        if ($deep) {
            foreach (new ParentIterator($this->getIterator()) as $child) {
                $child->sortChildren(TRUE);
            }
        }
        $this->resetInternalCache();
    }
    protected function exportChildren($key = NULL) {
        $key = isset($key) ? $key : strtoupper($this->plugin());
        $export[$key] = array();
        foreach ($this->children as $child) {
            $export[$key][] = $child->export();
        }
        return $export;
    }
    
    /**
     * Determines whether the element should be exported in flat style.
     *
     * Flat style means that the export keys are written directly into the export
     * array, whereas else the export is written into a sub-array.
     */
    protected function exportFlat() {
        // By default we always use flat style for plugins without any parameters
        // or provided variables, as then only children have to be exported. E.g.
        // this applies to the OR and AND plugins.
        return $this->isRoot() || !$this->pluginParameterInfo() && !$this->providesVariables();
    }
    protected function exportToArray() {
        $export = array();
        if (!empty($this->info['variables'])) {
            $export['USES VARIABLES'] = $this->info['variables'];
        }
        if ($this->exportFlat()) {
            $export += $this->exportSettings() + $this->exportChildren();
        }
        else {
            $export[strtoupper($this->plugin())] = $this->exportSettings() + $this->exportChildren();
        }
        return $export;
    }
    public function import(array $export) {
        if (!empty($export['USES VARIABLES'])) {
            $this->info['variables'] = $export['USES VARIABLES'];
        }
        // Care for exports having the export array nested in a sub-array.
        if (!$this->exportFlat()) {
            $export = reset($export);
        }
        $this->importSettings($export);
        $this->importChildren($export);
    }
    protected function importChildren($export, $key = NULL) {
        $key = isset($key) ? $key : strtoupper($this->plugin());
        foreach ($export[$key] as $child_export) {
            $plugin = _rules_import_get_plugin(rules_array_key($child_export), $this instanceof RulesActionInterface ? 'action' : 'condition');
            $child = rules_plugin_factory($plugin);
            $child->setParent($this);
            $child->import($child_export);
        }
    }
    public function resetInternalCache() {
        $this->availableVariables = NULL;
        foreach ($this->children as $child) {
            $child->resetInternalCache();
        }
    }
    
    /**
     * Overrides optimize().
     */
    public function optimize() {
        parent::optimize();
        // Now let the children optimize itself.
        foreach ($this as $element) {
            $element->optimize();
        }
    }

}