Shell scripts
Prev | Chapter 3. User-defined tools | Next

## Shell scripts

Shell script user tools execute command entered in the Command text field using default user shell on Unix systems or cmd.exe on Windows.

Its input and output are specified by the following controls:

- `Input` entry specifies what text from the document should be passed to the command. The text is passed via command's standard input, except for `Document copy` case.

  `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.
  `Document copy` | document contents will be saved to a temporary file and the file path will be stored in `INPUT_FILE` environment variable. No text will be passed to the command via standard input.

- `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.

Shell script user tools have a number of environment variables set. `APP_PID` variable is set 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:

`APP_PID` | current process id.
`DOC` | document basename ("`file.c`" for file `/home/user/file.c`).
`DOC_DIR` | document directory ("`/home/user`" for file `/home/user/file.c`). Full file path is ``$DOC_DIR`/`$DOC``.
`DOC_BASE` | basename without extension ("`file`" for file `/home/user/file.c`).
`DOC_EXT` | document filename extension including the period ("`.c`" for file `/home/user/file.c`). Basename is always ``$DOC_BASE``$DOC_EXT``.
`DOC_PATH` | full document path.
`LINE` | `1`-based number of the line containing cursor. For example, if cursor is at the first line then `LINE` will be set to `1`.
`LINE0` | `0`-based number of the line containing cursor. For example, if cursor is at the first line then `LINE0` will be set to `0`.
`DATA_DIR` | user data directory (`$HOME/.local/share/medit/` on Unix systems).
`INPUT_FILE` | if `input` was set to "Document copy" then this is set to full path of the temporary file containing document text.

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.

Prev | Up | Next
Storing tools in files | Home | Lua scripts