2.1. Managing tools

To create a new tool or to modify existing ones, open Preferences dialog and select Tools in the list on the left.

Select the tool in the list or click the New button to create a new one. To modify the order in which the tools appear in the Tools menu (or in the document context menu), use the Up and Down button. To rename a tool, click its name in the list to select it and then click again to edit the name. Use the Delete button to delete a tool.

The following controls are available to modify the tools behavior:

Files

Specifies for which files the tool is going to be available. The entry content can be the following:

  • a comma-separated list of file patterns, e.g. "*.c,*.h";

  • a comma-separated list of languages prefixed with "langs:", e.g. "langs: c, c++, objc";

  • a regular expression matching document filename prefixed with "regex:", e.g. the above pattern list may be written as "regex:\.[ch]$".

Empty entry means the tool will be available for all documents.

Options

Specifies under which conditions the tool should be enabled. It is a comma-separated list of the following:

  • need-doc: the tool needs an open document;

  • need-file: the tool will not work in new unsaved documents.

  • need-save: the document will be saved before the command is executed.

  • need-save-all: all open documents will be saved before the command is executed.

Command type

The type of the tool: a Python script, a Lua script, or a shell script.

Code text field

Here you enter the actual script text.

Shell script tools also have the following controls available:

Input

Specifies what text from the document should be passed to the command via its standard input:

None: no input text.

Selected lines: the lines containing selection or the line containing the cursor in case when no text is selected.

Selection: exact selected text. This will be different from "Selected lines" if selection does not span whole lines of the document, for instance if it is a single word.

Whole document: whole document contents.

Output

Specifies how the standard output of the command should be redirected.

None: the command output will be suppressed.

None, asynchronous: the command output will be suppressed, and the command will be executed in background. For instance, you should use this if you need to launch some external program like a web browser.

Output pane: the command output will be displayed in an output pane. This is useful for running programs like compilers, where you want to see the output.

Insert into the document: output will be inserted into the current document at the cursor position. It will replace the text used as an input, if any.

New document: new document will be created and the command output will be inserted into it.

Filter

If the output pane is used, then it can be passed through a filter: the filter can match filenames and line numbers, so when you click the text in the output pane it will open the corresponding file. This is used for compilers and similar commands, which output locations of errors in processed files.