WS. prepare for new doc style

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@181961 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Nuno Lopes 2005-03-12 20:29:57 +00:00
parent 773763148a
commit e5dacc095d
2 changed files with 287 additions and 301 deletions

View file

@ -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:

View file

@ -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 @@ $replacement = "\${1}1,\$3";
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: