From 0ae7f996f59b3db0b2acec84f04c1dee0c1e2832 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Sat, 2 Feb 2013 11:51:25 -0500 Subject: [PATCH] Make sure all the lookup plugins are documented. --- docsite/rst/playbooks2.rst | 79 ++++++++++++++++++++++++------------- hacking/module_formatter.py | 3 +- 2 files changed, 53 insertions(+), 29 deletions(-) diff --git a/docsite/rst/playbooks2.rst b/docsite/rst/playbooks2.rst index b80a97d3541..08a69c41749 100644 --- a/docsite/rst/playbooks2.rst +++ b/docsite/rst/playbooks2.rst @@ -276,17 +276,17 @@ In Ansible 0.8, a few shortcuts are available for testing whether a variable is There is a matching 'is_unset' that works the same way. Quoting the variable inside the function is mandatory. -When combining `only_if` with `with_items`, be aware that the `only_if` statement is processed for each item. -This is a deliberate design:: +When combining `only_if` with `with_items`, be aware that the `only_if` statement is processed seperately for each item. +This is by 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. +While `only_if` is a pretty good option for advanced users, it exposes more guts than we'd like, and +we can do better. In 1.0, we added 'when', which is like syntactic sugar for `only_if` and hides +this level of complexity. See more on this below. Conditional Execution (Simplified) `````````````````````````````````` @@ -435,8 +435,8 @@ More Loops .. versionadded: 0.8 Various 'lookup plugins' allow additional ways to iterate over data. Ansible will have more of these -over time. In 0.8, the only lookup plugins that comes stock are 'with_fileglob' and 'with_sequence', but -you can also write your own. +over time. You can write your own, as is covered in the API section. Each typically takes a list and +can accept more than one parameter. 'with_fileglob' matches all files in a single directory, non-recursively, that match a pattern. It can be used like this:: @@ -451,26 +451,61 @@ be used like this:: # copy each file over that matches the given pattern - action: copy src=$item dest=/etc/fooapp/ owner=root mode=600 - with_fileglob: /playbooks/files/fooapp/* + with_fileglob: + - /playbooks/files/fooapp/* + +.. versionadded: 0.9 + +Many new lookup abilities were added in 0.9. Remeber lookup plugins are run on the "controlling" machine:: + + --- + - hosts: all + + tasks: + + - action: debug msg="$item is an environment variable" + with_env: + - HOME + - LANG + + - action: debug msg="$item is a line from the result of this command" + with_lines: + - cat /etc/motd + + - action: debug msg="$item is the raw result of running this command" + with_pipe: + - date + + - action: debug msg="$item is value in Redis for somekey" + with_redis_kv: + - redis://localhost:6379,somekey + + - action: debug msg="$item is a DNS TXT record for example.com" + with_dnstxt: + - example.com + + - action: debug msg="$item is a value from evaluation of this template" + with_template: + - ./some_template.j2 .. versionadded: 1.0 'with_sequence' generates a sequence of items in ascending numerical order. You -can specify a 'start', an 'end' value (inclusive), and a 'stride' value (to skip -some numbers of values), and a printf-style 'format' string. It accepts -arguments both as key-value pairs and in a shortcut of the form -"[start-]end[/stride][:format]". All numerical values can be specified in -hexadecimal (i.e. 0x3f8) or octal (i.e. 0644). Negative numbers are not -supported. Here is an example that leverages most of its features:: +can specify a start, end, and an optional step value. - ---- +Arguments can be either key-value pairs or as a shortcut in the format +"[start-]end[/stride][:format]". The format is a printf style string. + +Numerical values can be specified in decimal, hexadecimal (0x3f8) or octal (0600). +Negative numbers are not supported. This works as follows:: + + --- - hosts: all tasks: # create groups - group: name=evens state=present - - group: name=odds state=present # create 32 test users @@ -484,17 +519,7 @@ supported. Here is an example that leverages most of its features:: - file: dest=/var/stuff/$item state=directory with_sequence: start=4 end=16 -The key-value form also supports a 'count' option, which always generates -'count' entries regardless of the stride. The count option is mostly useful for -avoiding off-by-one errors and errors calculating the number of entries in a -sequence when a stride is specified. The shortcut form cannot be used to -specify a count. As an example:: - - ---- - - hosts: all - - tasks: - + # a simpler way to use the sequence plugin # create 4 groups - group: name=group${item} state=present with_sequence: count=4 diff --git a/hacking/module_formatter.py b/hacking/module_formatter.py index 217d325f170..71e8777a43c 100755 --- a/hacking/module_formatter.py +++ b/hacking/module_formatter.py @@ -30,8 +30,7 @@ import time import datetime import subprocess import ansible.utils -from ansible.utils import module_docs - +import ansible.utils.module_docs as module_docs # Get parent directory of the directory this script lives in MODULEDIR=os.path.abspath(os.path.join(