doc

docs/klish3.ru.md

@@ -605,7 +605,7 @@ SEQ сам может быть элементом контейнера SWITCH.
 интерактивности для не-интерактивных действий.
 
 
-#### Атрибут `parmanent`
+#### Атрибут `permanent`
 
 Система klish может быть запущена в режиме "dry-run", когда все действия не
 будут в реальности выполняться, а их код возврата всегда будет иметь значение
@@ -648,14 +648,125 @@ SEQ сам может быть элементом контейнера SWITCH.
 определенный внутри плугина.
 
 
+#### Атрибут `update_retcode`
+
+В одной команде может содержаться несколько элементов `ACTION`. Это называется
+"блок действий". Каждое из действий имеет свой код
+возврата. Однако команда вцелом тоже должна иметь код возврата и этот код
+должен быть одним значением, а не массивом.
+
+По умолчанию действия `ACTION` выполняются последовательно и как только одно из
+действий вернет ошибку, выполнение блока останавливается и общим кодом возврата
+считается ошибка. Если ни одно действие из блока не вернуло ошибку, то кодом
+возврата считается код возврата последнего действия в блоке.
+
+Иногда требуется, чтобы в независимости от кода возврата определенного действия
+выполнение блока продолжилось. Для этого может использоваться атрибут
+`update_retcode`. Атрибут может принимать значение `true` или `false`. По
+умолчанию используется `true`. Это означает, что код возврата текущего действия
+влияет на общий код возврата. На этом этапе общему коду возврата будет присвоено
+значение текущего кода возврата. Если значение флага установлено в значение
+`false`, то текущий код возврата игнорируется и никак не будет влиять на
+формирование общего кода возврата. Также и выполнение блока действий не будет
+прервано в случае ошибки на этапе выполнения текущего действия.
+
+
 #### Атрибут `exec_on`
 
+При выполнении блока действий (несколько `ACTION` внутри одного элемента),
+действия выполняются последовательно, пока не будут выполнены все действия,
+либо пока одно из действий не вернет ошибку. В таком случае выполнение блока
+прерывается. Однако это поведение можно регулировать атрибутом `exec_on`.
+Атрибут может принимать следующие значения:
 
-#### Атрибут `update_retcode`
+* `success` - текущее действие будет отправлено на выполнение, если значение
+общего кода возврата на данный момент - "успех".
+* `fail` - текущее действие будет отправлено на выполнение, если значение
+общего кода возврата на данный момент - "ошибка".
+* `always` - текущее действие будет выполнено вне зависимости от общего кода
+возврата.
+* `never` - действие не будет выполняться ни при каких условиях.
+
+По умолчанию используется значение `success`, т.е. действия выполняются, если
+до этого не было ошибок.
+
+```
+<ACTION sym="printl">1</ACTION>
+<ACTION sym="printl" exec_on="never">2</ACTION>
+<ACTION sym="printl">3</ACTION>
+<ACTION sym="printl" exec_on="fail">4</ACTION>
+<ACTION sym="script">/bin/false</ACTION>
+<ACTION sym="printl">6</ACTION>
+<ACTION sym="printl" exec_on="fail" update_retcode="false">7</ACTION>
+<ACTION sym="printl" exec_on="always">8</ACTION>
+<ACTION sym="printl" exec_on="fail">9</ACTION>
+```
+
+Данный пример выведет на экран:
+
+```
+1
+3
+7
+8
+```
+
+Строка "1" выведется, потому что вначале выполнения блока действий общий код
+возврата принимается равным значению "успех", а так же значение `exec_on` по
+умолчанию равно `success`.
+
+Строка "2" не выведется, потому что `on_exec="never"`, т.е. не выполнять ни при
+каких условиях.
+
+Строка "3" выполнится, потому что предыдущее действие (строка "1") выполнилось
+успешно.
+
+Строка "4" не выполнится, потому что стоит условие `on_exec="fail"`, а при этом
+предыдущее действие "3" выполнилось успешно и установило общий код возврата в
+значение "успех".
+
+Строка "5" выполнится и переведет общий код возврата в значение "ошибка".
+
+Строка "6" не выполнится, потому что текущий общий код возврата равен значению
+"ошибка", а строка должна выполнится, только если общий код возврата успешен.
+
+Строка "7" выведется, так как стоит условие `on_exec="fail"`, текущий общий код
+возврата действительно равен "ошибке". Обратите внимание, что хотя само действие
+выполнится успешно, общий код возврата не будет изменен, так как использован
+атрибут `update_retcode="false"`.
+
+Строка "8" выведется, потому что стоит условие `on_exec="always"`, что означает
+выполнить действие вне зависимости от текущего общего кода возврата.
+
+Строка "9" не выведется, потому что строка "8" изменила общий код возврата на
+значение "успех".
 
 
 #### Данные внутри тега
 
+Данные внутри тега `ACTION` используются по усмотрению самого символа,
+указанного атрибутом `sym`. Как пример можно привести символ `script` из плугина
+`script`. Этот символ использует данные внутри тега, как код скрипта, который
+он должен выполнить.
+
+```
+<COMMAND name="ls" help="List root dir">
+	<ACTION sym="script">
+	ls /
+	</ACTION>
+</COMMAND>
+
+<COMMAND name="pytest" help="Test for Phyton script">
+	<ACTION sym="script">#!/usr/bin/python
+	import os
+	print('ENV', os.getenv("KLISH_COMMAND"))
+	</ACTION>
+</COMMAND>
+```
+
+Обратите внимание, что в команде "pytest" указан шебанг `#!/usr/bin/python`,
+который указывает с помощью какого интерпретатора нужно выполнять скрипт.
+
 
 ### ENTRY