nlopess Sat Mar 12 15:29:58 2005 EDT
Modified files:
/phpdoc/en/reference/pcre/functions preg-replace-callback.xml
preg-replace.xml
Log:
WS. prepare for new doc style
http://cvs.php.net/diff.php/phpdoc/en/reference/pcre/functions/preg-replace-callback.xml?r1=1.9&r2=1.10&ty=u
Index: phpdoc/en/reference/pcre/functions/preg-replace-callback.xml
diff -u phpdoc/en/reference/pcre/functions/preg-replace-callback.xml:1.9
phpdoc/en/reference/pcre/functions/preg-replace-callback.xml:1.10
--- phpdoc/en/reference/pcre/functions/preg-replace-callback.xml:1.9 Thu Mar
3 08:42:12 2005
+++ phpdoc/en/reference/pcre/functions/preg-replace-callback.xml Sat Mar
12 15:29:57 2005
@@ -1,104 +1,100 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
<!-- splitted from ./en/functions/pcre.xml, last change in rev 1.47 -->
- <refentry id="function.preg-replace-callback">
- <refnamediv>
- <refname>preg_replace_callback</refname>
- <refpurpose>Perform a regular expression search and replace using a
callback</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <methodsynopsis>
- <type>mixed</type><methodname>preg_replace_callback</methodname>
-
<methodparam><type>mixed</type><parameter>pattern</parameter></methodparam>
-
<methodparam><type>callback</type><parameter>callback</parameter></methodparam>
-
<methodparam><type>mixed</type><parameter>subject</parameter></methodparam>
- <methodparam
choice="opt"><type>int</type><parameter>limit</parameter></methodparam>
- </methodsynopsis>
- <para>
- The behavior of this function is almost identical to
- <function>preg_replace</function>, except for the fact that instead of
- <parameter>replacement</parameter> parameter, one should specify a
- <parameter>callback</parameter> that will be called and passed an array of
- matched elements in the subject string. The callback should return the
- replacement string.
- </para>
- <example>
- <title><function>preg_replace_callback</function> example</title>
- <programlisting role='php'>
+<refentry id="function.preg-replace-callback">
+ <refnamediv>
+ <refname>preg_replace_callback</refname>
+ <refpurpose>Perform a regular expression search and replace using a
callback</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>mixed</type><methodname>preg_replace_callback</methodname>
+ <methodparam><type>mixed</type><parameter>pattern</parameter></methodparam>
+
<methodparam><type>callback</type><parameter>callback</parameter></methodparam>
+ <methodparam><type>mixed</type><parameter>subject</parameter></methodparam>
+ <methodparam
choice="opt"><type>int</type><parameter>limit</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ The behavior of this function is almost identical to
+ <function>preg_replace</function>, except for the fact that instead of
+ <parameter>replacement</parameter> parameter, one should specify a
+ <parameter>callback</parameter> that will be called and passed an array of
+ matched elements in the subject string. The callback should return the
+ replacement string.
+ </para>
+ <example>
+ <title><function>preg_replace_callback</function> example</title>
+ <programlisting role='php'>
<![CDATA[
<?php
- // this text was used in 2002
- // we want to get this up to date for 2003
- $text = "April fools day is 04/01/2002\n";
- $text.= "Last christmas was 12/24/2001\n";
-
- // the callback function
- function next_year($matches)
- {
- // as usual: $matches[0] is the complete match
- // $matches[1] the match for the first subpattern
- // enclosed in '(...)' and so on
- return $matches[1].($matches[2]+1);
- }
-
- echo preg_replace_callback(
- "|(\d{2}/\d{2}/)(\d{4})|",
- "next_year",
- $text);
-
- // result is:
- // April fools day is 04/01/2003
- // Last christmas was 12/24/2002
+// this text was used in 2002
+// we want to get this up to date for 2003
+$text = "April fools day is 04/01/2002\n";
+$text.= "Last christmas was 12/24/2001\n";
+// the callback function
+function next_year($matches)
+{
+ // as usual: $matches[0] is the complete match
+ // $matches[1] the match for the first subpattern
+ // enclosed in '(...)' and so on
+ return $matches[1].($matches[2]+1);
+}
+echo preg_replace_callback(
+ "|(\d{2}/\d{2}/)(\d{4})|",
+ "next_year",
+ $text);
+// result is:
+// April fools day is 04/01/2003
+// Last christmas was 12/24/2002
?>
]]>
- </programlisting>
- </example>
- <para>
- You'll often need the <parameter>callback</parameter> function
- for a <function>preg_replace_callback</function> in just one place.
- In this case you can use <function>create_function</function> to
- declare an anonymous function as callback within the call to
- <function>preg_replace_callback</function>. By doing it this way
- you have all information for the call in one place and do not
- clutter the function namespace with a callback functions name
- not used anywhere else.
- </para>
- <example>
- <title><function>preg_replace_callback</function> and
<function>create_function</function></title>
- <programlisting role='php'>
+ </programlisting>
+ </example>
+ <para>
+ You'll often need the <parameter>callback</parameter> function
+ for a <function>preg_replace_callback</function> in just one place.
+ In this case you can use <function>create_function</function> to
+ declare an anonymous function as callback within the call to
+ <function>preg_replace_callback</function>. By doing it this way
+ you have all information for the call in one place and do not
+ clutter the function namespace with a callback functions name
+ not used anywhere else.
+ </para>
+ <example>
+ <title><function>preg_replace_callback</function> and
<function>create_function</function></title>
+ <programlisting role='php'>
<![CDATA[
<?php
- /* a unix-style command line filter to convert uppercase
- * letters at the beginning of paragraphs to lowercase */
-
- $fp = fopen("php://stdin", "r") or die("can't read stdin");
- while (!feof($fp)) {
- $line = fgets($fp);
- $line = preg_replace_callback(
- '|<p>\s*\w|',
- create_function(
- // single quotes are essential here,
- // or alternative escape all $ as \$
- '$matches',
- 'return strtolower($matches[0]);'
- ),
- $line
- );
- echo $line;
- }
- fclose($fp);
+/* a unix-style command line filter to convert uppercase
+ * letters at the beginning of paragraphs to lowercase */
+$fp = fopen("php://stdin", "r") or die("can't read stdin");
+while (!feof($fp)) {
+ $line = fgets($fp);
+ $line = preg_replace_callback(
+ '|<p>\s*\w|',
+ create_function(
+ // single quotes are essential here,
+ // or alternative escape all $ as \$
+ '$matches',
+ 'return strtolower($matches[0]);'
+ ),
+ $line
+ );
+ echo $line;
+}
+fclose($fp);
?>
]]>
- </programlisting>
- </example>
- <para>
- See also <function>preg_replace</function>,
- <function>create_function</function>,
- &listendand; &seealso.callback;.
- </para>
- </refsect1>
- </refentry>
+ </programlisting>
+ </example>
+ <para>
+ See also <function>preg_replace</function>,
+ <function>create_function</function>,
+ &listendand; &seealso.callback;.
+ </para>
+ </refsect1>
+</refentry>
<!-- Keep this comment at the end of the file
Local variables:
http://cvs.php.net/diff.php/phpdoc/en/reference/pcre/functions/preg-replace.xml?r1=1.14&r2=1.15&ty=u
Index: phpdoc/en/reference/pcre/functions/preg-replace.xml
diff -u phpdoc/en/reference/pcre/functions/preg-replace.xml:1.14
phpdoc/en/reference/pcre/functions/preg-replace.xml:1.15
--- phpdoc/en/reference/pcre/functions/preg-replace.xml:1.14 Tue Dec 14
13:35:42 2004
+++ phpdoc/en/reference/pcre/functions/preg-replace.xml Sat Mar 12 15:29:57 2005
@@ -1,56 +1,56 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.14 $ -->
+<!-- $Revision: 1.15 $ -->
<!-- splitted from ./en/functions/pcre.xml, last change in rev 1.2 -->
- <refentry id="function.preg-replace">
- <refnamediv>
- <refname>preg_replace</refname>
- <refpurpose>Perform a regular expression search and replace</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <methodsynopsis>
- <type>mixed</type><methodname>preg_replace</methodname>
-
<methodparam><type>mixed</type><parameter>pattern</parameter></methodparam>
-
<methodparam><type>mixed</type><parameter>replacement</parameter></methodparam>
-
<methodparam><type>mixed</type><parameter>subject</parameter></methodparam>
- <methodparam
choice="opt"><type>int</type><parameter>limit</parameter></methodparam>
- </methodsynopsis>
- <para>
- Searches <parameter>subject</parameter> for matches to
- <parameter>pattern</parameter> and replaces them with
- <parameter>replacement</parameter>. If
- <parameter>limit</parameter> is specified, then only
- <parameter>limit</parameter> matches will be replaced; if
- <parameter>limit</parameter> is omitted or is -1, then all
- matches are replaced.
- </para>
- <para>
- <parameter>Replacement</parameter> may contain references of the form
- <literal>\\<replaceable>n</replaceable></literal> or (since PHP 4.0.4)
- <literal><replaceable>$n</replaceable></literal>, with the latter form
- being the preferred one. Every such reference will be replaced by the text
- captured by the <replaceable>n</replaceable>'th parenthesized pattern.
- <replaceable>n </replaceable>can be from 0 to 99, and
- <literal>\\0</literal> or <literal>$0</literal> refers to the text matched
- by the whole pattern. Opening parentheses are counted from left to right
- (starting from 1) to obtain the number of the capturing subpattern.
- </para>
- <para>
- When working with a replacement pattern where a backreference is
immediately
- followed by another number (i.e.: placing a literal number immediately
- after a matched pattern), you cannot use the familiar
<literal>\\1</literal>
- notation for your backreference. <literal>\\11</literal>, for example,
- would confuse <function>preg_replace</function> since it does not know
whether
- you want the <literal>\\1</literal> backreference followed by a literal
<literal>1</literal>,
- or the <literal>\\11</literal> backreference followed by nothing. In
this case
- the solution is to use <literal>\${1}1</literal>. This creates an
- isolated <literal>$1</literal> backreference, leaving the
<literal>1</literal>
- as a literal.
- </para>
- <para>
- <example>
- <title>Using backreferences followed by numeric literals</title>
- <programlisting role="php">
+<refentry id="function.preg-replace">
+ <refnamediv>
+ <refname>preg_replace</refname>
+ <refpurpose>Perform a regular expression search and replace</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>mixed</type><methodname>preg_replace</methodname>
+ <methodparam><type>mixed</type><parameter>pattern</parameter></methodparam>
+
<methodparam><type>mixed</type><parameter>replacement</parameter></methodparam>
+ <methodparam><type>mixed</type><parameter>subject</parameter></methodparam>
+ <methodparam
choice="opt"><type>int</type><parameter>limit</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ Searches <parameter>subject</parameter> for matches to
+ <parameter>pattern</parameter> and replaces them with
+ <parameter>replacement</parameter>. If
+ <parameter>limit</parameter> is specified, then only
+ <parameter>limit</parameter> matches will be replaced; if
+ <parameter>limit</parameter> is omitted or is -1, then all
+ matches are replaced.
+ </para>
+ <para>
+ <parameter>Replacement</parameter> may contain references of the form
+ <literal>\\<replaceable>n</replaceable></literal> or (since PHP 4.0.4)
+ <literal><replaceable>$n</replaceable></literal>, with the latter form
+ being the preferred one. Every such reference will be replaced by the text
+ captured by the <replaceable>n</replaceable>'th parenthesized pattern.
+ <replaceable>n </replaceable>can be from 0 to 99, and
+ <literal>\\0</literal> or <literal>$0</literal> refers to the text matched
+ by the whole pattern. Opening parentheses are counted from left to right
+ (starting from 1) to obtain the number of the capturing subpattern.
+ </para>
+ <para>
+ When working with a replacement pattern where a backreference is immediately
+ followed by another number (i.e.: placing a literal number immediately
+ after a matched pattern), you cannot use the familiar <literal>\\1</literal>
+ notation for your backreference. <literal>\\11</literal>, for example,
+ would confuse <function>preg_replace</function> since it does not know
whether
+ you want the <literal>\\1</literal> backreference followed by a literal
<literal>1</literal>,
+ or the <literal>\\11</literal> backreference followed by nothing. In this
case
+ the solution is to use <literal>\${1}1</literal>. This creates an
+ isolated <literal>$1</literal> backreference, leaving the
<literal>1</literal>
+ as a literal.
+ </para>
+ <para>
+ <example>
+ <title>Using backreferences followed by numeric literals</title>
+ <programlisting role="php">
<![CDATA[
<?php
$string = "April 15, 2003";
@@ -59,229 +59,219 @@
echo preg_replace($pattern, $replacement, $string);
?>
]]>
- </programlisting>
- <para>
- This example will output :
- </para>
- <screen>
+ </programlisting>
+ <para>
+ This example will output :
+ </para>
+ <screen>
<![CDATA[
April1,2003
]]>
- </screen>
- </example>
- </para>
- <para>
- If matches are found, the new <parameter>subject</parameter> will
- be returned, otherwise <parameter>subject</parameter> will be
- returned unchanged.
- </para>
- <para>
- Every parameter to <function>preg_replace</function> (except
- <parameter>limit</parameter>) can be an unidimensional array.
- When using arrays with <parameter>pattern</parameter> and
- <parameter>replacement</parameter>, the keys are processed in the order
- they appear in the array. This is <emphasis>not necessarily</emphasis>
- the same as the numerical index order. If you use indexes to identify
- which <parameter>pattern</parameter> should be replaced by which
- <parameter>replacement</parameter>, you should perform a
- <function>ksort</function> on each array prior to calling
- <function>preg_replace</function>.
- </para>
- <para>
- <example>
- <title>Using indexed arrays with
<function>preg_replace</function></title>
- <programlisting role="php">
+ </screen>
+ </example>
+ </para>
+ <para>
+ If matches are found, the new <parameter>subject</parameter> will
+ be returned, otherwise <parameter>subject</parameter> will be
+ returned unchanged.
+ </para>
+ <para>
+ Every parameter to <function>preg_replace</function> (except
+ <parameter>limit</parameter>) can be an unidimensional array.
+ When using arrays with <parameter>pattern</parameter> and
+ <parameter>replacement</parameter>, the keys are processed in the order
+ they appear in the array. This is <emphasis>not necessarily</emphasis>
+ the same as the numerical index order. If you use indexes to identify
+ which <parameter>pattern</parameter> should be replaced by which
+ <parameter>replacement</parameter>, you should perform a
+ <function>ksort</function> on each array prior to calling
+ <function>preg_replace</function>.
+ </para>
+ <para>
+ <example>
+ <title>Using indexed arrays with <function>preg_replace</function></title>
+ <programlisting role="php">
<![CDATA[
<?php
$string = "The quick brown fox jumped over the lazy dog.";
-
$patterns[0] = "/quick/";
$patterns[1] = "/brown/";
$patterns[2] = "/fox/";
-
$replacements[2] = "bear";
$replacements[1] = "black";
$replacements[0] = "slow";
-
echo preg_replace($patterns, $replacements, $string);
?>
]]>
- </programlisting>
- <para>
- Output:
- </para>
- <screen>
+ </programlisting>
+ <para>
+ Output:
+ </para>
+ <screen>
<![CDATA[
The bear black slow jumped over the lazy dog.
]]>
- </screen>
- <para>
- By ksorting patterns and replacements, we should get what we wanted.
- </para>
- <programlisting role="php">
+ </screen>
+ <para>
+ By ksorting patterns and replacements, we should get what we wanted.
+ </para>
+ <programlisting role="php">
<![CDATA[
<?php
-
ksort($patterns);
ksort($replacements);
-
echo preg_replace($patterns, $replacements, $string);
-
?>
]]>
- </programlisting>
- <para>
- Output :
- </para>
- <screen>
+ </programlisting>
+ <para>
+ Output :
+ </para>
+ <screen>
<![CDATA[
The slow black bear jumped over the lazy dog.
]]>
- </screen>
- </example>
- </para>
- <para>
- If <parameter>subject</parameter> is an array, then the search
- and replace is performed on every entry of
- <parameter>subject</parameter>, and the return value is an array
- as well.
- </para>
- <para>
- If <parameter>pattern</parameter> and <parameter>replacement</parameter>
- are arrays, then <function>preg_replace</function> takes a value from
- each array and uses them to do search and replace on
- <parameter>subject</parameter>. If <parameter>replacement</parameter>
- has fewer values than <parameter>pattern</parameter>, then empty string
- is used for the rest of replacement values. If <parameter>pattern
- </parameter> is an array and <parameter>replacement</parameter> is a
- string, then this replacement string is used for every value of
- <parameter>pattern</parameter>. The converse would not make sense,
- though.
- </para>
- <para>
- The <literal>e</literal> modifier makes <function>preg_replace</function>
- treat the <parameter>replacement</parameter> parameter as PHP code after
- the appropriate references substitution is done. Tip: make sure that
- <parameter>replacement</parameter> constitutes a valid PHP code string,
- otherwise PHP will complain about a parse error at the line containing
- <function>preg_replace</function>.
- </para>
- <para>
- <example>
- <title>Replacing several values</title>
- <programlisting role="php">
+ </screen>
+ </example>
+ </para>
+ <para>
+ If <parameter>subject</parameter> is an array, then the search
+ and replace is performed on every entry of
+ <parameter>subject</parameter>, and the return value is an array
+ as well.
+ </para>
+ <para>
+ If <parameter>pattern</parameter> and <parameter>replacement</parameter>
+ are arrays, then <function>preg_replace</function> takes a value from
+ each array and uses them to do search and replace on
+ <parameter>subject</parameter>. If <parameter>replacement</parameter>
+ has fewer values than <parameter>pattern</parameter>, then empty string
+ is used for the rest of replacement values. If <parameter>pattern
+ </parameter> is an array and <parameter>replacement</parameter> is a
+ string, then this replacement string is used for every value of
+ <parameter>pattern</parameter>. The converse would not make sense,
+ though.
+ </para>
+ <para>
+ The <literal>e</literal> modifier makes <function>preg_replace</function>
+ treat the <parameter>replacement</parameter> parameter as PHP code after
+ the appropriate references substitution is done. Tip: make sure that
+ <parameter>replacement</parameter> constitutes a valid PHP code string,
+ otherwise PHP will complain about a parse error at the line containing
+ <function>preg_replace</function>.
+ </para>
+ <para>
+ <example>
+ <title>Replacing several values</title>
+ <programlisting role="php">
<![CDATA[
<?php
$patterns = array ("/(19|20)(\d{2})-(\d{1,2})-(\d{1,2})/",
- "/^\s*{(\w+)}\s*=/");
+ "/^\s*{(\w+)}\s*=/");
$replace = array ("\\3/\\4/\\1\\2", "$\\1 =");
echo preg_replace($patterns, $replace, "{startDate} = 1999-5-27");
?>
]]>
- </programlisting>
- <para>
- This example will produce:
- </para>
- <screen>
+ </programlisting>
+ <para>
+ This example will produce:
+ </para>
+ <screen>
<![CDATA[
$startDate = 5/27/1999
]]>
- </screen>
- </example>
- </para>
- <para>
- <example>
- <title>Using the 'e' modifier</title>
- <programlisting role="php">
+ </screen>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title>Using the 'e' modifier</title>
+ <programlisting role="php">
<![CDATA[
<?php
preg_replace("/(<\/?)(\w+)([^>]*>)/e",
- "'\\1'.strtoupper('\\2').'\\3'",
- $html_body);
+ "'\\1'.strtoupper('\\2').'\\3'",
+ $html_body);
?>
]]>
- </programlisting>
- <para>
- This would capitalize all HTML tags in the input text.
- </para>
- </example>
- </para>
+ </programlisting>
<para>
- <example>
- <title>Convert HTML to text</title>
- <programlisting role="php">
+ This would capitalize all HTML tags in the input text.
+ </para>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title>Convert HTML to text</title>
+ <programlisting role="php">
<![CDATA[
<?php
// $document should contain an HTML document.
// This will remove HTML tags, javascript sections
// and white space. It will also convert some
// common HTML entities to their text equivalent.
-
$search = array ("'<script[^>]*?>.*?</script>'si", // Strip out javascript
- "'<[\/\!]*?[^<>]*?>'si", // Strip out HTML tags
- "'([\r\n])[\s]+'", // Strip out white space
- "'&(quot|#34);'i", // Replace HTML entities
- "'&(amp|#38);'i",
- "'&(lt|#60);'i",
- "'&(gt|#62);'i",
- "'&(nbsp|#160);'i",
- "'&(iexcl|#161);'i",
- "'&(cent|#162);'i",
- "'&(pound|#163);'i",
- "'&(copy|#169);'i",
- "'&#(\d+);'e"); // evaluate as php
-
+ "'<[\/\!]*?[^<>]*?>'si", // Strip out HTML tags
+ "'([\r\n])[\s]+'", // Strip out white space
+ "'&(quot|#34);'i", // Replace HTML entities
+ "'&(amp|#38);'i",
+ "'&(lt|#60);'i",
+ "'&(gt|#62);'i",
+ "'&(nbsp|#160);'i",
+ "'&(iexcl|#161);'i",
+ "'&(cent|#162);'i",
+ "'&(pound|#163);'i",
+ "'&(copy|#169);'i",
+ "'&#(\d+);'e"); // evaluate as php
$replace = array ("",
- "",
- "\\1",
- "\"",
- "&",
- "<",
- ">",
- " ",
- chr(161),
- chr(162),
- chr(163),
- chr(169),
- "chr(\\1)");
-
+ "",
+ "\\1",
+ "\"",
+ "&",
+ "<",
+ ">",
+ " ",
+ chr(161),
+ chr(162),
+ chr(163),
+ chr(169),
+ "chr(\\1)");
$text = preg_replace($search, $replace, $document);
?>
]]>
- </programlisting>
- </example>
- </para>
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title>Strip whitespace</title>
<para>
- <example>
- <title>Strip whitespace</title>
- <para>
- This example strips excess whitespace from a string.
- </para>
- <programlisting role="php">
+ This example strips excess whitespace from a string.
+ </para>
+ <programlisting role="php">
<![CDATA[
<?php
$str = 'foo o';
$str = preg_replace('/\s\s+/', ' ', $str);
-
// This will be 'foo o' now
echo $str;
?>
]]>
- </programlisting>
- </example>
- </para>
- <note>
- <para>
- Parameter <parameter>limit</parameter> was added after PHP 4.0.1pl2.
- </para>
- </note>
- <para>
- See also <function>preg_match</function>,
- <function>preg_match_all</function>, and
- <function>preg_split</function>.
- </para>
- </refsect1>
- </refentry>
+ </programlisting>
+ </example>
+ </para>
+ <note>
+ <para>
+ Parameter <parameter>limit</parameter> was added after PHP 4.0.1pl2.
+ </para>
+ </note>
+ <para>
+ See also <function>preg_match</function>,
+ <function>preg_match_all</function>, and
+ <function>preg_split</function>.
+ </para>
+ </refsect1>
+</refentry>
<!-- Keep this comment at the end of the file
Local variables:
