.. zsh-module-meta::
   :name: zsh/pcre
   :summary: Interface to the PCRE library.

.. index:: single: regular expressions, perl-compatible; Command

The ``zsh/pcre`` module makes some commands available as builtins:

.. index:: single: pcre_compile; Function

``pcre_compile`` [ ``-aimxs`` ] :var:`PCRE`
    
    Compiles a perl-compatible regular expression.
    
    Option ``-a`` will force the pattern to be anchored.
    Option ``-i`` will compile a case-insensitive pattern.
    Option ``-m`` will compile a multi-line pattern; that is,
    ``^`` and ``$`` will match newlines within the pattern.
    Option ``-x`` will compile an extended pattern, wherein
    whitespace and ``#`` comments are ignored.
    Option ``-s`` makes the dot metacharacter match all characters,
    including those that indicate newline.
    

.. index:: single: pcre_study; Function

``pcre_study``
    
    Requests JIT compilation for the previously-compiled PCRE which
    may result in faster matching.
    

.. index:: single: pcre_match; Function

``pcre_match`` [ ``-v`` :var:`var` ] [ ``-a`` :var:`arr` ] [ ``-A`` :var:`assoc` ] [ ``-n`` :var:`offset` ] [ ``-bd`` ] :var:`string`
    
    Returns successfully if ``string`` matches the previously-compiled
    PCRE.
    
    Upon successful match,
    if the expression captures substrings within parentheses,
    ``pcre_match`` will set the array ``match`` to those
    substrings, unless the ``-a`` option is given, in which
    case it will set the array :var:`arr`.  Similarly, the variable
    ``MATCH`` will be set to the entire matched portion of the
    string, unless the ``-v`` option is given, in which case the variable
    :var:`var` will be set. Furthermore, any named captures will
    be stored in the associative array ``.pcre.match`` unless an
    alternative is given with ``-A``.
    No variables are altered if there is no successful match.
    A ``-n`` option starts searching for a match from the
    byte :var:`offset` position in :var:`string`.  If the ``-b`` option is given,
    the variable ``ZPCRE_OP`` will be set to an offset pair string,
    representing the byte offset positions of the entire matched portion
    within the :var:`string`.  For example, a ``ZPCRE_OP`` set to "32 45" indicates
    that the matched portion began on byte offset 32 and ended on byte offset 44.
    Here, byte offset position 45 is the position directly after the matched
    portion.  Keep in mind that the byte position isn't necessarily the same
    as the character position when UTF-8 characters are involved.
    Consequently, the byte offset positions are only to be relied on in the
    context of using them for subsequent searches on :var:`string`, using an offset
    position as an argument to the ``-n`` option.  This is mostly
    used to implement the "find all non-overlapping matches" functionality.
    
    A simple example of "find all non-overlapping matches":
    
    
    .. code-block:: zsh
       :class: example

        string="The following zip codes: 78884 90210 99513"
        pcre_compile -m "\d{5}"
        accum=()
        pcre_match -b -- $string
        while [[ $? -eq 0 ]] do
            b=($=ZPCRE_OP)
            accum+=$MATCH
            pcre_match -b -n $b[2] -- $string
        done
        print -l $accum
    
    
    The option ``-d`` uses the alternative breadth-first DFA search algorithm of
    pcre. This sets ``match``, or the array given with ``-a``, to all the matches
    found from the same start point in the subject.
    
    If the regular expression contains string callouts, these are executed as
    shell code, while numerical callouts are ignored. During the execution of the
    callout, the string the regular expression is matching against is available
    in the parameter ``.pcre.subject``. The parameter ``.pcre.pos`` contains the
    position in that string that is currently being matched against. If there is
    a non-zero return status from the shell code, the callout does not match. Note
    that callouts are not available in the below -pcre-match test condition. It is
    also likely not a good idea to call any pcre related builtins from a callout. As
    an example, the following will print out ``bar``:
    
    
    .. code-block:: zsh
       :class: example

        pcre_compile 'foo(?C"echo ${.pcre.subject[${.pcre.pos},-1]}")'
        pcre_match foobar
    
    

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

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

:var:`expr` ``-pcre-match`` :var:`pcre`
    
    Matches a string against a perl-compatible regular expression.
    
    For example,
    
    
    .. code-block:: zsh
       :class: example

        [[ "$text" -pcre-match ^d+$ ]] &&
        print text variable contains only "d's".
    
    
    .. index:: single: REMATCH_PCRE; Program
    
    
    .. index:: single: NO_CASE_MATCH; Program
    
    
    If the ``REMATCH_PCRE`` option is set, the ``=~`` operator is equivalent to
    ``-pcre-match``, and the ``NO_CASE_MATCH`` option may be used.  Note that
    ``NO_CASE_MATCH`` never applies to the ``pcre_match`` builtin, instead use
    the ``-i`` switch of ``pcre_compile``.
    

