Bladeren bron

Added test. Updated docs.

Piotr Jasiun 10 jaren geleden
bovenliggende
commit
b210ee0492

+ 29 - 3
packages/ckeditor5-utils/src/document/position.js

@@ -8,7 +8,6 @@
 CKEDITOR.define( function() {
 	/**
 	 * Position is always before of after a node.
-	 * See {@link #position} property for more information.
 	 *
 	 * @class document.Position
 	 */
@@ -20,7 +19,18 @@ CKEDITOR.define( function() {
 		 * @param {Number} offset Offset in that element.
 		 */
 		constructor( parent, offset ) {
+			/**
+			 * Parent element.
+			 *
+			 * @type {document.Element}
+			 */
 			this.parent = parent;
+
+			/**
+			 * Node offset in the parent element.
+			 *
+			 * @type {Number}
+			 */
 			this.offset = offset;
 		}
 
@@ -56,16 +66,32 @@ CKEDITOR.define( function() {
 			return path;
 		}
 
+		/**
+		 * Node directly before the position.
+		 *
+		 * @type {Node}
+		 */
 		get nodeBefore() {
 			return this.parent.children[ this.offset - 1 ] || null;
 		}
 
+		/**
+		 * Node directly after the position.
+		 *
+		 * @type {Node}
+		 */
 		get nodeAfter() {
 			return this.parent.children[ this.offset ] || null;
 		}
 
-		equals( otherPossition ) {
-			return this.offset === otherPossition.offset && this.parent === otherPossition.parent;
+		/**
+		 * Two positions equals if parent and offset equal.
+		 *
+		 * @param {document.Position} otherPosition Position to compare.
+		 * @returns {Boolean} true if positions equal.
+		 */
+		equals( otherPosition ) {
+			return this.offset === otherPosition.offset && this.parent === otherPosition.parent;
 		}
 	}
 

+ 40 - 10
packages/ckeditor5-utils/src/document/positioniterator.js

@@ -15,9 +15,9 @@ CKEDITOR.define( [
 	var CHARACTER = 2;
 
 	/**
-	 * Range iterator class.
+	 * Position iterator class. It allows to iterate forward and backward over the tree document.
 	 *
-	 * @class document.Range
+	 * @class document.PositionIterator
 	 */
 	class PositionIterator {
 		/**
@@ -26,19 +26,39 @@ CKEDITOR.define( [
 		 * @param {document.range} boundaries Range to define boundaries of the iterator.
 		 */
 		constructor( boundaries, iteratorPosition ) {
-			/**
-			 * Start position.
-			 *
-			 * @type {document.Position}
-			 */
 			if ( boundaries instanceof Position ) {
 				this.position = boundaries;
 			} else {
 				this.boundaries =  boundaries;
 				this.position = iteratorPosition || boundaries.start;
 			}
+
+			/**
+			 * Iterator position.
+			 *
+			 * @property {document.Position} position
+			 */
+
+			/**
+			 * Iterator boundaries. When {@link #next} is called on end boundary or {@link #previous} on the
+			 * first then `{ done: true }` is returned.
+			 *
+			 * If boundaries are not defined they are set before first and after last child of the root node.
+			 *
+			 * @property {document.Range} boundaries
+			 */
 		}
 
+		/**
+		 * Move {@link #position} to the next position and returned skipped value.
+		 *
+		 * @returns {Object} Value between last and new {@link #position}.
+		 * @returns {Boolean} return.done True if iterator is done.
+		 * @returns {Object} return.value
+		 * @returns {Number} return.value.type Skipped value type, possible options: {@link PositionIterator#OPENING_TAG},
+		 * {@link PositionIterator#CLOSING_TAG} or {@link PositionIterator#CHARACTER}.
+		 * @returns {Node} return.value.node Skipped node.
+		 */
 		next() {
 			var position = this.position;
 
@@ -68,6 +88,16 @@ CKEDITOR.define( [
 			}
 		}
 
+		/**
+		 * Move {@link #position} to the previous position and returned skipped value.
+		 *
+		 * @returns {Object} Value between last and new {@link #position}.
+		 * @returns {Boolean} return.done True if iterator is done.
+		 * @returns {Object} return.value
+		 * @returns {Number} return.value.type Skipped value type, possible options: {@link PositionIterator#OPENING_TAG},
+		 * {@link PositionIterator#CLOSING_TAG} or {@link PositionIterator#CHARACTER}.
+		 * @returns {Node} return.value.node Skipped node.
+		 */
 		previous() {
 			var position = this.position;
 
@@ -109,21 +139,21 @@ CKEDITOR.define( [
 	}
 
 	/**
-	 * Flag for linear data opening tag.
+	 * Flag for opening tag.
 	 *
 	 * @readonly
 	 */
 	PositionIterator.OPENING_TAG = OPENING_TAG;
 
 	/**
-	 * Flag for linear data closing tag.
+	 * Flag for closing tag.
 	 *
 	 * @readonly
 	 */
 	PositionIterator.CLOSING_TAG = CLOSING_TAG;
 
 	/**
-	 * Flag for linear data character.
+	 * Flag for character.
 	 *
 	 * @readonly
 	 */

+ 12 - 1
packages/ckeditor5-utils/src/document/range.js

@@ -7,7 +7,7 @@
 
 CKEDITOR.define( [ 'document/positioniterator' ], function( PositionIterator ) {
 	/**
-	 * Range class.
+	 * Range class. Range is iterable.
 	 *
 	 * @class document.Range
 	 */
@@ -34,10 +34,21 @@ CKEDITOR.define( [ 'document/positioniterator' ], function( PositionIterator ) {
 			this.end = end;
 		}
 
+		/**
+		 * Two ranges equals if first and last positions equal.
+		 *
+		 * @param {document.Range} otherRange Range to compare.
+		 * @returns {Boolean} true if ranges equal.
+		 */
 		equals( otherRange ) {
 			return this.start.equals( otherRange.start ) && this.end.equals( otherRange.end );
 		}
 
+		/**
+		 * Range iterator.
+		 *
+		 * @async see document.PositionIterator
+		 */
 		[ Symbol.iterator ]() {
 			return new PositionIterator( this );
 		}

+ 38 - 1
packages/ckeditor5-utils/tests/document/positioniterator.js

@@ -86,8 +86,9 @@ describe( 'range iterator', function() {
 		var Position = modules[ 'document/position' ];
 
 		var iterator = new PositionIterator( new Position( root, 0 ) );
+		var i, len;
 
-		for ( var i = 0, len = expectedItems.length; i < len; i++ ) {
+		for ( i = 0, len = expectedItems.length; i < len; i++ ) {
 			expect( iterator.next() ).to.deep.equal( { done: false, value: expectedItems[ i ] } );
 		}
 		expect( iterator.next() ).to.have.property( 'done' ).that.is.true;
@@ -105,6 +106,42 @@ describe( 'range iterator', function() {
 		expect( iterator.previous() ).to.have.property( 'done' ).that.is.true;
 	} );
 
+	it( 'should return next position in the boundaries', function() {
+		var PositionIterator = modules[ 'document/positioniterator' ];
+		var Position = modules[ 'document/position' ];
+		var Range = modules[ 'document/range' ];
+
+		var start = new Position( paragraph, 0 );
+		var end = new Position( img2, 0 );
+
+		var iterator = new PositionIterator( new Range( start, end ) );
+
+		var i, len;
+
+		for ( i = 3, len = expectedItems.length; i < 7; i++ ) {
+			expect( iterator.next() ).to.deep.equal( { done: false, value: expectedItems[ i ] } );
+		}
+		expect( iterator.next() ).to.have.property( 'done' ).that.is.true;
+	} );
+
+	it( 'should return previous position in the boundaries', function() {
+		var PositionIterator = modules[ 'document/positioniterator' ];
+		var Position = modules[ 'document/position' ];
+		var Range = modules[ 'document/range' ];
+
+		var start = new Position( paragraph, 0 );
+		var end = new Position( img2, 0 );
+
+		var iterator = new PositionIterator( new Range( start, end ), end );
+
+		var i, len;
+
+		for ( i = 6, len = expectedItems.length; i > 2; i-- ) {
+			expect( iterator.previous() ).to.deep.equal( { done: false, value: expectedItems[ i ] } );
+		}
+		expect( iterator.previous() ).to.have.property( 'done' ).that.is.true;
+	} );
+
 	it( 'should return iterate over the range', function() {
 		var Position = modules[ 'document/position' ];
 		var Range = modules[ 'document/range' ];