github/atom
1
1
Fork 0
mirror of https://github.com/atom/atom.git synced 2026-04-06 03:02:13 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3229 from atom/docs-metadata

Browse Source 
New API docs
This commit is contained in:
Ben Ogle
2014-08-27 11:33:04 -07:00
parent 5360b719f2 cb34539508
commit bbdd304834
30 changed files with 2084 additions and 1765 deletions
Download Patch File Download Diff File Expand all files Collapse all files

126
src/atom.coffee
View File

@@ -17,29 +17,14 @@ WindowEventHandler = require './window-event-handler'
# Public: Atom global for dealing with packages, themes, menus, and the window.
#
# An instance of this class is always available as the `atom` global.
#
# ## Useful properties available:
#
# * `atom.clipboard` - A {Clipboard} instance
# * `atom.config` - A {Config} instance
# * `atom.contextMenu` - A {ContextMenuManager} instance
# * `atom.deserializers` - A {DeserializerManager} instance
# * `atom.keymaps` - A {KeymapManager} instance
# * `atom.menu` - A {MenuManager} instance
# * `atom.packages` - A {PackageManager} instance
# * `atom.project` - A {Project} instance
# * `atom.syntax` - A {Syntax} instance
# * `atom.themes` - A {ThemeManager} instance
# * `atom.workspace` - A {Workspace} instance
# * `atom.workspaceView` - A {WorkspaceView} instance
module.exports =
class Atom extends Model
@version: 1 # Increment this when the serialization format changes
# Public: Load or create the Atom environment in the given mode.
#
# mode - Pass 'editor' or 'spec' depending on the kind of environment you
# want to build.
# * `mode` A {String} mode that is either 'editor' or 'spec' depending on the
# kind of environment you want to build.
#
# Returns an Atom instance, fully initialized
@loadOrCreate: (mode) ->
@@ -113,6 +98,42 @@ class Atom extends Model
workspaceViewParentSelector: 'body'
lastUncaughtError: null
# Public: A {Clipboard} instance
clipboard: null
# Public: A {Config} instance
config: null
# Public: A {ContextMenuManager} instance
contextMenu: null
# Public: A {DeserializerManager} instance
deserializers: null
# Public: A {KeymapManager} instance
keymaps: null
# Public: A {MenuManager} instance
menu: null
# Public: A {PackageManager} instance
packages: null
# Public: A {Project} instance
project: null
# Public: A {Syntax} instance
syntax: null
# Public: A {ThemeManager} instance
themes: null
# Public: A {Workspace} instance
workspace: null
# Public: A {WorkspaceView} instance
workspaceView: null
# Call .loadOrCreate instead
constructor: (@state) ->
{@mode} = @state
@@ -120,8 +141,9 @@ class Atom extends Model
@deserializers = new DeserializerManager()
# Public: Sets up the basic services that should be available in all modes
# (both spec and application). Call after this instance has been assigned to
# the `atom` global.
# (both spec and application).
#
# Call after this instance has been assigned to the `atom` global.
initialize: ->
window.onerror = =>
@openDevTools()
@@ -193,7 +215,11 @@ class Atom extends Model
# Public: Get the dimensions of this window.
#
# Returns an object with x, y, width, and height keys.
# Returns an {Object} with the following keys:
# * `x` The window's x-position {Number}.
# * `y` The window's y-position {Number}.
# * `width` The window's width {Number}.
# * `height` The window's height {Number}.
getWindowDimensions: ->
browserWindow = @getCurrentWindow()
[x, y] = browserWindow.getPosition()
@@ -207,11 +233,11 @@ class Atom extends Model
# in the dimensions parameter. If x or y are omitted the window will be
# centered. If height or width are omitted only the position will be changed.
#
# dimensions - An {Object} with the following keys:
# :x - The new x coordinate.
# :y - The new y coordinate.
# :width - The new width.
# :height - The new height.
# * `dimensions` An {Object} with the following keys:
# * `x` The new x coordinate.
# * `y` The new y coordinate.
# * `width` The new width.
# * `height` The new height.
setWindowDimensions: ({x, y, width, height}) ->
if width? and height?
@setSize(width, height)
@@ -260,7 +286,7 @@ class Atom extends Model
# Public: Get the load settings for the current window.
#
# Returns an object containing all the load setting key/value pairs.
# Returns an {Object} containing all the load setting key/value pairs.
getLoadSettings: ->
@constructor.getLoadSettings()
@@ -364,23 +390,21 @@ class Atom extends Model
# Calling this method without an options parameter will open a prompt to pick
# a file/folder to open in the new window.
#
# options - An {Object} with the following keys:
# :pathsToOpen - An {Array} of {String} paths to open.
# :newWindow - A {Boolean}, true to always open a new window instead of
# reusing existing windows depending on the paths to open.
# :devMode - A {Boolean}, true to open the window in development mode.
# Development mode loads the Atom source from the locally
# cloned repository and also loads all the packages in
# ~/.atom/dev/packages
# :safeMode - A {Boolean}, true to open the window in safe mode. Safe
# mode prevents all packages installed to ~/.atom/packages
# from loading.
# * `options` An {Object} with the following keys:
# * `pathsToOpen` An {Array} of {String} paths to open.
# * `newWindow` A {Boolean}, true to always open a new window instead of
# reusing existing windows depending on the paths to open.
# * `devMode` A {Boolean}, true to open the window in development mode.
# Development mode loads the Atom source from the locally cloned
# repository and also loads all the packages in ~/.atom/dev/packages
# * `safeMode` A {Boolean}, true to open the window in safe mode. Safe
# mode prevents all packages installed to ~/.atom/packages from loading.
open: (options) ->
ipc.send('open', options)
# Public: Open a confirm dialog.
#
# ## Example
# ## Examples
#
# ```coffee
# atom.confirm
@@ -391,12 +415,12 @@ class Atom extends Model
# Bad: -> window.alert('bummer')
# ```
#
# options - An {Object} with the following keys:
# :message - The {String} message to display.
# :detailedMessage - The {String} detailed message to display.
# :buttons - Either an array of strings or an object where keys are
# button names and the values are callbacks to invoke when
# clicked.
# * `options` An {Object} with the following keys:
# * `message` The {String} message to display.
# * `detailedMessage` The {String} detailed message to display.
# * `buttons` Either an array of strings or an object where keys are
# button names and the values are callbacks to invoke when
# clicked.
#
# Returns the chosen button index {Number} if the buttons option was an array.
confirm: ({message, detailedMessage, buttons}={}) ->
@@ -459,15 +483,15 @@ class Atom extends Model
# Public: Set the size of current window.
#
# width - The {Number} of pixels.
# height - The {Number} of pixels.
# * `width` The {Number} of pixels.
# * `height` The {Number} of pixels.
setSize: (width, height) ->
@getCurrentWindow().setSize(width, height)
# Public: Set the position of current window.
#
# x - The {Number} of pixels.
# y - The {Number} of pixels.
# * `x` The {Number} of pixels.
# * `y` The {Number} of pixels.
setPosition: (x, y) ->
ipc.send('call-window-method', 'setPosition', x, y)
@@ -554,7 +578,7 @@ class Atom extends Model
# This time include things like loading and activating packages, creating
# DOM elements for the editor, and reading the config.
#
# Returns the number of milliseconds taken to load the window or null
# Returns the {Number} of milliseconds taken to load the window or null
# if the window hasn't finished loading yet.
getWindowLoadTime: ->
@loadTime
@@ -586,8 +610,8 @@ class Atom extends Model
# The globals will be set on the `window` object and removed after the
# require completes.
#
# id - The {String} module name or path.
# globals - An {Object} to set as globals during require (default: {})
# * `id` The {String} module name or path.
# * `globals` An optinal {Object} to set as globals during require.
requireWithGlobals: (id, globals={}) ->
existingGlobals = {}
for key, value of globals

43
src/buffered-node-process.coffee
View File

@@ -6,34 +6,35 @@ path = require 'path'
#
# This is necessary on Windows since it doesn't support shebang `#!` lines.
#
# ## Requiring in packages
# ## Examples
#
# ```coffee
# {BufferedNodeProcess} = require 'atom'
# {BufferedNodeProcess} = require 'atom'
# ```
module.exports =
class BufferedNodeProcess extends BufferedProcess
# Public: Runs the given Node script by spawning a new child process.
#
# options - An {Object} with the following keys:
# :command - The {String} path to the JavaScript script to execute.
# :args - The {Array} of arguments to pass to the script (optional).
# :options - The options {Object} to pass to Node's `ChildProcess.spawn`
# method (optional).
# :stdout - The callback {Function} that receives a single argument which
# contains the standard output from the command. The callback is
# called as data is received but it's buffered to ensure only
# complete lines are passed until the source stream closes. After
# the source stream has closed all remaining data is sent in a
# final call (optional).
# :stderr - The callback {Function} that receives a single argument which
# contains the standard error output from the command. The
# callback is called as data is received but it's buffered to
# ensure only complete lines are passed until the source stream
# closes. After the source stream has closed all remaining data
# is sent in a final call (optional).
# :exit - The callback {Function} which receives a single argument
# containing the exit status (optional).
# * `options` An {Object} with the following keys:
# * `command` The {String} path to the JavaScript script to execute.
# * `args` The {Array} of arguments to pass to the script (optional).
# * `options` The options {Object} to pass to Node's `ChildProcess.spawn`
# method (optional).
# * `stdout` The callback {Function} that receives a single argument which
# contains the standard output from the command. The callback is
# called as data is received but it's buffered to ensure only
# complete lines are passed until the source stream closes. After
# the source stream has closed all remaining data is sent in a
# final call (optional).
# * `stderr` The callback {Function} that receives a single argument which
# contains the standard error output from the command. The
# callback is called as data is received but it's buffered to
# ensure only complete lines are passed until the source stream
# closes. After the source stream has closed all remaining data
# is sent in a final call (optional).
# * `exit` The callback {Function} which receives a single argument
# containing the exit status (optional).
constructor: ({command, args, options, stdout, stderr, exit}) ->
node =
if process.platform is 'darwin'

46
src/buffered-process.coffee
View File

@@ -4,7 +4,7 @@ ChildProcess = require 'child_process'
# Public: A wrapper which provides standard error/output line buffering for
# Node's ChildProcess.
#
# ## Requiring in packages
# ## Examples
#
# ```coffee
# {BufferedProcess} = require 'atom'
@@ -19,25 +19,25 @@ module.exports =
class BufferedProcess
# Public: Runs the given command by spawning a new child process.
#
# options - An {Object} with the following keys:
# :command - The {String} command to execute.
# :args - The {Array} of arguments to pass to the command (optional).
# :options - The options {Object} to pass to Node's `ChildProcess.spawn`
# method (optional).
# :stdout - The callback {Function} that receives a single argument which
# contains the standard output from the command. The callback is
# called as data is received but it's buffered to ensure only
# complete lines are passed until the source stream closes. After
# the source stream has closed all remaining data is sent in a
# final call (optional).
# :stderr - The callback {Function} that receives a single argument which
# contains the standard error output from the command. The
# callback is called as data is received but it's buffered to
# ensure only complete lines are passed until the source stream
# closes. After the source stream has closed all remaining data
# is sent in a final call (optional).
# :exit - The callback {Function} which receives a single argument
# containing the exit status (optional).
# * `options` An {Object} with the following keys:
# * `command` The {String} command to execute.
# * `args` The {Array} of arguments to pass to the command (optional).
# * `options` The options {Object} to pass to Node's `ChildProcess.spawn`
# method (optional).
# * `stdout` The callback {Function} that receives a single argument which
# contains the standard output from the command. The callback is
# called as data is received but it's buffered to ensure only
# complete lines are passed until the source stream closes. After
# the source stream has closed all remaining data is sent in a
# final call (optional).
# * `stderr` The callback {Function} that receives a single argument which
# contains the standard error output from the command. The
# callback is called as data is received but it's buffered to
# ensure only complete lines are passed until the source stream
# closes. After the source stream has closed all remaining data
# is sent in a final call (optional).
# * `exit` The callback {Function} which receives a single argument
# containing the exit status (optional).
constructor: ({command, args, options, stdout, stderr, exit}={}) ->
options ?= {}
# Related to joyent/node#2318
@@ -95,9 +95,9 @@ class BufferedProcess
# Helper method to pass data line by line.
#
# stream - The Stream to read from.
# onLines - The callback to call with each line of data.
# onDone - The callback to call when the stream has closed.
# * `stream` The Stream to read from.
# * `onLines` The callback to call with each line of data.
# * `onDone` The callback to call when the stream has closed.
bufferStream: (stream, onLines, onDone) ->
stream.setEncoding('utf8')
buffered = ''

