From 7d990fa1674adaf50858332ccc23586cadb8a93c Mon Sep 17 00:00:00 2001 From: Dag Wieers Date: Mon, 22 Oct 2012 12:25:08 +0200 Subject: [PATCH] Clarify how only_if works, also combined with with_items - The old documentation stated not to quote the variable in the function, which is obviously wrong. When using lists or integers, we have to quote otherwise the startswith() method will trip over its non-existence. - It was unclear that the only_if statement is processed for each item when doing with_items, so I added an example making it crystal clear how this can be used in your advantage (or why a non-existing list variable can break your logic if you expected the only_if to be processed once before running the task) --- docsite/rst/playbooks2.rst | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docsite/rst/playbooks2.rst b/docsite/rst/playbooks2.rst index 20db976b80..e3b5b7c257 100644 --- a/docsite/rst/playbooks2.rst +++ b/docsite/rst/playbooks2.rst @@ -272,12 +272,20 @@ In Ansible 0.8, a few shortcuts are available for testing whether a variable is tasks: - action: command echo hi - only_if: is_set($some_variable) + only_if: is_set('$some_variable') -There is a matching 'is_unset' that works the same way. Do not quote the variables inside the function. +There is a matching 'is_unset' that works the same way. Quoting the variable inside the function is mandatory. -While only_if is a pretty good option for advanced users, it exposes more guts of the engine than we'd like, and -we can do better. In 0.9, we will be adding 'when', which will be like a syntactic sugar for only_if and hide +When combining `only_if` with `with_items`, be aware that the `only_if` statement is processed for each item. +This is a deliberate design:: + + tasks: + - action: command echo $item + with_item: [ 0, 2, 4, 6, 8, 10 ] + only_if: "$item > 5" + +While `only_if` is a pretty good option for advanced users, it exposes more guts of the engine than we'd like, and +we can do better. In 0.9, we will be adding `when`, which will be like a syntactic sugar for `only_if` and hide this level of complexity -- it will numerous built in operators. Conditional Imports