%medit-defines; ]> &medit; allows extending its functionality with user-defined tools. It can be a Lua script or a Python script (if &medit; has been built with Python support) which are executed inside &medit;, or a shell script which can use the text of the open document as its input and/or output. There are some predefined tools which you can use as an example or to modify to suit your needs. 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 Up and Down buttons. 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. Options Specifies under which conditions the tool should be enabled. 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. Options entry content 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. Files 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 that the tool will be available for all documents. Shell script tools also have the following controls available: Input entry 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 entry specifies how the standard output of the command should be redirected. None the command output will be discarded. None, asynchronous the command output will be discarded, and the command will be executed in background. 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 combo. 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. 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 &medit-user-tools-dir; 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. 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 the 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 same as the Options entry content in the Preferences dialog. In addition to these, you can set input and output options for executable files: input none, lines, selection, or doc. output none, async, pane, insert, or new-doc. filter output filter name. In addition to the document text passed via standard input, shell scripts have a number of environment variables set. APP_PID variable is set to the current process process id, so that opening a file in the same instance of &medit; is as simple as medit filename (on the other hand, you will have to use command line options if you need to run a new &medit; instance). The following environment variables are set when scripts are executed: DOC document basename. DOC_DIR document directory. Full file path is $DOC_DIR/$DOC. DOC_BASE basename without extension. DOC_EXT document filename extension including the period. Basename is always $DOC_BASE$DOC_EXT. LINE the number of the line containing cursor. DATA_DIR user data directory (&medit-user-data-dir;). For example the tools are stored in $DATA_DIR/menu.cfg file and in files in the $DATA_DIR/tools/ directory. Additionally, all shell commands which run inside &medit; will have DATA_DIR/scripts directories in $PATH, so you may place some &medit;-specific programs or scripts into DATA_DIR/scripts/ to be used from shell script tools. Medit API for Lua scripts. Gtk API for Lua scripts. Medit API for Python scripts.