medit/doc/user-tools.texi

@node User-defined tools
@chapter User-defined tools
@helpsection{USER_TOOLS}

@medit{} allows extending its functionality with user-defined
@dfn{tools}. It can be a Lua or Python (provided @medit{} has been
built with Python support) script which is 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.

@menu
* Managing tools:: Managing tools.
* Storing tools in files:: Storing tools in files.
@c  * Lua scripts:: Lua scripts.
* Shell scripts:: Shell scripts.
@end menu

@node Managing tools
@section Managing tools
@helpsection{USER_TOOLS_MANAGING}

To create a new tool or to modify existing ones, open
@uilabel{Preferences} dialog and select @uilabel{Tools} in the list on the left.

Select the tool in the list or click the @uilabel{New}
button to create a new one. To modify the order in which the tools
appear in the @uilabel{Tools} menu (or in the document
context menu), use @uilabel{Up} and @uilabel{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 @uilabel{Delete} button to delete a tool.

The following controls are available to modify the tools behavior:
@table @asis
@item @uilabel{Files}
Specifies for which files the tool is going to be available.
@item @uilabel{Options}
Specifies under which conditions the tool should be enabled.
@item @uilabel{Command type}
The type of the tool: a Python script, a Lua script, or a shell script.
@item @uilabel{Code} text field
Here you enter the actual script text.
@end table

@uilabel{Options} entry content is a comma-separated list of the following:
@table @var
@item need-doc
the tool needs an open document.
@item need-file
the tool will not work in new unsaved documents.
@item need-save
the document will be saved before the command is executed.
@item need-save-all
all open documents will be saved before the command is executed.
@end table

@uilabel{Files} entry content can be the following:
@itemize @bullet
@item
a comma-separated list of file patterns, e.g. "@code{*.c,*.h}";
@item
a comma-separated list of languages prefixed with "@code{langs:}", e.g. "@code{langs: c, c++, objc}";
@item
a regular expression matching document filename prefixed with "@code{regex:}", e.g. the above
pattern list may be written as "@code{regex:\.[ch]$}".
@end itemize

Empty entry means that the tool will be available for all documents.

Shell script tools also have the following controls available:

@uilabel{Input} entry specifies what text from the document should be passed to the command via its standard input:
@table @uilabel
@item None
no input text.
@item Selected lines
the lines containing selection or the line containing the cursor in case when no text is selected.
@item 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.
@item Whole document
whole document contents.
@end table

@uilabel{Output} entry specifies how the standard output of the command should be redirected.
@table @uilabel
@item None
the command output will be discarded.
@item None, asynchronous
the command output will be discarded, and the command will be executed in background.
For instance, you should use this if you need to launch some external program like a web browser.
@item 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.
@item 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.
@item New document
new document will be created and the command output will be inserted into it.
@end table

@uilabel{Filter} combo. If the output pane is used, then it can be passed through a @dfn{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.


@node Storing tools in files
@section Storing tools in files
@helpsection{USER_TOOLS_FILES}

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

Names of the files in the @file{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 @file{00-Do Something},
@file{01-Another tool} files to have them in that order in the menu. The files
may be of three types: files with extension "@file{.py}", they will be used
as Python scripts; files with extension "@file{.lua}", they will be used
as Lua scripts; and 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:
@example
!! @var{key}=@var{value}; @var{key}=@var{value}; ... !!
@end example

@var{key} may be one of the following:
@table @var
@item position
it can be ``start`` or ``end``, and defines whether the menu item will be located at the start or at the end of the menu.
@item id
the tool identificator.
@item name
the tool name, i.e. the label used in the menu item. Overrides the file name.
@item accel
default keyboard accelerator used to invoke this tool.
@item 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.
@item langs
comma-separated list of languages for which this tool will be enabled.
@item file-filter
defines for which files this tool will be enabled. The value has the same format as in the @uilabel{Preferences} dialog.
@item options
same as the @uilabel{Options} entry content in the @uilabel{Preferences} dialog.
@end table

In addition to these, you can set input and output options for executable files:
@table @var
@item input
can be @code{none}, @code{lines}, @code{selection}, or @code{doc}.
@item output
can be @code{none}, @code{async}, @code{pane}, @code{insert}, or @code{new-doc}.
@item filter
the output filter name.
@end table


@c  @node Lua scripts
@c  @section Lua scripts
@c
@c  Lua scripts can use the standard Lua library, ``lfs`` library, and ``medit`` package
@c  which provides some text editor API. Lua scripts have the following variables and functions available.
@c
@c  - ``doc``: a table with the following fields:
@c    | ``file``     | the document file path. |
@c    | ``name``     | the document file basename.
@c    | ``dir``      | the document file directory.
@c    | ``ext``      | the document filename extension including the period.
@c    | ``base``     | the document filename without the extension: the basename is always ``base..ext``.
@c  - ``Cut()``, ``Copy()``, ``Paste()``: clipboard operations.
@c  - ``Backspace()``, ``Delete()``: corresponding key actions.
@c  - ``Up()``, ``Down()``, ``Left()``, ``Right()``: move cursor as the arrow keys do.
@c  - ``Selection()``: returns selected text as a string. Returns ``nil`` when no text is selected.
@c  - ``Select(n)``: selects ``n`` characters to the right if ``n`` is positive, and ``-n`` characters to the left if it is negative.
@c  - ``Insert(...)``: inserts text at cursor. Namely, it converts each argument to a string and inserts the result into the document.
@c  - ``NewLine()``: inserts new line character.
@c
@c  The following functions are provided for more advanced text manipulation. Position in the
@c  document is denoted by the character offset from the beginning of the document, starting
@c  from 1, so the first character is at position 1. Functions which take or return ranges use pairs of
@c  offsets, a pair ``start``, ``end`` denotes range of text from
@c  ``start`` to ``end``, **not** including the character at offset ``end``. For instance, the
@c  single-character range consisting of the first character in the document corresponds to the
@c  pair ``1, 2``. Non-positive offset denotes the end of the document.
@c
@c  - ``InsertText(pos, ...)``: inserts text at the position ``pos``.
@c  - ``DeleteText(start, end)``: deletes text in the range ``[start..end)``.
@c  - ``GetInsert()``: returns position of the cursor in the document.
@c  - ``GetSelectionBounds()``: returns positions of the selection start and end. If no text is
@c    selected, returns pair ``pos, pos`` where ``pos`` is the cursor position.
@c  - ``GetLine([pos])``: returns line number of the character at the position ``pos``. If ``pos``
@c    is not specified, it defaults to the cursor position.
@c  - ``GetPosAtLine(n)``: returns position at the beginning of the ``n``-th line.
@c  - ``LineStart([pos])``: returns the position of the beginning of the line which contains character at ``pos``.
@c    If ``pos`` is not specified, it defaults to the cursor position.
@c  - ``LineEnd([pos])``: returns the position of the end of the line which contains character at ``pos``.
@c    If ``pos`` is not specified, it defaults to the cursor position.
@c  - ``ForwardLine([pos, [n]])``: returns the position of the beginning of the next line (or
@c    ``n``-th line if ``n`` is specified). ``pos`` defaults to the cursor position if not
@c    specified.
@c  - ``BackwardLine([pos, [n]])``: returns the position of the beginning of the previous line
@c    (or ``n``-th line backwards if ``n`` is specified). ``pos`` defaults to the cursor position
@c    if not specified.
@c  - ``GetText(start, end)``: returns the text in the ``[start..end)``. If ``start == end``, it
@c    returns an empty string, not ``nil``.


@node Shell scripts
@section Shell scripts
@helpsection{USER_TOOLS_SHELL_SCRIPTS}

In addition to the document text passed via standard input,
shell scripts have a number of environment variables set. @env{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 @code{@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:
@table @env
@item DOC
the document basename.
@item DOC_DIR
the document file directory. The full file path is @file{$DOC_DIR/$DOC}.
@item DOC_BASE
the basename without extension.
@item DOC_EXT
the document filename extension including the period. The basename is always @file{$DOC_BASE$DOC_EXT}.
@item LINE
the number of the line containing cursor.
@item DATA_DIR
the user data directory. For example the tools are stored in @file{$DATA_DIR/menu.cfg} file and in files in the @file{$DATA_DIR/tools/} directory.
@end table

Additionally, all processes ran from inside @medit{} will have @file{DATADIR/scripts}
directories in @code{$PATH}, so you may place some @medit{}-specific programs
or scripts into @file{USERDATADIR/scripts/} to be used from shell script tools.