From b1a5b58fa283923dc222d64ca3bf968ba1b9576f Mon Sep 17 00:00:00 2001 From: Nathan Sobo Date: Thu, 29 Oct 2015 14:32:21 -0600 Subject: [PATCH] Rename Marker to TextEditorMarker to resolve ambiguity w/ TextBuffer API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We expose both kinds of markers in Atom, and the docs were actually wrong when we refer to Markers from TextBuffer because it linked to the TextEditor layer’s Marker implementation. This will clarify the difference. --- src/cursor.coffee | 4 +- src/decoration.coffee | 6 +-- src/display-buffer.coffee | 22 ++++---- src/gutter.coffee | 4 +- ...arker.coffee => text-editor-marker.coffee} | 26 +++++----- src/text-editor.coffee | 52 +++++++++---------- 6 files changed, 57 insertions(+), 57 deletions(-) rename src/{marker.coffee => text-editor-marker.coffee} (94%) diff --git a/src/cursor.coffee b/src/cursor.coffee index 40cde4aca..0f87c2760 100644 --- a/src/cursor.coffee +++ b/src/cursor.coffee @@ -7,7 +7,7 @@ Model = require './model' # where text can be inserted. # # Cursors belong to {TextEditor}s and have some metadata attached in the form -# of a {Marker}. +# of a {TextEditorMarker}. module.exports = class Cursor extends Model screenPosition: null @@ -127,7 +127,7 @@ class Cursor extends Model Section: Cursor Position Details ### - # Public: Returns the underlying {Marker} for the cursor. + # Public: Returns the underlying {TextEditorMarker} for the cursor. # Useful with overlay {Decoration}s. getMarker: -> @marker diff --git a/src/decoration.coffee b/src/decoration.coffee index 937909ec7..f57d234d1 100644 --- a/src/decoration.coffee +++ b/src/decoration.coffee @@ -11,7 +11,7 @@ translateDecorationParamsOldToNew = (decorationParams) -> decorationParams.gutterName = 'line-number' decorationParams -# Essential: Represents a decoration that follows a {Marker}. A decoration is +# Essential: Represents a decoration that follows a {TextEditorMarker}. A decoration is # basically a visual representation of a marker. It allows you to add CSS # classes to line numbers in the gutter, lines, and add selection-line regions # around marked ranges of text. @@ -25,7 +25,7 @@ translateDecorationParamsOldToNew = (decorationParams) -> # decoration = editor.decorateMarker(marker, {type: 'line', class: 'my-line-class'}) # ``` # -# Best practice for destroying the decoration is by destroying the {Marker}. +# Best practice for destroying the decoration is by destroying the {TextEditorMarker}. # # ```coffee # marker.destroy() @@ -72,7 +72,7 @@ class Decoration # Essential: Destroy this marker. # - # If you own the marker, you should use {Marker::destroy} which will destroy + # If you own the marker, you should use {TextEditorMarker::destroy} which will destroy # this decoration. destroy: -> return if @destroyed diff --git a/src/display-buffer.coffee b/src/display-buffer.coffee index 331f50fa2..203d3360d 100644 --- a/src/display-buffer.coffee +++ b/src/display-buffer.coffee @@ -8,7 +8,7 @@ Model = require './model' Token = require './token' Decoration = require './decoration' LayerDecoration = require './layer-decoration' -Marker = require './marker' +TextEditorMarker = require './text-editor-marker' class BufferToScreenConversionError extends Error constructor: (@message, @metadata) -> @@ -826,21 +826,21 @@ class DisplayBuffer extends Model decorationsForMarkerId: (markerId) -> @decorationsByMarkerId[markerId] - # Retrieves a {Marker} based on its id. + # Retrieves a {TextEditorMarker} based on its id. # # id - A {Number} representing a marker id # - # Returns the {Marker} (if it exists). + # Returns the {TextEditorMarker} (if it exists). getMarker: (id) -> unless marker = @markers[id] if bufferMarker = @buffer.getMarker(id) - marker = new Marker({bufferMarker, displayBuffer: this}) + marker = new TextEditorMarker({bufferMarker, displayBuffer: this}) @markers[id] = marker marker # Retrieves the active markers in the buffer. # - # Returns an {Array} of existing {Marker}s. + # Returns an {Array} of existing {TextEditorMarker}s. getMarkers: -> @buffer.getMarkers().map ({id}) => @getMarker(id) @@ -850,7 +850,7 @@ class DisplayBuffer extends Model # Public: Constructs a new marker at the given screen range. # # range - The marker {Range} (representing the distance between the head and tail) - # options - Options to pass to the {Marker} constructor + # options - Options to pass to the {TextEditorMarker} constructor # # Returns a {Number} representing the new marker's ID. markScreenRange: (args...) -> @@ -860,7 +860,7 @@ class DisplayBuffer extends Model # Public: Constructs a new marker at the given buffer range. # # range - The marker {Range} (representing the distance between the head and tail) - # options - Options to pass to the {Marker} constructor + # options - Options to pass to the {TextEditorMarker} constructor # # Returns a {Number} representing the new marker's ID. markBufferRange: (range, options) -> @@ -869,7 +869,7 @@ class DisplayBuffer extends Model # Public: Constructs a new marker at the given screen position. # # range - The marker {Range} (representing the distance between the head and tail) - # options - Options to pass to the {Marker} constructor + # options - Options to pass to the {TextEditorMarker} constructor # # Returns a {Number} representing the new marker's ID. markScreenPosition: (screenPosition, options) -> @@ -878,7 +878,7 @@ class DisplayBuffer extends Model # Public: Constructs a new marker at the given buffer position. # # range - The marker {Range} (representing the distance between the head and tail) - # options - Options to pass to the {Marker} constructor + # options - Options to pass to the {TextEditorMarker} constructor # # Returns a {Number} representing the new marker's ID. markBufferPosition: (bufferPosition, options) -> @@ -895,7 +895,7 @@ class DisplayBuffer extends Model # # Refer to {DisplayBuffer::findMarkers} for details. # - # Returns a {Marker} or null + # Returns a {TextEditorMarker} or null findMarker: (params) -> @findMarkers(params)[0] @@ -916,7 +916,7 @@ class DisplayBuffer extends Model # :containedInBufferRange - A {Range} or range-compatible {Array}. Only # returns markers contained within this range. # - # Returns an {Array} of {Marker}s + # Returns an {Array} of {TextEditorMarker}s findMarkers: (params) -> params = @translateToBufferMarkerParams(params) @buffer.findMarkers(params).map (stringMarker) => @getMarker(stringMarker.id) diff --git a/src/gutter.coffee b/src/gutter.coffee index 8418823bf..f59fa7b6e 100644 --- a/src/gutter.coffee +++ b/src/gutter.coffee @@ -71,13 +71,13 @@ class Gutter isVisible: -> @visible - # Essential: Add a decoration that tracks a {Marker}. When the marker moves, + # Essential: Add a decoration that tracks a {TextEditorMarker}. When the marker moves, # is invalidated, or is destroyed, the decoration will be updated to reflect # the marker's state. # # ## Arguments # - # * `marker` A {Marker} you want this decoration to follow. + # * `marker` A {TextEditorMarker} you want this decoration to follow. # * `decorationParams` An {Object} representing the decoration. It is passed # to {TextEditor::decorateMarker} as its `decorationParams` and so supports # all options documented there. diff --git a/src/marker.coffee b/src/text-editor-marker.coffee similarity index 94% rename from src/marker.coffee rename to src/text-editor-marker.coffee index 16f644027..e1ac89fd3 100644 --- a/src/marker.coffee +++ b/src/text-editor-marker.coffee @@ -6,7 +6,7 @@ _ = require 'underscore-plus' # targets, misspelled words, and anything else that needs to track a logical # location in the buffer over time. # -# ### Marker Creation +# ### TextEditorMarker Creation # # Use {TextEditor::markBufferRange} rather than creating Markers directly. # @@ -40,7 +40,7 @@ _ = require 'underscore-plus' # # See {TextEditor::markBufferRange} for usage. module.exports = -class Marker +class TextEditorMarker bufferMarkerSubscription: null oldHeadBufferPosition: null oldHeadScreenPosition: null @@ -66,7 +66,7 @@ class Marker @bufferMarker.destroy() @disposables.dispose() - # Essential: Creates and returns a new {Marker} with the same properties as + # Essential: Creates and returns a new {TextEditorMarker} with the same properties as # this marker. # # {Selection} markers (markers with a custom property `type: "selection"`) @@ -79,7 +79,7 @@ class Marker # marker. The new marker's properties are computed by extending this marker's # properties with `properties`. # - # Returns a {Marker}. + # Returns a {TextEditorMarker}. copy: (properties) -> @displayBuffer.getMarker(@bufferMarker.copy(properties).id) @@ -129,7 +129,7 @@ class Marker @emitter.on 'did-destroy', callback ### - Section: Marker Details + Section: TextEditorMarker Details ### # Essential: Returns a {Boolean} indicating whether the marker is valid. Markers can be @@ -140,7 +140,7 @@ class Marker # Essential: Returns a {Boolean} indicating whether the marker has been destroyed. A marker # can be invalid without being destroyed, in which case undoing the invalidating # operation would restore the marker. Once a marker is destroyed by calling - # {Marker::destroy}, no undo/redo operation can ever bring it back. + # {TextEditorMarker::destroy}, no undo/redo operation can ever bring it back. isDestroyed: -> @bufferMarker.isDestroyed() @@ -179,14 +179,14 @@ class Marker # Essential: Returns a {Boolean} indicating whether this marker is equivalent to # another marker, meaning they have the same range and options. # - # * `other` {Marker} other marker + # * `other` {TextEditorMarker} other marker isEqual: (other) -> return false unless other instanceof @constructor @bufferMarker.isEqual(other.bufferMarker) # Essential: Compares this marker to another based on their ranges. # - # * `other` {Marker} + # * `other` {TextEditorMarker} # # Returns a {Number} compare: (other) -> @@ -225,28 +225,28 @@ class Marker @setBufferRange(@displayBuffer.bufferRangeForScreenRange(screenRange), options) # Essential: Retrieves the buffer position of the marker's start. This will always be - # less than or equal to the result of {Marker::getEndBufferPosition}. + # less than or equal to the result of {TextEditorMarker::getEndBufferPosition}. # # Returns a {Point}. getStartBufferPosition: -> @bufferMarker.getStartPosition() # Essential: Retrieves the screen position of the marker's start. This will always be - # less than or equal to the result of {Marker::getEndScreenPosition}. + # less than or equal to the result of {TextEditorMarker::getEndScreenPosition}. # # Returns a {Point}. getStartScreenPosition: -> @displayBuffer.screenPositionForBufferPosition(@getStartBufferPosition(), wrapAtSoftNewlines: true) # Essential: Retrieves the buffer position of the marker's end. This will always be - # greater than or equal to the result of {Marker::getStartBufferPosition}. + # greater than or equal to the result of {TextEditorMarker::getStartBufferPosition}. # # Returns a {Point}. getEndBufferPosition: -> @bufferMarker.getEndPosition() # Essential: Retrieves the screen position of the marker's end. This will always be - # greater than or equal to the result of {Marker::getStartScreenPosition}. + # greater than or equal to the result of {TextEditorMarker::getStartScreenPosition}. # # Returns a {Point}. getEndScreenPosition: -> @@ -330,7 +330,7 @@ class Marker # Returns a {String} representation of the marker inspect: -> - "Marker(id: #{@id}, bufferRange: #{@getBufferRange()})" + "TextEditorMarker(id: #{@id}, bufferRange: #{@getBufferRange()})" destroyed: -> delete @displayBuffer.markers[@id] diff --git a/src/text-editor.coffee b/src/text-editor.coffee index 9273841eb..a4ad70b6e 100644 --- a/src/text-editor.coffee +++ b/src/text-editor.coffee @@ -1396,7 +1396,7 @@ class TextEditor extends Model Section: Decorations ### - # Essential: Adds a decoration that tracks a {Marker}. When the marker moves, + # Essential: Adds a decoration that tracks a {TextEditorMarker}. When the marker moves, # is invalidated, or is destroyed, the decoration will be updated to reflect # the marker's state. # @@ -1417,28 +1417,28 @@ class TextEditor extends Model # # ``` # * __overlay__: Positions the view associated with the given item at the head - # or tail of the given `Marker`. - # * __gutter__: A decoration that tracks a {Marker} in a {Gutter}. Gutter + # or tail of the given `TextEditorMarker`. + # * __gutter__: A decoration that tracks a {TextEditorMarker} in a {Gutter}. Gutter # decorations are created by calling {Gutter::decorateMarker} on the # desired `Gutter` instance. # # ## Arguments # - # * `marker` A {Marker} you want this decoration to follow. + # * `marker` A {TextEditorMarker} you want this decoration to follow. # * `decorationParams` An {Object} representing the decoration e.g. # `{type: 'line-number', class: 'linter-error'}` # * `type` There are several supported decoration types. The behavior of the # types are as follows: # * `line` Adds the given `class` to the lines overlapping the rows - # spanned by the `Marker`. + # spanned by the `TextEditorMarker`. # * `line-number` Adds the given `class` to the line numbers overlapping - # the rows spanned by the `Marker`. + # the rows spanned by the `TextEditorMarker`. # * `highlight` Creates a `.highlight` div with the nested class with up - # to 3 nested regions that fill the area spanned by the `Marker`. + # to 3 nested regions that fill the area spanned by the `TextEditorMarker`. # * `overlay` Positions the view associated with the given item at the - # head or tail of the given `Marker`, depending on the `position` + # head or tail of the given `TextEditorMarker`, depending on the `position` # property. - # * `gutter` Tracks a {Marker} in a {Gutter}. Created by calling + # * `gutter` Tracks a {TextEditorMarker} in a {Gutter}. Created by calling # {Gutter::decorateMarker} on the desired `Gutter` instance. # * `class` This CSS class will be applied to the decorated line number, # line, highlight, or overlay. @@ -1446,16 +1446,16 @@ class TextEditor extends Model # corresponding view registered. Only applicable to the `gutter` and # `overlay` types. # * `onlyHead` (optional) If `true`, the decoration will only be applied to - # the head of the `Marker`. Only applicable to the `line` and + # the head of the `TextEditorMarker`. Only applicable to the `line` and # `line-number` types. # * `onlyEmpty` (optional) If `true`, the decoration will only be applied if - # the associated `Marker` is empty. Only applicable to the `gutter`, + # the associated `TextEditorMarker` is empty. Only applicable to the `gutter`, # `line`, and `line-number` types. # * `onlyNonEmpty` (optional) If `true`, the decoration will only be applied - # if the associated `Marker` is non-empty. Only applicable to the + # if the associated `TextEditorMarker` is non-empty. Only applicable to the # `gutter`, `line`, and `line-number` types. # * `position` (optional) Only applicable to decorations of type `overlay`, - # controls where the overlay view is positioned relative to the `Marker`. + # controls where the overlay view is positioned relative to the `TextEditorMarker`. # Values can be `'head'` (the default), or `'tail'`. # # Returns a {Decoration} object @@ -1472,7 +1472,7 @@ class TextEditor extends Model # # Returns an {Object} of decorations in the form # `{1: [{id: 10, type: 'line-number', class: 'someclass'}], 2: ...}` - # where the keys are {Marker} IDs, and the values are an array of decoration + # where the keys are {TextEditorMarker} IDs, and the values are an array of decoration # params objects attached to the marker. # Returns an empty object when no decorations are found decorationsForScreenRowRange: (startScreenRow, endScreenRow) -> @@ -1567,7 +1567,7 @@ class TextEditor extends Model # region in any way, including changes that end at the marker's # start or start at the marker's end. This is the most fragile strategy. # - # Returns a {Marker}. + # Returns a {TextEditorMarker}. markBufferRange: (args...) -> @displayBuffer.markBufferRange(args...) @@ -1602,7 +1602,7 @@ class TextEditor extends Model # region in any way, including changes that end at the marker's # start or start at the marker's end. This is the most fragile strategy. # - # Returns a {Marker}. + # Returns a {TextEditorMarker}. markScreenRange: (args...) -> @displayBuffer.markScreenRange(args...) @@ -1611,7 +1611,7 @@ class TextEditor extends Model # * `position` A {Point} or {Array} of `[row, column]`. # * `options` (optional) See {TextBuffer::markRange}. # - # Returns a {Marker}. + # Returns a {TextEditorMarker}. markBufferPosition: (args...) -> @displayBuffer.markBufferPosition(args...) @@ -1620,11 +1620,11 @@ class TextEditor extends Model # * `position` A {Point} or {Array} of `[row, column]`. # * `options` (optional) See {TextBuffer::markRange}. # - # Returns a {Marker}. + # Returns a {TextEditorMarker}. markScreenPosition: (args...) -> @displayBuffer.markScreenPosition(args...) - # Essential: Find all {Marker}s that match the given properties. + # Essential: Find all {TextEditorMarker}s that match the given properties. # # This method finds markers based on the given properties. Markers can be # associated with custom properties that will be compared with basic equality. @@ -1649,7 +1649,7 @@ class TextEditor extends Model # Extended: Observe changes in the set of markers that intersect a particular # region of the editor. # - # * `callback` A {Function} to call whenever one or more {Marker}s appears, + # * `callback` A {Function} to call whenever one or more {TextEditorMarker}s appears, # disappears, or moves within the given region. # * `event` An {Object} with the following keys: # * `insert` A {Set} containing the ids of all markers that appeared @@ -1665,13 +1665,13 @@ class TextEditor extends Model observeMarkers: (callback) -> @displayBuffer.observeMarkers(callback) - # Extended: Get the {Marker} for the given marker id. + # Extended: Get the {TextEditorMarker} for the given marker id. # # * `id` {Number} id of the marker getMarker: (id) -> @displayBuffer.getMarker(id) - # Extended: Get all {Marker}s. Consider using {::findMarkers} + # Extended: Get all {TextEditorMarker}s. Consider using {::findMarkers} getMarkers: -> @displayBuffer.getMarkers() @@ -1888,7 +1888,7 @@ class TextEditor extends Model getCursorsOrderedByBufferPosition: -> @getCursors().sort (a, b) -> a.compare(b) - # Add a cursor based on the given {Marker}. + # Add a cursor based on the given {TextEditorMarker}. addCursor: (marker) -> cursor = new Cursor(editor: this, marker: marker, config: @config) @cursors.push(cursor) @@ -2237,7 +2237,7 @@ class TextEditor extends Model # Extended: Select the range of the given marker if it is valid. # - # * `marker` A {Marker} + # * `marker` A {TextEditorMarker} # # Returns the selected {Range} or `undefined` if the marker is invalid. selectMarker: (marker) -> @@ -2363,9 +2363,9 @@ class TextEditor extends Model _.reduce(tail, reducer, [head]) return result if fn? - # Add a {Selection} based on the given {Marker}. + # Add a {Selection} based on the given {TextEditorMarker}. # - # * `marker` The {Marker} to highlight + # * `marker` The {TextEditorMarker} to highlight # * `options` (optional) An {Object} that pertains to the {Selection} constructor. # # Returns the new {Selection}.