Previous: Storing tools in files | Up: User-defined Tools | Next: Shell scripts

### Lua scripts

Lua scripts can use the standard Lua library, `lfs` library, and `medit` package which provides some text editor API. Lua scripts have the following variables and functions available.

- `doc`: a table with the following fields:

`file` | the document file path.
`name` | the document file basename.
`dir` | the document file directory.
`ext` | the document filename extension including the period.
`base` | the document filename without the extension: the basename is always `base..ext`.

- `Cut()`, `Copy()`, `Paste()`: clipboard operations.
- `Backspace()`, `Delete()`: corresponding key actions.
- `Up()`, `Down()`, `Left()`, `Right()`: move cursor as the arrow keys do.
- `Selection()`: returns selected text as a string. Returns `nil` when no text is selected.
- `Select(n)`: selects `n` characters to the right if `n` is positive, and `-n` characters to the left if it is negative.
- `Insert(...)`: inserts text at cursor. Namely, it converts each argument to a string and inserts the result into the document.
- `NewLine()`: inserts new line character.

  The following functions are provided for more advanced text manipulation. Position in the document is denoted by the character offset from the beginning of the document, starting from 1, so the first character is at position 1. Functions which take or return ranges use pairs of offsets, a pair `start`, `end` denotes range of text from `start` to `end`, not including the character at offset `end`. For instance, the single-character range consisting of the first character in the document corresponds to the pair `1, 2`. Non-positive offset denotes the end of the document.

- `InsertText(pos, ...)`: inserts text at the position `pos`.
- `DeleteText(start, end)`: deletes text in the range `[start..end)`.
- `GetInsert()`: returns position of the cursor in the document.
- `GetSelectionBounds()`: returns positions of the selection start and end. If no text is selected, returns pair `pos, pos` where `pos` is the cursor position.
- `GetLine([pos])`: returns line number of the character at the position `pos`. If `pos` is not specified, it defaults to the cursor position.
- `GetPosAtLine(n)`: returns position at the beginning of the `n`-th line.
- `LineStart([pos])`: returns the position of the beginning of the line which contains character at `pos`. If `pos` is not specified, it defaults to the cursor position.
- `LineEnd([pos])`: returns the position of the end of the line which contains character at `pos`. If `pos` is not specified, it defaults to the cursor position.
- `ForwardLine([pos, [n]])`: returns the position of the beginning of the next line (or `n`-th line if `n` is specified). `pos` defaults to the cursor position if not specified.
- `BackwardLine([pos, [n]])`: returns the position of the beginning of the previous line (or `n`-th line backwards if `n` is specified). `pos` defaults to the cursor position if not specified.
- `GetText(start, end)`: returns the text in the `[start..end)`. If `start == end`, it returns an empty string, not `nil`.

Previous: Storing tools in files | Up: User-defined Tools | Next: Shell scripts