.. _stdlib_regex:

==========================
正则表达式库
==========================

.. include:: detail/regex.rst

`experimental` REGEX 模块实现了正则表达式解析器和模式匹配功能。

目前，该模块处于早期阶段，只实现了极少数基本的 regex 操作。

所有函数和符号都在 “regex ”模块中，请使用 require 访问该模块。 ::

    require daslib/regex


++++++++++++
类型别名
++++++++++++

.. _alias-CharSet:

.. das:attribute:: CharSet = uint[8]

表示 8 位字符集的位数组。

.. _alias-ReGenRandom:

.. das:attribute:: ReGenRandom = iterator<uint>

|typedef-regex-ReGenRandom|

.. _alias-MaybeReNode:

.. das:attribute:: MaybeReNode is a variant type

+-------+---------------------------------------------+
+value  + :ref:`regex::ReNode <struct-regex-ReNode>` ?+
+-------+---------------------------------------------+
+nothing+void?                                        +
+-------+---------------------------------------------+


单一正则表达式节点或无。

++++++++++++
枚举
++++++++++++

.. _enum-regex-ReOp:

.. das:attribute:: ReOp

+--------+-+
+Char    +0+
+--------+-+
+Set     +1+
+--------+-+
+Any     +2+
+--------+-+
+Eos     +3+
+--------+-+
+Group   +4+
+--------+-+
+Plus    +5+
+--------+-+
+Star    +6+
+--------+-+
+Question+7+
+--------+-+
+Concat  +8+
+--------+-+
+Union   +9+
+--------+-+


正则表达式操作类型。

.. _struct-regex-ReNode:

.. das:attribute:: ReNode



ReNode 字段是

+-------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+op     + :ref:`regex::ReOp <enum-regex-ReOp>`                                                                                                                                                          +
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+id     +int                                                                                                                                                                                            +
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+fun2   +function<(regex: :ref:`regex::Regex <struct-regex-Regex>` ;node: :ref:`regex::ReNode <struct-regex-ReNode>` ?;str:uint8? const):uint8?>                                                        +
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+gen2   +function<(node: :ref:`regex::ReNode <struct-regex-ReNode>` ?;rnd: :ref:`ReGenRandom <alias-ReGenRandom>` ;str: :ref:`strings::StringBuilderWriter <handle-strings-StringBuilderWriter>` ):void>+
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+at     +range                                                                                                                                                                                          +
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+text   +string                                                                                                                                                                                         +
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+textLen+int                                                                                                                                                                                            +
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+all    +array< :ref:`regex::ReNode <struct-regex-ReNode>` ?>                                                                                                                                           +
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+left   + :ref:`regex::ReNode <struct-regex-ReNode>` ?                                                                                                                                                  +
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+right  + :ref:`regex::ReNode <struct-regex-ReNode>` ?                                                                                                                                                  +
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+subexpr+ :ref:`regex::ReNode <struct-regex-ReNode>` ?                                                                                                                                                  +
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+next   + :ref:`regex::ReNode <struct-regex-ReNode>` ?                                                                                                                                                  +
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+cset   + :ref:`CharSet <alias-CharSet>`                                                                                                                                                                +
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+index  +int                                                                                                                                                                                            +
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+tail   +uint8?                                                                                                                                                                                         +
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+


正则表达式解析树中的单个节点。

.. _struct-regex-Regex:

.. das:attribute:: Regex



Regex 字段是

+-----------+---------------------------------------------+
+root       + :ref:`regex::ReNode <struct-regex-ReNode>` ?+
+-----------+---------------------------------------------+
+match      +uint8?                                       +
+-----------+---------------------------------------------+
+groups     +array<tuple<range;string>>                   +
+-----------+---------------------------------------------+
+earlyOut   + :ref:`CharSet <alias-CharSet>`              +
+-----------+---------------------------------------------+
+canEarlyOut+bool                                         +
+-----------+---------------------------------------------+


正则表达式。

