External Tools

The External Tools plugin allows to invoke external applications with data related to the current document, for example its URL, directory, text or selection. Once enabled, a config page appears as depicted below that allows to change or remove existing tools. Similarly, new tools can be added to your liking. The tools will then appear in the External Tools submenu of the Tools menu of the application.

The config page allows to add new external tools by clicking on the Add button. In this case, a popup menu appears where one can either add a new external tool, add an existing tool from a predefined list, or add a new category to organize the external tools into categories. Similarly, the existing tools can be modified either by double-click or by invoking Edit..., and Remove removes the selected tools.

Configuring External Tools

Editing a tool opens a config dialog that allows fine-grained configuration of the tool:

As can be seen, many details can be defined, namely:

Name, the name of the tool, which will later appear in the menu.

Icon, optional icon that is visible in the menu.

Executable, executable including either a full path, or your executable must be in the PATH environment variable.

Arguments, optional arguments that are passed to the executable.

Input, optional input that is passed to the process via stdin.

Working directory, the working directory the tool will be started in. If empty, the working directory is set to the current document’s path.

Mime types, if set, the tool is active only if the current document’s mime type matches.

Save, when invoked, saves none, the current document, or all documents.

Trigger, a trigger to execute this tool. A trigger will only affect the currently active document and will only execute if the mimetype of current active document matches the mimetype of the external tool.

Following triggers are available:

None, this is the default, it means the tool has no trigger.

Before Save, this trigger will execute right before saving the document.

After Save, this trigger will execute the tool after the document was saved.

Reload current document after execution, useful when the current file is modified on disk.

Output, the output defines the target of stdout. It is either set to Ignored, Insert at Cursor Position, Replace Selected Text, Replace Current Document, Append to Current Document, Insert in New Document, Copy to Clipboard, or Display in Pane.

Editor command, optional command that can be used to invoke the external tool via the built-in command line.

The button Defaults is visible only for tools that are shipped with Kate. When clicked, all tool’s settings reverted to default (aka factory) values.

Variable Expansion

Some editing fields such as the Executable, the Arguments, the Input and the Working Directory support variables that are expanded on tool invocation. This is indicated by the icon {} that appears once one of these text input fields has focus (see red circle):

Hovering over one of these text input fields also shows a tooltip with the current expanded text. Further, clicking on the {} action will open a dialog that lists all available variables:

This feature provides a lot of flexibility when defining an external tool since all variables of the form %{...} are expanded when the tool gets invoked. There are two kind of variables supported:

%{variable-name}
%{variable-name:<value>}

The first form %{variable-name} simply replaces the variable with its contents. For instance, the variable %{Document:FileName} is replaced by the current document’s filename without its path. The second form %{variable-name:<value>} gets the <value> as contents. For example, this can be used to expand an environment variable with %{ENV:HOME}, or one can obtain the current date in the preferred format like %{Date:yyyy-MM-dd}.

Supported variables include:

Document:FileBaseName: File base name without path and suffix of the current document.

Document:FileExtension: File extension of the current document.

Document:FileName: File name without path of the current document.

Document:FilePath: Full path of the current document including the file name

Document:Text: Contents of the current document.

Document:Path: Full path of the current document excluding the file name.

Document:NativeFilePath: Full document path including file name, with native path separator (backslash on Windows).

Document:NativePath: Full document path excluding file name, with native path separator (backslash on Windows).

Document:Cursor:Line: Line number of the text cursor position in current document (starts with 0).

Document:Cursor:Column: Column number of the text cursor position in current document (starts with 0).

Document:Cursor:XPos: X component in global screen coordinates of the cursor position.

Document:Cursor:YPos: Y component in global screen coordinates of the cursor position.

Document:Selection:Text: Text selection of the current document.

Document:Selection:StartLine: Start line of selected text of the current document.

Document:Selection:StartColumn: Start column of selected text of the current document.

Document:Selection:EndLine: End line of selected text of the current document.

Document:Selection:EndColumn: End column of selected text of the current document.

Document:RowCount: Number of rows of the current document.

