From 99a2b5f3006ebe1845565071099c4fe54b227590 Mon Sep 17 00:00:00 2001 From: Baptiste Mille-Mathias Date: Tue, 20 Apr 2021 17:52:54 +0200 Subject: [PATCH] Provide results to examples (#73984) --- .../rst/user_guide/playbooks_filters.rst | 55 +++++++++++++++---- 1 file changed, 43 insertions(+), 12 deletions(-) diff --git a/docs/docsite/rst/user_guide/playbooks_filters.rst b/docs/docsite/rst/user_guide/playbooks_filters.rst index 984de55e4b3..6398676a07c 100644 --- a/docs/docsite/rst/user_guide/playbooks_filters.rst +++ b/docs/docsite/rst/user_guide/playbooks_filters.rst @@ -293,18 +293,24 @@ To get a list combining the elements of other lists use ``zip``:: - name: Give me list combo of two lists ansible.builtin.debug: - msg: "{{ [1,2,3,4,5] | zip(['a','b','c','d','e','f']) | list }}" + msg: "{{ [1,2,3,4,5,6] | zip(['a','b','c','d','e','f']) | list }}" + + # => [[1, "a"], [2, "b"], [3, "c"], [4, "d"], [5, "e"], [6, "f"]] - name: Give me shortest combo of two lists ansible.builtin.debug: msg: "{{ [1,2,3] | zip(['a','b','c','d','e','f']) | list }}" + # => [[1, "a"], [2, "b"], [3, "c"]] + To always exhaust all lists use ``zip_longest``:: - name: Give me longest combo of three lists , fill with X ansible.builtin.debug: msg: "{{ [1,2,3] | zip_longest(['a','b','c','d','e','f'], [21, 22, 23], fillvalue='X') | list }}" + # => [[1, "a", 21], [2, "b", 22], [3, "c", 23], ["X", "d", "X"], ["X", "e", "X"], ["X", "f", "X"]] + Similarly to the output of the ``items2dict`` filter mentioned above, these filters can be used to construct a ``dict``:: {{ dict(keys_list | zip(values_list)) }} @@ -640,11 +646,11 @@ To get permutations of a list:: - name: Give me largest permutations (order matters) ansible.builtin.debug: - msg: "{{ [1,2,3,4,5] | permutations | list }}" + msg: "{{ [1,2,3,4,5] | ansible.builtin.permutations | list }}" - name: Give me permutations of sets of three ansible.builtin.debug: - msg: "{{ [1,2,3,4,5] | permutations(3) | list }}" + msg: "{{ [1,2,3,4,5] | ansible.builtin.permutations(3) | list }}" combinations ^^^^^^^^^^^^ @@ -652,7 +658,7 @@ Combinations always require a set size:: - name: Give me combinations for sets of two ansible.builtin.debug: - msg: "{{ [1,2,3,4,5] | combinations(2) | list }}" + msg: "{{ [1,2,3,4,5] | ansible.builtin.combinations(2) | list }}" Also see the :ref:`zip_filter` @@ -921,10 +927,12 @@ To get the maximum value in a list of objects:: Flatten a list (same thing the `flatten` lookup does):: {{ [3, [4, 2] ] | flatten }} + # => [3, 4, 2] Flatten only the first level of a list (akin to the `items` lookup):: {{ [3, [4, [2]] ] | flatten(levels=1) }} + # => [3, 4, [2]] .. versionadded:: 2.11 @@ -932,7 +940,7 @@ Flatten only the first level of a list (akin to the `items` lookup):: Preserve nulls in a list, by default flatten removes them. :: {{ [3, None, [4, [2]] ] | flatten(levels=1, skip_nulls=False) }} - + # => [3, None, 4, [2]] .. _set_theory_filters: @@ -989,21 +997,26 @@ You can calculate logs, powers, and roots of numbers with Ansible filters. Jinja Get the logarithm (default is e):: - {{ myvar | log }} + {{ 8 | log }} + # => 2.0794415416798357 Get the base 10 logarithm:: - {{ myvar | log(10) }} + {{ 8 | log(10) }} + # => 0.9030899869919435 Give me the power of 2! (or 5):: - {{ myvar | pow(2) }} - {{ myvar | pow(5) }} + {{ 8 | pow(5) }} + # => 32768.0 Square root, or the 5th:: - {{ myvar | root }} - {{ myvar | root(5) }} + {{ 8 | root }} + # => 2.8284271247461903 + + {{ 8 | root(5) }} + # => 1.5157165665103982 Managing network interactions @@ -1035,6 +1048,7 @@ IP address filter can also be used to extract specific information from an IP address. For example, to get the IP address itself from a CIDR, you can use:: {{ '192.0.2.1/24' | ansible.netcommon.ipaddr('address') }} + # => 192.168.0.1 More information about ``ipaddr`` filter and complete usage guide can be found in :ref:`playbooks_filters_ipaddr`. @@ -1281,14 +1295,17 @@ Encrypting and checksumming strings and passwords To get the sha1 hash of a string:: {{ 'test1' | hash('sha1') }} + # => "b444ac06613fc8d63795be9ad0beaf55011936ac" To get the md5 hash of a string:: {{ 'test1' | hash('md5') }} + # => "5a105e8b9d40e1329780d62ea2265d8a" Get a string checksum:: {{ 'test2' | checksum }} + # => "109f4b3c50d7b0df729d299bc6f8e9ef9066971f" Other hashes (platform dependent):: @@ -1297,14 +1314,17 @@ Other hashes (platform dependent):: To get a sha512 password hash (random salt):: {{ 'passwordsaresecret' | password_hash('sha512') }} + # => "$6$UIv3676O/ilZzWEE$ktEfFF19NQPF2zyxqxGkAceTnbEgpEKuGBtk6MlU4v2ZorWaVQUMyurgmHCh2Fr4wpmQ/Y.AlXMJkRnIS4RfH/" To get a sha256 password hash with a specific salt:: {{ 'secretpassword' | password_hash('sha256', 'mysecretsalt') }} + # => "$5$mysecretsalt$ReKNyDYjkKNqRVwouShhsEqZ3VOE8eoVO4exihOfvG4" An idempotent method to generate unique hashes per system is to use a salt that is consistent between runs:: {{ 'secretpassword' | password_hash('sha512', 65534 | random(seed=inventory_hostname) | string) }} + # => "$6$43927$lQxPKz2M2X.NWO.gK.t7phLwOKQMcSq72XxDZQ0XzYV6DlL1OD72h417aj16OnHTGxNzhftXJQBcjbunLEepM0" Hash types available depend on the control system running Ansible, 'hash' depends on hashlib, password_hash depends on passlib (https://passlib.readthedocs.io/en/stable/lib/passlib.hash.html). @@ -1313,6 +1333,7 @@ Hash types available depend on the control system running Ansible, 'hash' depend Some hash types allow providing a rounds parameter:: {{ 'secretpassword' | password_hash('sha256', 'mysecretsalt', rounds=10000) }} + # => "$5$rounds=10000$mysecretsalt$Tkm80llAxD4YHll6AgNIztKn0vzAACsuuEfYeGP7tm7" .. _other_useful_filters: @@ -1468,9 +1489,11 @@ To search a string with a regex, use the "regex_search" filter:: # search for "foo" in "foobar" {{ 'foobar' | regex_search('(foo)') }} + # => "foo" # will return empty if it cannot find a match {{ 'ansible' | regex_search('(foobar)') }} + # => "" # case insensitive search in multiline mode {{ 'foo\nBAR' | regex_search("^bar", multiline=True, ignorecase=True) }} @@ -1486,18 +1509,23 @@ To replace text in a string with regex, use the "regex_replace" filter:: # convert "ansible" to "able" {{ 'ansible' | regex_replace('^a.*i(.*)$', 'a\\1') }} + # => 'able' # convert "foobar" to "bar" {{ 'foobar' | regex_replace('^f.*o(.*)$', '\\1') }} + # => 'bar' # convert "localhost:80" to "localhost, 80" using named groups {{ 'localhost:80' | regex_replace('^(?P.+):(?P\\d+)$', '\\g, \\g') }} + # => 'localhost, 80' # convert "localhost:80" to "localhost" {{ 'localhost:80' | regex_replace(':80') }} + # => 'localhost' # change a multiline string - {{ var | regex_replace('^', '#CommentThis#', multiline=True) }} + {{ 'var' | regex_replace('^', '#CommentThis#', multiline=True) }} + # => '#CommentThis#var' .. note:: If you want to match the whole string and you are using ``*`` make sure to always wraparound your regular expression with the start/end anchors. For example ``^(.*)$`` will always match only one result, while ``(.*)`` on some Python versions will match the whole string and an empty string at the end, which means it will make two replacements:: @@ -1683,12 +1711,15 @@ To format a date using a string (like with the shell date command), use the "str # Display year-month-day {{ '%Y-%m-%d' | strftime }} + # => "2021-03-19" # Display hour:min:sec {{ '%H:%M:%S' | strftime }} + # => "21:51:04" # Use ansible_date_time.epoch fact {{ '%Y-%m-%d %H:%M:%S' | strftime(ansible_date_time.epoch) }} + # => "2021-03-19 21:54:09" # Use arbitrary epoch value {{ '%Y-%m-%d' | strftime(0) }} # => 1970-01-01