diff --git a/README.md b/README.md index 09752c2c..a83f2f49 100644 --- a/README.md +++ b/README.md @@ -134,13 +134,62 @@ There are also activity notifications for terminal tabs not in focus. ## Services -For plugin writers, the `x-terminal` package supports two services, `atom-xterm` and `platformioIDETerminal`, which +For plugin writers, the `x-terminal` package supports three services, `terminal`, `atom-xterm`, and `platformioIDETerminal`, which can be used to easily open terminals. These methods are provided using Atom's [services](http://flight-manual.atom.io/behind-atom/sections/interacting-with-other-packages-via-services/) API. To use a service, add a consumer method to consume the service, or rather a JavaScript object that provides methods to open terminals and run commands. +### 'terminal' service v1.0.0 + +The `terminal` service provides an object with `updateProcessEnv`, `run`, `getTerminalViews`, and `open` methods. + +As an example on how to use the provided `run()` method, your +`package.json` should have the following. + +```json +{ + "consumedServices": { + "terminal": { + "versions": { + "^1.0.0": "consumeTerminalService" + } + } + } +} +``` + +Your package's main module should then define a `consumeTerminalService` +method, for example. + +```js +import { Disposable } from 'atom' + +export default { + terminalService: null, + + consumeTerminalService (terminalService) { + this.terminalService = terminalService + return new Disposable(() => { + this.terminalService = null + }) + }, + + // . . . +} +``` + +Once the service is consumed, use the `run()` method that is provided +by the service, for example. + +```js +// Launch `somecommand --foo --bar --baz` in a terminal. +this.terminalService.run([ + 'somecommand --foo --bar --baz' +]) +``` + ### 'atom-xterm' service v2.0.0 The `atom-xterm` service provides the diff --git a/package.json b/package.json index d2d9e0ec..7fa59965 100644 --- a/package.json +++ b/package.json @@ -45,6 +45,12 @@ "versions": { "1.1.0": "providePlatformIOIDEService" } + }, + "terminal": { + "description": "Run commands and open terminals.", + "versions": { + "1.0.0": "provideTerminalService" + } } }, "dependencies": { diff --git a/spec/x-terminal-spec.js b/spec/x-terminal-spec.js index a06c8393..27ea10ed 100644 --- a/spec/x-terminal-spec.js +++ b/spec/x-terminal-spec.js @@ -268,3 +268,38 @@ describe('x-terminal', () => { }) }) }) + +describe('x-terminal services', () => { + beforeEach(async () => { + atom.packages.triggerDeferredActivationHooks() + atom.packages.triggerActivationHook('core:loaded-shell-environment') + await atom.packages.activatePackage('x-terminal') + }) + + it('terminal.run', async () => { + spyOn(xTerminalInstance, 'runCommands') + const service = await new Promise(resolve => { + atom.packages.serviceHub.consume('terminal', '^1.0.0', resolve) + }) + service.run(['test']) + expect(xTerminalInstance.runCommands).toHaveBeenCalledWith(['test']) + }) + + it('platformioIDETerminal.run', async () => { + spyOn(xTerminalInstance, 'runCommands') + const service = await new Promise(resolve => { + atom.packages.serviceHub.consume('platformioIDETerminal', '^1.1.0', resolve) + }) + service.run(['test']) + expect(xTerminalInstance.runCommands).toHaveBeenCalledWith(['test']) + }) + + it('atom-xterm.openTerminal', async () => { + spyOn(xTerminalInstance, 'openTerminal') + const service = await new Promise(resolve => { + atom.packages.serviceHub.consume('atom-xterm', '^2.0.0', resolve) + }) + service.openTerminal({}) + expect(xTerminalInstance.openTerminal).toHaveBeenCalledWith({}) + }) +}) diff --git a/src/x-terminal.js b/src/x-terminal.js index 2456dc04..3ec6b20f 100644 --- a/src/x-terminal.js +++ b/src/x-terminal.js @@ -593,6 +593,17 @@ class XTerminalSingleton { } } + /** + * Function providing service functions offered by 'terminal' service. + * + * @function + * @returns {Object} Object holding service functions. + */ + provideTerminalService () { + // for now it is the same as platformioIDETerminal service + return this.providePlatformIOIDEService() + } + close () { this.performOnActiveTerminal(t => t.exit()) } @@ -724,3 +735,7 @@ export function provideAtomXtermService () { export function providePlatformIOIDEService () { return XTerminalSingleton.instance.providePlatformIOIDEService() } + +export function provideTerminalService () { + return XTerminalSingleton.instance.provideTerminalService() +}