zak Sun Jul 1 23:03:44 2001 EDT
Modified files:
/phpdoc/en/language control-structures.xml
Log:
Clarified declare/ticks documentation
Made ticks a sect2 within declare's sect1
Added an illustrative example for ticks
Index: phpdoc/en/language/control-structures.xml
diff -u phpdoc/en/language/control-structures.xml:1.30
phpdoc/en/language/control-structures.xml:1.31
--- phpdoc/en/language/control-structures.xml:1.30 Tue Jun 26 08:32:47 2001
+++ phpdoc/en/language/control-structures.xml Sun Jul 1 23:03:43 2001
@@ -68,7 +68,7 @@
program.
</simpara>
</sect1>
-
+
<sect1 id="control-structures.else">
<title><literal>else</literal></title>
<para>
@@ -101,7 +101,7 @@
</para>
</sect1>
-
+
<sect1 id="control-structures.elseif">
<title><literal>elseif</literal></title>
<para>
@@ -149,7 +149,7 @@
<literal>TRUE</literal>.
</simpara>
</sect1>
-
+
<sect1 id="control-structures.alternative-syntax">
<title>Alternative syntax for control structures</title>
<para>
@@ -166,8 +166,8 @@
</para>
<para>
PHP offers an alternative syntax for some of its control
- structures; namely, <literal>if</literal>,
- <literal>while</literal>, <literal>for</literal>,
+ structures; namely, <literal>if</literal>,
+ <literal>while</literal>, <literal>for</literal>,
<literal>foreach</literal>, and <literal>switch</literal>.
In each case, the basic form of the alternate syntax is to change
the opening brace to a colon (:) and the closing brace to
@@ -262,9 +262,9 @@
$i before the increment
(post-increment) */
}
-
+
/* example 2 */
-
+
$i = 1;
while ($i <= 10):
print $i;
@@ -274,7 +274,7 @@
</informalexample>
</para>
</sect1>
-
+
<sect1 id="control-structures.do.while">
<title><literal>do..while</literal></title>
<simpara>
@@ -292,7 +292,7 @@
</simpara>
<para>
There is just one syntax for <literal>do..while</literal> loops:
-
+
<informalexample>
<programlisting role="php">
$i = 0;
@@ -340,7 +340,7 @@
`feature'.
</simpara>
</sect1>
-
+
<sect1 id="control-structures.for">
<title><literal>for</literal></title>
<para>
@@ -386,22 +386,22 @@
<informalexample>
<programlisting role="php">
/* example 1 */
-
+
for ($i = 1; $i <= 10; $i++) {
print $i;
}
-
+
/* example 2 */
-
+
for ($i = 1;;$i++) {
if ($i > 10) {
break;
}
print $i;
}
-
+
/* example 3 */
-
+
$i = 1;
for (;;) {
if ($i > 10) {
@@ -410,9 +410,9 @@
print $i;
$i++;
}
-
+
/* example 4 */
-
+
for ($i = 1; $i <= 10; print $i, $i++) ;
</programlisting>
</informalexample>
@@ -449,7 +449,7 @@
<title><literal>foreach</literal></title>
<para>
PHP 4 (not PHP 3) includes a <literal>foreach</literal> construct,
- much like perl and some other languages. This simply gives an easy
+ much like perl and some other languages. This simply gives an easy
way to iterate over arrays. There are two syntaxes; the second is
a minor but useful extension of the first:
<informalexample>
@@ -475,7 +475,7 @@
<note>
<para>
When <literal>foreach</literal> first starts executing, the
- internal array pointer is automatically reset to the first element
+ internal array pointer is automatically reset to the first element
of the array. This means that you do not need to call
<function>reset</function> before a <literal>foreach</literal>
loop.
@@ -585,7 +585,7 @@
</informalexample>
</para>
</sect1>
-
+
<sect1 id="control-structures.break">
<title><literal>break</literal></title>
<simpara>
@@ -596,7 +596,7 @@
<simpara>
<literal>break</literal> accepts an optional numeric argument
which tells it how many nested enclosing structures are to be
- broken out of.
+ broken out of.
</simpara>
<para>
<informalexample>
@@ -628,7 +628,7 @@
</informalexample>
</para>
</sect1>
-
+
<sect1 id="control-structures.continue">
<title><literal>continue</literal></title>
<simpara>
@@ -668,7 +668,7 @@
</informalexample>
</para>
</sect1>
-
+
<sect1 id="control-structures.switch">
<title><literal>switch</literal></title>
<simpara>
@@ -678,7 +678,7 @@
different values, and execute a different piece of code depending
on which value it equals to. This is exactly what the
<literal>switch</literal> statement is for.
- </simpara>
+ </simpara>
<para>
The following two examples are two different ways to write the
same thing, one using a series of <literal>if</literal>
@@ -695,7 +695,7 @@
if ($i == 2) {
print "i equals 2";
}
-
+
switch ($i) {
case 0:
print "i equals 0";
@@ -823,47 +823,112 @@
</informalexample>
</para>
</sect1>
-
+
<sect1 id="control-structures.declare">
<title><literal>declare</literal></title>
- <simpara>
- The <literal>declare</literal> statement is used to temporarily
- change the state of the parser in a block of code. Here's how it looks:
- </simpara>
<para>
+ The <literal>declare</literal> construct is used to is
+ used to set execution directives for a block of code.
+ The syntax of <literal>declare</literal> is similiar to
+ the syntax of other flow control constructs:
<informalexample>
+ <programlisting>
+declare (directive) statement
+ </programlisting>
+ </informalexample>
+ </para>
+ <para>
+ The <literal>directive</literal> section allows the
+ behavior of the <literal>declare</literal> block to
+ be set.
+ Currently only one directive is recognized: the
+ <literal>ticks</literal> directive. (See below for more
+ information on the
+ <link linkend="control-structures.declare.ticks">ticks</link>
+ directive)
+ </para>
+ <para>
+ The <literal>statement</literal> part of the
+ <literal>declare</literal> block will be executed - how
+ it is executed and what side-effects occur during execution
+ may depend on the directive set in the
+ <literal>directive</literal> block.
+ </para>
+ <sect2 id="control-structures.declare.ticks">
+ <title>Ticks</title>
+ <para>A tick is an event that occurs for every
+ <replaceable>N</replaceable> low-level statements executed
+ by the parser within the <literal>declare</literal> block.
+ The value for <replaceable>N</replaceable> is specified
+ using <literal>ticks=<replaceable>N</replaceable></literal>
+ within the <literal>declare</literal> blocks's
+ <literal>directive</literal> section.
+ </para>
+ <para>
+ The event(s) that occurs on each tick is specified using the
+ <function>register_tick_function</function>. See the example
+ below for more details. Note that more than one event can occur
+ for each tick.
+ </para>
+ <para>
+ <example>
+ <title>Profile a section of PHP code</title>
<programlisting role="php">
-function tick()
+<pre>
+<?php
+// A function that records the time when it is called
+function profile ($dump = FALSE)
{
- static $i;
- printf("[tick i=%d]\n", ++$i);
+ static $profile;
+
+ // Return the times stored in profile, then erase it
+ if ($dump) {
+ $temp = $profile;
+ unset ($profile);
+ return ($temp);
+ }
+
+ $profile[] = microtime ();
}
-register_tick_function("tick");
+// Set up a tick handler
+register_tick_function("profile");
-declare (ticks = 2) {
- 1; 2; 3;
+// Initialize the function before the declare block
+profile ();
+
+// Run a block of code, throw a tick every 2nd statement
+declare (ticks=2) {
+ for ($x = 1; $x < 50; ++$x) {
+ echo similar_text (md5($x), md5($x*$x)), "<br>";
+ }
}
-</programlisting>
- </informalexample>
- This example shows the only implemented parser parameter today:
- ticks. A tick is an event that occurs for every
- <replaceable>N</replaceable> low-level statements executed by the
- parser, where <replaceable>N</replaceable> is specified in the
- <literal>declare</literal> statement. The example above will print:
- <computeroutput>[tick i=1]
-[tick i=2]
-</computeroutput>
+
+// Display the data stored in the profiler
+print_r (profile (TRUE));
+?>
+</pre>
+ </programlisting>
+ </example>
+ The example profiles the PHP code within the 'declare'
+ block, recording the time at which every second low-level
+ statement in the block was executed. This information can
+ then be used to find the slow areas within particular
+ segments of code. This process can be performed using other
+ methods: using ticks is more convenient and easier to
+ implement.
</para>
<simpara>
- Ticks is well suited for implementing simple multitasking,
- backgrounded IO and many other things in PHP.
+ Ticks are well suited for debugging, implementing simple
+ multitasking, backgrounded I/O and many other tasks.
</simpara>
<simpara>
See also <function>register_tick_function</function> and
<function>unregister_tick_function</function>.
</simpara>
+ </sect2>
</sect1>
+
<sect1 id="function.require">
<title><function>require</function></title>
<simpara>
@@ -947,7 +1012,7 @@
<informalexample>
<programlisting role="php">
/* This example assumes that someserver is configured to parse .php
- * files and not .txt files. Also, 'works' here means that the variables
+ * files and not .txt files. Also, 'works' here means that the variables
* $varone and $vartwo are available within the require()ed file. */
/* Won't work; file.txt wasn't handled by someserver. */
@@ -955,10 +1020,10 @@
/* Won't work; looks for a file named 'file.php?varone=1&vartwo=2'
* on the local filesystem. */
-require ("file.php?varone=1&vartwo=2");
+require ("file.php?varone=1&vartwo=2");
/* Works. */
-require ("http://someserver/file.php?varone=1&vartwo=2";);
+require ("http://someserver/file.php?varone=1&vartwo=2";);
$varone = 1;
$vartwo = 2;
@@ -979,10 +1044,10 @@
<simpara>
See also <function>include</function>, <function>require_once</function>,
<function>include_once</function>, <function>readfile</function>,
- and <function>virtual</function>.
+ and <function>virtual</function>.
</simpara>
</sect1>
-
+
<sect1 id="function.include">
<title><function>include</function></title>
<simpara>
@@ -1038,14 +1103,14 @@
<informalexample>
<programlisting role="php">
/* This is WRONG and will not work as desired. */
-
+
if ($condition)
include($file);
else
include($other);
-
+
/* This is CORRECT. */
-
+
if ($condition) {
include($file);
} else {
@@ -1123,7 +1188,7 @@
</screen>
However, PHP 3 will give the following output:
<screen>
-Before the return
+Before the return
27Back in main.html
Parse error: parse error in /home/torben/public_html/phptest/main.html on line 5
@@ -1167,7 +1232,7 @@
<informalexample>
<programlisting role="php">
/* This example assumes that someserver is configured to parse .php
- * files and not .txt files. Also, 'works' here means that the variables
+ * files and not .txt files. Also, 'works' here means that the variables
* $varone and $vartwo are available within the include()ed file. */
/* Won't work; file.txt wasn't handled by someserver. */
@@ -1175,10 +1240,10 @@
/* Won't work; looks for a file named 'file.php?varone=1&vartwo=2'
* on the local filesystem. */
-include ("file.php?varone=1&vartwo=2");
+include ("file.php?varone=1&vartwo=2");
/* Works. */
-include ("http://someserver/file.php?varone=1&vartwo=2";);
+include ("http://someserver/file.php?varone=1&vartwo=2";);
$varone = 1;
$vartwo = 2;
@@ -1190,58 +1255,58 @@
<simpara>
See also <function>require</function>, <function>require_once</function>,
<function>include_once</function>, <function>readfile</function>,
- and <function>virtual</function>.
+ and <function>virtual</function>.
</simpara>
</sect1>
-
+
<sect1 id="function.require-once">
<title><function>require_once</function></title>
<para>
The <function>require_once</function> statement replaces
itself with the specified file, much like the C preprocessor's
<literal>#include</literal> works, and in that respect is
- similar to the <function>require</function> statement. The main
- difference is that in an inclusion chain, the use of
- <function>require_once</function> will assure that the code is
- added to your script only once, and avoid clashes with variable
- values or function names that can happen.
+ similar to the <function>require</function> statement. The main
+ difference is that in an inclusion chain, the use of
+ <function>require_once</function> will assure that the code is
+ added to your script only once, and avoid clashes with variable
+ values or function names that can happen.
</para>
<para>
For example, if you create the following 2 include files
- <literal>utils.inc</literal> and <literal>foolib.inc</literal>
- <example>
- <title>utils.inc</title>
- <programlisting role="php">
+ <literal>utils.inc</literal> and <literal>foolib.inc</literal>
+ <example>
+ <title>utils.inc</title>
+ <programlisting role="php">
<?php
define(PHPVERSION, floor(phpversion()));
echo "GLOBALS ARE NICE\n";
function goodTea() {
- return "Oolong tea tastes good!";
+ return "Oolong tea tastes good!";
}
?>
- </programlisting>
- </example>
- <example>
- <title>foolib.inc</title>
- <programlisting role="php">
+ </programlisting>
+ </example>
+ <example>
+ <title>foolib.inc</title>
+ <programlisting role="php">
<?php
require ("utils.inc");
function showVar($var) {
- if (PHPVERSION == 4) {
- print_r($var);
- } else {
- var_dump($var);
- }
+ if (PHPVERSION == 4) {
+ print_r($var);
+ } else {
+ var_dump($var);
+ }
}
// bunch of other functions ...
?>
- </programlisting>
- </example>
- And then you write a script <literal>cause_error_require.php</literal>
- <example>
- <title>cause_error_require.php</title>
- <programlisting role="php">
+ </programlisting>
+ </example>
+ And then you write a script <literal>cause_error_require.php</literal>
+ <example>
+ <title>cause_error_require.php</title>
+ <programlisting role="php">
<?php
require("foolib.inc");
/* the following will generate an error */
@@ -1253,45 +1318,45 @@
echo "Printing foo: \n";
showVar($foo);
?>
- </programlisting>
- </example>
- When you try running the latter one, the resulting ouptut will be (using
- PHP 4.01pl2):
- <informalexample>
- <programlisting>
+ </programlisting>
+ </example>
+ When you try running the latter one, the resulting ouptut will be (using
+ PHP 4.01pl2):
+ <informalexample>
+ <programlisting>
GLOBALS ARE NICE
GLOBALS ARE NICE
Fatal error: Cannot redeclare goodTea() in utils.inc on line 5
- </programlisting>
- </informalexample>
- By modifying <literal>foolib.inc</literal> and
- <literal>cause_errror_require.php</literal>
- to use <function>require_once</function>
- instead of <function>require</function> and renaming the
- last one to <literal>avoid_error_require_once.php</literal>, we have:
- <example>
- <title>foolib.inc (fixed)</title>
- <programlisting role="php">
+ </programlisting>
+ </informalexample>
+ By modifying <literal>foolib.inc</literal> and
+ <literal>cause_errror_require.php</literal>
+ to use <function>require_once</function>
+ instead of <function>require</function> and renaming the
+ last one to <literal>avoid_error_require_once.php</literal>, we have:
+ <example>
+ <title>foolib.inc (fixed)</title>
+ <programlisting role="php">
...
require_once("utils.inc");
function showVar($var) {
...
- </programlisting>
- </example>
- <example>
- <title>avoid_error_require_once.php</title>
- <programlisting role="php">
+ </programlisting>
+ </example>
+ <example>
+ <title>avoid_error_require_once.php</title>
+ <programlisting role="php">
...
require_once("foolib.inc");
require_once("utils.inc");
$foo = array("1",array("complex","quaternion"));
...
- </programlisting>
- </example>
- And when running the latter, the output will be (using PHP 4.0.1pl2):
- <informalexample>
- <programlisting>
+ </programlisting>
+ </example>
+ And when running the latter, the output will be (using PHP 4.0.1pl2):
+ <informalexample>
+ <programlisting>
GLOBALS ARE NICE
this is requiring globals.inc again which is also
required in foolib.inc
@@ -1307,53 +1372,53 @@
)
)
- </programlisting>
- </informalexample>
+ </programlisting>
+ </informalexample>
</para>
<para>
Also note that, analogous to the behavior of the
- <literal>#include</literal> of the C preprocessor, this statement
- acts at "compile time", e.g. when the script is parsed and before it
- is executed, and should not be used for parts of the script that need
- to be inserted dynamically during its execution. You should use
- <function>include_once</function> or <function>include</function>
- for that purpose.
+ <literal>#include</literal> of the C preprocessor, this statement
+ acts at "compile time", e.g. when the script is parsed and before it
+ is executed, and should not be used for parts of the script that need
+ to be inserted dynamically during its execution. You should use
+ <function>include_once</function> or <function>include</function>
+ for that purpose.
</para>
<para>
- For more examples on using <function>require_once</function> and
- <function>include_once</function>, look at the PEAR code included in
- the latest PHP source code distributions.
+ For more examples on using <function>require_once</function> and
+ <function>include_once</function>, look at the PEAR code included in
+ the latest PHP source code distributions.
</para>
<para>
See also: <function>require</function>,
<function>include</function>, <function>include_once</function>,
<function>get_required_files</function>,
<function>get_included_files</function>, <function>readfile</function>,
- and <function>virtual</function>.
+ and <function>virtual</function>.
</para>
</sect1>
-
+
<sect1 id="function.include-once">
<title><function>include_once</function></title>
<para>
The <function>include_once</function> statement includes and evaluates
the specified file during the execution of the script.
- This is a behavior similar to the <function>include</function> statement,
- with the important difference that if the code from a file has already
- been included, it will not be included again.
+ This is a behavior similar to the <function>include</function> statement,
+ with the important difference that if the code from a file has already
+ been included, it will not be included again.
</para>
<para>
As mentioned in the <function>require_once</function> description, the
- <function>include_once</function> should be used in the cases in which
- the same file might be included and evaluated more than once during a
- particular execution of a script, and you want to be sure that it is
- included exactly once to avoid problems with function redefinitions,
- variable value reassignments, etc.
+ <function>include_once</function> should be used in the cases in which
+ the same file might be included and evaluated more than once during a
+ particular execution of a script, and you want to be sure that it is
+ included exactly once to avoid problems with function redefinitions,
+ variable value reassignments, etc.
</para>
<para>
- For more examples on using <function>require_once</function> and
- <function>include_once</function>, look at the PEAR code included in
- the latest PHP source code distributions.
+ For more examples on using <function>require_once</function> and
+ <function>include_once</function>, look at the PEAR code included in
+ the latest PHP source code distributions.
</para>
<para>
<function>include_once</function> was added in PHP 4.0.1pl2
@@ -1363,12 +1428,12 @@
<function>include</function>, <function>require_once</function>,
<function>get_required_files</function>,
<function>get_included_files</function>, <function>readfile</function>,
- and <function>virtual</function>.
+ and <function>virtual</function>.
</para>
</sect1>
-
+
</chapter>
-
+
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
@@ -1387,4 +1452,4 @@
-->
<!-- Keep this comment for vi/vim/gvim
vi: et:ts=1:sw=1
--->
+-->
