quick-spawn

Under Development

Contributions are welcome.

Requirements

• Atom ≥ 1.10.0

Installation

Using APM

apm install quick-spawn

Using Git + APM + NPM

git clone -b latest https://github.com/ksxatompackages/quick-spawn.git quick-spawn
cd quick-spawn
apm link $(pwd)

Using Git + NPM

Clone directly - Linux, macOS

git clone -b latest https://github.com/ksxatompackages/quick-spawn.git ~/.atom/packages/quick-spawn
cd ~/.atom/packages/quick-spawn
npm install

Clone directly - Windows

git clone -b latest https://github.com/ksxatompackages/quick-spawn.git %USERPROFILE%\.atom\packages\quick-spawn
cd %USERPROFILE%\.atom\packages\quick-spawn
npm install

Clone and Link - Linux, macOS

git clone -b latest https://github.com/ksxatompackages/quick-spawn.git quick-spawn
cd quick-spawn
npm install
ln $(pwd) ~/.atom/quick-spawn

Clone and Link - Windows

git clone -b latest https://github.com/ksxatompackages/quick-spawn.git quick-spawn
cd quick-spawn
npm install
mklink /J %USERPROFILE%\.atom\packages\quick-spawn %CD%

Usage

DISCLAIMER: This package is designed to provide a powerful and stable APIs and DOM UI, so you can create simple iteractive terminal by hacking Atom. The mean point of this package is not the basic one but the advanced one. For this reason, we do not intend to provide full features for basic usage, our intention mainly focus in advanced user experience.

Basic Use

Basic use is a behaviour that is turned on by default, you can tweak it in Settings (Shortcut: Ctrl+,) or by editing config.cson (Command Palette: Application: Open Your Config). If you feel you need more, go check advanced.

Tweak in Settings

You can't do much in Settings, to do more, checkout config.cson.

• Basic Use: Enabled (Checkbox): Whether basic feature is enabled, default to on.

• Basic Use: Executable Path (Text Input): Which program will be executed if you command, default to bash (Checkout MSYS2 or just install Git to get bash for Windows).

• Basic Use: Working Directory (Select List): Either activated-project-directory, activated-file-container, or executable-container. Default to activated-project-directory.

• Basic Use: Hide Stdin (Checkbox): Whether typed input should be hidden, default to on.

• Basic Use: Hide Stdout (Checkbox): Whether stdout data should be hidden, default to on.

• Basic Use: Hide StdErr (Checkbox): Whether stderr data should be hidden, default to on.

• Basic Use: Service Type (Select List): Either temporary, background or suspended-background. Default to temporary.

• Basic Use: UI Type (Select List): Either tab, panel, dialog, hidden or detached. Default to tab.

• Basic Use: External Terminal (Text Box): Which terminal would be open if UI Type is detached.

• Basic Use: Detached Text Box (Select List): Either none, mini-editor, editor, editor-tab. Default to none.

• Basic Use: Atom Command (Text Input): Register a command that is callable from Command-Palette, default to quick-spawn:basic-use, which would be shown to you as Quick Spawn: Basic Use.

• Basic Use: Keybinding (Text Input): Register a Keyboard Shortcut for Basic Use.

Tweak by Opening config.cson

See also: http://flight-manual.atom.io/using-atom/sections/basic-customization/

1. The following fields are tweakable by opening Settings, so let move on!

• basic-use:enabled (boolean)

• basic-use:executable-path (string)

• basic-use:working-directory (string enum)

• basic-use:hide-stdin (boolean)

• basic-use:hide-stdout (boolean)

• basic-use:hide-stderr (boolean)

• basic-use:service-type (string enum)

• basic-use:ui-type (string enum)

• basic-use:external-terminal (string)

• basic-use:detached-text-box (string enum)

• basic-use:atom-command (string)

• basic-use:keybinding (string)

2. The following fields are little more advanced

• basic-use:command-line-arguments (array of string)

  • List of arguments which is passed when spawn the process

• basic-use:io-file (object)

  • Key: stdin, stdout, and stderr
  • Value: A valid file path

• basic-use:io-pipe (object)

  • Key: stdin, stdout, and stderr
  • Value: A valid path to an executable file

• global:environment-variable (object)

  • Key: Variable name
  • Value: Variable value. Either a string; or an object (called descriptor) which contains middle (optional string array property - if undefined, use Atom's environment variable with the same name), before (optional string array property), after (optional string array property), and delimeter (optional character property, default to :).

Advanced Use

Prerequisite

The following section is filled with full of JavaScript, so in order to understand the tutorial, you better know JavaScript. However, if you don't know JavaScript yet, don't worry, you can still exploit some of its advantages, just copy-paste it (see below).

Overview

This package provides a strong JavaScript APIs and customizable UI for user to create a simple console (a.k.a. shell, terminal) by hacking Atom.

In a nutshell, hacking Atom is any of the following:

• Modifying your Atom's Init File (i.e. init.coffee or init.js)
• Creating an Atom package. P.S. We always thank whoever try to create a plugin for this package.
• Open Atom's DevTools (It's actually Google Chrome's DevTools) and have fun with some JavaScript commands.

All code snippets of the following tutorials are writen in JavaScript to make it easy for non-Coffee JavaScript users. It won't be such a pain for Coffee enthusiasts because they must know JavaScript as well as their flavour. But it might be somehow difficult for non-JS users, so please do one of the following if you just want a copy-paste:

• Remove init.coffee, create an empty init.js, then write things in it.
• Create a whatever.js file to write things in, then add require 'whatever.js' to your init.coffee.
• Create a simple Atom package in JavaScript so you can paste any JS code in.

Examples

Prerequisite: Import the Package as a NodeJS module

const quickSpawnAPIs = require(global.atom.packages.resolvePackagePath('quick-spawn'))

Simple Resigtration

Register exactly one atom-command for exactly one spawn-subscription

Get full example init.js

quickSpawnAPIs.registerSingleSubscription({
  execCmd: () => 'bash',
  workingDirectory: () => global.atom.workspace.getActivePaneItem().getDirectoryPath(),
  attached: false,
  suspended: true,
  viewStdIO: ['stdin', 'stdout', 'stderr'],
  atomCmd: 'quick-spawn-advanced:bash-simple',
  atomKeybinding: 'ctrl-shift-b a',
  atomTarget: 'atom-workspace',
  type: 'tab',
  exitOnClose: true,
  closeOnExit: true,
  detachedTextBox: 'none'
})

Shareable Resigtration

Register multiple atom-commands with different configurations with one shared spawn-subscription

Get full example init.js

quickSpawnAPIs
  .registerSpawnCommand({
    execCmd: () => 'bash',
    workingDirectory: () => global.atom.workspace.getActivePaneItem().getDirectoryPath(),
    attached: false,
    suspended: true
  })
  .registerAtomCommand({
    viewStdIO: ['stdin', 'stdout', 'stderr'],
    atomCmd: 'quick-spawn-advanced:bash-shareable',
    atomKeybinding: 'ctrl-shift-b b',
    atomTarget: 'atom-workspace',
    type: 'tab',
    oncreated: view => {
      const spawnSubscription = view.getSpawnSubscription()
      view.on('show', () => console.log('show', view))
      view.on('hide', () => console.log('hide', view))
      view.on('hide', () => spawnSubscription.destroy())
      view.on('destroy', () => console.log('destroy', view))
      spawnSubscription.on('exit', code => {
        console.log(`${spawnSubscription.execCommand} exited with code ${code}`)
        view.destroy() // optional though
      })
    }
  })

Documentation

latest

v0.0.1

License

MIT