php-doc-en/reference/pcre/reference.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<reference id="ref.pcre">
  <title>Regular Expression Functions (Perl-Compatible)</title>
  <titleabbrev>PCRE</titleabbrev>   

  <partintro>
   <para id="pcre.intro">
    The syntax for patterns used in these functions closely resembles
    Perl. The expression should be enclosed in the delimiters, a
    forward slash (/), for example.  Any character can be used for
    delimiter as long as it's not alphanumeric or backslash (\). If
    the delimiter character has to be used in the expression itself,
    it needs to be escaped by backslash. Since PHP 4.0.4, you can also use
    Perl-style (), {}, [], and &lt;&gt; matching delimiters.
   </para>
   <para>
    The ending delimiter may be followed by various modifiers that
    affect the matching. 
    See <link linkend="pcre.pattern.modifiers">Pattern Modifiers</link>.
   </para>
   <para>
    PHP also supports regular expressions using a POSIX-extended syntax
    using the <link linkend="ref.regex">POSIX-extended regex functions.</link>.
   </para>
   
   <section id="pcre.requirements">
    <title>Requirements</title>
    <para>
     Regular expression support is provided by the PCRE library
     package, which is open source software, written by Philip Hazel,
     and copyright by the University of Cambridge, England. It is
     available at <ulink url="&url.pcre;">&url.pcre;</ulink>.
    </para>
   </section>
    
   <section id="pcre.installation">
    <title>Installation</title>
    <para>
     Beginning with PHP 4.2.0 this function are enabled by default.
     For older versions you have to configure and compile PHP 
     with <option role="configure">--with-pcre-regex[=DIR]</option> in order
     to use these functions. You can disable the pcre functions with <option
     role="configure">--without-pcre-regex</option>.
    </para>
   </section>

   <section id="pcre.configuration">
    <title>Runtime Configuration</title>
     &no.config;
   </section>

   <section id="pcre.resources">
    <title>Resource types</title>
     &no.resource;
   </section>

   <section id="pcre.constants">
    <title>Predefined constants</title>
    <para>
     <table>
      <title>PREG constants</title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>constant</entry>
         <entry>description</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>PREG_PATTERN_ORDER</entry>
         <entry>
          Orders results so that $matches[0] is an array of full pattern
          matches, $matches[1] is an array of strings matched by the first
          parenthesized subpattern, and so on. This flag is only used with
          <function>preg_match_all</function>.
         </entry>
        </row>
        <row>
         <entry>PREG_SET_ORDER</entry>
         <entry>
          Orders results so that $matches[0] is an array of first set of
          matches, $matches[1] is an array of second set of matches, and so
          on. This flag is only used with <function>preg_match_all</function>.
         </entry>
        </row>
        <row>
         <entry>PREG_OFFSET_CAPTURE</entry>
         <entry>
          See the description of
          <constant>PREG_SPLIT_OFFSET_CAPTURE</constant>.  This flag is
          available since <literal>PHP</literal> 4.3.0 .
         </entry>
        </row>
        <row>
         <entry>PREG_SPLIT_NO_EMPTY</entry>
         <entry>
          This flag tells <function>preg_split</function> to only return only
          non-empty pieces.
         </entry>
        </row>
        <row>
         <entry>PREG_SPLIT_DELIM_CAPTURE</entry>
         <entry>
          This flag tells <function>preg_split</function> to capture
          parenthesized expression in the delimiter pattern as well. This flag
          is available since <literal>PHP</literal> 4.0.5 .
         </entry>
        </row>
        <row>
         <entry>PREG_SPLIT_OFFSET_CAPTURE</entry>
         <entry>
          If this flag is set, for every occuring match the appendant string
          offset will also be returned. Note that this changes the return
          value in an array where very element is an array consisting of the
          matched string at offset 0 and it's string offset into subject at
          offset 1. This flag is available since <literal>PHP</literal> 4.3.0
          and is only used for <function>preg_split</function>.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
   </section>

   <section id="pcre.examples">
    <title>Examples</title>
    <para>
     <example>
      <title>Examples of valid patterns</title>
      <itemizedlist>
       <listitem><simpara><literal>/&lt;\/\w+&gt;/</literal></simpara></listitem>
       <listitem><simpara><literal>|(\d{3})-\d+|Sm</literal></simpara></listitem>
       <listitem><simpara><literal>/^(?i)php[34]/</literal></simpara></listitem>
       <listitem><simpara><literal>{^\s+(\s+)?$}</literal></simpara></listitem>
      </itemizedlist>
     </example>
    </para>
    <para>
     <example>
      <title>Examples of invalid patterns</title>
      <itemizedlist>
       <listitem>
        <simpara>
         <literal>/href='(.*)'</literal> - missing ending delimiter
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         <literal>/\w+\s*\w+/J</literal> - unknown modifier 'J'
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         <literal>1-\d3-\d3-\d4|</literal> - missing starting delimiter
        </simpara>
       </listitem>
      </itemizedlist>
     </example>
    </para>
   </section>

  </partintro>

&reference.pcre.functions;

</reference>

<!-- 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:"../../../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
-->