18
src/clipboard.coffee
View File

@@ -4,6 +4,14 @@ crypto = require 'crypto'
# Public: Represents the clipboard used for copying and pasting in Atom.
#
# An instance of this class is always available as the `atom.clipboard` global.
#
# ## Examples
#
# ```coffee
# atom.clipboard.write('hello')
#
# console.log(atom.clipboard.read()) # 'hello'
# ```
module.exports =
class Clipboard
metadata: null
@@ -11,7 +19,7 @@ class Clipboard
# Creates an `md5` hash of some text.
#
# text - A {String} to hash.
# * `text` A {String} to hash.
#
# Returns a hashed {String}.
md5: (text) ->
@@ -22,8 +30,8 @@ class Clipboard
# The metadata associated with the text is available by calling
# {::readWithMetadata}.
#
# text - The {String} to store.
# metadata - The additional info to associate with the text.
# * `text` The {String} to store.
# * `metadata` The additional info to associate with the text.
write: (text, metadata) ->
@signatureForMetadata = @md5(text)
@metadata = metadata
@@ -39,8 +47,8 @@ class Clipboard
# associated metadata.
#
# Returns an {Object} with the following keys:
# :text - The {String} clipboard text.
# :metadata - The metadata stored by an earlier call to {::write}.
# * `text` The {String} clipboard text.
# * `metadata` The metadata stored by an earlier call to {::write}.
readWithMetadata: ->
text = @read()
if @signatureForMetadata is @md5(text)

83
src/config.coffee
View File

@@ -15,9 +15,9 @@ pathWatcher = require 'pathwatcher'
# * Create your own root keypath using your package's name.
# * Don't depend on (or write to) configuration keys outside of your keypath.
#
# ## Example
# ## Examples
#
# ```coffeescript
# ```coffee
# atom.config.set('my-package.key', 'value')
# atom.config.observe 'my-package.key', ->
# console.log 'My configuration changed:', atom.config.get('my-package.key')
@@ -88,17 +88,17 @@ class Config
_.extend hash, defaults
@emit 'updated'
# Public: Get the {String} path to the config file being used.
# Extended: Get the {String} path to the config file being used.
getUserConfigPath: ->
@configFilePath
# Public: Returns a new {Object} containing all of settings and defaults.
# Extended: Returns a new {Object} containing all of settings and defaults.
getSettings: ->
_.deepExtend(@settings, @defaultSettings)
# Public: Retrieves the setting for the given key.
# Essential: Retrieves the setting for the given key.
#
# keyPath - The {String} name of the key to retrieve.
# * `keyPath` The {String} name of the key to retrieve.
#
# Returns the value from Atom's default settings, the user's configuration
# file, or `null` if the key doesn't exist in either.
@@ -117,19 +117,19 @@ class Config
value
# Public: Retrieves the setting for the given key as an integer.
# Extended: Retrieves the setting for the given key as an integer.
#
# keyPath - The {String} name of the key to retrieve
# * `keyPath` The {String} name of the key to retrieve
#
# Returns the value from Atom's default settings, the user's configuration
# file, or `NaN` if the key doesn't exist in either.
getInt: (keyPath) ->
parseInt(@get(keyPath))
# Public: Retrieves the setting for the given key as a positive integer.
# Extended: Retrieves the setting for the given key as a positive integer.
#
# keyPath - The {String} name of the key to retrieve
# defaultValue - The integer {Number} to fall back to if the value isn't
# * `keyPath` The {String} name of the key to retrieve
# * `defaultValue` The integer {Number} to fall back to if the value isn't
# positive, defaults to 0.
#
# Returns the value from Atom's default settings, the user's configuration
@@ -137,12 +137,12 @@ class Config
getPositiveInt: (keyPath, defaultValue=0) ->
Math.max(@getInt(keyPath), 0) or defaultValue
# Public: Sets the value for a configuration setting.
# Essential: Sets the value for a configuration setting.
#
# This value is stored in Atom's internal configuration file.
#
# keyPath - The {String} name of the key.
# value - The value of the setting.
# * `keyPath` The {String} name of the key.
# * `value` The value of the setting.
#
# Returns the `value`.
set: (keyPath, value) ->
@@ -153,47 +153,47 @@ class Config
@update()
value
# Public: Toggle the value at the key path.
# Extended: Toggle the value at the key path.
#
# The new value will be `true` if the value is currently falsy and will be
# `false` if the value is currently truthy.
#
# keyPath - The {String} name of the key.
# * `keyPath` The {String} name of the key.
#
# Returns the new value.
toggle: (keyPath) ->
@set(keyPath, !@get(keyPath))
# Public: Restore the key path to its default value.
# Extended: Restore the key path to its default value.
#
# keyPath - The {String} name of the key.
# * `keyPath` The {String} name of the key.
#
# Returns the new value.
restoreDefault: (keyPath) ->
@set(keyPath, _.valueForKeyPath(@defaultSettings, keyPath))
# Public: Get the default value of the key path.
# Extended: Get the default value of the key path.
#
# keyPath - The {String} name of the key.
# * `keyPath` The {String} name of the key.
#
# Returns the default value.
getDefault: (keyPath) ->
defaultValue = _.valueForKeyPath(@defaultSettings, keyPath)
_.deepClone(defaultValue)
# Public: Is the key path value its default value?
# Extended: Is the key path value its default value?
#
# keyPath - The {String} name of the key.
# * `keyPath` The {String} name of the key.
#
# Returns a {Boolean}, `true` if the current value is the default, `false`
# otherwise.
isDefault: (keyPath) ->
not _.valueForKeyPath(@settings, keyPath)?
# Public: Push the value to the array at the key path.
# Extended: Push the value to the array at the key path.
#
# keyPath - The {String} key path.
# value - The value to push to the array.
# * `keyPath` The {String} key path.
# * `value` The value to push to the array.
#
# Returns the new array length {Number} of the setting.
pushAtKeyPath: (keyPath, value) ->
@@ -202,10 +202,10 @@ class Config
@set(keyPath, arrayValue)
result
# Public: Add the value to the beginning of the array at the key path.
# Extended: Add the value to the beginning of the array at the key path.
#
# keyPath - The {String} key path.
# value - The value to shift onto the array.
# * `keyPath` The {String} key path.
# * `value` The value to shift onto the array.
#
# Returns the new array length {Number} of the setting.
unshiftAtKeyPath: (keyPath, value) ->
@@ -216,8 +216,8 @@ class Config
# Public: Remove the value from the array at the key path.
#
# keyPath - The {String} key path.
# value - The value to remove from the array.
# * `keyPath` The {String} key path.
# * `value` The value to remove from the array.
#
# Returns the new array value of the setting.
removeAtKeyPath: (keyPath, value) ->
@@ -226,20 +226,17 @@ class Config
@set(keyPath, arrayValue)
result
# Public: Establishes an event listener for a given key.
# Essential: Add a listener for changes to a given key path.
#
# `callback` is fired whenever the value of the key is changed and will
# be fired immediately unless the `callNow` option is `false`.
#
# keyPath - The {String} name of the key to observe
# options - An optional {Object} containing the `callNow` key.
# callback - The {Function} to call when the value of the key changes.
# The first argument will be the new value of the key and the
#   second argument will be an {Object} with a `previous` property
# that is the prior value of the key.
# * `keyPath` The {String} name of the key to observe
# * `options` An optional {Object} containing the `callNow` key.
# * `callback` The {Function} to call when the value of the key changes.
# The first argument will be the new value of the key and the
#   second argument will be an {Object} with a `previous` property
# that is the prior value of the key.
#
# Returns an {Object} with the following keys:
# :off - A {Function} that unobserves the `keyPath` when called.
# * `off` A {Function} that unobserves the `keyPath` when called.
observe: (keyPath, options={}, callback) ->
if _.isFunction(options)
callback = options
@@ -259,9 +256,9 @@ class Config
callback(value) if options.callNow ? true
subscription
# Public: Unobserve all callbacks on a given key.
# Unobserve all callbacks on a given key.
#
# keyPath - The {String} name of the key to unobserve.
# * `keyPath` The {String} name of the key to unobserve.
unobserve: (keyPath) ->
@off("updated.#{keyPath.replace(/\./, '-')}")

33
src/context-menu-manager.coffee
View File

@@ -22,15 +22,13 @@ class ContextMenuManager
]
# Public: Creates menu definitions from the object specified by the menu
# cson API.
# JSON API.
#
# name - The path of the file that contains the menu definitions.
# object - The 'context-menu' object specified in the menu cson API.
# options - An {Object} with the following keys:
# :devMode - Determines whether the entries should only be shown when
# the window is in dev mode.
#
# Returns nothing.
# * `name` The path of the file that contains the menu definitions.
# * `object` The 'context-menu' object specified in the menu JSON API.
# * `options` An optional {Object} with the following keys:
# * `devMode` Determines whether the entries should only be shown when
# the window is in dev mode.
add: (name, object, {devMode}={}) ->
for selector, items of object
for label, commandOrSubmenu of items
@@ -43,6 +41,8 @@ class ContextMenuManager
menuItem = @buildMenuItem(label, commandOrSubmenu)
@addBySelector(selector, menuItem, {devMode})
undefined
buildMenuItem: (label, command) ->
if command is '-'
{type: 'separator'}
@@ -52,12 +52,12 @@ class ContextMenuManager
# Registers a command to be displayed when the relevant item is right
# clicked.
#
# selector - The css selector for the active element which should include
# the given command in its context menu.
# definition - The object containing keys which match the menu template API.
# options - An {Object} with the following keys:
# :devMode - Indicates whether this command should only appear while the
# editor is in dev mode.
# * `selector` The css selector for the active element which should include
# the given command in its context menu.
# * `definition` The object containing keys which match the menu template API.
# * `options` An optional {Object} with the following keys:
# * `devMode` Indicates whether this command should only appear while the
# editor is in dev mode.
addBySelector: (selector, definition, {devMode}={}) ->
definitions = if devMode then @devModeDefinitions else @definitions
if not _.findWhere(definitions[selector], definition) or _.isEqual(definition, {type: 'separator'})
@@ -79,7 +79,7 @@ class ContextMenuManager
# active element are listed first. The further down the list you go, the higher
# up the ancestor hierarchy they match.
#
# element - The DOM element to generate the menu template for.
# * `element` The DOM element to generate the menu template for.
menuTemplateForMostSpecificElement: (element, {devMode}={}) ->
menuTemplate = @definitionsForElement(element, {devMode})
if element.parentElement
@@ -109,9 +109,12 @@ class ContextMenuManager
delete template.executeAtBuild
# Public: Request a context menu to be displayed.
#
# * `event` A DOM event.
showForEvent: (event) ->
@activeElement = event.target
menuTemplate = @combinedMenuTemplateForElement(event.target)
return unless menuTemplate?.length > 0
@executeBuildHandlers(event, menuTemplate)
remote.getCurrentWindow().emit('context-menu', menuTemplate)
undefined

