Storing tools in files
Prev | Chapter 3. User-defined tools | Next

## Storing tools in files

It is possible to create tools without using the Preferences dialog, they can be stored in files in `tools` subfolder of the medit data folders (or `tools-context` for tools which appear in the document context menu). In particular, on Unix systems you can place files into `$HOME/.local/share/medit-1/tools/` folder.

Names of the files in the `tools` folder are used as their menu item labels, after stripping first three characters, so you can use trhee-character prefix to affect the order of the menu items, e.g. you can have `00-Do Something`, `01-Another tool` files to have them in that order in the menu. The files may be of three types:

- files with extension "`.py`", they will be used as Python scripts;
- files with extension "`.lua`", they will be used as Lua scripts;
- executable files, they will be executed in the same way as shell commands.

Note that files with `.py` and `.lua` extensions will be executed inside medit process; if you want to use them as regular scripts, then just remove the extension.

To set parameters for a tool, place them on the first or the second line of the file in the following format:

    !! key=value; key=value; ... !!

`key` may be one of the following:

`position` | it can be `start` or `end`, and it defines whether the menu item will be located at the start or at the end of the menu.
`id` | the tool identificator.
`name` | the tool name, i.e. the label used in the menu item. Overrides the file name.
`accel` | default keyboard accelerator used to invoke this tool.
`menu` | the menu to place this tool into. By default tools are located in the Tools menu, but they can be as well put into any other menu.
`langs` | comma-separated list of languages for which this tool will be enabled.
`file-filter` | defines for which files this tool will be enabled. The value has the same format as in the Preferences dialog.

`options`

this corresponds to Requires and Save controls in the Preferences dialog. It is a comma-separated list of the following:

`need-doc` | tool will be enabled only if there is an open document.
`need-file` | tool will be enabled only if current document is saved on disk (i.e. it is not "Untitled").
`need-save` | current document will be automatically saved before the command is executed.
`need-save-all` | all open documents will be automatically saved before the command is executed.

In addition to these, you can set input and output options for executable files (see the section called “Shell scripts” for the meaning of these options):

`input` | `none`, `lines`, `selection`, or `doc`.
`output` | `none`, `async`, `pane`, `insert`, or `new-doc`.
`filter` | output filter name.

Prev | Up | Next
Managing tools in Preferences dialog | Home | Shell scripts