Document:Variable:<variable>: Expand arbitrary document variables.

Date:Locale: The current date in current locale format.

Date:ISO: The current date (ISO).

Date:<value>: The current date (QDate formatstring).

Time:Locale: The current time in current locale format.

Time:ISO: The current time (ISO).

Time:<value>: The current time (QTime formatstring).

ENV:<value>: Access to environment variables.

JS:<expression>: Evaluate simple JavaScript statements.

PercentEncoded:<text>: Percent encoded text.

UUID: Generate a new UUID.

List of Default Tools

Several tools are shipped by default. However, if you have more useful tools please contribute those to (kwrite-devel kde.org) so that we can add them to this list. All default tools are visible in the list view by default. However, all tools can be changed to your liking, including the category or even deleting tools. Deleted tools can be added back again by clicking on the Add button in the config page as described above.

git-cola

git-cola is a graphical git client that enables you to easily stage and commit changes. If installed, it is available also through the command line by typing git-cola

Name: git-cola

Icon: git-cola

Executable: git-cola

Arguments: -r %{Document:Path}

Editor command: git-cola

gitk

gitk is a git client as well that allows to nicely visualize the git history.

Name: gitk

Icon: git-gui

Executable: gitk

Working directory: %{Document:Path}

Editor command: gitk

git blame

Starts git blame to easily follow git changes in the current file.

Name: git blame

Executable: git

Arguments: gui blame %{Document:FileName}

Save: Current Document

Working directory: %{Document:Path}

Editor command: git-blame

Run Shell Script

Starts an external konsole in which the current document is executed. The script needs to state the interpreter in the first line via a shebang #!/path/interpreter.

Name: Run Shell Script

Icon: system-run

Executable: konsole

Arguments: -e sh -c "cd %{Document:Path} && pwd && chmod -vc a+x %{Document:FileName} && ./%{Document:FileName} ; echo Press any key to continue. && read -n 1"

Save: Current Document

Working directory: %{Document:Path}

Editor command: run-script

Google Selected Text

Search in google for the selected text.

Name: Google Selected Text

Icon: globe

Executable: xdg-open

Arguments: "https://www.google.com/search?q=%{Document:Selection:Text}"

Editor command: google

Insert UUID

Inserts a new UUID each time this action is invoked.

Name: Insert UUID

Executable: echo

Arguments: %{UUID}

Output: Insert at Cursor Position

Editor command: uuid

Clang Format Full File

Runs clang-format on the current file on disk. The document is reloaded afterwards.

Name: Clang Format Full File

Executable: clang-format

Arguments: -i %{Document:FileName}

Working directory: %{Document:Path}

Save: Current Document

Reload: Yes

Editor command: clang-format-file

Clang Format Selected Text

Runs clang-format just on the selected text in the current document.

Name: Clang Format Selected Text

Executable: clang-format

Arguments: -assume-fileName: %{Document:FileName}

Working directory: %{Document:Path}

Input: %{Document:Selection:Text}

Output: Replace Selected Text

Editor command: clang-format-selection

Qt Quick 2 Preview (qmlscene)

Previews the current qml file in qmlscene.

Name: Qt Quick 2 Preview (qmlscene)

Executable: qmlscene

Arguments: %{Document:FileName}

Save: Current Document

Working directory: %{Document:Path}

Editor command: qml-preview

JSON Format Full File

Format the entire JSON file.

Name: JSON Format Full File

Icon: application-json

Executable: jq

Arguments: %{Document:FileName}

Save: Current Document

Working directory: %{Document:Path}

Output: Replace Current Document

Editor command: json-format-file

XML Format Full File

Format the entire XML file.

Name: JSON Format Full File

Icon: application-xml

Executable: xmllint

Arguments: --format %{Document:FileName}

Save: Current Document

Working directory: %{Document:Path}

Output: Replace Current Document

Editor command: xml-format-file

http://docs.kde.org/
Prev	Working with Plugins	Next

Prev	Contents	Next
Working with Plugins	Working with Plugins	Backtrace Browser Plugin
http://docs.kde.org/