.. zsh-module-meta::
   :name: zsh/regex
   :summary: Interface to the POSIX regex library.

.. index:: single: regular expressions; Command

.. index:: single: regex; Command

The ``zsh/regex`` module makes available the following test condition:

.. index:: single: regex-match; Function

:var:`expr` ``-regex-match`` :var:`regex`
    
    Matches a string against a POSIX extended regular expression.
    On successful match,
    matched portion of the string will normally be placed in the ``MATCH``
    variable.  If there are any capturing parentheses within the regex, then
    the ``match`` array variable will contain those.
    If the match is not successful, then the variables will not be altered.
    
    For example,
    
    
    .. code-block:: zsh
       :class: example

        [[ alphabetical -regex-match ^a([^a]+)a([^a]+)a ]] &&
        print -l $MATCH X $match
    
    
    If the option ``REMATCH_PCRE`` is not set, then the ``=~`` operator will
    automatically load this module as needed and will invoke the
    ``-regex-match`` operator.
    
    If ``BASH_REMATCH`` is set, then the array ``BASH_REMATCH`` will be set
    instead of ``MATCH`` and ``match``.
    
    Note that the ``zsh/regex`` module logic relies on the host system. The 
    same :var:`expr` and :var:`regex` pair could produce different results on different
    platforms if a :var:`regex` with non-standard syntax is given.
    
    For example, no syntax for matching a word boundary is defined in the POSIX
    extended regular expression standard. GNU ``libc`` and BSD ``libc`` both provide 
    such syntaxes as extensions (``\b`` and ``[[:<:]]/[[:>:]]`` respectively), 
    but neither of these syntaxes is supported by both of these implementations.
    
    Refer to the :manpage:`regcomp(3)` and :manpage:`re_format(7)` manual pages on your
    system for locally-supported syntax.
    