112
src/cursor.coffee
View File

@@ -2,11 +2,36 @@
{Model} = require 'theorist'
_ = require 'underscore-plus'
# Public: The `Cursor` class represents the little blinking line identifying
# Extended: The `Cursor` class represents the little blinking line identifying
# where text can be inserted.
#
# Cursors belong to {Editor}s and have some metadata attached in the form
# of a {Marker}.
#
# ## Events
#
# ### moved
#
# Extended: Emit when a cursor has been moved. If there are multiple cursors,
# it will be emit for each cursor.
#
# * `event` {Object}
# * `oldBufferPosition` {Point}
# * `oldScreenPosition` {Point}
# * `newBufferPosition` {Point}
# * `newScreenPosition` {Point}
# * `textChanged` {Boolean}
#
# ### destroyed
#
# Extended: Emit when the cursor is destroyed
#
# ### visibility-changed
#
# Extended: Emit when the Cursor is hidden or shown
#
# * `visible` {Boolean} true when cursor is visible
#
module.exports =
class Cursor extends Model
screenPosition: null
@@ -63,11 +88,10 @@ class Cursor extends Model
# Public: Moves a cursor to a given screen position.
#
# screenPosition - An {Array} of two numbers: the screen row, and the screen
# column.
# options - An {Object} with the following keys:
# :autoscroll - A Boolean which, if `true`, scrolls the {Editor} to wherever
# the cursor moves to.
# * `screenPosition` {Array} of two numbers: the screen row, and the screen column.
# * `options` (optional) {Object} with the following keys:
# * `autoscroll` A Boolean which, if `true`, scrolls the {Editor} to wherever
# the cursor moves to.
setScreenPosition: (screenPosition, options={}) ->
@changePosition options, =>
@marker.setHeadScreenPosition(screenPosition, options)
@@ -82,11 +106,10 @@ class Cursor extends Model
# Public: Moves a cursor to a given buffer position.
#
# bufferPosition - An {Array} of two numbers: the buffer row, and the buffer
# column.
# options - An {Object} with the following keys:
# :autoscroll - A Boolean which, if `true`, scrolls the {Editor} to wherever
# the cursor moves to.
# * `bufferPosition` {Array} of two numbers: the buffer row, and the buffer column.
# * `options` (optional) {Object} with the following keys:
# * `autoscroll` A Boolean which, if `true`, scrolls the {Editor} to wherever
# the cursor moves to.
setBufferPosition: (bufferPosition, options={}) ->
@changePosition options, =>
@marker.setHeadBufferPosition(bufferPosition, options)
@@ -114,10 +137,9 @@ class Cursor extends Model
# Public: Get the RegExp used by the cursor to determine what a "word" is.
#
# options: An optional {Object} with the following keys:
# :includeNonWordCharacters - A {Boolean} indicating whether to include
# non-word characters in the regex.
# (default: true)
# * `options` (optional) {Object} with the following keys:
# * `includeNonWordCharacters` A {Boolean} indicating whether to include
# non-word characters in the regex. (default: true)
#
# Returns a {RegExp}.
wordRegExp: ({includeNonWordCharacters}={}) ->
@@ -228,9 +250,9 @@ class Cursor extends Model
# Public: Moves the cursor left one screen column.
#
# options - An {Object} with the following keys:
# :moveToEndOfSelection - if true, move to the left of the selection if a
# selection exists.
# * `options` (optional) {Object} with the following keys:
# * `moveToEndOfSelection` if true, move to the left of the selection if a
# selection exists.
moveLeft: ({moveToEndOfSelection}={}) ->
range = @marker.getScreenRange()
if moveToEndOfSelection and not range.isEmpty()
@@ -242,9 +264,9 @@ class Cursor extends Model
# Public: Moves the cursor right one screen column.
#
# options - An {Object} with the following keys:
# :moveToEndOfSelection - if true, move to the right of the selection if a
# selection exists.
# * `options` (optional) {Object} with the following keys:
# * `moveToEndOfSelection` if true, move to the right of the selection if a
# selection exists.
moveRight: ({moveToEndOfSelection}={}) ->
range = @marker.getScreenRange()
if moveToEndOfSelection and not range.isEmpty()
@@ -332,14 +354,14 @@ class Cursor extends Model
# Public: Retrieves the buffer position of where the current word starts.
#
# options - An {Object} with the following keys:
# :wordRegex - A {RegExp} indicating what constitutes a "word"
# (default: {::wordRegExp}).
# :includeNonWordCharacters - A {Boolean} indicating whether to include
# non-word characters in the default word regex.
# Has no effect if wordRegex is set.
# :allowPrevious - A {Boolean} indicating whether the beginning of the
# previous word can be returned.
# * `options` (optional) An {Object} with the following keys:
# * `wordRegex` A {RegExp} indicating what constitutes a "word"
# (default: {::wordRegExp}).
# * `includeNonWordCharacters` A {Boolean} indicating whether to include
# non-word characters in the default word regex.
# Has no effect if wordRegex is set.
# * `allowPrevious` A {Boolean} indicating whether the beginning of the
# previous word can be returned.
#
# Returns a {Range}.
getBeginningOfCurrentWordBufferPosition: (options = {}) ->
@@ -407,12 +429,12 @@ class Cursor extends Model
# Public: Retrieves the buffer position of where the current word ends.
#
# options - An {Object} with the following keys:
# :wordRegex - A {RegExp} indicating what constitutes a "word"
# (default: {::wordRegExp})
# :includeNonWordCharacters - A Boolean indicating whether to include
# non-word characters in the default word regex.
# Has no effect if wordRegex is set.
# * `options` (optional) {Object} with the following keys:
# * `wordRegex` A {RegExp} indicating what constitutes a "word"
# (default: {::wordRegExp})
# * `includeNonWordCharacters` A Boolean indicating whether to include
# non-word characters in the default word regex. Has no effect if
# wordRegex is set.
#
# Returns a {Range}.
getEndOfCurrentWordBufferPosition: (options = {}) ->
@@ -431,11 +453,11 @@ class Cursor extends Model
# Public: Retrieves the buffer position of where the next word starts.
#
# options -
# :wordRegex - A {RegExp} indicating what constitutes a "word"
# (default: {::wordRegExp}).
# * `options` (optional) {Object}
# * `wordRegex` A {RegExp} indicating what constitutes a "word"
# (default: {::wordRegExp}).
#
# Returns a {Range}.
# Returns a {Range}
getBeginningOfNextWordBufferPosition: (options = {}) ->
currentBufferPosition = @getBufferPosition()
start = if @isInsideWord() then @getEndOfCurrentWordBufferPosition() else currentBufferPosition
@@ -450,9 +472,9 @@ class Cursor extends Model
# Public: Returns the buffer Range occupied by the word located under the cursor.
#
# options -
# :wordRegex - A {RegExp} indicating what constitutes a "word"
# (default: {::wordRegExp}).
# * `options` (optional) {Object}
# * `wordRegex` A {RegExp} indicating what constitutes a "word"
# (default: {::wordRegExp}).
getCurrentWordBufferRange: (options={}) ->
startOptions = _.extend(_.clone(options), allowPrevious: false)
endOptions = _.extend(_.clone(options), allowNext: false)
@@ -460,9 +482,9 @@ class Cursor extends Model
# Public: Returns the buffer Range for the current line.
#
# options -
# :includeNewline: - A {Boolean} which controls whether the Range should
# include the newline.
# * `options` (optional) {Object}
# * `includeNewline` A {Boolean} which controls whether the Range should
# include the newline.
getCurrentLineBufferRange: (options) ->
@editor.bufferRangeForBufferRow(@getBufferRow(), options)

85
src/decoration.coffee
View File

@@ -4,7 +4,7 @@ _ = require 'underscore-plus'
idCounter = 0
nextId = -> idCounter++
# Public: Represents a decoration that follows a {Marker}. A decoration is
# Essential: Represents a decoration that follows a {Marker}. 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.
@@ -20,27 +20,39 @@ nextId = -> idCounter++
#
# Best practice for destorying the decoration is by destroying the {Marker}.
#
# ```
# ```coffee
# marker.destroy()
# ```
#
# You should only use {Decoration::destroy} when you still need or do not own
# the marker.
#
# ### IDs
# Each {Decoration} has a unique ID available via `decoration.id`.
# ## Events
#
# ### Events
# A couple of events are emitted:
# ### updated
#
# * `destroyed`: When the {Decoration} is destroyed
# * `updated`: When the {Decoration} is updated via {Decoration::update}.
# Event object has properties `oldParams` and `newParams`
# Extended: When the {Decoration} is updated via {Decoration::update}.
#
# * `event` {Object}
# * `oldParams` {Object} the old parameters the decoration used to have
# * `newParams` {Object} the new parameters the decoration now has
#
# ### destroyed
#
# Extended: When the {Decoration} is destroyed
#
module.exports =
class Decoration
Emitter.includeInto(this)
# Extended: Check if the `decorationParams.type` matches `type`
#
# * `decorationParams` {Object} eg. `{type: 'gutter', class: 'my-new-class'}`
# * `type` {String} type like `'gutter'`, `'line'`, etc. `type` can also
# be an {Array} of {String}s, where it will return true if the decoration's
# type matches any in the array.
#
# Returns {Boolean}
@isType: (decorationParams, type) ->
if _.isArray(decorationParams.type)
type in decorationParams.type
@@ -53,21 +65,34 @@ class Decoration
@flashQueue = null
@isDestroyed = false
# Public: Destroy this marker.
#
# If you own the marker, you should use {Marker::destroy} which will destroy
# this decoration.
destroy: ->
return if @isDestroyed
@isDestroyed = true
@displayBuffer.removeDecoration(this)
@emit 'destroyed'
# Essential: An id unique across all {Decoration} objects
getId: -> @id
# Public: Update the marker with new params. Allows you to change the decoration's class.
# Essential: Returns the marker associated with this {Decoration}
getMarker: -> @marker
# Essential: Returns the {Decoration}'s params.
getParams: -> @params
# Public: Check if this decoration is of type `type`
#
# ```
# * `type` {String} type like `'gutter'`, `'line'`, etc. `type` can also
# be an {Array} of {String}s, where it will return true if the decoration's
# type matches any in the array.
#
# Returns {Boolean}
isType: (type) ->
Decoration.isType(@params, type)
# Essential: Update the marker with new params. Allows you to change the decoration's class.
#
# ## Examples
#
# ```coffee
# decoration.update({type: 'gutter', class: 'my-new-class'})
# ```
#
# * `newParams` {Object} eg. `{type: 'gutter', class: 'my-new-class'}`
update: (newParams) ->
return if @isDestroyed
oldParams = @params
@@ -76,19 +101,15 @@ class Decoration
@displayBuffer.decorationUpdated(this)
@emit 'updated', {oldParams, newParams}
# Public: Returns the marker associated with this {Decoration}
getMarker: -> @marker
# Public: Returns the {Decoration}'s params.
getParams: -> @params
# Public: Check if this decoration is of type `type`
# Essential: Destroy this marker.
#
# type - A {String} type like `'gutter'`
#
# Returns a {Boolean}
isType: (type) ->
Decoration.isType(@params, type)
# If you own the marker, you should use {Marker::destroy} which will destroy
# this decoration.
destroy: ->
return if @isDestroyed
@isDestroyed = true
@displayBuffer.removeDecoration(this)
@emit 'destroyed'
matchesPattern: (decorationPattern) ->
return false unless decorationPattern?

