External_Programs for Sublime Text 3

A plug-in for integration of external programs into Sublime Text 3, as text commands and window commands.

Program invocation is not interactive; if one needs to edit a command line on each invocation, wish to use an interpreter from Sublime Text or fully-featured options for program invocation, xe better use one of the three alternatives mentioned in Rationals.

• Summary
• Installation
• The external_program text command
• Rationals
• License

Summary

Provides external_program, a command to run an external program on, either:

• the current file;
• the file URI with/without character position/range fragment identifier;
• the current selection (or whole buffer if there is no selection);
• nothing.

Passes the data to the program via, either:

• a single argument;
• its standard input stream;
• a temporary file;
• nothing (makes sense when the argument is nothing).

Writes back the result from the program taken from its standard output (or the temporary file, if desired), either:

• inserted at the caret;
• as a replacement of the selected text (or whole buffer if there was no selection in the first place);
• to an output panel;
• to a Sublime Text phantom;
• to nothing.

“Selection” means single selection, not multiple selections. If there is no selection, the plugin takes the whole buffer, no matter it's saved to a file or not.

In case of errors, messages are written to the status bar. If the invoked program sent text to its standard error stream, it will be displayed in an errors output panel. Note: this is not where the plug-in writes its own error messages, including the program returned status code (when non-zero), which always go to the status bar.

Two commands are available from the command palette, to show the errors and output panel: “External Program: Show Errors” and “External Program: Show Output”.

External programs are executed asynchronously.

Installation

Either using Package Control, or manually using a source archive. For manual install in Packages/, the plug-in is to be installed as External_Programs, as using another name, would break file references.

The external_program text command

Integration of external program with simple invocation (no complex command line), mainly as text command.

A part of this command's documentation is in Summary.

Two helper commands are provided:

• external_program_show_errors;
• external_program_show_output.

Which are available from the command palette as:

• “External Program: Show Errors”;
• “External Program: Show Output”.

Creating a command

Example usage from a *.sublime-commands file:

{
    "caption": "Text: Format",
    "command": "external_program",
    "args": {
        "source": "selected_text",
        "through": "stdin",
      "executable": "format-text",
      // "executable": ["format-text", "--file", "$file"],
      "output": "stdout",
        "destination": "insert_replace",
        "panels": "reset"
    }
}

Main parameters and their options are shown in the below diagram:

"source"     -->     "through"      -->  "executable" (*) -->     "output"     -->  "destination"
---------------     -----------------       ----------------     ----------------     ----------------
"selected_text"          "stdin"              string|array         "stdout" (d)       "insert_replace"
 "file_name"        "single_argument"                            "temporary_file"      "output_panel"
  "file_uri"        "temporary_file"                                                     "phantom"
  "text_uri"

                                *: required
                                d: default

And the additional parameters:

• panels: [enum] reset (default) | accumulate;

Only executable parameter is required. If you omit a parameter that doesn't have a default value, that feature is not used.

If there won't be any arguments for the executable, it can be represented as string. Otherwise it can be an array which contains all the arguments (see the example above). Also if the executable parameter is an array, it may contain some special variables. These are the same variables that Sublime Text uses in its build system. See the list below:

If the command you're running starts a GUI application, then don't set the destination parameter. If the destination is set, then the plugin waits for the command's stdout and return code. This typically ends with a timeout error for a GUI application which is expected to run for a long time.

When the destination is insert_replace, modifying selections or the buffer aborts the command to display results (actual program is not aborted).

When panels is accumulate means new content to the output and errors panels, is appended to their previous content.

As for the through parameter, temporary_file option is useful when sending a selection string to a command which only accepts a file argument and doesn't support stdin. It saves the selection to a temporary file (located in the Packages folder) and then sends its path to the command as an argument. After the execution is completed, temporary file is deleted automatically. If you want to read the output from the same temporary file (instead of stdout), set the output parameter to temporary_file.

More on source:

• selected_text: the selected text where the selection is not a multiple selection; if there is no selection, whole buffer is used;
• file_name: the simple file name, that is, base name with extension (note the working directory is that of the file);
• file_uri: URI with the file: protocol and an absolute path, percent-encoded as necessary;
• text_uri: file URI with text position or range fragment identifier, after RFC 5147, using the char scheme only, where the selection is not a multiple selection (when no selection, this is the same as file_uri).

Settings

The command uses these settings:

• errors_panel_name, which defaults to errors;
• output_panel_name, which defaults to output;
• timeout_delay, which defaults to 3 (seconds, not milliseconds).

If a setting is not found, the above default values are used.

Changing the errors_panel_name and output_panel_name settings, actually requires a restart to apply (this may change in a future version).

Notes: to display a panel using a Sublime Text Command, the panel name must be prefixed with output. (also note the dot). Ex: output.output, for the output panel or output.errors for the errors panel. None of these two panels exists before something was to be written to it.

The panels are displayed using the color scheme after the corresponding Sublime Text preferences, and panels switch color scheme when this preference is changed.

Rationals

The program invocation is purposely simple. This plug-in provides what I believe should be part of the core of an editor, and that's not the purpose of an editor to be another shell or to provide command line edition features (that's the purpose of plug-ins). So there never will be more than single argument passing or (exclusive or) passing via standard input stream.

This plug-in is to invoke external specially crafted simple commands as external programs or wrapper scripts (which is a convenient tactic, as it allows the reuse of these commands from editor to editor, in a simple manner):

• If one needs to run a shell or interpreter from from Sublime Text, xe better use External REPL for this purpose.
• If one needs to run external commands interactively, or possibly long running process asynchronously, there is also: External Command.
• If one needs fully-featured options, xe better use Commando.

This package with the two firsts, may be installed together, as their features do not overlap (I'm personally using a patched version of External Command along to External_Programs). The third will supersede this one if one wants features which a purposely simple program invocation will never provides.

License

See LICENSE file.