MDL-24932 moodleemoticon tinymce: use restoreSelection() instead of custom bookmark...
[moodle.git] / backup / util / structure / base_nested_element.class.php
CommitLineData
69dd0c8c
EL
1<?php
2
3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
18/**
19 * @package moodlecore
20 * @subpackage backup-structure
21 * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23 *
24 * TODO: Finish phpdocs
25 */
26
27/**
28 * Abstract class representing one nestable element (non final) piece of information
29 */
30abstract class base_nested_element extends base_final_element {
31
32 /** @var array final elements of the element (maps to XML final elements of the tag) */
33 private $final_elements;
34
35 /** @var array children base_elements of this element (describes structure of the XML file) */
36 private $children;
37
38 /** @var base_optigroup optional group of this element (branches to be processed conditionally) */
39 private $optigroup;
40
41 /** @var array elements already used by the base_element, to avoid circular references */
42 private $used;
43
44 /**
45 * Constructor - instantiates one base_nested_element, specifying its basic info.
46 *
47 * @param string $name name of the element
48 * @param array $attributes attributes this element will handle (optional, defaults to null)
49 * @param array $final_elements this element will handle (optional, defaults to null)
50 */
51 public function __construct($name, $attributes = null, $final_elements = null) {
52 parent::__construct($name, $attributes);
53 $this->final_elements = array();
54 if (!empty($final_elements)) {
55 $this->add_final_elements($final_elements);
56 }
57 $this->children = array();
58 $this->optigroup = null;
59 $this->used[] = $name;
60 }
61
62 protected function get_used() {
63 return $this->used;
64 }
65
66 protected function set_used($used) {
67 $this->used = $used;
68 }
69
70 protected function add_used($element) {
71 $this->used = array_merge($this->used, $element->get_used());
72 }
73
74 protected function check_and_set_used($element) {
75 $grandparent = $this->get_grandoptigroupelement_or_grandparent();
76 if ($existing = array_intersect($grandparent->get_used(), $element->get_used())) { // Check the element isn't being used already
77 throw new base_element_struct_exception('baseelementexisting', implode($existing));
78 }
79 $grandparent->add_used($element);
80 // If the parent is one optigroup, add the element useds to it too
81 if ($grandparent->get_parent() instanceof base_optigroup) {
82 $grandparent->get_parent()->add_used($element);
83 }
84
85 }
86
87/// Public API starts here
88
89 public function get_final_elements() {
90 return $this->final_elements;
91 }
92
93 public function get_final_element($name) {
94 if (array_key_exists($name, $this->final_elements)) {
95 return $this->final_elements[$name];
96 } else {
97 return null;
98 }
99 }
100
101 public function get_children() {
102 return $this->children;
103 }
104
105 public function get_child($name) {
106 if (array_key_exists($name, $this->children)) {
107 return $this->children[$name];
108 } else {
109 return null;
110 }
111 }
112
113 public function get_optigroup() {
114 return $this->optigroup;
115 }
116
117 public function add_final_elements($final_elements) {
118 if ($final_elements instanceof base_final_element || is_string($final_elements)) { // Accept 1 final_element, object or string
119 $final_elements = array($final_elements);
120 }
121 if (is_array($final_elements)) {
122 foreach ($final_elements as $final_element) {
123 if (is_string($final_element)) { // Accept string final_elements
124 $final_element = $this->get_new_final_element($final_element);
125 }
126 if (!($final_element instanceof base_final_element)) {
127 throw new base_element_struct_exception('baseelementnofinalelement', get_class($final_element));
128 }
129 if (array_key_exists($final_element->get_name(), $this->final_elements)) {
130 throw new base_element_struct_exception('baseelementexists', $final_element->get_name());
131 }
132 $this->final_elements[$final_element->get_name()] = $final_element;
133 $final_element->set_parent($this);
134 }
135 } else {
136 throw new base_element_struct_exception('baseelementincorrect');
137 }
138 }
139
140 public function add_child($element) {
141 if (!($element instanceof base_nested_element)) { // parameter must be a base_nested_element
142 if (!$found = get_class($element)) {
143 $found = 'non object';
144 }
145 throw new base_element_struct_exception('nestedelementincorrect', $found);
146 }
147 $this->check_and_set_used($element);
148 $this->children[$element->get_name()] = $element;
149 $element->set_parent($this);
150 }
151
152 public function add_optigroup($optigroup) {
153 if (!($optigroup instanceof base_optigroup)) { // parameter must be a base_optigroup
154 if (!$found = get_class($optigroup)) {
155 $found = 'non object';
156 }
157 throw new base_element_struct_exception('optigroupincorrect', $found);
158 }
159 if ($this->optigroup !== null) {
160 throw new base_element_struct_exception('optigroupalreadyset', $found);
161 }
162 $this->check_and_set_used($optigroup);
163 $this->optigroup = $optigroup;
164 $optigroup->set_parent($this);
165 }
166
167 public function get_value() {
168 throw new base_element_struct_exception('nestedelementnotvalue');
169 }
170
171 public function set_value($value) {
172 throw new base_element_struct_exception('nestedelementnotvalue');
173 }
174
175 public function clean_value() {
176 throw new base_element_struct_exception('nestedelementnotvalue');
177 }
178
179 public function clean_values() {
180 parent::clean_values();
181 if (!empty($this->final_elements)) {
182 foreach ($this->final_elements as $final_element) {
183 $final_element->clean_values();
184 }
185 }
186 if (!empty($this->children)) {
187 foreach ($this->children as $child) {
188 $child->clean_values();
189 }
190 }
191 if (!empty($this->optigroup)) {
192 $this->optigroup->clean_values();
193 }
194 }
195
196 public function to_string($showvalue = false) {
197 $output = parent::to_string($showvalue);
198 if (!empty($this->final_elements)) {
199 foreach ($this->final_elements as $final_element) {
200 $output .= PHP_EOL . $final_element->to_string($showvalue);
201 }
202 }
203 if (!empty($this->children)) {
204 foreach ($this->children as $child) {
205 $output .= PHP_EOL . $child->to_string($showvalue);
206 }
207 }
208 if (!empty($this->optigroup)) {
209 $output .= PHP_EOL . $this->optigroup->to_string($showvalue);
210 }
211 return $output;
212 }
213
214// Implementable API
215
216 /**
217 * Returns one instace of the @final_element class to work with
218 * when final_elements are added simply by name
219 */
220 abstract protected function get_new_final_element($name);
221}
222
223/**
224 * base_element exception to control all the errors while building the nested tree
225 *
226 * This exception will be thrown each time the base_element class detects some
227 * inconsistency related with the building of the nested tree representing one base part
228 * (invalid objects, circular references, double parents...)
229 */
230class base_element_struct_exception extends base_atom_exception {
231
232 /**
233 * Constructor - instantiates one base_element_struct_exception
234 *
235 * @param string $errorcode key for the corresponding error string
236 * @param object $a extra words and phrases that might be required in the error string
237 * @param string $debuginfo optional debugging information
238 */
239 public function __construct($errorcode, $a = null, $debuginfo = null) {
240 parent::__construct($errorcode, $a, $debuginfo);
241 }
242}