doc: klish plugin

docs/klish3.ru.md

@@ -1831,36 +1831,181 @@ SEQ сам может быть элементом контейнера SWITCH.
 
 ## Плугин "klish"
 
+В состав дерева исходных кодов klish входит код стандартного плугина "klish".
+Плугин содержит базовые типы данных, команду навигации и другие вспомогательные
+символы. В подавляющем большинстве случаев этот плугин нужно использовать.
+Однако он не подключается автоматически, т.к. в каких-то редких специфических
+случаях может понадобиться возможность работать без него.
+
+Стандартный способ подключить плугин "klish" в конфигурационных файлах:
+
+```
+<PLUGIN name="klish"/>
+```
+
+Вместе с плугином идет файл `ptypes.xml`, где объявлены базовые типы данных в
+виде элементов [`PTYPE`](#ptype). Объявленные типы данных используют символы
+плугина для проверки соответствия аргумента типу данных.
+
 
 ### Типы данных
 
+Все символы раздела предназначены для использования в элементах `PTYPE`, если
+не указано иное, и проверяют соответствие введенного аргумента типу данных.
+
+
 #### Символ `COMMAND`
 
+Символ `COMMAND` проверяет, что введенный аргумент совпадает с именем команды.
+Т.е. с атрибутами `name` или `value` элементов `COMMAND` или `PARAM`. Если
+атрибут `value` задан, то используется его значение в качестве имени команды.
+Если не задан, то используется значение атрибута `name`. Регистр символов в
+названии команды не учитывается.
+
+
 #### Символ `completion_COMMAND`
 
+Символ `completion_COMMAND` предназначен для элемента `COMPL`, вложенного в
+`PTYPE`. Символ используется, чтобы сформировать строку автодополнения для
+команды. Автодополнением для команды является название самой команды. Если
+атрибут `value` задан, то используется его значение в качестве имени команды.
+Если не задан, то используется значение атрибута `name`.
+
+
 #### Символ `help_COMMAND`
 
+Символ `help_COMMAND` предназначен для элемента `HELP`, вложенного в
+`PTYPE`. Символ используется, чтобы сформировать строку описания (помощи) для
+команды. Если атрибут `value` задан, то используется его значение в качестве
+имени команды. Если не задан, то используется значение атрибута `name`. В
+качестве самой подсказки используется значение атрибута `help` команды.
+
+
 #### Символ `COMMAND_CASE`
 
+Символ `COMMAND_CASE` полностью аналогичен символу [`COMMAND`](#символ-command),
+кроме того, что он учитывает регистр символов в названии команды.
+
+
 #### Символ `INT`
 
+Символ `INT` проверяет, что введенный аргумент является целым числом.
+Разрядность числа соответствует типу `long long int` в языке C.
+Внутри элемента [`ACTION`](#action) может быть определен допустимый диапазон для
+целого числа. Указывается минимальное и максимальное значения, разделенные
+пробелом.
+
+```
+<ACTION sym="INT">-30 80</ACTION>
+```
+
+Число может принимать значения в диапазоне от "-30" до "80".
+
+
 #### Символ `UINT`
 
+Символ `UINT` проверяет, что введенный аргумент является беззнаковым целым
+числом. Разрядность числа соответствует типу `unsigned long long int` в языке C.
+Внутри элемента [`ACTION`](#action) может быть определен допустимый диапазон для
+числа. Указывается минимальное и максимальное значения, разделенные пробелом.
+
+```
+<ACTION sym="UINT">30 80</ACTION>
+```
+
+Число может принимать значения в диапазоне от "30" до "80".
+
+
 #### Символ `STRING`
 
+Символ `STRING` проверяет, что введенный аргумент является строкой. Сейчас нет
+никаких специфических требований к строкам.
+
+
 ### Навигация
 
+С помощью команд навигации оператор меняет текущий путь сессии.
+
+
 #### Символ `nav`
 
+Символ `nav` предназначен для навигации. С помощью подкоманд символа `nav` можно
+менять текущий путь сессии. Все подкоманды символа `nav` указываются внутри
+элемента `ACTION` - каждая команда на отдельной строке.
+
+Подкоманды символа `nav`:
+
+* `push <view>` - войти в указанный `VIEW`. К текущему пути сессии добавляется
+еще один уровень вложенности.
+* `pop [num]` - выйти на указанное число уровней вложенности. Т.е. исключить из
+текущего пути сессии `num` верхних уровней. Аргумент `num` является
+опциональным. По умолчанию `num=1`. Если мы уже находимся в корневом `VIEW`, т.е.
+текущий путь содержит только один уровень, то `pop` завершит сессию и выйдет из
+klish.
+* `top` - перейти в корневой уровень текущего пути сессии. Т.е. выйти из всех
+вложенных `VIEW`.
+* `replace <view>` - заменить `VIEW`, находящийся на текущем уровне вложенности
+на указанный `VIEW`. Количество уровней вложенности не увеличивается. Меняется
+только самый последний компонент пути.
+* `exit` - закончить сессию и выйти из klish.
+
+```
+<ACTION sym="nav">
+pop
+push /view_name1
+</ACTION>
+```
+
+Пример показывает как можно повторить подкоманду `replace`, использую другие
+подкоманды.
+
+
 ### Вспомогательные функции
 
+
 #### Символ `nop`
-#### Символ `tsym`
+
+Пустая команда. Символ ничего не делает. Всегда возвращает значение
+`0` - "успех".
+
+
 #### Символ `print`
+
+Печатает текст, указанный в теле элемента `ACTION`. В конце текста перевод
+строки не выводится.
+
+```
+<ACTION sym="print">Text to print</ACTION>
+```
+
+
 #### Символ `printl`
+
+Печатает текст, указанный в теле элемента `ACTION`. В конце текста добавляется
+перевод строки.
+
+```
+<ACTION sym="printl">Text to print</ACTION>
+```
+
 #### Символ `pwd`
+
+Печатает текущий путь сессии. Нужен в основном для отладки.
+
+
 #### Символ `prompt`
 
+Символ `prompt` помогает формировать текст приглашения для оператора. В теле
+элемента `ACTION` указывается текст приглашения, который может содержать
+подстановки вида `%s`, где "s" - это какой либо печатный символ. Вместо такой
+конструкции в текст подставляются полезные строки. Список реализованных
+подстановок:
+
+* `%%` - сам символ `%`.
+* `%h` - имя хоста.
+* `%u` - имя текущего пользователя.
+
+
 ## Плугин "script"