Merge pull request #1516 from ckeditor/t/1515

Other: Renamed view `Writer` to `DowncastWriter`. Closes #1515.

BREAKING CHANGE: The `engine/view/writer` module was renamed to `engine/view/downcastwriter`.

Author: scofalik

src/controller/datacontroller.js

@@ -21,7 +21,7 @@ import { convertText, convertToModelFragment } from '../conversion/upcast-conver
 
 import ViewDocumentFragment from '../view/documentfragment';
 import ViewDocument from '../view/document';
-import ViewWriter from '../view/writer';
+import ViewDowncastWriter from '../view/downcastwriter';
 
 import ModelRange from '../model/range';
 
@@ -153,9 +153,9 @@ export default class DataController {
 
 		const viewDocumentFragment = new ViewDocumentFragment();
 
-		// Create separate ViewWriter just for data conversion purposes.
+		// Create separate ViewDowncastWriter just for data conversion purposes.
 		// We have no view controller and rendering do DOM in DataController so view.change() block is not used here.
-		const viewWriter = new ViewWriter( new ViewDocument() );
+		const viewWriter = new ViewDowncastWriter( new ViewDocument() );
 		this.mapper.bindElements( modelElementOrFragment, viewDocumentFragment );
 
 		this.downcastDispatcher.convertInsert( modelRange, viewWriter );

src/conversion/downcast-converters.js

@@ -364,7 +364,7 @@ function _normalizeToElementConfig( view, viewElementType ) {
 // Creates a view element instance from the provided {@link module:engine/view/elementdefinition~ElementDefinition} and class.
 //
 // @param {module:engine/view/elementdefinition~ElementDefinition} viewElementDefinition
-// @param {module:engine/view/writer~Writer} viewWriter
+// @param {module:engine/view/downcastwriter~DowncastWriter} viewWriter
 // @param {'container'|'attribute'|'ui'} viewElementType
 // @returns {module:engine/view/element~Element}
 function _createViewElementFromDefinition( viewElementDefinition, viewWriter, viewElementType ) {

src/conversion/downcastdispatcher.js

@@ -74,7 +74,7 @@ import { extend } from 'lodash-es';
  * converted the change should also stop the event (for efficiency purposes).
  *
  * When providing custom listeners for `DowncastDispatcher` remember to use provided
- * {@link module:engine/view/writer~Writer view writer} to apply changes to the view document.
+ * {@link module:engine/view/downcastwriter~DowncastWriter view downcast writer} to apply changes to the view document.
  *
  * Example of a custom converter for `DowncastDispatcher`:
  *
@@ -120,7 +120,7 @@ export default class DowncastDispatcher {
 	 * Takes {@link module:engine/model/differ~Differ model differ} object with buffered changes and fires conversion basing on it.
 	 *
 	 * @param {module:engine/model/differ~Differ} differ Differ object with buffered changes.
-	 * @param {module:engine/view/writer~Writer} writer View writer that should be used to modify view document.
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
 	 */
 	convertChanges( differ, writer ) {
 		// Before the view is updated, remove markers which have changed.
@@ -155,7 +155,7 @@ export default class DowncastDispatcher {
 	 * @fires insert
 	 * @fires attribute
 	 * @param {module:engine/model/range~Range} range Inserted range.
-	 * @param {module:engine/view/writer~Writer} writer View writer that should be used to modify view document.
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
 	 */
 	convertInsert( range, writer ) {
 		this.conversionApi.writer = writer;
@@ -195,7 +195,7 @@ export default class DowncastDispatcher {
 	 * @param {module:engine/model/position~Position} position Position from which node was removed.
 	 * @param {Number} length Offset size of removed node.
 	 * @param {String} name Name of removed node.
-	 * @param {module:engine/view/writer~Writer} writer View writer that should be used to modify view document.
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
 	 */
 	convertRemove( position, length, name, writer ) {
 		this.conversionApi.writer = writer;
@@ -215,7 +215,7 @@ export default class DowncastDispatcher {
 	 * @param {String} key Key of the attribute that has changed.
 	 * @param {*} oldValue Attribute value before the change or `null` if the attribute has not been set before.
 	 * @param {*} newValue New attribute value or `null` if the attribute has been removed.
-	 * @param {module:engine/view/writer~Writer} writer View writer that should be used to modify view document.
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
 	 */
 	convertAttribute( range, key, oldValue, newValue, writer ) {
 		this.conversionApi.writer = writer;
@@ -251,7 +251,7 @@ export default class DowncastDispatcher {
 	 * @fires attribute
 	 * @param {module:engine/model/selection~Selection} selection Selection to convert.
 	 * @param {Array.<module:engine/model/markercollection~Marker>} markers Array of markers containing model markers.
-	 * @param {module:engine/view/writer~Writer} writer View writer that should be used to modify view document.
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
 	 */
 	convertSelection( selection, markers, writer ) {
 		const markersAtSelection = Array.from( markers.getMarkersAtPosition( selection.getFirstPosition() ) );
@@ -308,7 +308,7 @@ export default class DowncastDispatcher {
 	 * @fires addMarker
 	 * @param {String} markerName Marker name.
 	 * @param {module:engine/model/range~Range} markerRange Marker range.
-	 * @param {module:engine/view/writer~Writer} writer View writer that should be used to modify view document.
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
 	 */
 	convertMarkerAdd( markerName, markerRange, writer ) {
 		// Do not convert if range is in graveyard or not in the document (e.g. in DocumentFragment).
@@ -357,7 +357,7 @@ export default class DowncastDispatcher {
 	 * @fires removeMarker
 	 * @param {String} markerName Marker name.
 	 * @param {module:engine/model/range~Range} markerRange Marker range.
-	 * @param {module:engine/view/writer~Writer} writer View writer that should be used to modify view document.
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
 	 */
 	convertMarkerRemove( markerName, markerRange, writer ) {
 		// Do not convert if range is in graveyard or not in the document (e.g. in DocumentFragment).

src/view/attributeelement.js

@@ -15,7 +15,7 @@ const DEFAULT_PRIORITY = 10;
 
 /**
  * Attributes are elements which define document presentation. They are mostly elements like `<b>` or `<span>`.
- * Attributes can be broken and merged by the {@link module:engine/view/writer~Writer view writer}.
+ * Attributes can be broken and merged by the {@link module:engine/view/downcastwriter~DowncastWriter view downcast writer}.
  *
  * Editing engine does not define fixed HTML DTD. This is why the type of the {@link module:engine/view/element~Element} need to
  * be defined by the feature developer. Creating an element you should use {@link module:engine/view/containerelement~ContainerElement}
@@ -27,7 +27,7 @@ export default class AttributeElement extends Element {
 	/**
 	 * Creates a attribute element.
 	 *
-	 * @see module:engine/view/writer~Writer#createAttributeElement
+	 * @see module:engine/view/downcastwriter~DowncastWriter#createAttributeElement
 	 * @protected
 	 * @see module:engine/view/element~Element
 	 */
@@ -43,7 +43,7 @@ export default class AttributeElement extends Element {
 		this.getFillerOffset = getFillerOffset;
 
 		/**
-		 * Element priority. Decides in what order elements are wrapped by {@link module:engine/view/writer~Writer}.
+		 * Element priority. Decides in what order elements are wrapped by {@link module:engine/view/downcastwriter~DowncastWriter}.
 		 *
 		 * @protected
 		 * @member {Number}
@@ -63,7 +63,7 @@ export default class AttributeElement extends Element {
 		 * Keeps all the attribute elements that have the same {@link module:engine/view/attributeelement~AttributeElement#id ids}
 		 * and still exist in the view tree.
 		 *
-		 * This property is managed by {@link module:engine/view/writer~Writer}.
+		 * This property is managed by {@link module:engine/view/downcastwriter~DowncastWriter}.
 		 *
 		 * @protected
 		 * @member {Set|null}
@@ -72,7 +72,7 @@ export default class AttributeElement extends Element {
 	}
 
 	/**
-	 * Element priority. Decides in what order elements are wrapped by {@link module:engine/view/writer~Writer}.
+	 * Element priority. Decides in what order elements are wrapped by {@link module:engine/view/downcastwriter~DowncastWriter}.
 	 *
 	 * @readonly
 	 * @returns {Number}
@@ -142,10 +142,10 @@ export default class AttributeElement extends Element {
 	 * elements have to have the same {@link module:engine/view/attributeelement~AttributeElement#id} value to be
 	 * considered similar.
 	 *
-	 * Similarity is important for {@link module:engine/view/writer~Writer}. For example:
+	 * Similarity is important for {@link module:engine/view/downcastwriter~DowncastWriter}. For example:
 	 *
 	 * * two following similar elements can be merged together into one, longer element,
-	 * * {@link module:engine/view/writer~Writer#unwrap} checks similarity of passed element and processed element to
+	 * * {@link module:engine/view/downcastwriter~DowncastWriter#unwrap} checks similarity of passed element and processed element to
 	 * decide whether processed element should be unwrapped,
 	 * * etc.
 	 *

src/view/containerelement.js

@@ -23,16 +23,15 @@ import Element from './element';
  * DOM properly. {@link module:engine/view/domconverter~DomConverter} will ensure that `ContainerElement` is editable and it is possible
  * to put caret inside it, even if the container is empty.
  *
- * Secondly, {@link module:engine/view/writer~Writer view writer} uses this information.
- * Nodes {@link module:engine/view/writer~Writer#breakAttributes breaking} and {@link module:engine/view/writer~Writer#mergeAttributes
- * merging}
- * is performed only in a bounds of a container nodes.
+ * Secondly, {@link module:engine/view/downcastwriter~DowncastWriter view downcast writer} uses this information.
+ * Nodes {@link module:engine/view/downcastwriter~DowncastWriter#breakAttributes breaking} and
+ * {@link module:engine/view/downcastwriter~DowncastWriter#mergeAttributes merging} is performed only in a bounds of a container nodes.
  *
  * For instance if `<p>` is an container and `<b>` is attribute:
  *
  *		<p><b>fo^o</b></p>
  *
- * {@link module:engine/view/writer~Writer#breakAttributes breakAttributes} will create:
+ * {@link module:engine/view/downcastwriter~DowncastWriter#breakAttributes breakAttributes} will create:
  *
  *		<p><b>fo</b><b>o</b></p>
  *
@@ -49,7 +48,7 @@ export default class ContainerElement extends Element {
 	 * Creates a container element.
 	 *
 	 * @see module:engine/view/element~Element
-	 * @see module:engine/view/writer~Writer#createContainerElement
+	 * @see module:engine/view/downcastwriter~DowncastWriter#createContainerElement
 	 * @protected
 	 */
 	constructor( name, attrs, children ) {

src/view/document.js

@@ -112,8 +112,8 @@ export default class Document {
 	 * to elements based on the view structure or selection. However, is you need DOM elements to be already updated, use
 	 * {@link module:engine/view/view~View#event:render render event}.
 	 *
-	 * As a parameter, a post-fixer callback receives a {@link module:engine/view/writer~Writer writer} instance connected with the
-	 * executed changes block.
+	 * As a parameter, a post-fixer callback receives a {@link module:engine/view/downcastwriter~DowncastWriter downcast writer}
+	 * instance connected with the executed changes block.
 	 *
 	 * @param {Function} postFixer
 	 */
@@ -125,7 +125,7 @@ export default class Document {
 	 * Performs post-fixer loops. Executes post-fixer callbacks as long as none of them has done any changes to the model.
 	 *
 	 * @protected
-	 * @param {module:engine/view/writer~Writer} writer
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer
 	 */
 	_callPostFixers( writer ) {
 		let wasFixed = false;

src/view/writer.js renamed to src/view/downcastwriter.js

@@ -4,7 +4,7 @@
  */
 
 /**
- * @module module:engine/view/writer
+ * @module module:engine/view/downcastwriter
  */
 
 import Position from './position';
@@ -21,11 +21,13 @@ import EditableElement from './editableelement';
 import { isPlainObject } from 'lodash-es';
 
 /**
- * View writer class. Provides set of methods used to properly manipulate nodes attached to
+ * View downcast writer class. Provides set of methods used to properly manipulate nodes attached to
  * {@link module:engine/view/document~Document view document}. It is not recommended to use it directly. To get an instance
  * of view writer associated with the document use {@link module:engine/view/view~View#change view.change()) method.
+ * The `DowncastWriter` is designed to work with semantic view which is the view downcasted from model. For working with
+ * ordinary view (e.g. parsed from string) {@link module:engine/view/upcastwriter~UpcastWriter upcast writer} should be used.
  */
-export default class Writer {
+export default class DowncastWriter {
 	constructor( document ) {
 		/**
 		 * @readonly
@@ -88,7 +90,7 @@ export default class Writer {
 	 * 		// Removes all ranges.
 	 *		writer.setSelection( null );
 	 *
-	 * `Writer#setSelection()` allow passing additional options (`backward`, `fake` and `label`) as the last argument.
+	 * `DowncastWriter#setSelection()` allow passing additional options (`backward`, `fake` and `label`) as the last argument.
 	 *
 	 *		// Sets selection as backward.
 	 *		writer.setSelection( range, { backward: true } );
@@ -369,8 +371,8 @@ export default class Writer {
 	 *
 	 * **Note:** {@link module:engine/view/documentfragment~DocumentFragment DocumentFragment} is treated like a container.
 	 *
-	 * **Note:** Difference between {@link module:engine/view/writer~Writer#breakAttributes breakAttributes} and
-	 * {@link module:engine/view/writer~Writer#breakContainer breakContainer} is that `breakAttributes` breaks all
+	 * **Note:** Difference between {@link module:engine/view/downcastwriter~DowncastWriter#breakAttributes breakAttributes} and
+	 * {@link module:engine/view/downcastwriter~DowncastWriter#breakContainer breakContainer} is that `breakAttributes` breaks all
 	 * {@link module:engine/view/attributeelement~AttributeElement attribute elements} that are ancestors of given `position`,
 	 * up to the first encountered {@link module:engine/view/containerelement~ContainerElement container element}.
 	 * `breakContainer` assumes that given `position` is directly in container element and breaks that container element.
@@ -389,7 +391,7 @@ export default class Writer {
 	 *
 	 * @see module:engine/view/attributeelement~AttributeElement
 	 * @see module:engine/view/containerelement~ContainerElement
-	 * @see module:engine/view/writer~Writer#breakContainer
+	 * @see module:engine/view/downcastwriter~DowncastWriter#breakContainer
 	 * @param {module:engine/view/position~Position|module:engine/view/range~Range} positionOrRange Position where
 	 * to break attribute elements.
 	 * @returns {module:engine/view/position~Position|module:engine/view/range~Range} New position or range, after breaking the attribute
@@ -413,15 +415,15 @@ export default class Writer {
 	 *        <p>^foobar</p> -> ^<p>foobar</p>
 	 *        <p>foobar^</p> -> <p>foobar</p>^
 	 *
-	 * **Note:** Difference between {@link module:engine/view/writer~Writer#breakAttributes breakAttributes} and
-	 * {@link module:engine/view/writer~Writer#breakContainer breakContainer} is that `breakAttributes` breaks all
+	 * **Note:** Difference between {@link module:engine/view/downcastwriter~DowncastWriter#breakAttributes breakAttributes} and
+	 * {@link module:engine/view/downcastwriter~DowncastWriter#breakContainer breakContainer} is that `breakAttributes` breaks all
 	 * {@link module:engine/view/attributeelement~AttributeElement attribute elements} that are ancestors of given `position`,
 	 * up to the first encountered {@link module:engine/view/containerelement~ContainerElement container element}.
 	 * `breakContainer` assumes that given `position` is directly in container element and breaks that container element.
 	 *
 	 * @see module:engine/view/attributeelement~AttributeElement
 	 * @see module:engine/view/containerelement~ContainerElement
-	 * @see module:engine/view/writer~Writer#breakAttributes
+	 * @see module:engine/view/downcastwriter~DowncastWriter#breakAttributes
 	 * @param {module:engine/view/position~Position} position Position where to break element.
 	 * @returns {module:engine/view/position~Position} Position between broken elements. If element has not been broken,
 	 * the returned position is placed either before it or after it.
@@ -480,14 +482,14 @@ export default class Writer {
 	 *        <p><b>[]</b></p> -> <p>[]</p>
 	 *        <p><b>foo</b><i>[]</i><b>bar</b></p> -> <p><b>foo{}bar</b></p>
 	 *
-	 * **Note:** Difference between {@link module:engine/view/writer~Writer#mergeAttributes mergeAttributes} and
-	 * {@link module:engine/view/writer~Writer#mergeContainers mergeContainers} is that `mergeAttributes` merges two
+	 * **Note:** Difference between {@link module:engine/view/downcastwriter~DowncastWriter#mergeAttributes mergeAttributes} and
+	 * {@link module:engine/view/downcastwriter~DowncastWriter#mergeContainers mergeContainers} is that `mergeAttributes` merges two
 	 * {@link module:engine/view/attributeelement~AttributeElement attribute elements} or {@link module:engine/view/text~Text text nodes}
 	 * while `mergeContainer` merges two {@link module:engine/view/containerelement~ContainerElement container elements}.
 	 *
 	 * @see module:engine/view/attributeelement~AttributeElement
 	 * @see module:engine/view/containerelement~ContainerElement
-	 * @see module:engine/view/writer~Writer#mergeContainers
+	 * @see module:engine/view/downcastwriter~DowncastWriter#mergeContainers
 	 * @param {module:engine/view/position~Position} position Merge position.
 	 * @returns {module:engine/view/position~Position} Position after merge.
 	 */
@@ -547,14 +549,14 @@ export default class Writer {
 	 *        <p>foo</p>^<p>bar</p> -> <p>foo^bar</p>
 	 *        <div>foo</div>^<p>bar</p> -> <div>foo^bar</div>
 	 *
-	 * **Note:** Difference between {@link module:engine/view/writer~Writer#mergeAttributes mergeAttributes} and
-	 * {@link module:engine/view/writer~Writer#mergeContainers mergeContainers} is that `mergeAttributes` merges two
+	 * **Note:** Difference between {@link module:engine/view/downcastwriter~DowncastWriter#mergeAttributes mergeAttributes} and
+	 * {@link module:engine/view/downcastwriter~DowncastWriter#mergeContainers mergeContainers} is that `mergeAttributes` merges two
 	 * {@link module:engine/view/attributeelement~AttributeElement attribute elements} or {@link module:engine/view/text~Text text nodes}
 	 * while `mergeContainer` merges two {@link module:engine/view/containerelement~ContainerElement container elements}.
 	 *
 	 * @see module:engine/view/attributeelement~AttributeElement
 	 * @see module:engine/view/containerelement~ContainerElement
-	 * @see module:engine/view/writer~Writer#mergeAttributes
+	 * @see module:engine/view/downcastwriter~DowncastWriter#mergeAttributes
 	 * @param {module:engine/view/position~Position} position Merge position.
 	 * @returns {module:engine/view/position~Position} Position after merge.
 	 */
@@ -1304,7 +1306,7 @@ export default class Writer {
 	}
 
 	/**
-	 * Helper function used by other `Writer` methods. Breaks attribute elements at the boundaries of given range.
+	 * Helper function used by other `DowncastWriter` methods. Breaks attribute elements at the boundaries of given range.
 	 *
 	 * @private
 	 * @param {module:engine/view/range~Range} range Range which `start` and `end` positions will be used to break attributes.
@@ -1336,7 +1338,7 @@ export default class Writer {
 	}
 
 	/**
-	 * Helper function used by other `Writer` methods. Breaks attribute elements at given position.
+	 * Helper function used by other `DowncastWriter` methods. Breaks attribute elements at given position.
 	 *
 	 * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `view-writer-cannot-break-empty-element` when break position
 	 * is placed inside {@link module:engine/view/emptyelement~EmptyElement EmptyElement}.