14
src/deserializer-manager.coffee
View File

@@ -3,7 +3,7 @@
# An instance of this class is always available as the `atom.deserializers`
# global.
#
# ### Registering a deserializer
# ## Examples
#
# ```coffee
# class MyPackageView extends View
@@ -24,21 +24,21 @@ class DeserializerManager
# Public: Register the given class(es) as deserializers.
#
# classes - One or more classes to register.
# * `classes` One or more classes to register.
add: (classes...) ->
@deserializers[klass.name] = klass for klass in classes
# Public: Remove the given class(es) as deserializers.
#
# classes - One or more classes to remove.
# * `classes` One or more classes to remove.
remove: (classes...) ->
delete @deserializers[name] for {name} in classes
# Public: Deserialize the state and params.
#
# state - The state {Object} to deserialize.
# params - The params {Object} to pass as the second arguments to the
# deserialize method of the deserializer.
# * `state` The state {Object} to deserialize.
# * `params` The params {Object} to pass as the second arguments to the
# deserialize method of the deserializer.
deserialize: (state, params) ->
return unless state?
@@ -51,7 +51,7 @@ class DeserializerManager
# Get the deserializer for the state.
#
# state - The state {Object} being deserialized.
# * `state` The state {Object} being deserialized.
get: (state) ->
return unless state?

51
src/editor-view.coffee
View File

@@ -10,7 +10,9 @@ EditorComponent = require './editor-component'
#
# The EditorView manages the {Editor}, which manages the file buffers.
#
# ## Requiring in packages
# ## Examples
#
# Requiring in packages
#
# ```coffee
# {EditorView} = require 'atom'
@@ -18,14 +20,14 @@ EditorComponent = require './editor-component'
# miniEditorView = new EditorView(mini: true)
# ```
#
# ## Iterating over the open editor views
# Iterating over the open editor views
#
# ```coffee
# for editorView in atom.workspaceView.getEditorViews()
# console.log(editorView.getModel().getPath())
# ```
#
# ## Subscribing to every current and future editor
# Subscribing to every current and future editor
#
# ```coffee
# atom.workspace.eachEditorView (editorView) ->
@@ -67,7 +69,7 @@ class EditorView extends View
# The constructor for setting up an `EditorView` instance.
#
# editorOrParams - Either an {Editor}, or an object with one property, `mini`.
# * `editorOrParams` Either an {Editor}, or an object with one property, `mini`.
# If `mini` is `true`, a "miniature" `Editor` is constructed.
# Typically, this is ideal for scenarios where you need an Atom editor,
# but without all the chrome, like scrollbars, gutter, _e.t.c._.
@@ -125,7 +127,7 @@ class EditorView extends View
# Public: Get the underlying editor model for this view.
#
# Returns an {Editor}.
# Returns an {Editor}
getModel: -> @editor
getEditor: -> @editor
@@ -173,17 +175,17 @@ class EditorView extends View
# Public: Scrolls the editor to the given screen position.
#
# screenPosition - An object that represents a buffer position. It can be either
# an {Object} (`{row, column}`), {Array} (`[row, column]`), or {Point}
# options - A hash matching the options available to {::scrollToScreenPosition}
# * `screenPosition` An object that represents a buffer position. It can be either
# an {Object} (`{row, column}`), {Array} (`[row, column]`), or {Point}
# * `options` (optional) {Object} matching the options available to {::scrollToScreenPosition}
scrollToScreenPosition: (screenPosition, options) ->
@editor.scrollToScreenPosition(screenPosition, options)
# Public: Scrolls the editor to the given buffer position.
#
# bufferPosition - An object that represents a buffer position. It can be either
# an {Object} (`{row, column}`), {Array} (`[row, column]`), or {Point}
# options - A hash matching the options available to {::scrollToBufferPosition}
# * `bufferPosition` An object that represents a buffer position. It can be either
# an {Object} (`{row, column}`), {Array} (`[row, column]`), or {Point}
# * `options` (optional) {Object} matching the options available to {::scrollToBufferPosition}
scrollToBufferPosition: (bufferPosition, options) ->
@editor.scrollToBufferPosition(bufferPosition, options)
@@ -192,17 +194,17 @@ class EditorView extends View
# Public: Converts a buffer position to a pixel position.
#
# position - An object that represents a buffer position. It can be either
# an {Object} (`{row, column}`), {Array} (`[row, column]`), or {Point}
# * `bufferPosition` An object that represents a buffer position. It can be either
# an {Object} (`{row, column}`), {Array} (`[row, column]`), or {Point}
#
# Returns an object with two values: `top` and `left`, representing the pixel positions.
# Returns an {Object} with two values: `top` and `left`, representing the pixel positions.
pixelPositionForBufferPosition: (bufferPosition) ->
@editor.pixelPositionForBufferPosition(bufferPosition)
# Public: Converts a screen position to a pixel position.
#
# position - An object that represents a screen position. It can be either
# an {Object} (`{row, column}`), {Array} (`[row, column]`), or {Point}
# * `screenPosition` An object that represents a screen position. It can be either
# an {Object} (`{row, column}`), {Array} (`[row, column]`), or {Point}
#
# Returns an object with two values: `top` and `left`, representing the pixel positions.
pixelPositionForScreenPosition: (screenPosition) ->
@@ -283,7 +285,7 @@ class EditorView extends View
# Public: Sets the font family for the editor.
#
# fontFamily - A {String} identifying the CSS `font-family`.
# * `fontFamily` A {String} identifying the CSS `font-family`.
setFontFamily: (fontFamily) ->
@component?.setFontFamily(fontFamily)
@@ -295,7 +297,7 @@ class EditorView extends View
# Public: Sets the font size for the editor.
#
# fontSize - A {Number} indicating the font size in pixels.
# * `fontSize` A {Number} indicating the font size in pixels.
setFontSize: (fontSize) ->
@component?.setFontSize(fontSize)
@@ -306,27 +308,26 @@ class EditorView extends View
#
# Calling this method has no effect when called on a mini editor.
#
# lineHeight - A {Number} without a unit suffix identifying the CSS
# `line-height`.
# * `lineHeight` A {Number} without a unit suffix identifying the CSS `line-height`.
setLineHeight: (lineHeight) ->
@component.setLineHeight(lineHeight)
# Public: Sets whether you want to show the indentation guides.
#
# showIndentGuide - A {Boolean} you can set to `true` if you want to see the
# indentation guides.
# * `showIndentGuide` A {Boolean} you can set to `true` if you want to see the
# indentation guides.
setShowIndentGuide: (showIndentGuide) ->
@component.setShowIndentGuide(showIndentGuide)
# Public: Enables/disables soft wrap on the editor.
#
# softWrap - A {Boolean} which, if `true`, enables soft wrap
# * `softWrap` A {Boolean} which, if `true`, enables soft wrap
setSoftWrap: (softWrap) ->
@editor.setSoftWrap(softWrap)
# Public: Set whether invisible characters are shown.
#
# showInvisibles - A {Boolean} which, if `true`, show invisible characters.
# * `showInvisibles` A {Boolean} which, if `true`, show invisible characters.
setShowInvisibles: (showInvisibles) ->
@component.setShowInvisibles(showInvisibles)
@@ -361,7 +362,7 @@ class EditorView extends View
#
# This only affects mini editors.
#
# placeholderText - A {String} of text to display when empty.
# * `placeholderText` A {String} of text to display when empty.
setPlaceholderText: (placeholderText) ->
if @component?
@component.setProps({placeholderText})

2338
src/editor.coffee
View File

File diff suppressed because it is too large Load Diff

118
src/git.coffee
View File

