preg-replace-callback.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: c1f37a6c270aadbbb3da56a3973ffd62197adf2b Maintainer: daijie Status: ready -->
<!-- CREDITS: mowangjuanzi, Luffy -->
<refentry xml:id="function.preg-replace-callback" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>preg_replace_callback</refname>
  <refpurpose>执行一个正则表达式搜索并且使用一个回调进行替换</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>string</type><type>array</type><type>null</type></type><methodname>preg_replace_callback</methodname>
   <methodparam><type class="union"><type>string</type><type>array</type></type><parameter>pattern</parameter></methodparam>
   <methodparam><type>callable</type><parameter>callback</parameter></methodparam>
   <methodparam><type class="union"><type>string</type><type>array</type></type><parameter>subject</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>limit</parameter><initializer>-1</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter role="reference">count</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
  </methodsynopsis>
  <para>
  这个函数的行为除了可以指定一个
  <parameter>callback</parameter> 替代
  <parameter>replacement</parameter>
  进行替换字符串的计算，其他方面等同于
  <function>preg_replace</function>。
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>pattern</parameter></term>
     <listitem>
      <para>
      要搜索的模式，可以是字符串或一个字符串数组。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>callback</parameter></term>
     <listitem>
      <para>
      一个回调函数，在每次需要替换时调用，调用时函数得到的参数是从 <parameter>subject</parameter>
      中匹配到的结果。回调函数返回真正参与替换的字符串。这是该回调函数的签名：
      </para>
      <para>
       <methodsynopsis>
        <type>string</type><methodname><replaceable>handler</replaceable></methodname>
        <methodparam><type>array</type><parameter>matches</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
        经常会需要 <parameter>callback</parameter> 函数而仅用于
        <function>preg_replace_callback</function> 一个地方的调用。在这种情况下，你可以使用
        <link linkend="functions.anonymous">匿名函数</link> 来定义一个匿名函数作为
        <function>preg_replace_callback</function>
        调用时的回调。 这样做你可以保留所有调用信息在同一个位置并且不会因为一个不在任何其他地方使用的回调函数名称而污染函数名称空间。
      </para>
      <para>
       <example>
        <title><function>preg_replace_callback</function> 和
        匿名函数</title>
        <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
/* 一个unix样式的命令行过滤器，用于将段落开始部分的大写字母转换为小写。 */
$fp = fopen("php://stdin", "r") or die("can't read stdin");
while (!feof($fp)) {
    $line = fgets($fp);
    $line = preg_replace_callback(
        '|<p>\s*\w|',
        function ($matches) {
            return strtolower($matches[0]);
        },
        $line
    );
    echo $line;
}
fclose($fp);
?>
]]>
        </programlisting>
       </example>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>subject</parameter></term>
     <listitem>
      <para>
       要搜索替换的目标字符串或字符串数组。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>limit</parameter></term>
     <listitem>
      <para>
      对于每个模式用于每个 <parameter>subject</parameter> 字符串的最大可替换次数。
      默认是 <literal>-1</literal>（无限制）。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>count</parameter></term>
     <listitem>
      <para>
       如果指定，这个变量将被填充为替换执行的次数。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       <parameter>flags</parameter> 可以是 <constant>PREG_OFFSET_CAPTURE</constant>
       和 <constant>PREG_UNMATCHED_AS_NULL</constant> 标志的组合， 这会影响匹配到的结果的格式。
       相关详情请参阅 <function>preg_match</function> 中的描述。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
    如果 <parameter>subject</parameter> 是一个数组，
    <function>preg_replace_callback</function> 返回一个数组，其他情况返回字符串。错误发生时返回 &null;。
  </para>
  <para>
  如果查找到了匹配，返回替换后的目标字符串（或字符串数组），其他情况
  <parameter>subject</parameter> 将会无变化返回。
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  &pcre.pattern.warning;
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>7.4.0</entry>
       <entry>
        新增 <parameter>flags</parameter> 参数。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>preg_replace_callback</function>示例</title>
    <programlisting role="php">
<![CDATA[
<?php
// 将文本中的年份增加一年.
$text = "April fools day is 04/01/2002\n";
$text.= "Last christmas was 12/24/2001\n";
// 回调函数
function next_year($matches)
{
  // 通常: $matches[0]是完成的匹配
  // $matches[1]是第一个捕获子组的匹配
  // 以此类推
  return $matches[1].($matches[2]+1);
}
echo preg_replace_callback(
            "|(\d{2}/\d{2}/)(\d{4})|",
            "next_year",
            $text);

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
April fools day is 04/01/2003
Last christmas was 12/24/2002
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title><function>preg_replace_callback</function> 使用递归构造处理 BB 码的封装</title>
    <programlisting role="php">
<![CDATA[
<?php
$input = "plain [indent] deep [indent] deeper [/indent] deep [/indent] plain";

function parseTagsRecursive($input)
{
     /* 译注: 对此正则表达式分段分析
     * 首尾两个#是正则分隔符
     * \[indent] 匹配一个原文的[indent]
     * ((?:[^[]|\[(?!/?indent])|(?R))+)分析:
     *   (?:[^[]|\[(?!/?indent])分析:
     *  首先它是一个非捕获子组
     *   两个可选路径, 一个是非[字符, 另一个是[字符但后面紧跟着不是/indent或indent.
     *   (?R) 正则表达式递归
     *     \[/indent] 匹配结束的[/indent]
     * /

    $regex = '#\[indent]((?:[^[]|\[(?!/?indent])|(?R))+)\[/indent]#';

    if (is_array($input)) {
        $input = '<div style="margin-left: 10px">'.$input[1].'</div>';
    }

    return preg_replace_callback($regex, 'parseTagsRecursive', $input);
}

$output = parseTagsRecursive($input);

echo $output;
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><link linkend="pcre.pattern">PCRE 模式</link></member>
    <member><function>preg_replace_callback_array</function></member>
    <member><function>preg_quote</function></member>
    <member><function>preg_replace</function></member>
    <member><function>preg_last_error</function></member>
    <member><link linkend="functions.anonymous">匿名函数</link></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->