++++++++++++++++++++++++++
汇编和验证
++++++++++++++++++++++++++

  *  :ref:`visit_top_down (node:regex::ReNode? -const;blk:block\<(var n:regex::ReNode? -const):void\> const) : void <function-_at_regex_c__c_visit_top_down_1_ls_S_ls_regex_c__c_ReNode_gr__gr__qm__CN_ls_n_gr_0_ls_1_ls_S_ls_regex_c__c_ReNode_gr__gr__qm__gr_1_ls_v_gr__builtin_>` 
  *  :ref:`is_valid (re:regex::Regex -const) : bool <function-_at_regex_c__c_is_valid_S_ls_regex_c__c_Regex_gr_>` 
  *  :ref:`regex_compile (re:regex::Regex -const;expr:string const) : bool <function-_at_regex_c__c_regex_compile_S_ls_regex_c__c_Regex_gr__Cs>` 
  *  :ref:`regex_compile (expr:string const) : regex::Regex <function-_at_regex_c__c_regex_compile_Cs>` 
  *  :ref:`regex_compile (re:regex::Regex -const) : regex::Regex <function-_at_regex_c__c_regex_compile_S_ls_regex_c__c_Regex_gr_>` 
  *  :ref:`regex_debug (regex:regex::Regex const) : void <function-_at_regex_c__c_regex_debug_CS_ls_regex_c__c_Regex_gr_>` 
  *  :ref:`debug_set (cset:uint const[8]) : void <function-_at_regex_c__c_debug_set_C_lb_8_rb_Y_ls_CharSet_gr_u>` 

.. _function-_at_regex_c__c_visit_top_down_1_ls_S_ls_regex_c__c_ReNode_gr__gr__qm__CN_ls_n_gr_0_ls_1_ls_S_ls_regex_c__c_ReNode_gr__gr__qm__gr_1_ls_v_gr__builtin_:

.. das:function:: visit_top_down(node: ReNode?; blk: block<(var n:ReNode?):void> const)

+--------+-------------------------------------------------------------------+
+argument+argument type                                                      +
+========+===================================================================+
+node    + :ref:`regex::ReNode <struct-regex-ReNode>` ?                      +
+--------+-------------------------------------------------------------------+
+blk     +block<(n: :ref:`regex::ReNode <struct-regex-ReNode>` ?):void> const+
+--------+-------------------------------------------------------------------+


|function-regex-visit_top_down|

.. _function-_at_regex_c__c_is_valid_S_ls_regex_c__c_Regex_gr_:

.. das:function:: is_valid(re: Regex)

is_valid returns bool

+--------+------------------------------------------+
+argument+argument type                             +
+========+==========================================+
+re      + :ref:`regex::Regex <struct-regex-Regex>` +
+--------+------------------------------------------+


如果枚举编译正确，则返回 `true`

.. _function-_at_regex_c__c_regex_compile_S_ls_regex_c__c_Regex_gr__Cs:

.. das:function:: regex_compile(re: Regex; expr: string const)

regex_compile returns bool

+--------+------------------------------------------+
+argument+argument type                             +
+========+==========================================+
+re      + :ref:`regex::Regex <struct-regex-Regex>` +
+--------+------------------------------------------+
+expr    +string const                              +
+--------+------------------------------------------+


编译正则表达式。
编译表达式的有效性由 `is_valid` 检查。

.. _function-_at_regex_c__c_regex_compile_Cs:

.. das:function:: regex_compile(expr: string const)

regex_compile returns  :ref:`regex::Regex <struct-regex-Regex>` 

+--------+-------------+
+argument+argument type+
+========+=============+
+expr    +string const +
+--------+-------------+


编译正则表达式。
编译表达式的有效性由 `is_valid` 检查。

.. _function-_at_regex_c__c_regex_compile_S_ls_regex_c__c_Regex_gr_:

.. das:function:: regex_compile(re: Regex)

regex_compile returns  :ref:`regex::Regex <struct-regex-Regex>` 

+--------+------------------------------------------+
+argument+argument type                             +
+========+==========================================+
+re      + :ref:`regex::Regex <struct-regex-Regex>` +
+--------+------------------------------------------+


编译正则表达式。
编译表达式的有效性由 `is_valid` 检查。

.. _function-_at_regex_c__c_regex_debug_CS_ls_regex_c__c_Regex_gr_:

.. das:function:: regex_debug(regex: Regex const)

+--------+------------------------------------------------+
+argument+argument type                                   +
+========+================================================+
+regex   + :ref:`regex::Regex <struct-regex-Regex>`  const+
+--------+------------------------------------------------+


以人类可读的形式打印正则表达式及其相关信息。

.. _function-_at_regex_c__c_debug_set_C_lb_8_rb_Y_ls_CharSet_gr_u:

.. das:function:: debug_set(cset: CharSet)

+--------+--------------------------------+
+argument+argument type                   +
+========+================================+
+cset    + :ref:`CharSet <alias-CharSet>` +
+--------+--------------------------------+


以人类可读的形式打印字符集。

