goba Mon Aug 20 07:55:11 2001 EDT Modified files: /phpdoc/en/language basic-syntax.xml constants.xml control-structures.xml expressions.xml functions.xml oop.xml types.xml variables.xml Log: Introducing PEAR standards for function calls, class and function definitions, control structures. Fixing some bad indentation. WS ONLY FIXES.
Index: phpdoc/en/language/basic-syntax.xml diff -u phpdoc/en/language/basic-syntax.xml:1.13 phpdoc/en/language/basic-syntax.xml:1.14 --- phpdoc/en/language/basic-syntax.xml:1.13 Sun Aug 19 07:09:16 2001 +++ phpdoc/en/language/basic-syntax.xml Mon Aug 20 07:55:11 2001 @@ -1,5 +1,5 @@ <?xml encoding="iso-8859-1"?> -<!-- $Revision: 1.13 $ --> +<!-- $Revision: 1.14 $ --> <chapter id="language.basic-syntax"> <title>Basic syntax</title> @@ -115,14 +115,11 @@ <programlisting role="php"> <?php -if ( boolean-expression ) -{ +if (boolean-expression) { ?> <strong>This is true.</strong> <?php -} -else -{ +} else { ?> <strong>This is false.</strong> <?php @@ -179,10 +176,10 @@ The "one-line" comment styles actually only comment to the end of the line or the current block of PHP code, whichever comes first.</simpara> - <informalexample><programlisting> + <informalexample><programlisting> <h1>This is an <?php # echo "simple";?> example.</h1> <p>The header above will say 'This is an example'. -</programlisting></informalexample> + </programlisting></informalexample> <simpara> You should be careful not to nest 'C' style comments, which can Index: phpdoc/en/language/constants.xml diff -u phpdoc/en/language/constants.xml:1.16 phpdoc/en/language/constants.xml:1.17 --- phpdoc/en/language/constants.xml:1.16 Sun Aug 19 07:09:16 2001 +++ phpdoc/en/language/constants.xml Mon Aug 20 07:55:11 2001 @@ -1,5 +1,5 @@ <?xml encoding="iso-8859-1"?> -<!-- $Revision: 1.16 $ --> +<!-- $Revision: 1.17 $ --> <chapter id="language.constants"> <title>Constants</title> @@ -256,11 +256,12 @@ <title>Using __FILE__ and __LINE__</title> <programlisting> <?php -function report_error($file, $line, $message) { +function report_error($file, $line, $message) +{ echo "An error occured in $file on line $line: $message."; } -report_error(__FILE__,__LINE__, "Something went wrong!"); +report_error(__FILE__, __LINE__, "Something went wrong!"); ?> </programlisting> </example> Index: phpdoc/en/language/control-structures.xml diff -u phpdoc/en/language/control-structures.xml:1.36 phpdoc/en/language/control-structures.xml:1.37 --- phpdoc/en/language/control-structures.xml:1.36 Sun Aug 19 07:09:16 2001 +++ phpdoc/en/language/control-structures.xml Mon Aug 20 07:55:11 2001 @@ -1,5 +1,5 @@ <?xml encoding="iso-8859-1"?> -<!-- $Revision: 1.36 $ --> +<!-- $Revision: 1.37 $ --> <chapter id="control-structures"> <title>Control Structures</title> @@ -178,9 +178,9 @@ <literal>endswitch;</literal>, respectively. <informalexample> <programlisting role="php"> - <?php if ($a == 5): ?> - A is equal to 5 - <?php endif; ?> +<?php if ($a == 5): ?> +A is equal to 5 +<?php endif; ?> </programlisting> </informalexample> </para> @@ -415,7 +415,7 @@ /* example 4 */ -for ($i = 1; $i <= 10; print $i, $i++) ; +for ($i = 1; $i <= 10; print $i, $i++); </programlisting> </informalexample> </para> @@ -1283,7 +1283,8 @@ <?php define("PHPVERSION", floor(phpversion())); echo "GLOBALS ARE NICE\n"; -function goodTea() { +function goodTea() +{ return "Oolong tea tastes good!"; } ?> @@ -1294,7 +1295,8 @@ <programlisting role="php"> <?php require ("utils.inc"); -function showVar($var) { +function showVar($var) +{ if (PHPVERSION == 4) { print_r($var); } else { @@ -1343,7 +1345,8 @@ <programlisting role="php"> ... require_once("utils.inc"); -function showVar($var) { +function showVar($var) +{ ... </programlisting> </example> Index: phpdoc/en/language/expressions.xml diff -u phpdoc/en/language/expressions.xml:1.12 phpdoc/en/language/expressions.xml:1.13 --- phpdoc/en/language/expressions.xml:1.12 Sun Aug 19 07:09:17 2001 +++ phpdoc/en/language/expressions.xml Mon Aug 20 07:55:11 2001 @@ -1,5 +1,5 @@ <?xml encoding="iso-8859-1"?> -<!-- $Revision: 1.12 $ --> +<!-- $Revision: 1.13 $ --> <chapter id="language.expressions"> <title>Expressions</title> @@ -28,7 +28,8 @@ <informalexample> <programlisting> -function foo () { +function foo () +{ return 5; } </programlisting> @@ -127,7 +128,7 @@ <informalexample><programlisting> $first ? $second : $third -</programlisting></informalexample> + </programlisting></informalexample> If the value of the first subexpression is &true; (non-zero), then the second subexpression is evaluated, and that is the result of @@ -141,7 +142,8 @@ <informalexample> <programlisting> -function double($i) { +function double($i) +{ return $i*2; } $b = $a = 5; /* assign the value five into the variable $a and $b */ @@ -160,7 +162,9 @@ value of 24. the value of the assignment (24) is then assigned into $h, and $h ends with the value of 24 as well. */ -</programlisting></informalexample></para> + </programlisting> + </informalexample> + </para> <simpara> In the beginning of the chapter we said that we'll be describing Index: phpdoc/en/language/functions.xml diff -u phpdoc/en/language/functions.xml:1.15 phpdoc/en/language/functions.xml:1.16 --- phpdoc/en/language/functions.xml:1.15 Sun Aug 19 07:09:17 2001 +++ phpdoc/en/language/functions.xml Mon Aug 20 07:55:11 2001 @@ -1,5 +1,5 @@ <?xml encoding="iso-8859-1"?> -<!-- $Revision: 1.15 $ --> +<!-- $Revision: 1.16 $ --> <chapter id="functions"> <title>Functions</title> @@ -11,7 +11,8 @@ <informalexample> <programlisting role="php"> -function foo ($arg_1, $arg_2, ..., $arg_n) { +function foo ($arg_1, $arg_2, ..., $arg_n) +{ echo "Example function.\n"; return $retval; } @@ -78,7 +79,8 @@ <informalexample> <programlisting role="php"> -function takes_array($input) { +function takes_array($input) +{ echo "$input[0] + $input[1] = ", $input[0]+$input[1]; } </programlisting> @@ -102,7 +104,8 @@ <informalexample> <programlisting role="php"> -function add_some_extra(&$string) { +function add_some_extra(&$string) +{ $string .= 'and something extra.'; } $str = 'This is a string, '; @@ -119,7 +122,8 @@ <informalexample> <programlisting role="php"> -function foo ($bar) { +function foo ($bar) +{ $bar .= ' and something extra.'; } $str = 'This is a string, '; @@ -142,7 +146,8 @@ <informalexample> <programlisting role="php"> -function makecoffee ($type = "cappucino") { +function makecoffee ($type = "cappucino") +{ return "Making a cup of $type.\n"; } echo makecoffee (); @@ -171,7 +176,8 @@ <informalexample> <programlisting role="php"> -function makeyogurt ($type = "acidophilus", $flavour) { +function makeyogurt ($type = "acidophilus", $flavour) +{ return "Making a bowl of $type $flavour.\n"; } @@ -195,7 +201,8 @@ <informalexample> <programlisting role="php"> -function makeyogurt ($flavour, $type = "acidophilus") { +function makeyogurt ($flavour, $type = "acidophilus") +{ return "Making a bowl of $type $flavour.\n"; } @@ -244,7 +251,8 @@ <informalexample> <programlisting role="php"> -function square ($num) { +function square ($num) +{ return $num * $num; } echo square (4); // outputs '16'. @@ -258,7 +266,8 @@ <informalexample> <programlisting role="php"> -function small_numbers() { +function small_numbers() +{ return array (0, 1, 2); } list ($zero, $one, $two) = small_numbers(); @@ -271,11 +280,12 @@ when assigning the returned value to a variable: <informalexample> <programlisting role="php"> -function &returns_reference() { +function &returns_reference() +{ return $someref; } -$newref =&returns_reference(); +$newref =& returns_reference(); </programlisting> </informalexample> </para> @@ -330,18 +340,20 @@ <title>Variable function example</title> <programlisting role="php"> <?php -function foo() { +function foo() +{ echo "In foo()<br>\n"; } -function bar( $arg = '' ) { +function bar($arg = '') +{ echo "In bar(); argument was '$arg'.<br>\n"; } $func = 'foo'; $func(); $func = 'bar'; -$func( 'test' ); +$func('test'); ?> </programlisting> </example> Index: phpdoc/en/language/oop.xml diff -u phpdoc/en/language/oop.xml:1.21 phpdoc/en/language/oop.xml:1.22 --- phpdoc/en/language/oop.xml:1.21 Sun Aug 19 07:09:17 2001 +++ phpdoc/en/language/oop.xml Mon Aug 20 07:55:11 2001 @@ -1,5 +1,5 @@ <?xml encoding="iso-8859-1"?> -<!-- $Revision: 1.21 $ --> +<!-- $Revision: 1.22 $ --> <chapter id="language.oop"> <title>Classes and Objects</title> @@ -12,18 +12,21 @@ <informalexample> <programlisting role="php"> <?php -class Cart { +class Cart +{ var $items; // Items in our shopping cart // Add $num articles of $artnr to the cart - function add_item ($artnr, $num) { + function add_item ($artnr, $num) + { $this->items[$artnr] += $num; } // Take $num articles of $artnr out of the cart - function remove_item ($artnr, $num) { + function remove_item ($artnr, $num) + { if ($this->items[$artnr] > $num) { $this->items[$artnr] -= $num; return true; @@ -80,7 +83,8 @@ <informalexample> <programlisting role="php"> /* None of these will work in PHP 4. */ -class Cart { +class Cart +{ var $todays_date = date("Y-m-d"); var $name = $firstname; var $owner = 'Fred ' . 'Jones'; @@ -88,13 +92,15 @@ } /* This is how it should be done. */ -class Cart { +class Cart +{ var $todays_date; var $name; var $owner; var $items; - function Cart() { + function Cart() + { $this->todays_date = date("Y-m-d"); $this->name = $GLOBALS['firstname']; /* etc. . . */ @@ -112,11 +118,11 @@ <informalexample> <programlisting role="php"> - $cart = new Cart; - $cart->add_item("10", 1); +$cart = new Cart; +$cart->add_item("10", 1); - $another_cart = new Cart; - $another_cart->add_item("0815", 3); +$another_cart = new Cart; +$another_cart->add_item("0815", 3); </programlisting> </informalexample> @@ -149,7 +155,7 @@ <informalexample> <programlisting role="php"> // correct, single $ -$cart->items = array("10" => 1); +$cart->items = array("10" => 1); // invalid, because $cart->$items becomes $cart->"" $cart->$items = array("10" => 1); @@ -197,10 +203,12 @@ <informalexample> <programlisting role="php"> -class Named_Cart extends Cart { +class Named_Cart extends Cart +{ var $owner; - function set_owner ($name) { + function set_owner ($name) + { $this->owner = $name; } } @@ -218,9 +226,9 @@ <informalexample> <programlisting role="php"> $ncart = new Named_Cart; // Create a named cart -$ncart->set_owner ("kris"); // Name that cart +$ncart->set_owner("kris"); // Name that cart print $ncart->owner; // print the cart owners name -$ncart->add_item ("10", 1); // (inherited functionality from cart) +$ncart->add_item("10", 1); // (inherited functionality from cart) </programlisting> </informalexample> @@ -249,8 +257,10 @@ <informalexample> <programlisting role="php"> // Works in PHP 3 and PHP 4. -class Auto_Cart extends Cart { - function Auto_Cart () { +class Auto_Cart extends Cart +{ + function Auto_Cart() + { $this->add_item ("10", 1); } } @@ -270,19 +280,21 @@ <informalexample> <programlisting role="php"> // Works in PHP 3 and PHP 4. -class Constructor_Cart extends Cart { - function Constructor_Cart ($item = "10", $num = 1) { +class Constructor_Cart extends Cart +{ + function Constructor_Cart($item = "10", $num = 1) + { $this->add_item ($item, $num); } } // Shop the same old boring stuff. -$default_cart = new Constructor_Cart; +$default_cart = new Constructor_Cart; // Shop for real... -$different_cart = new Constructor_Cart ("20", 17); +$different_cart = new Constructor_Cart("20", 17); </programlisting> </informalexample> @@ -296,14 +308,18 @@ <informalexample> <programlisting role="php"> -class A { - function A() { +class A +{ + function A() + { echo "I am the constructor of A.<br>\n"; } } -class B extends A { - function C() { +class B extends A +{ + function C() + { echo "I am a regular function.<br>\n"; } } @@ -329,19 +345,24 @@ <informalexample> <programlisting role="php"> -class A { - function A() { +class A +{ + function A() + { echo "I am the constructor of A.<br>\n"; } - function B() { + function B() + { echo "I am a regular function named B in class A.<br>\n"; echo "I am not a constructor in A.<br>\n"; } } -class B extends A { - function C() { +class B extends A +{ + function C() + { echo "I am a regular function.<br>\n"; } } @@ -410,14 +431,18 @@ <informalexample> <programlisting role="php"> -class A { - function example() { +class A +{ + function example() + { echo "I am the original function A::example().<br>\n"; } } -class B extends A { - function example() { +class B extends A +{ + function example() + { echo "I am the redefined function B::example().<br>\n"; A::example(); } @@ -497,14 +522,18 @@ <informalexample> <programlisting role="php"> -class A { - function example() { +class A +{ + function example() + { echo "I am A::example() and provide basic functionality.<br>\n"; } } -class B extends A { - function example() { +class B extends A +{ + function example() + { echo "I am B::example and provide additional functionality().<br>\n"; parent::example(); } @@ -563,10 +592,12 @@ <informalexample> <programlisting role="php"> classa.inc: - class A { + class A + { var $one = 1; - function show_one() { + function show_one() + { echo $this->one; } } @@ -664,23 +695,27 @@ <informalexample> <programlisting role="php"> -class foo { - function foo($name) { +class foo +{ + function foo($name) + { // create a reference inside the global array $globalref global $globalref; - $globalref[] = &$this; + $globalref[] = &$this; // set name to passed value $this->setName($name); - // and put it out + // and put it out $this->echoName(); } - function echoName() { + function echoName() + { echo "<br>",$this->Name; } - function setName($name) { - $this->Name = $name; + function setName($name) + { + $this->Name = $name; } } </programlisting> @@ -688,112 +723,121 @@ </para> <para> - Let us check out if there is a difference between <varname>$bar1</varname> which has been created using the copy <literal>=</literal> operator - and <varname>$bar2</varname> which has been created using the reference <literal>=&</literal> operator... - + Let us check out if there is a difference between + <varname>$bar1</varname> which has been created using + the copy <literal>=</literal> operator and + <varname>$bar2</varname> which has been created using + the reference <literal>=&</literal> operator... <informalexample> <programlisting role="php"> - - $bar1 = new foo('set in constructor'); - $bar1->echoName(); - $globalref[0]->echoName(); - - /* output: - set in constructor - set in constructor - set in constructor */ - - $bar2 =& new foo('set in constructor'); - $bar2->echoName(); - $globalref[1]->echoName(); - - /* output: - set in constructor - set in constructor - set in constructor */ - + +$bar1 = new foo('set in constructor'); +$bar1->echoName(); +$globalref[0]->echoName(); + +/* output: +set in constructor +set in constructor +set in constructor */ + +$bar2 =& new foo('set in constructor'); +$bar2->echoName(); +$globalref[1]->echoName(); + +/* output: +set in constructor +set in constructor +set in constructor */ + </programlisting> </informalexample> </para> <para> - Apparently there is no difference, but in fact there is a very significant one: - <varname>$bar1</varname> and <varname>$globalref[0]</varname> are _NOT_ referenced, they are NOT the same variable. - This is because "new" does not return a reference by default, instead it returns a copy. - <note> - <simpara> - There is no performance loss (since php 4 and up use reference counting) returning copies instead of references. - On the contrary it is most often better to simply work with copies instead of references, because creating - references takes some time where creating copies virtually takes no time (unless none of them is a large array or object - and one of them gets changed and the other(s) one(s) subsequently, then it would be wise to use references to change them - all concurrently). - </simpara> - </note> + Apparently there is no difference, but in fact there is a + very significant one: <varname>$bar1</varname> and + <varname>$globalref[0]</varname> are _NOT_ referenced, they + are NOT the same variable. This is because "new" does not + return a reference by default, instead it returns a copy. + <note> + <simpara> + There is no performance loss (since php 4 and up use reference + counting) returning copies instead of references. On the + contrary it is most often better to simply work with copies + instead of references, because creating references takes some + time where creating copies virtually takes no time (unless none + of them is a large array or object and one of them gets changed + and the other(s) one(s) subsequently, then it would be wise to + use references to change them all concurrently). + </simpara> + </note> To prove what is written above let us watch the code below. - - <informalexample> + <informalexample> <programlisting role="php"> - // now we will change the name. what do you expect? - // you could expect that both $bar and $globalref[0] change their names... - $bar1->setName('set from outside'); - - // as mentioned before this is not the case. - $bar1->echoName(); - $globalref[0]->echoName(); - - /* output: - set on object creation - set from outside */ - - // let us see what is different with $bar2 and $globalref[1] - $bar2->setName('set from outside'); - - // luckily they are not only equyl, they are thesame variable - // thus $bar2->Name and $globalref[1]->Name are the same too - $bar2->echoName(); - $globalref[1]->echoName(); - - /* output: - set from outside - set from outside */ - - </programlisting> - </informalexample> - </para> +// now we will change the name. what do you expect? +// you could expect that both $bar and $globalref[0] change their names... +$bar1->setName('set from outside'); + +// as mentioned before this is not the case. +$bar1->echoName(); +$globalref[0]->echoName(); + +/* output: +set on object creation +set from outside */ + +// let us see what is different with $bar2 and $globalref[1] +$bar2->setName('set from outside'); + +// luckily they are not only equyl, they are thesame variable +// thus $bar2->Name and $globalref[1]->Name are the same too +$bar2->echoName(); +$globalref[1]->echoName(); + +/* output: +set from outside +set from outside */ + </programlisting> + </informalexample> + </para> <para> Another final example, try to understand it. - <informalexample> + <informalexample> <programlisting role="php"> - -class a { - function a($i) { +class a +{ + function a($i) + { $this->value = $i; // try to figure out why we do not need a reference here $this->b = new b($this); } - function createRef() { + function createRef() + { $this->c = new b($this); } - function echoValue() { + function echoValue() + { echo "<br>","class ",get_class($this),': ',$this->value; - } + } } -class b { - - function b(&$a) { +class b +{ + function b(&$a) + { $this->a = &$a; } - function echoValue() { + function echoValue() + { echo "<br>","class ",get_class($this),': ',$this->a->value; - } - + } } // try to undestand why using a simple copy here would yield @@ -820,12 +864,10 @@ class b: 11 class b: 11 */ - </programlisting> - </informalexample> - </para> -</sect1> - - + </programlisting> + </informalexample> + </para> + </sect1> </chapter> <!-- Keep this comment at the end of the file Index: phpdoc/en/language/types.xml diff -u phpdoc/en/language/types.xml:1.45 phpdoc/en/language/types.xml:1.46 --- phpdoc/en/language/types.xml:1.45 Sun Aug 19 07:09:17 2001 +++ phpdoc/en/language/types.xml Mon Aug 20 07:55:11 2001 @@ -1,5 +1,5 @@ <?xml encoding="iso-8859-1"?> -<!-- $Revision: 1.45 $ --> +<!-- $Revision: 1.46 $ --> <chapter id="language.types"> <title>Types</title> @@ -155,20 +155,17 @@ structure</link>. <informalexample> <programlisting role="php"> -if ($action == "show_version") // == is an <link linkend="language.operators">operator</link> which returns a <type>boolean</type> -{ +if ($action == "show_version") { // == is an <link +linkend="language.operators">operator</link> which returns a <type>boolean</type> echo "The version is 1.23"; } // this is not necessary: -if ($show_separators == true) -{ +if ($show_separators == true) { echo "<hr>\n"; } // because you can simply type this: -if ($show_separators) -{ +if ($show_separators) { echo "<hr>\n"; } </programlisting> @@ -710,11 +707,13 @@ EOD; /* More complex example, with variables. */ -class foo { +class foo +{ var $foo; var $bar; - function foo() { + function foo() + { $this->foo = 'Foo'; $this->bar = array('Bar1', 'Bar2', 'Bar3'); } @@ -1304,8 +1303,7 @@ <programlisting role="php"> $colors = array('red','blue','green','yellow'); -foreach ( $colors as $color ) -{ +foreach ( $colors as $color ) { echo "Do you like $color?\n"; } @@ -1331,8 +1329,7 @@ <example id="language.types.array.examples.changeloop"> <title>Collection</title> <programlisting role="php"> -<link linkend="control-structures.foreach">foreach</link> ( $colors as $key => $color ) -{ +<link linkend="control-structures.foreach">foreach</link> ( $colors as $key => $color +) { // won't work: //$color = <link linkend="function.strtoupper">strtoupper</link>($color); @@ -1377,7 +1374,7 @@ <programlisting role="php"> // fill an array with all items from a <link linkend="ref.dir">directory</link> $handle = <link linkend="function.opendir">opendir</link>('.'); -while ( $file = <link linkend="function.readdir">readdir</link>($handle) ) +while ($file = <link linkend="function.readdir">readdir</link>($handle)) { $files[] = $file; } @@ -1641,8 +1638,10 @@ <informalexample> <programlisting role="php"> <?php -class foo { - function do_foo() { +class foo +{ + function do_foo() + { echo "Doing foo."; } } @@ -1705,10 +1704,6 @@ </para> </sect2> - - - - </sect1> <sect1 id="language.types.null"> Index: phpdoc/en/language/variables.xml diff -u phpdoc/en/language/variables.xml:1.17 phpdoc/en/language/variables.xml:1.18 --- phpdoc/en/language/variables.xml:1.17 Sun Aug 5 06:51:47 2001 +++ phpdoc/en/language/variables.xml Mon Aug 20 07:55:11 2001 @@ -1,5 +1,5 @@ <?xml encoding="iso-8859-1"?> -<!-- $Revision: 1.17 $ --> +<!-- $Revision: 1.18 $ --> <chapter id="language.variables"> <title>Variables</title> @@ -89,7 +89,8 @@ $bar = &$foo; // This is a valid assignment. $bar = &(24 * 7); // Invalid; references an unnamed expression. -function test() { +function test() +{ return 25; } @@ -599,11 +600,12 @@ <programlisting role="php"> $a = 1; /* global scope */ -Function Test () { +function Test() +{ echo $a; /* reference to local scope variable */ } -Test (); +Test(); </programlisting> </informalexample> @@ -625,13 +627,14 @@ $a = 1; $b = 2; -Function Sum () { +function Sum() +{ global $a, $b; $b = $a + $b; } -Sum (); +Sum(); echo $b; </programlisting> </informalexample> @@ -655,11 +658,12 @@ $a = 1; $b = 2; -Function Sum () { +function Sum() +{ $GLOBALS["b"] = $GLOBALS["a"] + $GLOBALS["b"]; } -Sum (); +Sum(); echo $b; </programlisting> </informalexample> @@ -680,7 +684,8 @@ <informalexample> <programlisting role="php"> -Function Test () { +function Test () +{ $a = 0; echo $a; $a++; @@ -700,7 +705,8 @@ <informalexample> <programlisting role="php"> -Function Test () { +function Test() +{ static $a = 0; echo $a; $a++; @@ -725,7 +731,8 @@ <informalexample> <programlisting role="php"> -Function Test () { +function Test() +{ static $count = 0; $count++; @@ -933,7 +940,7 @@ <informalexample> <programlisting role="php"> -SetCookie ("MyCookie[]", "Testing", time()+3600); +setcookie("MyCookie[]", "Testing", time()+3600); </programlisting> </informalexample> @@ -948,8 +955,8 @@ <title>SetCookie Example</title> <programlisting role="php"> $Count++; -SetCookie ("Count", $Count, time()+3600); -SetCookie ("Cart[$Count]", $item, time()+3600); +setcookie("Count", $Count, time()+3600); +setcookie("Cart[$Count]", $item, time()+3600); </programlisting> </example>