Hi all,
I've got a few additions to the language-section of the documentation.
Since I don't have a CVS account, whould anyone please commit these?
(a long time ago I already said I would write this, but I gave up when I
read about sgml,xml,cvs,dtd,etc, all terms i had never heard of
before...)
There is much more to come, as I'm by now an experienced php-programmer,
making money with it, so I feel I should do something back in
return. (in the end, my customers pay for it, but they don't know :)
Comments are more than welcome.
I hope pine didn't break any lines below. the diff can alse be found at
http://www.a-es2.uu.nl/~jeroen/diff
Greetz,
Jeroen
Jeroen van Wolffelaar
[EMAIL PROTECTED]
http://www.A-Eskwadraat.nl/~jeroen
The diff:
diff -c9 orig/basic-syntax.xml new/basic-syntax.xml
*** orig/basic-syntax.xml Tue May 8 20:03:08 2001
--- new/basic-syntax.xml Tue May 8 20:03:44 2001
***************
*** 7,24 ****
--- 7,25 ----
<para>
There are four ways of escaping from HTML and entering "PHP code
mode":</para>
<para>
<example>
<title>Ways of escaping from HTML</title>
<programlisting>
1. <? echo ("this is the simplest, an SGML processing
instruction\n"); ?>
+ <?= expression ?> This is a shortcut for "<? echo expr
?>
2. <?php echo("if you want to serve XHTML or XML documents, do
like this\n"); ?>
3. <script language="php">
echo ("some editors (like FrontPage) don't
like processing instructions");
</script>
4. <% echo ("You may optionally use ASP-style tags"); %>
diff -c9 orig/constants.xml new/constants.xml
*** orig/constants.xml Tue May 8 20:03:11 2001
--- new/constants.xml Tue May 8 20:03:47 2001
***************
*** 9,39 ****
redefined to another value.
</simpara>
<para>
The predefined constants (always available) are:
<variablelist>
<varlistentry>
! <term>__FILE__</term>
<listitem>
<simpara>
The name of the script file presently being parsed. If used
within a file which has been included or required, then the
name of the included file is given, and not the name of the
parent file.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
! <term>__LINE__</term>
<listitem>
<simpara>
The number of the line within the current script file which is
being parsed. If used within a file which has been included or
required, then the position within the included file is given.
</simpara>
</listitem>
</varlistentry>
--- 9,39 ----
redefined to another value.
</simpara>
<para>
The predefined constants (always available) are:
<variablelist>
<varlistentry>
! <term>__FILE__ (case-insensitive)</term>
<listitem>
<simpara>
The name of the script file presently being parsed. If used
within a file which has been included or required, then the
name of the included file is given, and not the name of the
parent file.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
! <term>__LINE__ (case-insensitive)</term>
<listitem>
<simpara>
The number of the line within the current script file which is
being parsed. If used within a file which has been included or
required, then the position within the included file is given.
</simpara>
</listitem>
</varlistentry>
***************
*** 52,79 ****
<listitem>
<simpara>
The name of the operating system on which the PHP parser is
executing; e.g. 'Linux'.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
! <term>TRUE</term>
<listitem>
<simpara>
A true value.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
! <term>FALSE</term>
<listitem>
<simpara>
A false value.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>E_ERROR</term>
--- 52,79 ----
<listitem>
<simpara>
The name of the operating system on which the PHP parser is
executing; e.g. 'Linux'.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
! <term>TRUE (case-insensitive)</term>
<listitem>
<simpara>
A true value.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
! <term>FALSE (case-insensitive)</term>
<listitem>
<simpara>
A false value.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>E_ERROR</term>
diff -c9 orig/expressions.xml new/expressions.xml
*** orig/expressions.xml Tue May 8 20:03:21 2001
--- new/expressions.xml Tue May 8 20:03:55 2001
***************
*** 165,191 ****
this case, a statement has the form of 'expr' ';' that is, an
expression followed by a semicolon. In '$b=$a=5;', $a=5 is a
valid expression, but it's not a statement by itself. '$b=$a=5;'
however is a valid statement.</simpara>
<simpara>
One last thing worth mentioning is the truth value of expressions.
In many events, mainly in conditional execution and loops, you're
not interested in the specific value of the expression, but only
! care about whether it means TRUE or FALSE (PHP doesn't have a
! dedicated boolean type). The truth value of expressions in PHP is
! calculated in a similar way to perl. Any numeric non-zero numeric
! value is TRUE, zero is FALSE. Be sure to note that negative
! values are non-zero and are thus considered TRUE! The empty
! string and the string "0" are FALSE; all other strings are TRUE.
! With non-scalar values (arrays and objects) - if the value
! contains no elements it's considered FALSE, otherwise it's
! considered TRUE.</simpara>
<simpara>
PHP provides a full and powerful implementation of expressions,
and
documenting it entirely goes beyond the scope of this manual. The
above examples should give you a good idea about what expressions
are and how you can construct useful expressions. Throughout the
rest of this manual we'll write <replaceable>expr</replaceable>
to indicate any valid PHP expression.</simpara>
--- 165,193 ----
this case, a statement has the form of 'expr' ';' that is, an
expression followed by a semicolon. In '$b=$a=5;', $a=5 is a
valid expression, but it's not a statement by itself. '$b=$a=5;'
however is a valid statement.</simpara>
<simpara>
One last thing worth mentioning is the truth value of expressions.
In many events, mainly in conditional execution and loops, you're
not interested in the specific value of the expression, but only
! care about whether it means TRUE or FALSE.
!
! <!-- (PHP doesn't have a
! dedicated boolean type) : WRONG, php does. -->
!
! The constants TRUE and FALSE (case-insensitive) are the two
! possible boolean values. When necessary, an expression is
! autmatically converted to boolean. See the
! <link linked="language.types.typecasting">section about
! type-casting</link> for details about how.
! </simpara>
<simpara>
PHP provides a full and powerful implementation of expressions,
and
documenting it entirely goes beyond the scope of this manual. The
above examples should give you a good idea about what expressions
are and how you can construct useful expressions. Throughout the
rest of this manual we'll write <replaceable>expr</replaceable>
to indicate any valid PHP expression.</simpara>
diff -c9 orig/types.xml new/types.xml
*** orig/types.xml Tue May 8 20:03:35 2001
--- new/types.xml Tue May 8 20:04:09 2001
***************
*** 5,22 ****
--- 5,28 ----
PHP supports the following types:
<itemizedlist>
<listitem>
<simpara>
<link linkend="language.types.array">array</link>
</simpara>
</listitem>
<listitem>
<simpara>
+ <link linkend="language.types.boolean">booleans
+ </link>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
<link linkend="language.types.double">floating-point numbers
</link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="language.types.integer">integer</link>
</simpara>
</listitem>
***************
*** 44,61 ****
--- 50,74 ----
use the <function>settype</function> function on it.
</simpara>
<simpara>
Note that a variable may behave in different manners in certain
situations, depending on what type it is at the time. For more
information, see the section on <link
linkend="language.types.type-juggling">Type Juggling</link>.
</simpara>
+ <sect1 id="language.types.boolean">
+ <title>Booleans</title>
+ <para>
+ This is the simpelest. Either TRUE or FALSE. <!-- more to come -->
+ </para>
+ </sect1>
+
<sect1 id="language.types.integer">
<title>Integers</title>
<para>
Integers can be specified using any of the following syntaxes:
<informalexample>
<programlisting role="php">
$a = 1234; # decimal number
$a = -123; # a negative number
$a = 0123; # octal number (equivalent to 83 decimal)
***************
*** 125,151 ****
<thead>
<row>
<entry>sequence</entry>
<entry>meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>\n</literal></entry>
! <entry>linefeed (LF or 0x0A in ASCII)</entry>
</row>
<row>
<entry><literal>\r</literal></entry>
! <entry>carriage return (CR or 0x0D in ASCII)</entry>
</row>
<row>
<entry><literal>\t</literal></entry>
! <entry>horizontal tab (HT or 0x09 in ASCII)</entry>
</row>
<row>
<entry><literal>\\</literal></entry>
<entry>backslash</entry>
</row>
<row>
<entry><literal>\$</literal></entry>
<entry>dollar sign</entry>
</row>
--- 138,164 ----
<thead>
<row>
<entry>sequence</entry>
<entry>meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>\n</literal></entry>
! <entry>linefeed (LF or 0x0A (10) in ASCII)</entry>
</row>
<row>
<entry><literal>\r</literal></entry>
! <entry>carriage return (CR or 0x0D (13) in ASCII)</entry>
</row>
<row>
<entry><literal>\t</literal></entry>
! <entry>horizontal tab (HT or 0x09 (9) in ASCII)</entry>
</row>
<row>
<entry><literal>\\</literal></entry>
<entry>backslash</entry>
</row>
<row>
<entry><literal>\$</literal></entry>
<entry>dollar sign</entry>
</row>
***************
*** 288,305 ****
--- 301,438 ----
/* Get the last character of a string. */
$str = 'This is still a test.';
$last = $str[strlen($str)-1];
?>
</programlisting>
</example>
</para>
+ <sect2 id="language.types.string.parsing">
+ <title>String parsing</title>
+ <!-- Section orig. by [EMAIL PROTECTED],
+ I used simpara all over, because I don't know when
+ to use para. There will also probably some typo's
+ and misspellings.
+ -->
+ <simpara>
+ When a string is specified in double quotes, variables are
+ parsed within it.
+ </simpara>
+ <simpara>
+ There are two types of syntax, a
+ <link linked="language.types.string.parsing.simple">simple</link>
+ one and a
+ <link
linked="language.types.string.parsing.complex">complex</link>
+ one.
+ The simple syntax is the most common and convenient, it provides
a way
+ to parse a variable, an array-value, or a object-property.
+ </simpara>
+ <simpara>
+ The complex syntax was introduced in PHP 4,
+ <!-- XXX was it? and starting with what version exactly? -->
+ and can by recognised
+ by the curly braces surrounding the expression.
+ </simpara>
+ <sect3 id="language.types.string.parsing.simple">
+ <title>Simple syntax</title>
+ <simpara>
+ If a $ is encoutered, the parser will
+ greedily take as much tokens as possible to form a valid
+ variable name. Enclose the the variable name in curly
+ braces if you want to explicitely specify the end of the
+ name.
+ </simpara>
+ <informalexample>
+ <programlisting role="php">
+ $beer = 'Heineken';
+ echo "$beer's taste is great"; // works, "'" is an invalid character
for varnames
+ echo "He drunk some $beers"; // won't work, 's' is a valid character
for varnames
+ echo "He drunk some ${beer}s"; // works
+ </programlisting>
+ </informalexample>
+ <simpara>
+ Similary, you can also have an array-index and an
+ object-property parsed. With array-indices, the
+ ']' marks the end of the index, for object-properties
+ the same rules apply as to simple variables, though
+ with object properties there doesn't exist a trick
+ like the one with variables.
+
+ <!-- XXX isn't true :(, this would be the trick
+ Also,
+ the same trick with curly-braces works if you
+ want to limit the greediness of parsers (aren't they
+ paying them enough or something?).
+ -->
+
+ </simpara>
+ <informalexample>
+ <programlisting role="php">
+ $fruits = array( 'strawberry' => 'red' , 'banana' => 'yellow' );
+ echo "A banana is $fruits[banana].";
+ echo "This square is $square->width meters broad.";
+ echo "This square is $square->width00 centimeters broad."; // won't
work,
+ // for a solution, see the <link
linked="language.types.string.parsing.complex">complex syntax</link>.
+
+ <!-- XXX this won't work:
+ echo "This square is $square->{width}00 centimeters broad.";
+ // XXX: php developers: it would be consequent to make this work.
+ // XXX: like the $obj->{expr} syntax outside a string works,
+ // XXX: analogously to the ${expr} syntax for variable var's.
+ -->
+
+ </programlisting>
+ </informalexample>
+ <simpara>
+ For anything more complex, you should use the complex syntax.
+ </simpara>
+ </sect3>
+ <sect3 id="language.types.string.parsing.complex">
+ <title>Complex (curly) syntax</title>
+ <simpara>
+ I didn't call this complex because the syntax is complex,
+ but because you can include complex expressions this way.
+ </simpara>
+ <simpara>
+ In fact, you can include any value that is in the namespace
+ in strings with this syntax. You simply write the expression
+ the same way as you would outside the string, and then include
+ it in { and }. Since you can't escape '{', this syntax will
+ only be recognised when the $ is immediately following the {.
+ (Use "{\$" to get a literal "{$").
+ Some examples to make it clear:
+ </simpara>
+ <informalexample>
+ <programlisting role="php">
+ $great = 'fantastic';
+ echo "This is { $great}"; // won't work, outputs: This is { fantastic}
+ echo "This is {$great}"; // works, outputs: This is fantastic
+ echo "This square is {$square->width}00 centimeters broad.";
+ echo "This works: {$arr[4][3]}";
+ echo "This is wrong: {$arr[foo][3]}"; // for the same reason
+ // as $foo[bar] is wrong outside a string.
+ <!-- XXX see the still-to-write explaination in the
arrays-section. -->
+ echo "You should do it this way: {$arr['foo'][3]}";
+ echo "You can even write {$obj->values[3]->name}";
+ echo "This is the value of the var named $name: {${$name}}";
+
+ <!-- <xxx> maybe it's better to leave this out?? -->
+ // this works, but i disencourage its use, since this is NOT
+ // involving functions, rather than mere variables, arrays and
objects.
+ $beer = 'Heineken';
+ echo "I'd like to have another {${ strrev('reeb') }}, hips";
+ <!-- </xxx> -->
+
+ </programlisting>
+ </informalexample>
+ </sect3>
+ </sect2>
<sect2 id="language.types.string.conversion">
<title>String conversion</title>
<simpara>
When a string is evaluated as a numeric value, the resulting
value and type are determined as follows.
</simpara>
<simpara>
The string will evaluate as a double if it contains any of the
***************
*** 646,663 ****
--- 779,799 ----
$foo = 10; // $foo is an integer
$bar = (double) $foo; // $bar is a double
</programlisting>
</informalexample>
</para>
<para>
The casts allowed are:
<itemizedlist>
<listitem>
+ <simpara>(bool), (boolean) - cast to boolean</simpara>
+ </listitem>
+ <listitem>
<simpara>(int), (integer) - cast to integer</simpara>
</listitem>
<listitem>
<simpara>(real), (double), (float) - cast to double</simpara>
</listitem>
<listitem>
<simpara>(string) - cast to string</simpara>
</listitem>
<listitem>
***************
*** 677,694 ****
--- 813,863 ----
$foo = ( int ) $bar;
</programlisting>
</informalexample>
</para>
<para>
It may not be obvious exactly what will happen when casting
between certain types. For instance, the following should be
noted.
</para>
+ <para>
+ When converting to boolean, the following values are considered
+ FALSE:
+
+ <itemizedlist>
+ <listitem>
+ <simpara>the boolean FALSE<!-- duh... --></simpara>
+ </listitem>
+ <listitem>
+ <simpara>the integer 0 (zero) </simpara>
+ </listitem>
+ <listitem>
+ <simpara>the float 0.0 (zero) </simpara>
+ </listitem>
+ <listitem>
+ <simpara>the empty string, and the string "0"</simpara>
+ </listitem>
+ <listitem>
+ <simpara>an array with zero elements</simpara>
+ </listitem>
+ <listitem>
+ <simpara>an object with zero elements</simpara>
+ </listitem>
+ </itemizedlist>
+
+ Every other value is considered true.
+ <!-- <XXX> this should be such a cute warning thing... -->
+ (-1 is considered TRUE!).
+ <!-- and/or a few examples, for the people only looking at
+ the examples... </XXX> -->
+ </para>
+
+
<para>
When casting from a scalar or a string variable to an array, the
variable will become the first element of the array:
<informalexample>
<programlisting role="php">
$var = 'ciao';
$arr = (array) $var;
echo $arr[0]; // outputs 'ciao'
</programlisting>
