DOCUMENTATION:
  name: regex_search
  version_added: "2.0"
  short_description: extract regex match from string
  description:
    - Search in a string to extract the part that matches the regular expression.
  notes:
    - Maps to Python's C(re.search).
    - 'The substring matched by the group is accessible via the symbolic group name or
      the ``\{number}`` special sequence. See examples section.'
    - The return for no match will be C(None) in most cases, depending on whether it is used with other filters/tests or not.
      It also depends on the Jinja version used and whether native is enabled.
    - "For a more complete explanation see U(https://docs.ansible.com/ansible-core/devel/reference_appendices/faq.html#why-does-the-regex-search-filter-return-none-instead-of-an-empty-string)."
  positional: _input, _regex
  options:
    _input:
      description: String to match against.
      type: str
      required: true
    _regex:
      description: Regular expression string that defines the match.
      type: str
    multiline:
      description: Search across line endings if V(True), do not if otherwise.
      type: bool
      default: no
    ignorecase:
      description: Force the search to be case insensitive if V(True), case sensitive otherwise.
      type: bool
      default: no

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:
    description: Matched string or if no match a C(None) or an empty string (see notes)
    type: str