Run sections are the essence of DevAssistant. They are responsible for performing all the tasks and actions to set up the environment and the project itself. For Creator and Preparer assistants, the section named run is always invoked, Modifier Assistants may invoke different sections based on metadata in a .devassistant file.
Note, that pre_run and post_run follow the same rules as run sections. See Assistants Invocation to find out how and when these sections are invoked.
Every section is a sequence of various commands, mostly invocations of commandline. Each command is a mapping of command type to command input:
run:
- command_runner: command_input
- command_runner_2: another_command_input
Note, that section is a general term used for any sequence of commands. Sections can have subsections (e.g. in conditions or loops), assuming they follow some rules (see below).
The list of all supported commands can be found at Command Reference, we only document the basic usage of the most important commands here. Note, that when you use variables (e.g. $variable) in command input, they get substituted for their values (undefined variables will remain unchanged).
command line invocation:
- cl: mkdir -p $spam
This will invoke a subshell and create a directory named $spam. If the command returns non-zero return code, DevAssistant will fail.
logging:
- log_i: Directory $spam created.
This command will log the given message at INFO level - either to terminal or GUI. You can use similar commands to log at different log levels: log_d for DEBUG, log_w for WARNING, log_e for ERROR and log_c for CRITICAL. By default, messages of level INFO and higher are logged. Log messages with levels ERROR and CRITICAL emit the message and then terminate execution of DevAssistant immediately.
conditions:
- if not $foo and $(ls /spam/spam/spam):
- log_i: This gets executed if the condition is satisfied.
- else:
- log_i: Else this section gets executed.
Conditions work as you’d expect in any programming language - if subsection gets executed if the condition evaluates to true, otherwise else subsection gets executed. The condition itself is an expression, see Expressions for detailed reference of expressions.
loops:
- for $i word_in $(ls):
- log_i: Found file $i.
Loops probably also work as you’d expect - they’ve got the control variable and an iterable. Loop iterators are expressions, see Expressions. Note, that you can use two forms of for loop. If you use word_in, DevAssistant will split the given expression on whitespace and then iterate over that, while if you use in, DevAssistant will iterate over single characters of the string.
variable assignment:
- $foo: "Some literal with value of "foo" variable: $foo"
This shows how to assign a literal value to a variable. It is also possible to assign the result of another command to a variable, see Section Results for how to use the execution flag.
Remember to check Command Reference for a comprehensive description of all commands.
DevAssistant distinguishes two different section types: input sections and execution sections. Some sections are inherently execution sections:
Generally, execution sections can be either:
or
Literal section can be any valid Yaml structure - string, list or mapping.
Similarly to expressions, sections return logical result and result:
Some examples follow:
run:
# now we're inherently in an execution section
- if $(ls /foo):
# now we're also in an execution section, e.g. the below sequence is executed
- foo:
# the input passed to "foo" command runner is inherently a literal input, e.g. not executed
# this means foo command runner will get a mapping with two key-value pairs as input, e.g.:
# {'some': 'string value', 'with': [ ... ]}
some: string value
with: [$list, $of, $substituted, $variables]
- $var: this string gets assigned to "var" with $substituted $variables
If you need to assign the result of an expression or execution section to a variable or pass it to a command runner, you need to use the execution flag: ~:
run:
- $foo~: ($this or $gets) and $executed_as_expression
- foo~:
# input of "foo" command runner will be result of the below execution section
- command_runner: literal_section
- command_runner_2~:
# similarly, input of command_runner_2 will be result of the below execution section
- cr: ci
- cr2: ci2
Note, that a string starting with the execution flag is also executed as an expression. If you want to create a literal that starts with ~, just use the escape value for it (~~):
run:
- $foo: ~$(ls) and $bar
- $bar: ~~/some_dir_in_users_home
- log_i: The tilde character (~) only needs to be escaped when starting a string.
Each command specifies its return value in a different way, see Command Reference.
Initially, variables are populated with values of arguments from the commandline/gui and there are no other variables defined for creator assistants. For modifier assistants global variables are prepopulated with some values read from .devassistant. You can either define (and assign to) your own variables or change the values of current ones.
Additionally, after each command, variables $LAST_RES and $LAST_LRES are populated with the result of the last command (these are also the return values of the command) - see Command Reference
The variable scope works as follows:
All variables are global in the sense that if you call a snippet or another section, it can see all the arguments that are defined.
When using variables that contain user input, they should always be quoted in the places where they are used for bash execution. That includes cl* commands, conditions that use bash return values and variable assignment that uses bash.
In all assistants, a few useful global variables are available. These include:
Note: if any of this information is not available, the corresponding variable will be empty. Also note, that you can rely on all the variables having lowercase content.
Expressions are used in assignments, conditions and as loop “iterables”. Every expression has a logical result (meaning success - True or failure - False) and result (meaning output). Logical result is used in conditions and variable assignments, result is used in variable assignments and loops. Note: when assigned to a variable, the logical result of an expression can be used in conditions as expected; the result is either True or False.
Syntax and semantics:
All these can be chained together, so, for instance, "1.8.1.4" in $(git --version) and defined $git is also a valid expression