++++++
访问
++++++

  *  :ref:`regex_group (regex:regex::Regex const;index:int const;match:string const) : string <function-_at_regex_c__c_regex_group_CS_ls_regex_c__c_Regex_gr__Ci_Cs>` 
  *  :ref:`regex_foreach (regex:regex::Regex -const;str:string const;blk:block\<(at:range const):bool\> const) : void <function-_at_regex_c__c_regex_foreach_S_ls_regex_c__c_Regex_gr__Cs_CN_ls_at_gr_0_ls_Cr_gr_1_ls_b_gr__builtin_>` 

.. _function-_at_regex_c__c_regex_group_CS_ls_regex_c__c_Regex_gr__Ci_Cs:

.. das:function:: regex_group(regex: Regex const; index: int const; match: string const)

regex_group returns string

+--------+------------------------------------------------+
+argument+argument type                                   +
+========+================================================+
+regex   + :ref:`regex::Regex <struct-regex-Regex>`  const+
+--------+------------------------------------------------+
+index   +int const                                       +
+--------+------------------------------------------------+
+match   +string const                                    +
+--------+------------------------------------------------+


返回给定组索引和匹配结果的字符串。

.. _function-_at_regex_c__c_regex_foreach_S_ls_regex_c__c_Regex_gr__Cs_CN_ls_at_gr_0_ls_Cr_gr_1_ls_b_gr__builtin_:

.. das:function:: regex_foreach(regex: Regex; str: string const; blk: block<(at:range const):bool> const)

+--------+------------------------------------------+
+argument+argument type                             +
+========+==========================================+
+regex   + :ref:`regex::Regex <struct-regex-Regex>` +
+--------+------------------------------------------+
+str     +string const                              +
+--------+------------------------------------------+
+blk     +block<(at:range const):bool> const        +
+--------+------------------------------------------+


遍历 `str` 中给定正则表达式的所有匹配项。

+++++
Match
+++++

  *  :ref:`regex_match (regex:regex::Regex -const;str:string const;offset:int const) : int <function-_at_regex_c__c_regex_match_S_ls_regex_c__c_Regex_gr__Cs_Ci>` 

.. _function-_at_regex_c__c_regex_match_S_ls_regex_c__c_Regex_gr__Cs_Ci:

.. das:function:: regex_match(regex: Regex; str: string const; offset: int const)

regex_match returns int

+--------+------------------------------------------+
+argument+argument type                             +
+========+==========================================+
+regex   + :ref:`regex::Regex <struct-regex-Regex>` +
+--------+------------------------------------------+
+str     +string const                              +
+--------+------------------------------------------+
+offset  +int const                                 +
+--------+------------------------------------------+


返回 `str` 中正则表达式的第一个匹配项。
如果指定了 `offset`，则不会首先匹配这么多的符号。

++++++++++
生成
++++++++++

  *  :ref:`re_gen_get_rep_limit () : uint <function-_at_regex_c__c_re_gen_get_rep_limit>` 
  *  :ref:`re_gen (re:regex::Regex -const;rnd:iterator\<uint\> -const) : string <function-_at_regex_c__c_re_gen_S_ls_regex_c__c_Regex_gr__Y_ls_ReGenRandom_gr_1_ls_u_gr_G>` 

.. _function-_at_regex_c__c_re_gen_get_rep_limit:

.. das:function:: re_gen_get_rep_limit()

re_gen_get_rep_limit returns uint

|function-regex-re_gen_get_rep_limit|

.. _function-_at_regex_c__c_re_gen_S_ls_regex_c__c_Regex_gr__Y_ls_ReGenRandom_gr_1_ls_u_gr_G:

.. das:function:: re_gen(re: Regex; rnd: ReGenRandom)

re_gen returns string

+--------+------------------------------------------+
+argument+argument type                             +
+========+==========================================+
+re      + :ref:`regex::Regex <struct-regex-Regex>` +
+--------+------------------------------------------+
+rnd     + :ref:`ReGenRandom <alias-ReGenRandom>`   +
+--------+------------------------------------------+


|function-regex-re_gen|

+++++++++++++
未分类
+++++++++++++

.. _function-_at_regex_c__c_regex_replace_S_ls_regex_c__c_Regex_gr__Cs_CN_ls_at_gr_0_ls_Cs_gr_1_ls_s_gr__builtin_:

.. das:function:: regex_replace(regex: Regex; str: string const; blk: block<(at:string const):string> const)

regex_replace returns string const

+--------+------------------------------------------+
+argument+argument type                             +
+========+==========================================+
+regex   + :ref:`regex::Regex <struct-regex-Regex>` +
+--------+------------------------------------------+
+str     +string const                              +
+--------+------------------------------------------+
+blk     +block<(at:string const):string> const     +
+--------+------------------------------------------+


遍历 `str` 中给定正则表达式的所有匹配项。