@@ -20,16 +20,16 @@ Task = require './task'
# For a repository with submodules this would have the following outcome:
#
# ```coffee
# repo = atom.project.getRepo()
# repo.getShortHead() # 'master'
# repo.getShortHead('vendor/path/to/a/submodule') # 'dead1234'
# repo = atom.project.getRepo()
# repo.getShortHead() # 'master'
# repo.getShortHead('vendor/path/to/a/submodule') # 'dead1234'
# ```
#
# ## Example
# ## Examples
#
# ```coffeescript
# git = atom.project.getRepo()
# console.log git.getOriginUrl()
# ```coffee
# git = atom.project.getRepo()
# console.log git.getOriginUrl()
# ```
#
# ## Requiring in packages
@@ -44,12 +44,12 @@ class Git
# Public: Creates a new Git instance.
#
# path - The path to the Git repository to open.
# options - An object with the following keys (default: {}):
# :refreshOnWindowFocus - `true` to refresh the index and statuses when the
# window is focused.
# * `path` The {String} path to the Git repository to open.
# * `options` An optinal {Object} with the following keys:
# * `refreshOnWindowFocus` A {Boolean}, `true` to refresh the index and
# statuses when the window is focused.
#
# Returns a Git instance or null if the repository could not be opened.
# Returns a {Git} instance or `null` if the repository could not be opened.
@open: (path, options) ->
return null unless path
try
@@ -114,8 +114,10 @@ class Git
else
checkoutHead()
# Public: Destroy this `Git` object. This destroys any tasks and subscriptions
# and releases the underlying libgit2 repository handle.
# Public: Destroy this {Git} object.
#
# This destroys any tasks and subscriptions and releases the underlying
# libgit2 repository handle.
destroy: ->
if @statusTask?
@statusTask.terminate()
@@ -147,7 +149,7 @@ class Git
# Public: Get the status of a single path in the repository.
#
# path - A {String} repository-relative path.
# `path` A {String} repository-relative path.
#
# Returns a {Number} representing the status. This value can be passed to
# {::isStatusModified} or {::isStatusNew} to get more information.
@@ -196,8 +198,8 @@ class Git
# `refs/remotes`. It also shortens the SHA-1 of a detached `HEAD` to 7
# characters.
#
# path - An optional {String} path in the repository to get this information
# for, only needed if the repository contains submodules.
# * `path` An optional {String} path in the repository to get this information
# for, only needed if the repository contains submodules.
#
# Returns a {String}.
getShortHead: (path) -> @getRepo(path).getShortHead()
@@ -207,12 +209,12 @@ class Git
#
# This is essentially the same as running:
#
# ```
# git reset HEAD -- <path>
# git checkout HEAD -- <path>
# ```sh
# git reset HEAD -- <path>
# git checkout HEAD -- <path>
# ```
#
# path - The {String} path to checkout.
# * `path` The {String} path to checkout.
#
# Returns a {Boolean} that's true if the method was successful.
checkoutHead: (path) ->
@@ -223,9 +225,9 @@ class Git
# Public: Checks out a branch in your repository.
#
# reference - The String reference to checkout
# create - A Boolean value which, if true creates the new reference if it
# doesn't exist.
# * `reference` The {String} reference to checkout.
# * `create` A {Boolean} value which, if true creates the new reference if
# it doesn't exist.
#
# Returns a Boolean that's true if the method was successful.
checkoutReference: (reference, create) ->
@@ -236,18 +238,18 @@ class Git
# This compares the working directory contents of the path to the `HEAD`
# version.
#
# path - The {String} path to check.
# * `path` The {String} path to check.
#
# Returns an {Object} with the following keys:
# :added - The {Number} of added lines.
# :deleted - The {Number} of deleted lines.
# * `added` The {Number} of added lines.
# * `deleted` The {Number} of deleted lines.
getDiffStats: (path) ->
repo = @getRepo(path)
repo.getDiffStats(repo.relativize(path))
# Public: Is the given path a submodule in the repository?
#
# path - The {String} path to check.
# * `path` The {String} path to check.
#
# Returns a {Boolean}.
isSubmodule: (path) ->
@@ -262,7 +264,7 @@ class Git
# Public: Get the status of a directory in the repository's working directory.
#
# path - The {String} path to check.
# * `path` The {String} path to check.
#
# Returns a {Number} representing the status. This value can be passed to
# {::isStatusModified} or {::isStatusNew} to get more information.
@@ -276,14 +278,14 @@ class Git
# Public: Retrieves the line diffs comparing the `HEAD` version of the given
# path and the given text.
#
# path - The {String} path relative to the repository.
# text - The {String} to compare against the `HEAD` contents
# * `path` The {String} path relative to the repository.
# * `text` The {String} to compare against the `HEAD` contents
#
# Returns an {Array} of hunk {Object}s with the following keys:
# :oldStart - The line {Number} of the old hunk.
# :newStart - The line {Number} of the new hunk.
# :oldLines - The {Number} of lines in the old hunk.
# :newLines - The {Number} of lines in the new hunk
# * `oldStart` The line {Number} of the old hunk.
# * `newStart` The line {Number} of the new hunk.
# * `oldLines` The {Number} of lines in the old hunk.
# * `newLines` The {Number} of lines in the new hunk
getLineDiffs: (path, text) ->
# Ignore eol of line differences on windows so that files checked in as
# LF don't report every line modified when the text contains CRLF endings.
@@ -293,68 +295,68 @@ class Git
# Public: Returns the git configuration value specified by the key.
#
# path - An optional {String} path in the repository to get this information
# for, only needed if the repository has submodules.
# * `path` An optional {String} path in the repository to get this information
# for, only needed if the repository has submodules.
getConfigValue: (key, path) -> @getRepo(path).getConfigValue(key)
# Public: Returns the origin url of the repository.
#
# path - An optional {String} path in the repository to get this information
# for, only needed if the repository has submodules.
# * `path` An optional {String} path in the repository to get this information
# for, only needed if the repository has submodules.
getOriginUrl: (path) -> @getConfigValue('remote.origin.url', path)
# Public: Returns the upstream branch for the current HEAD, or null if there
# is no upstream branch for the current HEAD.
#
# path - An optional {String} path in the repo to get this information for,
# only needed if the repository contains submodules.
# * `path` An optional {String} path in the repo to get this information for,
# only needed if the repository contains submodules.
#
# Returns a {String} branch name such as `refs/remotes/origin/master`.
getUpstreamBranch: (path) -> @getRepo(path).getUpstreamBranch()
# Public: Returns the current SHA for the given reference.
# Public: Returns the current {String} SHA for the given reference.
#
# reference - The {String} reference to get the target of.
# path - An optional {String} path in the repo to get the reference target
# for. Only needed if the repository contains submodules.
# * `reference` The {String} reference to get the target of.
# * `path` An optional {String} path in the repo to get the reference target
# for. Only needed if the repository contains submodules.
getReferenceTarget: (reference, path) ->
@getRepo(path).getReferenceTarget(reference)
# Public: Gets all the local and remote references.
#
# path - An optional {String} path in the repository to get this information
# for, only needed if the repository has submodules.
# * `path` An optional {String} path in the repository to get this information
# for, only needed if the repository has submodules.
#
# Returns an {Object} with the following keys:
# :heads - An {Array} of head reference names.
# :remotes - An {Array} of remote reference names.
# :tags - An {Array} of tag reference names.
# * `heads` An {Array} of head reference names.
# * `remotes` An {Array} of remote reference names.
# * `tags` An {Array} of tag reference names.
getReferences: (path) -> @getRepo(path).getReferences()
# Public: Returns the number of commits behind the current branch is from the
# its upstream remote branch.
#
# reference - The {String} branch reference name.
# path - The {String} path in the repository to get this information for,
# only needed if the repository contains submodules.
# * `reference` The {String} branch reference name.
# * `path` The {String} path in the repository to get this information for,
# only needed if the repository contains submodules.
getAheadBehindCount: (reference, path) ->
@getRepo(path).getAheadBehindCount(reference)
# Public: Get the cached ahead/behind commit counts for the current branch's
# upstream branch.
#
# path - An optional {String} path in the repository to get this information
# for, only needed if the repository has submodules.
# * `path` An optional {String} path in the repository to get this information
# for, only needed if the repository has submodules.
#
# Returns an {Object} with the following keys:
# :ahead - The {Number} of commits ahead.
# :behind - The {Number} of commits behind.
# * `ahead` The {Number} of commits ahead.
# * `behind` The {Number} of commits behind.
getCachedUpstreamAheadBehindCount: (path) ->
@getRepo(path).upstream ? @upstream
# Public: Get the cached status for the given path.
#
# path - A {String} path in the repository, relative or absolute.
# * `path` A {String} path in the repository, relative or absolute.
#
# Returns a status {Number} or null if the path is not in the cache.
getCachedPathStatus: (path) ->

21
src/menu-manager.coffee
View File

@@ -17,9 +17,9 @@ class MenuManager
atom.keymaps.on 'bundled-keymaps-loaded', => @loadPlatformItems()
atom.packages.on 'activated', => @sortPackagesMenu()
# Public: Adds the given item definition to the existing template.
# Public: Adds the given items to the application menu.
#
# ## Example
# ## Examples
# ```coffee
# atom.menu.add [
# {
@@ -29,23 +29,22 @@ class MenuManager
# ]
# ```
#
# items - An {Array} of menu item {Object}s containing the keys:
# :label - The {String} menu label.
# :submenu - An optional {Array} of sub menu items.
# :command - An optional {String} command to trigger when the item is
# clicked.
#
# Returns nothing.
# * `items` An {Array} of menu item {Object}s containing the keys:
# * `label` The {String} menu label.
# * `submenu` An optional {Array} of sub menu items.
# * `command` An optional {String} command to trigger when the item is
# clicked.
add: (items) ->
@merge(@template, item) for item in items
@update()
undefined
# Should the binding for the given selector be included in the menu
# commands.
#
# selector - A {String} selector to check.
# * `selector` A {String} selector to check.
#
# Returns true to include the selector, false otherwise.
# Returns a {Boolean}, true to include the selector, false otherwise.
includeSelector: (selector) ->
try
return true if document.body.webkitMatchesSelector(selector)

72
src/package-manager.coffee
View File

@@ -21,7 +21,7 @@ ThemePackage = require './theme-package'
# `deactivate()` on the package's main module.
# * Unloading a package removes it completely from the package manager.
#
# Packages can also be enabled/disabled via the `core.disabledPackages` config
# Packages can be enabled/disabled via the `core.disabledPackages` config
# settings and also by calling `enablePackage()/disablePackage()`.
module.exports =
class PackageManager
@@ -41,15 +41,17 @@ class PackageManager
@packageActivators = []
@registerPackageActivator(this, ['atom', 'textmate'])
# Public: Get the path to the apm command
# Extended: Get the path to the apm command.
#
# Return a {String} file path to apm.
getApmPath: ->
commandName = 'apm'
commandName += '.cmd' if process.platform is 'win32'
@apmPath ?= path.resolve(__dirname, '..', 'apm', 'node_modules', 'atom-package-manager', 'bin', commandName)
# Public: Get the paths being used to look for packages.
# Extended: Get the paths being used to look for packages.
#
# Returns an Array of String directory paths.
# Returns an {Array} of {String} directory paths.
getPackageDirPaths: ->
_.clone(@packageDirPaths)
@@ -59,13 +61,17 @@ class PackageManager
setPackageState: (name, state) ->
@packageStates[name] = state
# Public: Enable the package with the given name
# Extended: Enable the package with the given name.
#
# Returns the {Package} that was enabled or null if it isn't loaded.
enablePackage: (name) ->
pack = @loadPackage(name)
pack?.enable()
pack
# Public: Disable the package with the given name
# Extended: Disable the package with the given name.
#
# Returns the {Package} that was disabled or null if it isn't loaded.
disablePackage: (name) ->
pack = @loadPackage(name)
pack?.disable()
@@ -110,15 +116,23 @@ class PackageManager
pack.deactivate()
delete @activePackages[pack.name]
# Public: Get an array of all the active packages
# Essential: Get an {Array} of all the active {Package}s.
getActivePackages: ->
_.values(@activePackages)
# Public: Get the active package with the given name
# Essential: Get the active {Package} with the given name.
#
# * `name` - The {String} package name.
#
# Returns a {Package} or undefined.
getActivePackage: (name) ->
@activePackages[name]
# Public: Is the package with the given name active?
# Public: Is the {Package} with the given name active?
#
# * `name` - The {String} package name.
#
# Returns a {Boolean}.
isPackageActive: (name) ->
@getActivePackage(name)?
@@ -179,25 +193,37 @@ class PackageManager
else
throw new Error("No loaded package for name '#{name}'")
# Public: Get the loaded package with the given name
# Essential: Get the loaded {Package} with the given name.
#
# * `name` - The {String} package name.
#
# Returns a {Package} or undefined.
getLoadedPackage: (name) ->
@loadedPackages[name]
# Public: Is the package with the given name loaded?
# Essential: Is the package with the given name loaded?
#
# * `name` - The {String} package name.
#
# Returns a {Boolean}.
isPackageLoaded: (name) ->
@getLoadedPackage(name)?
# Public: Get an array of all the loaded packages
# Essential: Get an {Array} of all the loaded {Package}s
getLoadedPackages: ->
_.values(@loadedPackages)
# Get packages for a certain package type
#
# types - an {Array} of {String}s like ['atom', 'textmate'].
# * `types` an {Array} of {String}s like ['atom', 'textmate'].
getLoadedPackagesForTypes: (types) ->
pack for pack in @getLoadedPackages() when pack.getType() in types
# Public: Resolve the given package name to a path on disk.
# Extended: Resolve the given package name to a path on disk.
#
# * `name` - The {String} package name.
#
# Return a {String} folder path or undefined if it could not be resolved.
resolvePackagePath: (name) ->
return name if fs.isDirectorySync(name)
@@ -207,7 +233,11 @@ class PackageManager
packagePath = path.join(@resourcePath, 'node_modules', name)
return packagePath if @hasAtomEngine(packagePath)
# Public: Is the package with the given name disabled?
# Essential: Is the package with the given name disabled?
#
# * `name` - The {String} package name.
#
# Returns a {Boolean}.
isPackageDisabled: (name) ->
_.include(atom.config.get('core.disabledPackages') ? [], name)
@@ -215,7 +245,11 @@ class PackageManager
metadata = Package.loadMetadata(packagePath, true)
metadata?.engines?.atom?
# Public: Is the package with the given name bundled with Atom?
# Extended: Is the package with the given name bundled with Atom?
#
# * `name` - The {String} package name.
#
# Returns a {Boolean}.
isBundledPackage: (name) ->
@getPackageDependencies().hasOwnProperty(name)
@@ -228,7 +262,7 @@ class PackageManager
@packageDependencies
# Public: Get an array of all the available package paths.
# Extended: Get an {Array} of {String}s of all the available package paths.
getAvailablePackagePaths: ->
packagePaths = []
@@ -243,11 +277,11 @@ class PackageManager
_.uniq(packagePaths)
# Public: Get an array of all the available package names.
# Extended: Get an {Array} of {String}s of all the available package names.
getAvailablePackageNames: ->
_.uniq _.map @getAvailablePackagePaths(), (packagePath) -> path.basename(packagePath)
# Public: Get an array of all the available package metadata.
# Extended: Get an {Array} of {String}s of all the available package metadata.
getAvailablePackageMetadata: ->
packages = []
for packagePath in @getAvailablePackagePaths()

2
src/pane-view.coffee
View File

