Differences

This shows you the differences between two versions of the page.

--- guides:reference:templates:conditionals [2019/12/23 09:43] – ↷ Page moved from menu:build:templates:conditionals to guides:reference:templates:conditionals yspeerte
+++ guides:reference:templates:conditionals [2024/07/03 12:31] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
+{{indexmenu_n>3}}
+====== Conditionals ======
+Frequently parameter substitution in the templates require the conditional inclusion of the command line. Various forms of conditionals are supported by the YCE syntax. In its basic form the condition is stated between two vertical bars ''|<condition>|'' preceding the command line.
+Please note that in case of setting a login banner containing the vertical bar using a template, the following will be parsed as a condition and therefore not result in the envisioned banner.
+This template line
+<code>
+banner motd d |------- Warning: THIS IS A PRIVATE COMPUTER SYSTEM -------| d
+</code>
+Will result into this
+<code>
+banner motd d  d
+</code>
+However, by protecting the bars with a backslash will result in the desired command:
+<code>
+banner motd d \|------- Warning: THIS IS A PRIVATE COMPUTER SYSTEM -------\| d
+</code>
+===== Substitution condition =====
+<code>
+|<parameter>| template line
+|’value’| template line
+|’’| template line
+|[Function()]| template line
+</code>
+This tests the for a value of ''<parameter>''. In case the parameter is not blank (empty string), then the configuration line is parsed and inserted. If the parameter is empty (‘’) then the template line is skipped. In case the parameter does not exist in the current context, then an error message is generated.
+<code>
+|!<parameter>| template line
+|!’value’| template line
+</code>
+This form reverses the behavior: if the parameter is empty, the line is included. When it turns out it doesn’t exist, an error message will appear.
+In all cases the ''template line'' can include parameters from default or named contexts. It is quite common to test for a value before including the line based on that value:
+<code>
+|<local_user>| username <local_user> secret 0 <local_passwd>
+</code>
+===== Compare condition =====
+<code>
+|<parameter> = ‘value’| template line
+|<parameter> = <parameter2>| template line
+|<parameter> = ’’| template line
+|[Function()] = ...| template line
+</code>
+These compare the value of ''<parameter>'' with the mentioned values and then add the template line conditionally. The comparison is always made between the strings, even in case of numeric values. The results are analog to the conditional substitution.
+Also here it is possible to have ‘not equal to’. The negation ''!'' can can be placed at the start of the condition or being contracted with the ''=''.  Both forms behave equally.
+<code>
+|<parameter> != ‘value’| template line
+| ! <parameter> = value| template line
+</code>
+Quotes are optional for fixed values, but is recommended to use them. Actually the ''<'' ''>'' around parameters are also optional, although this form is strongly recommended. In many cases, the correct interpretation is given to the forms with or without quotes and/or brackets. See the examples:
+<code>
+|<hostname>| results in this line
+|'hostname'| results in this line
+|<hostname> = <hostname>| results in this line, interpretation is unambiguous
+|<hostname> = hostname| no results
+|<hostname> = 'hostname'| no results, interpretation is unambiguous
+</code>
+<code>
+|<hostname> = 'hvs-rn06001'| results in this line, it’s the real hostname
+|<hostname> = hvs-rn06001| results in this line, interpretation is correct, but ambiguous
+|hvs-rn06001 = hostname| no results, actually not correct
+|hvs-rn06001 = <hostname>| also no results, incorrect
+|'hvs-rn06001' = <hostname>| results in this line interpretatie is unambiguous
+</code>
+===== Multiple comparison =====
+<code>
+|<parameter> = (‘value1’,’value2’,...,'valueN')| template line
+|<parameter> = (<parameter2>,<parameter3>,...,'valueN')| template line
+</code>
+To prevent the same conditional template line to be used for a multiple number of values of a parameter, the values can be specified as a list. The brackets are optional. Also negations (''!'' and ''!='') are possible.
+===== Evaluation =====
+The all round ''[Eval()]'' function is very much suited for numeric comparisons and substring conditions. See  [[guides:reference:templates:functions#eval|Eval]] function for more details.
+===== Multiple comparison with context =====
+<code>
+|<parameter@context>| template line
+|<parameter@context> = <parameter2>| template line
+|<parameter@context> = ‘value’| template line
+</code>
+This generates a conditional line for all values of the context. This is mainly useful in the ''='' equation to use the corresponding index(es) of the context for the template line.
+<code>
+|<parameter@context> = (‘value1’,’value2’,...)| template line
+|<parameter1@context> = <parameter2@context>| template line
+</code>
+This equation has on both sides of the ''='' sign multiple values that are compared with each other. For every match (non case sensitive string comparisons) a template line is generated. The line shall use the same indexes in the context while substituting parameters as used for the conditions.
+<code>
+|<parameter> = (<parameter2@context>)| template line
+</code>
+===== AND conditionals =====
+It is possible to create an ''**AND**'' construction with the conditionals.
+By using:
+<code>
+|<valueA> = 'test'||<valueB> = 'address'|cli command
+</code>
+The cli command will only be executed when //Conditional A// **AND** //Conditional B// are true. \\
+Likewise:
+<code>
+|<valueA> = 'test'| command one |<valueB> = 'address'| command two
+</code>
+will only result in any output when both conditionals are true. When one of the conditionals fails, none of commands will be executed.
+===== Repeat and Else condition =====
+The result of the last conditional can be reused by testing on an empty condition (''||''). When combined with the negation (''!'') the last conditional result can be used to create an "ELSE" conditional: ''|!|'':
+<code>
+|<site_type> = 'retail' | {retail_stuff}
+add some generic config lines
+|!| {non_retail_stuff}
+</code>
+Be aware that the conditionals are evaluated at run-time. The LAST conditional result is really the last one executed and is not aware of its context. If, like in the example above, a sub-template is included that itself uses conditionals, then these will likely alter the ''||''.
+The "else" (''|!|'') will NOT be affected by possible conditionals in a sub template, it is not executed. The above example is quite safe.
+The repeat conditional is therefore best used for simple in-line commands or blocks.
+<code>
+# UNSAFE:
+# if {retail_stuff} uses conditionals
+|<site_type> = 'retail' | {retail_stuff}
+# because || now represents the result of the last conditional in {retail_stuff}
+|| {more_retail_stuff}
+# SAFE:
+|<site_type> = 'retail' | retail command line one \
+retail command line two \
+do generic commands
+# now reuse the last conditional safely:
+|| {more_retail_stuff}
+# but at this position, the ''||'' or ''|!|'' result might have changed
+</code>