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).
  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 C(True), do not if otherwise.
      type: bool
      default: no
    ignorecase:
      description: Force the search to be case insensitive if C(True), case sensitive otherwise.
      type: bool
      default: no

EXAMPLES: |

  # db => 'database42'
  db: "{{ 'server1/database42' | regex_search('database[0-9]+') }}"

  # drinkat => 'BAR'
  drinkat: "{{ 'foo\nBAR' | regex_search('^bar', multiline=True, ignorecase=True) }}"

RETURN:
  _value:
    description: Matched string or empty string if no match.
    type: str