@ckeditor/ckeditor5-engine 36.0.1 → 37.0.0-alpha.1

package/src/view/treewalker.js

@@ -17,8 +17,7 @@ export default class TreeWalker {
     /**
      * Creates a range iterator. All parameters are optional, but you have to specify either `boundaries` or `startPosition`.
      *
-     * @constructor
-     * @param {TODO ~TreeWalkerOptions} options Object with configuration.
+     * @param options Object with configuration.
      */
     constructor(options = {}) {
         if (!options.boundaries && !options.startPosition) {
@@ -37,112 +36,62 @@ export default class TreeWalker {
              */
             throw new CKEditorError('view-tree-walker-unknown-direction', options.startPosition, { direction: options.direction });
         }
-        /**
-         * Iterator boundaries.
-         *
-         * When the iterator is walking `'forward'` on the end of boundary or is walking `'backward'`
-         * on the start of boundary, then `{ done: true }` is returned.
-         *
-         * If boundaries are not defined they are set before first and after last child of the root node.
-         *
-         * @readonly
-         * @member {module:engine/view/range~Range} module:engine/view/treewalker~TreeWalker#boundaries
-         */
         this.boundaries = options.boundaries || null;
-        /**
-         * Iterator position. If start position is not defined then position depends on {@link #direction}. If direction is
-         * `'forward'` position starts form the beginning, when direction is `'backward'` position starts from the end.
-         *
-         * @readonly
-         * @member {module:engine/view/position~Position} module:engine/view/treewalker~TreeWalker#position
-         */
         if (options.startPosition) {
-            this.position = Position._createAt(options.startPosition);
+            this._position = Position._createAt(options.startPosition);
         }
         else {
-            this.position = Position._createAt(options.boundaries[options.direction == 'backward' ? 'end' : 'start']);
+            this._position = Position._createAt(options.boundaries[options.direction == 'backward' ? 'end' : 'start']);
         }
-        /**
-         * Walking direction. Defaults `'forward'`.
-         *
-         * @readonly
-         * @member {'backward'|'forward'} module:engine/view/treewalker~TreeWalker#direction
-         */
         this.direction = options.direction || 'forward';
-        /**
-         * Flag indicating whether all characters from {@link module:engine/view/text~Text} should be returned as one
-         * {@link module:engine/view/text~Text} or one by one as {@link module:engine/view/textproxy~TextProxy}.
-         *
-         * @readonly
-         * @member {Boolean} module:engine/view/treewalker~TreeWalker#singleCharacters
-         */
         this.singleCharacters = !!options.singleCharacters;
-        /**
-         * Flag indicating whether iterator should enter elements or not. If the iterator is shallow child nodes of any
-         * iterated node will not be returned along with `elementEnd` tag.
-         *
-         * @readonly
-         * @member {Boolean} module:engine/view/treewalker~TreeWalker#shallow
-         */
         this.shallow = !!options.shallow;
-        /**
-         * Flag indicating whether iterator should ignore `elementEnd` tags. If set to `true`, walker will not
-         * return a parent node of the start position. Each {@link module:engine/view/element~Element} will be returned once.
-         * When set to `false` each element might be returned twice: for `'elementStart'` and `'elementEnd'`.
-         *
-         * @readonly
-         * @member {Boolean} module:engine/view/treewalker~TreeWalker#ignoreElementEnd
-         */
         this.ignoreElementEnd = !!options.ignoreElementEnd;
-        /**
-         * Start boundary parent.
-         *
-         * @private
-         * @member {module:engine/view/node~Node} module:engine/view/treewalker~TreeWalker#_boundaryStartParent
-         */
         this._boundaryStartParent = this.boundaries ? this.boundaries.start.parent : null;
-        /**
-         * End boundary parent.
-         *
-         * @private
-         * @member {module:engine/view/node~Node} module:engine/view/treewalker~TreeWalker#_boundaryEndParent
-         */
         this._boundaryEndParent = this.boundaries ? this.boundaries.end.parent : null;
     }
     /**
      * Iterable interface.
-     *
-     * @returns {Iterable.<module:engine/view/treewalker~TreeWalkerValue>}
      */
     [Symbol.iterator]() {
         return this;
     }
+    /**
+     * Iterator position. If start position is not defined then position depends on {@link #direction}. If direction is
+     * `'forward'` position starts form the beginning, when direction is `'backward'` position starts from the end.
+     */
+    get position() {
+        return this._position;
+    }
     /**
      * Moves {@link #position} in the {@link #direction} skipping values as long as the callback function returns `true`.
      *
      * For example:
      *
-     * 		walker.skip( value => value.type == 'text' ); // <p>{}foo</p> -> <p>foo[]</p>
-     * 		walker.skip( value => true ); // Move the position to the end: <p>{}foo</p> -> <p>foo</p>[]
-     * 		walker.skip( value => false ); // Do not move the position.
+     * ```ts
+     * walker.skip( value => value.type == 'text' ); // <p>{}foo</p> -> <p>foo[]</p>
+     * walker.skip( value => true ); // Move the position to the end: <p>{}foo</p> -> <p>foo</p>[]
+     * walker.skip( value => false ); // Do not move the position.
+     * ```
      *
-     * @param {Function} skip Callback function. Gets {@link module:engine/view/treewalker~TreeWalkerValue} and should
+     * @param skip Callback function. Gets {@link module:engine/view/treewalker~TreeWalkerValue} and should
      * return `true` if the value should be skipped or `false` if not.
      */
     skip(skip) {
-        let done, value, prevPosition;
+        let nextResult;
+        let prevPosition;
         do {
             prevPosition = this.position;
-            ({ done, value } = this.next());
-        } while (!done && skip(value));
-        if (!done) {
-            this.position = prevPosition;
+            nextResult = this.next();
+        } while (!nextResult.done && skip(nextResult.value));
+        if (!nextResult.done) {
+            this._position = prevPosition;
         }
     }
     /**
      * Gets the next tree walker's value.
      *
-     * @returns {module:engine/view/treewalker~TreeWalkerValue} Object implementing iterator interface, returning
+     * @returns Object implementing iterator interface, returning
      * information about taken step.
      */
     next() {
@@ -155,11 +104,6 @@ export default class TreeWalker {
     }
     /**
      * Makes a step forward in view. Moves the {@link #position} to the next position and returns the encountered value.
-     *
-     * @private
-     * @returns {Object}
-     * @returns {Boolean} return.done `true` if iterator is done, `false` otherwise.
-     * @returns {module:engine/view/treewalker~TreeWalkerValue} return.value Information about taken step.
      */
     _next() {
         let position = this.position.clone();
@@ -179,7 +123,7 @@ export default class TreeWalker {
         if (parent instanceof Text) {
             if (position.isAtEnd) {
                 // Prevent returning "elementEnd" for Text node. Skip that value and return the next walker step.
-                this.position = Position._createAfter(parent);
+                this._position = Position._createAfter(parent);
                 return this._next();
             }
             node = parent.data[position.offset];
@@ -194,13 +138,13 @@ export default class TreeWalker {
             else {
                 position.offset++;
             }
-            this.position = position;
+            this._position = position;
             return this._formatReturnValue('elementStart', node, previousPosition, position, 1);
         }
         else if (node instanceof Text) {
             if (this.singleCharacters) {
                 position = new Position(node, 0);
-                this.position = position;
+                this._position = position;
                 return this._next();
             }
             else {
@@ -217,7 +161,7 @@ export default class TreeWalker {
                     // If not just keep moving forward.
                     position.offset++;
                 }
-                this.position = position;
+                this._position = position;
                 return this._formatReturnValue('text', item, previousPosition, position, charactersCount);
             }
         }
@@ -233,13 +177,13 @@ export default class TreeWalker {
             }
             const textProxy = new TextProxy(parent, position.offset, textLength);
             position.offset += textLength;
-            this.position = position;
+            this._position = position;
             return this._formatReturnValue('text', textProxy, previousPosition, position, textLength);
         }
         else {
             // `node` is not set, we reached the end of current `parent`.
             position = Position._createAfter(parent);
-            this.position = position;
+            this._position = position;
             if (this.ignoreElementEnd) {
                 return this._next();
             }
@@ -250,11 +194,6 @@ export default class TreeWalker {
     }
     /**
      * Makes a step backward in view. Moves the {@link #position} to the previous position and returns the encountered value.
-     *
-     * @private
-     * @returns {Object}
-     * @returns {Boolean} return.done True if iterator is done.
-     * @returns {module:engine/view/treewalker~TreeWalkerValue} return.value Information about taken step.
      */
     _previous() {
         let position = this.position.clone();
@@ -274,7 +213,7 @@ export default class TreeWalker {
         if (parent instanceof Text) {
             if (position.isAtStart) {
                 // Prevent returning "elementStart" for Text node. Skip that value and return the next walker step.
-                this.position = Position._createBefore(parent);
+                this._position = Position._createBefore(parent);
                 return this._previous();
             }
             node = parent.data[position.offset - 1];
@@ -285,7 +224,7 @@ export default class TreeWalker {
         if (node instanceof Element) {
             if (!this.shallow) {
                 position = new Position(node, node.childCount);
-                this.position = position;
+                this._position = position;
                 if (this.ignoreElementEnd) {
                     return this._previous();
                 }
@@ -295,14 +234,14 @@ export default class TreeWalker {
             }
             else {
                 position.offset--;
-                this.position = position;
+                this._position = position;
                 return this._formatReturnValue('elementStart', node, previousPosition, position, 1);
             }
         }
         else if (node instanceof Text) {
             if (this.singleCharacters) {
                 position = new Position(node, node.data.length);
-                this.position = position;
+                this._position = position;
                 return this._previous();
             }
             else {
@@ -320,7 +259,7 @@ export default class TreeWalker {
                     // If not just keep moving backward.
                     position.offset--;
                 }
-                this.position = position;
+                this._position = position;
                 return this._formatReturnValue('text', item, previousPosition, position, charactersCount);
             }
         }
@@ -336,26 +275,24 @@ export default class TreeWalker {
             }
             position.offset -= textLength;
             const textProxy = new TextProxy(parent, position.offset, textLength);
-            this.position = position;
+            this._position = position;
             return this._formatReturnValue('text', textProxy, previousPosition, position, textLength);
         }
         else {
             // `node` is not set, we reached the beginning of current `parent`.
             position = Position._createBefore(parent);
-            this.position = position;
+            this._position = position;
             return this._formatReturnValue('elementStart', parent, previousPosition, position, 1);
         }
     }
     /**
      * Format returned data and adjust `previousPosition` and `nextPosition` if reach the bound of the {@link module:engine/view/text~Text}.
      *
-     * @private
-     * @param {module:engine/view/treewalker~TreeWalkerValueType} type Type of step.
-     * @param {module:engine/view/item~Item} item Item between old and new position.
-     * @param {module:engine/view/position~Position} previousPosition Previous position of iterator.
-     * @param {module:engine/view/position~Position} nextPosition Next position of iterator.
-     * @param {Number} [length] Length of the item.
-     * @returns {module:engine/view/treewalker~TreeWalkerValue}
+     * @param type Type of step.
+     * @param item Item between old and new position.
+     * @param previousPosition Previous position of iterator.
+     * @param nextPosition Next position of iterator.
+     * @param length Length of the item.
      */
     _formatReturnValue(type, item, previousPosition, nextPosition, length) {
         // Text is a specific parent, because contains string instead of children.
@@ -368,7 +305,7 @@ export default class TreeWalker {
                 if (this.direction == 'forward' && !(this.boundaries && this.boundaries.end.isEqual(this.position))) {
                     nextPosition = Position._createAfter(item.textNode);
                     // When we change nextPosition of returned value we need also update walker current position.
-                    this.position = nextPosition;
+                    this._position = nextPosition;
                 }
                 else {
                     previousPosition = Position._createAfter(item.textNode);
@@ -379,7 +316,7 @@ export default class TreeWalker {
                 if (this.direction == 'backward' && !(this.boundaries && this.boundaries.start.isEqual(this.position))) {
                     nextPosition = Position._createBefore(item.textNode);
                     // When we change nextPosition of returned value we need also update walker current position.
-                    this.position = nextPosition;
+                    this._position = nextPosition;
                 }
                 else {
                     previousPosition = Position._createBefore(item.textNode);