doc

docs/klish3.ru.md

@@ -939,9 +939,154 @@ SEQ сам может быть элементом контейнера SWITCH.
 
 #### Атрибут `container`
 
+"Контейнером" в терминах klish является элемент, который содержит другие
+элементы, но сам не является видимым для оператора. Т.е. этот элемент не
+сопоставляется никаким позиционным параметрам при разборе введенной командной
+строки. Он только лишь организует другие элементы. Примером контейнеров являются
+`VIEW`, `SWITCH`, `SEQ`. Тег `VIEW` организует команды в области видимости, но
+сам элемент не является для оператора командой или параметром. Оператор не может
+ввести в командной строке имя этого элемента, он может обратиться сразу к
+вложенным в контейнер элементам (если они сами не являются контейнерами).
+
+Элементы `SWITCH` и `SEQ` также не видны оператору. Они определяют, как должны
+обрабатываться вложенные в них элементы.
+
+Атрибут `container` может принимать значения `true` или `false`. По умолчанию
+используется `false`, т.е. элемент не является контейнером. При этом надо
+заметить, что для всех элементов - обёрток, наследованных от `ENTRY`, значение
+атрибута заранее прописано в правильное значение. Т.е. использовать атрибут в
+реальных конфигах обычно не приходится. Только в специфических случаях он
+реально требуется.
+
 
 #### Атрибут `mode`
 
+Атрибут `mode` определяет то, как будут обрабатываться вложенные элементы при
+разборе введенной командной строки. Возможные значения:
+
+* `sequence` - вложенные элементы будут сопоставляться введенным оператором
+"словам" последовательно, один за другим. Таким образом все вложенные элементы
+могут принять значения при разборе.
+* `switch` - только один из вложенных элементов должен быть сопоставлен вводу от
+оператора. Это выбор одного из многих. Элементы, которые не были выбраны не
+получат значений.
+* `empty` - элемент не может иметь вложенных элементов.
+
+Так элемент `VIEW` принудительно имеет атрибут `mode="switch"`, предполагая, что
+он содержит внутри себя команды и не должно быть возможности в одной строке
+ввести сразу много команд друг за другом. Оператор выбирает в данный момент
+только одну команду.
+
+Элементы `COMMAND` и `PARAM` по умолчанию имеют настройку `mode="sequence"`, так
+как чаще всего внутри них размещены параметры, которые должны быть введены один
+за другим. Однако есть возможность переопределить атрибут `mode` в тегах
+`COMMAND`, `PARAM`.
+
+Элементы `SEQ` и `SWITCH` являются контейнерами и созданы только для того, чтобы
+менять способ обработки вложенных элементов. Элемент `SEQ` имеет
+`mode="sequence"`, элемент `SWITCH` имеет `mode="switch"`.
+
+Далее приведены примеры ветвлений внутри команды:
+
+```
+<!-- Example 1 -->
+<COMMAND name="cmd1">
+	<PARAM name="param1" ptype="/INT"/>
+	<PARAM name="param2" ptype="/STRING"/>
+</COMMAND>
+```
+
+Команда по умолчанию имеет `mod="sequence"`, поэтому оператор должен будет ввести
+оба параметра, один за другим.
+
+```
+<!-- Example 2 -->
+<COMMAND name="cmd2" mode="switch">
+	<PARAM name="param1" ptype="/INT"/>
+	<PARAM name="param2" ptype="/STRING"/>
+</COMMAND>
+```
+
+Значение атрибута `mode` переопределено, поэтому оператор должен будет ввести
+только один из параметров. Какому из параметров соответствуют введенные символы
+в данном случае будет определяться следующим образом. Сначала проверяется на
+корректность первый параметр "param1". Если строка соответствует формату целого
+числа, то параметр принимает свое значение и второй параметр не проверяется на
+соответствие, хотя он бы тоже подошел, так как тип `STRING` может содержать и
+числа. Таким образом при выборе одного параметра из многих, порядок указания
+параметров важен.
+
+```
+<!-- Example 3 -->
+<COMMAND name="cmd3">
+	<SWITCH>
+		<PARAM name="param1" ptype="/INT"/>
+		<PARAM name="param2" ptype="/STRING"/>
+	</SWITCH>
+</COMMAND>
+```
+
+Данный пример идентичен примеру "2". Только вместо атрибута `mode` используется
+вложенный тег `SWITCH`. Запись в примере "2" - короче, в примере "3" - нагляднее.
+
+```
+<!-- Example 4 -->
+<COMMAND name="cmd4">
+	<SWITCH>
+		<PARAM name="param1" ptype="/INT">
+			<PARAM name="param3" ptype="/STRING">
+			<PARAM name="param4" ptype="/STRING">
+		</PARAM>
+		<PARAM name="param2" ptype="/STRING"/>
+	</SWITCH>
+	<PARAM name="param5" ptype="/STRING"/>
+</COMMAND>
+```
+
+Тут демонстрируется, как идет разбор аргументов командной строки. Если выбран
+параметр "param1", то далее используются его вложенные элементы "param3" и
+"param4", а затем только следующий за `SWITCH` элемент "param5". Параметр
+"param2" никак не используется.
+
+Если вначале был выбран "param2", то затем обрабатывается "param5" и на этом
+процесс завершается.
+
+```
+<!-- Example 5 -->
+<COMMAND name="cmd5">
+	<SWITCH>
+		<SEQ>
+			<PARAM name="param1" ptype="/INT">
+			<PARAM name="param3" ptype="/STRING">
+			<PARAM name="param4" ptype="/STRING">
+		</SEQ>
+		<PARAM name="param2" ptype="/STRING"/>
+	</SWITCH>
+	<PARAM name="param5" ptype="/STRING"/>
+</COMMAND>
+```
+
+Пример полностью аналогичен поведению примера "4". Только вместо вложенности
+используется тег `SEQ`, который говорит, что если уж был выбран первый параметр
+из блока последовательных параметров, то остальные тоже необходимо ввести один
+за другим.
+
+```
+<!-- Example 6 -->
+<COMMAND name="cmd6">
+	<COMMAND name="cmd6_1">
+		<PARAM name="param3" ptype="/STRING">
+	</COMMAND>
+	<PARAM name="param1" ptype="/INT"/>
+	<PARAM name="param2" ptype="/STRING"/>
+</COMMAND>
+```
+
+Пример демонстрирует вложенную "подкоманду" с именем "cmd1_6". Тут подкоманда
+ничем не отличается от параметра, кроме того, что критерий сопоставления
+аргументов командной строки команде `COMMAND` состоит в том, чтобы введенный
+аргумент совпадал с именем команды.
+
 
 #### Атрибут `purpose`