From a9c9d5f2ad488a2bdbf225dc13f4ed0b8e745add Mon Sep 17 00:00:00 2001
From: Gwynne Raskind <gwynne@php.net>
Date: Thu, 21 Feb 2008 19:50:29 +0000
Subject: [PATCH] added documentation for nowdocs

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@253479 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language/types/string.xml | 116 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 111 insertions(+), 5 deletions(-)

diff --git a/language/types/string.xml b/language/types/string.xml
index e9c9c34131..5e2100898b 100644
--- a/language/types/string.xml
+++ b/language/types/string.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <sect1 xml:id="language.types.string">
  <title>Strings</title>
 
@@ -23,7 +23,7 @@
   <title>Syntax</title>
 
   <para>
-   A <type>string</type> literal can be specified in three different ways:
+   A <type>string</type> literal can be specified in four different ways:
   </para>
 
   <itemizedlist>
@@ -42,6 +42,12 @@
      <link linkend="language.types.string.syntax.heredoc">heredoc syntax</link>
     </simpara>
    </listitem>
+   <listitem>
+    <simpara>
+     <link linkend="language.types.string.syntax.nowdoc">nowdoc syntax</link>
+     (since PHP 5.3)
+    </simpara>
+   </listitem>
   </itemizedlist>
 
   <sect3 xml:id="language.types.string.syntax.single">
@@ -222,8 +228,8 @@ echo 'Variables do not $expand $either';
     </simpara>
 
     <para>
-     Heredocs can not be used for initializing class members. Use other
-     <type>string</type> syntaxes instead.
+     Heredocs can not be used for initializing class members. Use
+     <link linkend="language.types.string.syntax.nowdoc">nowdocs</link> instead.
     </para>
     
     <example>
@@ -286,7 +292,13 @@ EOT;
 ]]>
     </programlisting>
    </example>
-
+   &example.outputs;
+   <screen>
+<![CDATA[
+My name is "MyName". I am printing some foo.
+Now I am printing some Bar2.
+This should print a capital 'A': \x41]]></screen>
+   
    <note>
     <para>
      Heredoc support was added in PHP 4.
@@ -294,6 +306,100 @@ EOT;
    </note>
 
   </sect3>
+  
+  <sect3 xml:id="language.types.string.syntax.nowdoc">
+   <title>Nowdoc</title>
+   
+   <para>
+    Nowdocs are to single-quoted strings what heredocs are to double-quoted
+    strings. A nowdoc is specified similarly to a heredoc, but <emphasis>no
+    parsing is done</emphasis> inside a nowdoc. The construct is ideal for
+    embedding PHP code or other large blocks of text without the need for
+    escaping. It shares some features in common with the SGML
+    <literal>&amp;lt;![CDATA[ ]]&amp;gt;</literal> construct, in that it declares a
+    block of text which is not for parsing.
+   </para>
+   
+   <para>
+    A nowdoc is identified with the same <literal>&lt;&lt;&lt;</literal>
+    seqeuence used for heredocs, but the identifier which follows is enclosed in
+    single quotes, e.g. <literal>&lt;&lt;&lt;'EOT'</literal>. All the rules for
+    heredoc identifiers also apply to nowdoc identifiers, especially those
+    regarding the appearance of the closing identifier.
+   </para>
+   
+   <example>
+    <title>Nowdoc string quoting example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$str = <<<'EOD'
+Example of string
+spanning multiple lines
+using nowdoc syntax.
+EOD;
+
+/* More complex example, with variables. */
+class foo
+{
+    var $foo;
+    var $bar;
+
+    function foo()
+    {
+        $this->foo = 'Foo';
+        $this->bar = array('Bar1', 'Bar2', 'Bar3');
+    }
+}
+
+$foo = new foo();
+$name = 'MyName';
+
+echo <<<'EOT'
+My name is "$name". I am printing some $foo->foo.
+Now, I am printing some {$foo->bar[1]}.
+This should not print a capital 'A': \x41
+EOT;
+?>
+]]>
+    </programlisting>
+   </example>
+   &example.outputs;
+   <screen>
+<![CDATA[
+My name is "$name". I am printing some $foo->foo.
+Now, I am printing some {$foo->bar[1]}.
+This should not print a capital 'A': \x41]]></screen>
+   
+   <note>
+    <para>
+     Unlike heredocs, nowdocs can be used in any static data context. The
+     typical example is initializing class members or constants:
+    </para>
+    
+    <example>
+     <title>Static data example</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+class foo {
+    public $bar = <<<'EOT'
+bar
+EOT;
+}
+?>
+]]>
+     </programlisting>
+    </example>
+   </note>
+
+   <note>
+    <para>
+     Nowdoc support was added in PHP 5.3.
+    </para>
+   </note>
+
+  </sect3>
 
   <sect3 xml:id="language.types.string.parsing">
    <title>Variable parsing</title>