doc: klish plugin

docs/klish3.ru.md

@@ -1998,16 +1998,87 @@ push /view_name1
 Символ `prompt` помогает формировать текст приглашения для оператора. В теле
 элемента `ACTION` указывается текст приглашения, который может содержать
 подстановки вида `%s`, где "s" - это какой либо печатный символ. Вместо такой
-конструкции в текст подставляются полезные строки. Список реализованных
+конструкции в текст подставляется определенная строка. Список реализованных
 подстановок:
 
 * `%%` - сам символ `%`.
 * `%h` - имя хоста.
 * `%u` - имя текущего пользователя.
 
+```
+<ACTION sym="prompt">%u@%h&gt; </ACTION>
+```
+
 
 ## Плугин "script"
 
+Плугин "script" содержит всего один символ `script` и служит для выполнения
+скриптов. Скрипт содержится в теле элемента `ACTION`. Скрипт может быть написан
+на разных скриптовых языках программирования. По умолчанию считается, что скрипт
+написан для интерпретатора shell и запускается при помощи `/bin/sh`. Чтобы
+выбрать другой интерпретатор, используется "шебанг" (shebang). Шебанг - это
+текст вида `#!/path/to/binary`, находящийся в самой первой строке скрипта.
+Текст `/path/to/binary` - это путь, по которому находится интерпретатор скрипта.
+
+Плугин `script` входит в состав исходного кода проекта klish, а подключить
+плугин можно следующим образом:
+
+```
+<PLUGIN name="script"/>
+```
+
+Имя выполняемой команды и значения параметров передаются в скрипт с помощью
+переменных окружения. Поддерживаются следующие переменные окружения:
+
+* `KLISH_COMMAND` - имя выполняемой команды.
+* `KLISH_PARAM_<имя>` - значение параметра с именем `<имя>`.
+* `KLISH_PARAM_<имя>_<индекс>` - один параметр может иметь много значений, если
+для него задан атрибут `max` и значение этого атрибута больше единицы. Тогда
+значения можно получить по индексу.
+
+Примеры:
+
+```
+<COMMAND name="ls" help="List path">
+	<PARAM name="path" ptype="/STRING" help="Path"/>
+	<ACTION sym="script">
+	echo "$KLISH_COMMAND"
+	ls "$KLISH_PARAM_path"
+	</ACTION>
+</COMMAND>
+
+<COMMAND name="pytest" help="Test for Python script">
+	<ACTION sym="script">#!/usr/bin/python
+	import os
+	print('ENV', os.getenv("KLISH_COMMAND"))
+	</ACTION>
+</COMMAND>
+```
+
+Команда "ls" использует интерпретатор shell и выводит на экран список файлов по
+указанному в параметре "path" пути. Обратите внимание, что использование shell
+может быть небезопасно, из-за потенциальной возможности оператора внедрить в
+скрипт произвольный текст и, соответственно, выполнить произвольную команду.
+Использование shell доступно, но не рекомендуется. Очень сложно написать
+безопасный скрипт на shell.
+
+Команда "pytest" выполняет скрипт на языке Python. Обратите внимание на то, где
+определен шебанг. Первая строка скрипта - это строка, которая находится
+непосредственно за элементом `ACTION`. Строка, следующая за строкой, в которой
+объявлен `ACTION` считается уже второй и определять шебанг в ней нельзя.
 
 
 ## Плугин "lua"
+
+Плугин "lua" содержит всего один символ `lua` и служит для выполнения
+скриптов на языке "Lua". Скрипт содержится в теле элемента `ACTION`. В отличие
+от символа `script` из плугина ["script"](#плугин-script), символ `lua` не
+вызывает внешнюю программу-интерпретатор для выполнения скриптов, а использует
+внутренние механизмы для этого.
+
+Плугин `lua` входит в состав исходного кода проекта klish, а подключить
+плугин можно следующим образом:
+
+```
+<PLUGIN name="lua"/>
+```