@@ -5,7 +5,7 @@ PropertyAccessors = require 'property-accessors'
Pane = require './pane'
# Public: A container which can contains multiple items to be switched between.
# Extended: A container which can contains multiple items to be switched between.
#
# Items can be almost anything however most commonly they're {EditorView}s.
#

78
src/pane.coffee
View File

@@ -5,9 +5,43 @@ PaneAxis = require './pane-axis'
Editor = require './editor'
PaneView = null
# Public: A container for multiple items, one of which is *active* at a given
# Extended: A container for multiple items, one of which is *active* at a given
# time. With the default packages, a tab is displayed for each item and the
# active item's view is displayed.
#
# ## Events
# ### activated
#
# Extended: Emit when this pane as been activated
#
# ### item-added
#
# Extended: Emit when an item was added to the pane
#
# * `item` The pane item that has been added
# * `index` {Number} Index in the pane
#
# ### before-item-destroyed
#
# Extended: Emit before the item is destroyed
#
# * `item` The pane item that will be destoryed
#
# ### item-removed
#
# Extended: Emit when the item was removed from the pane
#
# * `item` The pane item that was removed
# * `index` {Number} Index in the pane
# * `destroying` {Boolean} `true` when the item is being removed because of destruction
#
# ### item-moved
#
# Extended: Emit when an item was moved within the pane
#
# * `item` The pane item that was moved
# * `newIndex` {Number} Index that the item was moved to
#
module.exports =
class Pane extends Model
atom.deserializers.add(this)
@@ -130,9 +164,9 @@ class Pane extends Model
# Public: Adds the item to the pane.
#
# item - The item to add. It can be a model with an associated view or a view.
# index - An optional index at which to add the item. If omitted, the item is
# added after the current active item.
# * `item` The item to add. It can be a model with an associated view or a view.
# * `index` (optional) {Number} at which to add the item. If omitted, the item is
# added after the current active item.
#
# Returns the added item
addItem: (item, index=@getActiveItemIndex() + 1) ->
@@ -145,11 +179,11 @@ class Pane extends Model
# Public: Adds the given items to the pane.
#
# items - An {Array} of items to add. Items can be models with associated
# views or views. Any items that are already present in items will
# not be added.
# index - An optional index at which to add the item. If omitted, the item is
# added after the current active item.
# * `items` An {Array} of items to add. Items can be models with associated
# views or views. Any items that are already present in items will
# not be added.
# * `index` (optional) {Number} index at which to add the item. If omitted, the item is
# added after the current active item.
#
# Returns an {Array} of the added items
addItems: (items, index=@getActiveItemIndex() + 1) ->
@@ -246,9 +280,8 @@ class Pane extends Model
# Public: Saves the specified item.
#
# item - The item to save.
# nextAction - An optional function which will be called after the item is
# saved.
# * `item` The item to save.
# * `nextAction` (optional) {Function} which will be called after the item is saved.
saveItem: (item, nextAction) ->
if item?.getUri?()
item.save?()
@@ -258,9 +291,8 @@ class Pane extends Model
# Public: Saves the given item at a prompted-for location.
#
# item - The item to save.
# nextAction - An optional function which will be called after the item is
# saved.
# * `item` The item to save.
# * `nextAction` (optional) {Function} which will be called after the item is saved.
saveItemAs: (item, nextAction) ->
return unless item?.saveAs?
@@ -294,8 +326,8 @@ class Pane extends Model
# Public: Creates a new pane to the left of the receiver.
#
# params - An object with keys:
# :items - An optional array of items with which to construct the new pane.
# * `params` {Object} with keys
# * `items` (optional) {Array} of items with which to construct the new pane.
#
# Returns the new {Pane}.
splitLeft: (params) ->
@@ -303,8 +335,8 @@ class Pane extends Model
# Public: Creates a new pane to the right of the receiver.
#
# params - An object with keys:
# :items - An optional array of items with which to construct the new pane.
# * `params` {Object} with keys:
# * `items` (optional) {Array} of items with which to construct the new pane.
#
# Returns the new {Pane}.
splitRight: (params) ->
@@ -312,8 +344,8 @@ class Pane extends Model
# Public: Creates a new pane above the receiver.
#
# params - An object with keys:
# :items - An optional array of items with which to construct the new pane.
# * `params` {Object} with keys:
# * `items` (optional) {Array} of items with which to construct the new pane.
#
# Returns the new {Pane}.
splitUp: (params) ->
@@ -321,8 +353,8 @@ class Pane extends Model
# Public: Creates a new pane below the receiver.
#
# params - An object with keys:
# :items - An optional array of items with which to construct the new pane.
# * `params` {Object} with keys:
# * `items` (optional) {Array} of items with which to construct the new pane.
#
# Returns the new {Pane}.
splitDown: (params) ->

55
src/project.coffee
View File

