:mod:`ure` -- 正则表达式
========================================

.. module:: ure
   :synopsis: 正则表达式

该模块实现相应CPython模块的子集，如下所示。更多信息，请参见
|CPython文档| :mod:`python:re`.

该模块实现正则表达式操作。支持的正则表达式语法是CPython ``re`` 模块的一个子集（实际上是POSIX扩展正则表达式的子集）。

支持的操作符和特殊序列是:

``.``
   匹配任何字符。

``[...]``
   匹配字符集。支持单个字符和范围，包括负集(例如 ``[^a-c]``)。

``^``
   匹配字符串的开头。

``$``
   匹配字符串的结尾。

``?``
   匹配零个或前面的子模式之一。

``*``
   匹配零个或多个先前的子模式。

``+``
   匹配一个或多个先前的子模式。

``??``
   非贪婪版本的 ``?`` ，匹配0或1，偏好零。

``*?``
   非贪婪版本的 ``*`` ，匹配零个或多个，并偏好最短的匹配。

``+?``
   非贪婪版本的 ``+`` ，匹配一个或多个，并偏好最短的匹配。

``|``
   匹配该操作符的左侧子模式或右侧子模式。

``(...)``
   分组。每个组都在捕获(它捕获的子字符串可以通过 `match.group()` 方法访问)。

``\d``
   数字匹配。相当于 ``[0-9]`` 。

``\D``
   非数字匹配。相当于 ``[^0-9]`` 。

``\s``
   匹配空格。相当于 ``[ \t-\r]`` 。

``\S``
   匹配非空格。相当于 ``[^ \t-\r]`` 。

``\w``
   匹配"单词字符" (仅限ASCII)。[相当于 ``[A-Za-z0-9_]`` 。

``\W``
   匹配非“单词字符”（仅限ASCII）。相当于 ``[^A-Za-z0-9_]`` 。

``\``
   转义字符。反斜杠后的任何其他字符（上面列出的字符除外）均按字面意义使用。例如，``\*`` 是相当于文本 ``*``（不作为 ``*`` 运算符处理）。
   请注意，``\r``, ``\n`` 等没有特别处理，将相当于字面字母 ``r``, ``n`` 等。因此不建议将原始Python字符串（ ``r""`` ）用于常规表达。
   例如，``r"\r\n"`` 用作常规表达式等价于 ``"rn"`` 。若要匹配后跟LF的CR字符，请使用 ``"\r\n"`` 。

**不支持**：
 
* 重复次数 (``{m,n}``) 
* 命名组 (``(?P<name>...)``) 
* 非捕获组(``(?:...)``)
* 更高级的断言(``\b``, ``\B``)
* 特殊字符转义，如 ``\r``, ``\n`` - 改用Python自己的转义
* 等等。

例子::

    import ure

    # As ure doesn't support escapes itself, use of r"" strings is not recommended.
    # 由于ure本身不支持转义，所以不推荐使用r""字符串
    
    regex = ure.compile("[\r\n]")

    regex.split("line1\rline2\nline3\r\n")

    # 结果:
    # ['line1', 'line2', 'line3', '', '']

函数
---------

.. function:: compile(regex_str, [flags])

   编译正则表达式，返回 `regex` 对象。

.. function:: match(regex_str, string)

   将 `regex` 与 `string` 匹配。匹配通常从字符串的起始位置进行。

.. function:: search(regex_str, string)

   在 `string` 中搜索 `regex` 。与 `match` 不同，这将首先搜索与正则表达式相匹配的字符串（若正则表达式固定，则字符串为0）。

.. function:: sub(regex_str, replace, string, count=0, flags=0)

   编译 *regex_str* 并在 *string* 中搜索它，用 *replace* 替换所有匹配项，然后返回新字符串。

   *replace* 可以是字符串或函数。如果是字符串，则可以使用格式为 ``\<number>`` 和 ``\g<number>`` 的转义序列扩展到相应的组（对于不匹配的组，则为空字符串）。
   如果 *replace* 是一个函数，则它必须采用单个参数（匹配项）并应返回替换字符串。

   如果指定了 *count* ，并且非零，那么在进行了相应次数的替换之后，替换将停止。忽略 *flags* 参数。

   注意：此方法的可用性取决于 `MicroPython port` 。

.. data:: DEBUG

   标记值，显示有关已编译表达式的调试信息。


.. _regex:

正则表达式对象
-------------

编译正则表达式。该类实例使用 `ure.compile()` 创建。

.. method:: regex.match(string)
            regex.search(string)
            regex.sub(replace, string, count=0, flags=0)

   与模块级函数 `match()` 和 `search()` , `sub` 相似。若将同一正则表达式应用于多个字符串，则使用该方法会大大提高效率。

.. method:: regex.split(string, max_split=-1)

   使用正则表达式拆分字符串。若给定，则指定将拆分的最大数量。返回字符串列表（若指定，则可能会有多达 *max_split+1* 个元素）。

Match 对象
-------------

匹配由 `match()` 和 `search()` 方法返回的对象。
并传递给 `sub()` 中的替换函数。

.. method:: match.group(index)

   返回匹配（子）字符串。若完全匹配 *index* 为0， 对于每个捕获组为1或更多。
   仅支持数字组。
   
.. method:: match.groups()

   返回一个包含该匹配组的所有子字符串的元组。

   注意：此方法的可用性取决于 `MicroPython port` 。

.. method:: match.start([index])
            match.end([index])

   返回匹配的子字符串组的起始或结束的原始字符串中的索引。*index* 默认为整个组，否则将选择一个组。

   注意：这些方法的可用性取决于 `MicroPython port` 。

.. method:: match.span([index])

   返回2元组 ``(match.start(index), match.end(index))`` 。

   注意：此方法的可用性取决于 `MicroPython port` 。