(#!) Shebang

A Sublime Text 2 plugin for running scripts based on the path specified in their ‘shebang’ lines and presenting the output in a separate buffer. It has additional support for Python scripts using virtualenv and can be used from either the command palette or as part of a .sublime-build system.

Install

Automatically

1. Install the Package Control plugin
2. Within ST2, show the command palette with ⇧⌘P then select Package Control: Install Package
3. Select Shebang from the list to install it.

Manually

download the current version from the project page or clone the git repository to your Packages directory:

git clone https://github.com/samizdatco/sublime-text-shebang.git Shebang

Usage

The plugin adds five commands to the command palette. They can be run from either a source script or its counterpart output window.

• Run Script
  run the current file
  This command will be available when the file begins with a shebang line or if its name ends in .py. Output will appear in a separate window with one tab for each script run so far.

• Run Shell Command…
  run an arbitrary command line
  Prompts the user for a command to run then executes it. When invoked from a buffer containing a runnable script, the prompt will default to the invocation used by Run Script.

• Restart Script
  stop a running script then relaunch it
  Will appear when visiting the buffer for a script that is currently running. By default a confirmation dialog will be presented before relaunching the script, though this can be disabled in Shebang.sublime-settings.

• Terminate Script
  Stop the current script
  In addition to its appearance in the commands palette, this can also be invoked by typing ctrl-c in either the script’s view or its corresponding output buffer.

• Browse Stack Trace
  Jump to an error line
  After running a script that terminated abnormally, jump to any of the lines in the resulting stack trace (currently python-only).

Configuration

General preferences are stored in a file called Shebang.sublime-settings. To make modifications, copy the settings file from the Shebang folder into your Packages/User directory.

Within the file you can redefine default behaviors:

• confirm_terminate true
  Whether to pop up a confirmation dialogue before terminating or restarting a running script.

• save_on_run true
  Whether to save the current script buffer prior to running it.

• use_separate_window false
  Whether to group output buffers in a separate window or open them next to the source script’s tab.

• virtualenv null
  A path (or path fragment) in which a virtualenv python environment can be found. If the value is an absolute or home-relative path, Shebang will simply use the interpreter at that path.
  ​
  If the value is an unrooted name, the script’s directory and all parent directories will be traversed and a subdir matching the name will be searched for. Shebang will use the match ‘closest’ in the directory hierarchy to the script (or default to system python if none is found).

Build System Integration

Shebang can also be used within .sublime-build files. It provides a build command called execute which is a multi-process version of the exec command seen in Sublime’s stock build systems.

To create a custom build system, create a *.sublime-build file using the syntax defined in the documentation, but replacing "target":"exec" with "target":"execute".

In addition to the standard fields, Shebang supports some extensions:

• prompt controls whether the user can edit the command line before it is executed
• virtualenv if present will override the value in the .sublime-settings file
• cmd can usually be omitted. If it is included, the build command will not inspect the file for a shebang line and will always use the cmd invocation instead.

Here is an example which defines a virtualenv search pattern and allows for building with ⌘B from python or shebang output windows. The Run variant allows ⇧⌘B to bring up the command line editor before running.

Save this to your Packages/User directory as Virtualenv.sublime-build and it will appear in Sublime’s Tools > Build System menu:

{
  "selector": "source.python,text.shebang",
  "target":"execute",
  "virtualenv":"env",
  "variants":[
    { "name": "Run", "target":"execute", "prompt":true }
  ] 
}

Unix Only (for now)

Shebang currently works on Linux and OS X. There's nothing inherently blocking Windows support, but I'm out of my element on that OS and lack a deep understanding of the path structure (or the typical locations of interpreters). If anyone sees places where the code could be modified to be less unix-centric I'd love to hear about it.