@@ -15,15 +15,30 @@ Editor = require './editor'
Task = require './task'
Git = require './git'
# Public: Represents a project that's opened in Atom.
# Extended: Represents a project that's opened in Atom.
#
# An instance of this class is always available as the `atom.project` global.
#
# ## Events
#
# ### path-changed
#
# Extended: Emit when the project's path has changed. Use {::getPath} to get the new path
#
# ### buffer-created
#
# Extended: Emit when a buffer is created. For example, when {::open} is called, this is fired.
#
# * `buffer` {TextBuffer} the new buffer that was created.
#
module.exports =
class Project extends Model
atom.deserializers.add(this)
Serializable.includeInto(this)
# Public: Find the local path for the given repository URL.
#
# * `repoUrl` {String} url to a git repository
@pathForRepositoryUrl: (repoUrl) ->
[repoName] = url.parse(repoUrl).path.split('/')[-1..]
repoName = repoName.replace(/\.git$/, '')
@@ -61,11 +76,13 @@ class Project extends Model
# Public: Returns the {Git} repository if available.
getRepo: -> @repo
# Public: Returns the project's fullpath.
# Public: Returns the project's {String} fullpath.
getPath: ->
@rootDirectory?.path
# Public: Sets the project's fullpath.
#
# * `projectPath` {String} path
setPath: (projectPath) ->
@path = projectPath
@rootDirectory?.off()
@@ -90,7 +107,7 @@ class Project extends Model
# the path is already absolute or if it is prefixed with a scheme, it is
# returned unchanged.
#
# uri - The {String} name of the path to convert.
# * `uri` The {String} name of the path to convert.
#
# Returns a {String} or undefined if the uri is not missing or empty.
resolve: (uri) ->
@@ -107,19 +124,23 @@ class Project extends Model
undefined
# Public: Make the given path relative to the project directory.
#
# * `fullPath` {String} full path
relativize: (fullPath) ->
return fullPath if fullPath?.match(/[A-Za-z0-9+-.]+:\/\//) # leave path alone if it has a scheme
@rootDirectory?.relativize(fullPath) ? fullPath
# Public: Returns whether the given path is inside this project.
#
# * `pathToCheck` {String} path
contains: (pathToCheck) ->
@rootDirectory?.contains(pathToCheck) ? false
# Given a path to a file, this constructs and associates a new
# {Editor}, showing the file.
#
# filePath - The {String} path of the file to associate with.
# options - Options that you can pass to the {Editor} constructor.
# * `filePath` The {String} path of the file to associate with.
# * `options` Options that you can pass to the {Editor} constructor.
#
# Returns a promise that resolves to an {Editor}.
open: (filePath, options={}) ->
@@ -158,7 +179,7 @@ class Project extends Model
# If the `filePath` already has a `buffer`, that value is used instead. Otherwise,
# `text` is used as the contents of the new buffer.
#
# filePath - A {String} representing a path. If `null`, an "Untitled" buffer is created.
# * `filePath` A {String} representing a path. If `null`, an "Untitled" buffer is created.
#
# Returns a promise that resolves to the {TextBuffer}.
bufferForPath: (filePath) ->
@@ -178,8 +199,8 @@ class Project extends Model
# Given a file path, this sets its {TextBuffer}.
#
# absoluteFilePath - A {String} representing a path.
# text - The {String} text to use as a buffer.
# * `absoluteFilePath` A {String} representing a path.
# * `text` The {String} text to use as a buffer.
#
# Returns a promise that resolves to the {TextBuffer}.
buildBuffer: (absoluteFilePath) ->
@@ -215,10 +236,10 @@ class Project extends Model
# Public: Performs a search across all the files in the project.
#
# regex - A {RegExp} to search with.
# options - An optional options {Object} (default: {}):
# :paths - An {Array} of glob patterns to search within
# iterator - A {Function} callback on each file found
# * `regex` {RegExp} to search with.
# * `options` (optional) {Object} (default: {})
# * `paths` An {Array} of glob patterns to search within
# * `iterator` {Function} callback on each file found
scan: (regex, options={}, iterator) ->
if _.isFunction(options)
iterator = options
@@ -261,11 +282,11 @@ class Project extends Model
# Public: Performs a replace across all the specified files in the project.
#
# regex - A {RegExp} to search with.
# replacementText - Text to replace all matches of regex with
# filePaths - List of file path strings to run the replace on.
# iterator - A {Function} callback on each file with replacements:
# `({filePath, replacements}) ->`.
# * `regex` A {RegExp} to search with.
# * `replacementText` Text to replace all matches of regex with
# * `filePaths` List of file path strings to run the replace on.
# * `iterator` A {Function} callback on each file with replacements:
# * `options` {Object} with keys `filePath` and `replacements`
replace: (regex, replacementText, filePaths, iterator) ->
deferred = Q.defer()

31
src/scroll-view.coffee
View File

@@ -2,22 +2,31 @@
# Public: Represents a view that scrolls.
#
# Subclasses must call `super` if overriding the `initialize` method or else
# the following events won't be handled by the ScrollView.
# Handles several core events to update scroll position:
#
# ## Events
# * `core:move-up`
# * `core:move-down`
# * `core:page-up`
# * `core:page-down`
# * `core:move-to-top`
# * `core:move-to-bottom`
# * `core:move-up` Scrolls the view up
# * `core:move-down` Scrolls the view down
# * `core:page-up` Scrolls the view up by the height of the page
# * `core:page-down` Scrolls the view down by the height of the page
# * `core:move-to-top` Scrolls the editor to the top
# * `core:move-to-bottom` Scroll the editor to the bottom
#
# ## Requiring in packages
# Subclasses must call `super` if overriding the `initialize` method.
#
# ## Examples
#
# ```coffee
# {ScrollView} = require 'atom'
# {ScrollView} = require 'atom'
#
# class MyView extends ScrollView
# @content: ->
# @div()
#
# initialize: ->
# super
# @text('super long content that will scroll')
# ```
#
module.exports =
class ScrollView extends View
initialize: ->

22
src/select-list-view.coffee
View File

@@ -2,7 +2,7 @@
EditorView = require './editor-view'
fuzzyFilter = require('fuzzaldrin').filter
# Public: Provides a view that renders a list of items with an editor that
# Essential: Provides a view that renders a list of items with an editor that
# filters the items. Used by many packages such as the fuzzy-finder,
# command-palette, symbols-view and autocomplete.
#
@@ -96,14 +96,14 @@ class SelectListView extends View
# This should be model items not actual views. {::viewForItem} will be
# called to render the item when it is being appended to the list view.
#
# items - The {Array} of model items to display in the list (default: []).
# * `items` The {Array} of model items to display in the list (default: []).
setItems: (@items=[]) ->
@populateList()
@setLoading()
# Public: Set the error message to display.
#
# message - The {String} error message (default: '').
# * `message` The {String} error message (default: '').
setError: (message='') ->
if message.length is 0
@error.text('').hide()
@@ -113,7 +113,7 @@ class SelectListView extends View
# Public: Set the loading message to display.
#
# message - The {String} loading message (default: '').
# * `message` The {String} loading message (default: '').
setLoading: (message='') ->
if message.length is 0
@loading.text("")
@@ -165,15 +165,15 @@ class SelectListView extends View
#
# Subclasses may override this method to customize the message.
#
# itemCount - The {Number} of items in the array specified to {::setItems}
# filteredItemCount - The {Number} of items that pass the fuzzy filter test.
# * `itemCount` The {Number} of items in the array specified to {::setItems}
# * `filteredItemCount` The {Number} of items that pass the fuzzy filter test.
#
# Returns a {String} message (default: 'No matches found').
getEmptyMessage: (itemCount, filteredItemCount) -> 'No matches found'
# Public: Set the maximum numbers of items to display in the list.
#
# maxItems - The maximum {Number} of items to display.
# * `maxItems` The maximum {Number} of items to display.
setMaxItems: (@maxItems) ->
selectPreviousItemView: ->
@@ -224,8 +224,8 @@ class SelectListView extends View
#
# This is called when the item is about to appended to the list view.
#
# item - The model item being rendered. This will always be one of the items
# previously passed to {::setItems}.
# * `item` The model item being rendered. This will always be one of the items
# previously passed to {::setItems}.
#
# Returns a String of HTML, DOM element, jQuery object, or View.
viewForItem: (item) ->
@@ -235,8 +235,8 @@ class SelectListView extends View
#
# This method must be overridden by subclasses.
#
# item - The selected model item. This will always be one of the items
# previously passed to {::setItems}.
# * `item` The selected model item. This will always be one of the items
# previously passed to {::setItems}.
#
# Returns a DOM element, jQuery object, or {View}.
confirmed: (item) ->

84
src/selection.coffee
View File

@@ -2,7 +2,20 @@
{Model} = require 'theorist'
{pick} = require 'underscore-plus'
# Public: Represents a selection in the {Editor}.
# Extended: Represents a selection in the {Editor}.
#
# ## Events
#
# ### screen-range-changed
#
# Extended: Emit when the selection was moved.
#
# * `screenRange` {Range} indicating the new screenrange
#
# ### destroyed
#
# Extended: Emit when the selection was destroyed
#
module.exports =
class Selection extends Model
cursor: null
@@ -56,8 +69,8 @@ class Selection extends Model
# Public: Modifies the screen range for the selection.
#
# screenRange - The new {Range} to use.
# options - A hash of options matching those found in {::setBufferRange}.
# * `screenRange` The new {Range} to use.
# * `options` (optional) {Object} options matching those found in {::setBufferRange}.
setScreenRange: (screenRange, options) ->
@setBufferRange(@editor.bufferRangeForScreenRange(screenRange), options)
@@ -67,11 +80,10 @@ class Selection extends Model
# Public: Modifies the buffer {Range} for the selection.
#
# screenRange - The new {Range} to select.
# options - An {Object} with the keys:
# :preserveFolds - if `true`, the fold settings are preserved after the
# selection moves.
# :autoscroll - if `true`, the {Editor} scrolls to the new selection.
# * `screenRange` The new {Range} to select.
# * `options` (optional) {Object} with the keys:
# * `preserveFolds` if `true`, the fold settings are preserved after the selection moves.
# * `autoscroll` if `true`, the {Editor} scrolls to the new selection.
setBufferRange: (bufferRange, options={}) ->
bufferRange = Range.fromObject(bufferRange)
@needsAutoscroll = options.autoscroll
@@ -141,7 +153,7 @@ class Selection extends Model
# Public: Selects an entire line in the buffer.
#
# row - The line {Number} to select (default: the row of the cursor).
# * `row` The line {Number} to select (default: the row of the cursor).
selectLine: (row=@cursor.getBufferPosition().row) ->
range = @editor.bufferRangeForBufferRow(row, includeNewline: true)
@setBufferRange(@getBufferRange().union(range))
@@ -160,7 +172,7 @@ class Selection extends Model
# Public: Selects the text from the current cursor position to a given screen
# position.
#
# position - An instance of {Point}, with a given `row` and `column`.
# * `position` An instance of {Point}, with a given `row` and `column`.
selectToScreenPosition: (position) ->
position = Point.fromObject(position)
@@ -181,7 +193,7 @@ class Selection extends Model
# Public: Selects the text from the current cursor position to a given buffer
# position.
#
# position - An instance of {Point}, with a given `row` and `column`.
# * `position` An instance of {Point}, with a given `row` and `column`.
selectToBufferPosition: (position) ->
@modifySelection => @cursor.setBufferPosition(position)
@@ -306,14 +318,14 @@ class Selection extends Model
# Public: Replaces text at the current selection.
#
# text - A {String} representing the text to add
# options - An {Object} with keys:
# :select - if `true`, selects the newly added text.
# :autoIndent - if `true`, indents all inserted text appropriately.
# :autoIndentNewline - if `true`, indent newline appropriately.
# :autoDecreaseIndent - if `true`, decreases indent level appropriately
# (for example, when a closing bracket is inserted).
# :undo - if `skip`, skips the undo stack for this operation.
# * `text` A {String} representing the text to add
# * `options` (optional) {Object} with keys:
# * `select` if `true`, selects the newly added text.
# * `autoIndent` if `true`, indents all inserted text appropriately.
# * `autoIndentNewline` if `true`, indent newline appropriately.
# * `autoDecreaseIndent` if `true`, decreases indent level appropriately
# (for example, when a closing bracket is inserted).
# * `undo` if `skip`, skips the undo stack for this operation.
insertText: (text, options={}) ->
oldBufferRange = @getBufferRange()
@editor.unfoldBufferRow(oldBufferRange.end.row)
@@ -345,8 +357,8 @@ class Selection extends Model
# Public: Indents the given text to the suggested level based on the grammar.
#
# text - The {String} to indent within the selection.
# indentBasis - The beginning indent level.
# * `text` The {String} to indent within the selection.
# * `indentBasis` The beginning indent level.
normalizeIndents: (text, indentBasis) ->
textPrecedingCursor = @cursor.getCurrentBufferLine()[0...@cursor.getBufferColumn()]
isCursorInsideExistingLine = /\S/.test(textPrecedingCursor)
@@ -378,9 +390,9 @@ class Selection extends Model
# non-whitespace characters, and otherwise inserts a tab. If the selection is
# non empty, calls {::indentSelectedRows}.
#
# options - A {Object} with the keys:
# :autoIndent - If `true`, the line is indented to an automatically-inferred
# level. Otherwise, {Editor::getTabText} is inserted.
# * `options` (optional) {Object} with the keys:
# * `autoIndent` If `true`, the line is indented to an automatically-inferred
# level. Otherwise, {Editor::getTabText} is inserted.
indent: ({ autoIndent }={}) ->
{ row, column } = @cursor.getBufferPosition()
@@ -549,16 +561,18 @@ class Selection extends Model
@cut(maintainClipboard)
# Public: Copies the selection to the clipboard and then deletes it.
#
# * `maintainClipboard` {Boolean} (default: false) See {::copy}
cut: (maintainClipboard=false) ->
@copy(maintainClipboard)
@delete()
# Public: Copies the current selection to the clipboard.
#
# If the `maintainClipboard` is set to `true`, a specific metadata property
# is created to store each content copied to the clipboard. The clipboard
# `text` still contains the concatenation of the clipboard with the
# current selection.
# * `maintainClipboard` {Boolean} if `true`, a specific metadata property
# is created to store each content copied to the clipboard. The clipboard
# `text` still contains the concatenation of the clipboard with the
# current selection. (default: false)
copy: (maintainClipboard=false) ->
return if @isEmpty()
text = @editor.buffer.getTextInRange(@getBufferRange())
@@ -598,9 +612,9 @@ class Selection extends Model
# Public: Identifies if a selection intersects with a given buffer range.
#
# bufferRange - A {Range} to check against.
# * `bufferRange` A {Range} to check against.
#
# Returns a Boolean.
# Returns a {Boolean}
intersectsBufferRange: (bufferRange) ->
@getBufferRange().intersectsWith(bufferRange)
@@ -612,17 +626,17 @@ class Selection extends Model
# Public: Identifies if a selection intersects with another selection.
#
# otherSelection - A {Selection} to check against.
# * `otherSelection` A {Selection} to check against.
#
# Returns a Boolean.
# Returns a {Boolean}
intersectsWith: (otherSelection) ->
@getBufferRange().intersectsWith(otherSelection.getBufferRange())
# Public: Combines the given selection into this selection and then destroys
# the given selection.
#
# otherSelection - A {Selection} to merge with.
# options - A hash of options matching those found in {::setBufferRange}.
# * `otherSelection` A {Selection} to merge with.
# * `options` (optional) {Object} options matching those found in {::setBufferRange}.
merge: (otherSelection, options) ->
myGoalBufferRange = @getGoalBufferRange()
otherGoalBufferRange = otherSelection.getGoalBufferRange()
@@ -638,7 +652,7 @@ class Selection extends Model
#
# See {Range::compare} for more details.
#
# otherSelection - A {Selection} to compare against.
# * `otherSelection` A {Selection} to compare against
compare: (otherSelection) ->
@getBufferRange().compare(otherSelection.getBufferRange())

9
src/syntax.coffee
View File

@@ -14,7 +14,7 @@ Token = require './token'
# An instance of this class is always available as the `atom.syntax` global.
#
# The Syntax class also contains properties for things such as the
# language-specific comment regexes.
# language-specific comment regexes. See {::getProperty} for more details.
module.exports =
class Syntax extends GrammarRegistry
PropertyAccessors.includeInto(this)
@@ -55,14 +55,15 @@ class Syntax extends GrammarRegistry
# Public: Get a property for the given scope and key path.
#
# ## Example
# ## Examples
#
# ```coffee
# comment = atom.syntax.getProperty(['.source.ruby'], 'editor.commentStart')
# console.log(comment) # '# '
# ```
#
# scope - An {Array} of {String} scopes.
# keyPath - A {String} key path.
# * `scope` An {Array} of {String} scopes.
# * `keyPath` A {String} key path.
#
# Returns a {String} property value or undefined.
getProperty: (scope, keyPath) ->

61
src/task.coffee
View File

@@ -6,27 +6,41 @@ child_process = require 'child_process'
#
# Used by the fuzzy-finder.
#
# ## Events
#
# * task:log - Emitted when console.log is called within the task.
# * task:warn - Emitted when console.warn is called within the task.
# * task:error - Emitted when console.error is called within the task.
# * task:completed - Emitted when the task has succeeded or failed.
#
# ## Requiring in packages
# ## Examples
#
# ```coffee
# {Task} = require 'atom'
# {Task} = require 'atom'
# ```
#
# ## Events
#
# ### task:log
#
# Emitted when console.log is called within the task.
#
# ### task:warn
#
# Emitted when console.warn is called within the task.
#
# ### task:error
#
# Emitted when console.error is called within the task.
#
# ### task:completed
#
# Emitted when the task has succeeded or failed.
#
module.exports =
class Task
Emitter.includeInto(this)
# Public: A helper method to easily launch and run a task once.
#
# taskPath - The {String} path to the CoffeeScript/JavaScript file which
# exports a single {Function} to execute.
# args - The arguments to pass to the exported function.
# * `taskPath` The {String} path to the CoffeeScript/JavaScript file which
# exports a single {Function} to execute.
# * `args` The arguments to pass to the exported function.
#
# Returns the created {Task}.
@once: (taskPath, args...) ->
task = new Task(taskPath)
task.once 'task:completed', -> task.terminate()
@@ -43,8 +57,8 @@ class Task
# Public: Creates a task.
#
# taskPath - The {String} path to the CoffeeScript/JavaScript file that
# exports a single {Function} to execute.
# * `taskPath` The {String} path to the CoffeeScript/JavaScript file that
# exports a single {Function} to execute.
constructor: (taskPath) ->
coffeeCacheRequire = "require('#{require.resolve('./coffee-cache')}').register();"
coffeeScriptRequire = "require('#{require.resolve('coffee-script')}').register();"
@@ -81,10 +95,10 @@ class Task
# Throws an error if this task has already been terminated or if sending a
# message to the child process fails.
#
# args - The arguments to pass to the function exported by this task's script.
# callback - An optional {Function} to call when the task completes.
# * `args` The arguments to pass to the function exported by this task's script.
# * `callback` (optional) A {Function} to call when the task completes.
start: (args..., callback) ->
throw new Error("Cannot start terminated process") unless @childProcess?
throw new Error('Cannot start terminated process') unless @childProcess?
@handleEvents()
if _.isFunction(callback)
@@ -92,20 +106,24 @@ class Task
else
args.push(callback)
@send({event: 'start', args})
undefined
# Public: Send message to the task.
#
# Throws an error if this task has already been terminated or if sending a
# message to the child process fails.
#
# message - The message to send to the task.
# * `message` The message to send to the task.
send: (message) ->
throw new Error("Cannot send message to terminated process") unless @childProcess?
@childProcess.send(message)
if @childProcess?
@childProcess.send(message)
else
throw new Error('Cannot send message to terminated process')
undefined
# Public: Forcefully stop the running task.
#
# No events are emitted.
# No more events are emitted once this method is called.
terminate: ->
return unless @childProcess?
@@ -114,3 +132,4 @@ class Task
@childProcess = null
@off()
undefined

34
src/theme-manager.coffee
View File

@@ -9,9 +9,32 @@ Q = require 'q'
Package = require './package'
{File} = require 'pathwatcher'
# Public: Handles loading and activating available themes.
# Extended: Handles loading and activating available themes.
#
# An instance of this class is always available as the `atom.themes` global.
#
# ## Events
#
# ### reloaded
#
# Extended: Emit when all styles have been reloaded.
#
# ### stylesheet-added
#
# Extended: Emit when a stylesheet has been added.
#
# * `stylesheet` {StyleSheet} object that was removed
#
# ### stylesheet-removed
#
# Extended: Emit when a stylesheet has been removed.
#
# * `stylesheet` {StyleSheet} object that was removed
#
# ### stylesheets-changed
#
# Extended: Emit anytime any style sheet is added or removed from the editor
#
module.exports =
class ThemeManager
Emitter.includeInto(this)
@@ -98,7 +121,7 @@ class ThemeManager
@refreshLessCache() # Update cache again now that @getActiveThemes() is populated
@loadUserStylesheet()
@reloadBaseStylesheets()
@emit('reloaded')
@emit 'reloaded'
deferred.resolve()
deferred.promise
@@ -124,7 +147,7 @@ class ThemeManager
# Public: Set the list of enabled themes.
#
# enabledThemeNames - An {Array} of {String} theme names.
# * `enabledThemeNames` An {Array} of {String} theme names.
setEnabledThemes: (enabledThemeNames) ->
atom.config.set('core.themes', enabledThemeNames)
@@ -187,9 +210,8 @@ class ThemeManager
#
# This supports both CSS and LESS stylsheets.
#
# stylesheetPath - A {String} path to the stylesheet that can be an absolute
# path or a relative path that will be resolved against the
# load path.
# * `stylesheetPath` A {String} path to the stylesheet that can be an absolute
# path or a relative path that will be resolved against the load path.
#
# Returns the absolute path to the required stylesheet.
requireStylesheet: (stylesheetPath, type = 'bundled', htmlElement) ->

26
src/workspace-view.coffee
View File

@@ -15,7 +15,7 @@ PaneRowView = require './pane-row-view'
PaneContainerView = require './pane-container-view'
Editor = require './editor'
# Public: The top-level view for the entire window. An instance of this class is
# Essential: The top-level view for the entire window. An instance of this class is
# available via the `atom.workspaceView` global.
#
# It is backed by a model object, an instance of {Workspace}, which is available
@@ -44,7 +44,7 @@ Editor = require './editor'
# the built-in `atom` module.
#
# ```coffee
# {WorkspaceView} = require 'atom'
# {WorkspaceView} = require 'atom'
# ```
#
# You can assign it to the `atom.workspaceView` global in the spec or just use
@@ -244,40 +244,56 @@ class WorkspaceView extends View
# Public: Prepend an element or view to the panels at the top of the
# workspace.
#
# * `element` jQuery object or DOM element
prependToTop: (element) ->
@vertical.prepend(element)
# Public: Append an element or view to the panels at the top of the workspace.
#
# * `element` jQuery object or DOM element
appendToTop: (element) ->
@panes.before(element)
# Public: Prepend an element or view to the panels at the bottom of the
# workspace.
#
# * `element` jQuery object or DOM element
prependToBottom: (element) ->
@panes.after(element)
# Public: Append an element or view to the panels at the bottom of the
# workspace.
#
# * `element` jQuery object or DOM element
appendToBottom: (element) ->
@vertical.append(element)
# Public: Prepend an element or view to the panels at the left of the
# workspace.
#
# * `element` jQuery object or DOM element
prependToLeft: (element) ->
@horizontal.prepend(element)
# Public: Append an element or view to the panels at the left of the
# workspace.
#
# * `element` jQuery object or DOM element
appendToLeft: (element) ->
@vertical.before(element)
# Public: Prepend an element or view to the panels at the right of the
# workspace.
#
# * `element` jQuery object or DOM element
prependToRight: (element) ->
@vertical.after(element)
# Public: Append an element or view to the panels at the right of the
# workspace.
#
# * `element` jQuery object or DOM element
appendToRight: (element) ->
@horizontal.append(element)
@@ -317,7 +333,8 @@ class WorkspaceView extends View
# Public: Register a function to be called for every current and future
# pane view in the workspace.
#
# callback - A {Function} with a {PaneView} as its only argument.
# * `callback` A {Function} with a {PaneView} as its only argument.
# * `paneView` {PaneView}
#
# Returns a subscription object with an `.off` method that you can call to
# unregister the callback.
@@ -338,7 +355,8 @@ class WorkspaceView extends View
# editor view in the workspace (only includes {EditorView}s that are pane
# items).
#
# callback - A {Function} with an {EditorView} as its only argument.
# * `callback` A {Function} with an {EditorView} as its only argument.
# * `editorView` {EditorView}
#
# Returns a subscription object with an `.off` method that you can call to
# unregister the callback.

80
src/workspace.coffee
View File

@@ -15,6 +15,20 @@ Pane = require './pane'
# Interact with this object to open files, be notified of current and future
# editors, and manipulate panes. To add panels, you'll need to use the
# {WorkspaceView} class for now until we establish APIs at the model layer.
#
# ## Events
#
# ### uri-opened
#
# Extended: Emit when something has been opened. This can be anything, from an
# editor to the settings view. You can get the new item via {::getActivePaneItem}
#
# ### editor-created
#
# Extended: Emit when an editor is created (a file opened).
#
# * `editor` {Editor} the new editor
#
module.exports =
class Workspace extends Model
atom.deserializers.add(this)
@@ -78,7 +92,7 @@ class Workspace extends Model
# Public: Register a function to be called for every current and future
# {Editor} in the workspace.
#
# callback - A {Function} with an {Editor} as its only argument.
# * `callback` A {Function} with an {Editor} as its only argument.
#
# Returns a subscription object with an `.off` method that you can call to
# unregister the callback.
@@ -98,22 +112,21 @@ class Workspace extends Model
# Public: Open a given a URI in Atom asynchronously.
#
# uri - A {String} containing a URI.
# options - An optional options {Object}
# :initialLine - A {Number} indicating which row to move the cursor to
# initially. Defaults to `0`.
# :initialColumn - A {Number} indicating which column to move the cursor to
# initially. Defaults to `0`.
# :split - Either 'left' or 'right'. If 'left', the item will be opened in
# leftmost pane of the current active pane's row. If 'right', the
# item will be opened in the rightmost pane of the current active
# pane's row.
# :activatePane - A {Boolean} indicating whether to call {Pane::activate} on
# the containing pane. Defaults to `true`.
# :searchAllPanes - A {Boolean}. If `true`, the workspace will attempt to
# activate an existing item for the given URI on any pane.
# If `false`, only the active pane will be searched for
# an existing item for the same URI. Defaults to `false`.
# * `uri` A {String} containing a URI.
# * `options` (optional) {Object}
# * `initialLine` A {Number} indicating which row to move the cursor to
# initially. Defaults to `0`.
# * `initialColumn` A {Number} indicating which column to move the cursor to
# initially. Defaults to `0`.
# * `split` Either 'left' or 'right'. If 'left', the item will be opened in
# leftmost pane of the current active pane's row. If 'right', the
# item will be opened in the rightmost pane of the current active pane's row.
# * `activatePane` A {Boolean} indicating whether to call {Pane::activate} on
# containing pane. Defaults to `true`.
# * `searchAllPanes` A {Boolean}. If `true`, the workspace will attempt to
# activate an existing item for the given URI on any pane.
# If `false`, only the active pane will be searched for
# an existing item for the same URI. Defaults to `false`.
#
# Returns a promise that resolves to the {Editor} for the file URI.
open: (uri, options={}) ->
@@ -132,7 +145,7 @@ class Workspace extends Model
@openUriInPane(uri, pane, options)
# Public: Open Atom's license in the active pane.
# Open Atom's license in the active pane.
openLicense: ->
@open(join(atom.getLoadSettings().resourcePath, 'LICENSE.md'))
@@ -140,14 +153,14 @@ class Workspace extends Model
# in specs. Calling this in production code will block the UI thread and
# everyone will be mad at you.**
#
# uri - A {String} containing a URI.
# options - An optional options {Object}
# :initialLine - A {Number} indicating which row to move the cursor to
# initially. Defaults to `0`.
# :initialColumn - A {Number} indicating which column to move the cursor to
# initially. Defaults to `0`.
# :activatePane - A {Boolean} indicating whether to call {Pane::activate} on
# the containing pane. Defaults to `true`.
# * `uri` A {String} containing a URI.
# * `options` An optional options {Object}
# * `initialLine` A {Number} indicating which row to move the cursor to
# initially. Defaults to `0`.
# * `initialColumn` A {Number} indicating which column to move the cursor to
# initially. Defaults to `0`.
# * `activatePane` A {Boolean} indicating whether to call {Pane::activate} on
# the containing pane. Defaults to `true`.
openSync: (uri='', options={}) ->
deprecate("Don't use the `changeFocus` option") if options.changeFocus?
@@ -207,14 +220,15 @@ class Workspace extends Model
#
# An {Editor} will be used if no openers return a value.
#
# ## Example
# ```coffeescript
# atom.project.registerOpener (uri) ->
# if path.extname(uri) is '.toml'
# return new TomlEditor(uri)
# ## Examples
#
# ```coffee
# atom.project.registerOpener (uri) ->
# if path.extname(uri) is '.toml'
# return new TomlEditor(uri)
# ```
#
# opener - A {Function} to be called when a path is being opened.
# * `opener` A {Function} to be called when a path is being opened.
registerOpener: (opener) ->
@openers.push(opener)
@@ -251,6 +265,8 @@ class Workspace extends Model
# Public: Get the first pane {Pane} with an item for the given URI.
#
# * `uri` {String} uri
#
# Returns a {Pane} or `undefined` if no pane exists for the given URI.
paneForUri: (uri) ->
@paneContainer.paneForUri(uri)