ansible.builtin.regex_search filter – extract regex match from string
Note
This filter plugin is part of ansible-core and included in all Ansible
installations. In most cases, you can use the short
plugin name
regex_search.
However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.regex_search for easy linking to the
plugin documentation and to avoid conflicting with other collections that may have
the same filter plugin name.
Synopsis
Search in a string to extract the part that matches the regular expression.
Input
This describes the input of the filter, the value before | ansible.builtin.regex_search.
Parameter |
Comments |
|---|---|
String to match against. |
Positional parameters
This describes positional parameters of the filter. These are the values positional1, positional2 and so on in the following
example: input | ansible.builtin.regex_search(positional1, positional2, ...)
Parameter |
Comments |
|---|---|
Regular expression string that defines the match. |
Keyword parameters
This describes keyword parameters of the filter. These are the values key1=value1, key2=value2 and so on in the following
example: input | ansible.builtin.regex_search(key1=value1, key2=value2, ...)
Parameter |
Comments |
|---|---|
Force the search to be case insensitive if Choices:
|
|
Search across line endings if Choices:
|
Notes
Note
When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters:
input | ansible.builtin.regex_search(positional1, positional2, key1=value1, key2=value2)Maps to Python’s
re.search.The substring matched by the group is accessible via the symbolic group name or the ``\{number}`` special sequence. See examples section.
Examples
# db => 'database42'
db: "{{ 'server1/database42' | regex_search('database[0-9]+') }}"
# Using inline regex flags instead of passing options to filter
# See https://docs.python.org/3/library/re.html for more information
# on inline regex flags
# server => 'sErver1'
db: "{{ 'sErver1/database42' | regex_search('(?i)server([0-9]+)') }}"
# drinkat => 'BAR'
drinkat: "{{ 'foo\nBAR' | regex_search('^bar', multiline=True, ignorecase=True) }}"
# Extracts server and database id from a string using number
# (the substring matched by the group is accessible via the \number special sequence)
db: "{{ 'server1/database42' | regex_search('server([0-9]+)/database([0-9]+)', '\\1', '\\2') }}"
# => ['1', '42']
# Extracts dividend and divisor from a division
# (the substring matched by the group is accessible via the symbolic group name)
db: "{{ '21/42' | regex_search('(?P<dividend>[0-9]+)/(?P<divisor>[0-9]+)', '\\g<dividend>', '\\g<divisor>') }}"
# => ['21', '42']
Return Value
Key |
Description |
|---|---|
Matched string or empty string if no match. Returned: success |
Hint
Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.