Documenting closure methods. Note I put the closures under

language/predefined/interfaces.xml, this will have to be
moved to a more appropriate location.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@318236 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Gustavo André dos Santos Lopes 2011-10-19 22:32:47 +00:00
parent 987249f1aa
commit efe3572eca
7 changed files with 454 additions and 11 deletions

View file

@ -369,19 +369,15 @@
<simpara>
The predefined final class <classname>Closure</classname> was introduced
in PHP 5.3.0. It is used for internal implementation of <link
in PHP 5.3.0. It is used for representing <link
linkend="functions.anonymous">anonymous functions</link>.
</simpara>
<simpara>
The class has a constructor forbidding the manual creation of the object
(issues <constant>E_RECOVERABLE_ERROR</constant>) and the
<literal>__invoke</literal> method with the <link
linkend="language.oop5.magic.invoke">calling magic</link>.
For more information, see its <link linkend="class.closure">class
page</link>.
</simpara>
</sect2>
<sect2 xml:id="reserved.classes.special">
<title>Special classes</title>

View file

@ -746,10 +746,8 @@ print $my_cart->getTotal(0.05) . "\n";
</example>
<simpara>
Anonymous functions are currently implemented using the
<link linkend="reserved.classes.closure">
<classname>Closure</classname></link> class. This is an implementation
detail and should not be relied upon.
Anonymous functions are implemented using the <link linkend="class.closure">
<classname>Closure</classname></link> class.
</simpara>
<note>

View file

@ -0,0 +1,85 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<phpdoc:classref xml:id="class.closure" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>The Closure class</title>
<titleabbrev>Closure</titleabbrev>
<partintro>
<!-- {{{ Closure intro -->
<section xml:id="closure.intro">
&reftitle.intro;
<para>
Class used to represent <link linkend="functions.anonymous">anonymous
functions</link>.
</para>
<para>
Anonymous functions, implemented in PHP 5.3, yield objects of this type.
This fact used to be considered an implementation detail, but it can now
be relied upon. Starting with PHP 5.4, this class has methods that allow
further control of the anonymous function after it has been created.
</para>
<para>
Besides the methods listed here, this class also has an
<literal>__invoke</literal> method. This is for consistency with other
classes that implement <link linkend="language.oop5.magic.invoke">calling
magic</link>, as this method is not used for calling the function.
</para>
</section>
<!-- }}} -->
<section xml:id="closure.synopsis">
&reftitle.classsynopsis;
<!-- {{{ Synopsis -->
<classsynopsis>
<ooclass><classname>Closure</classname></ooclass>
<!-- {{{ Class synopsis -->
<classsynopsisinfo>
<ooclass>
<classname>Closure</classname>
</ooclass>
</classsynopsisinfo>
<!-- }}} -->
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.closure')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
</classsynopsis>
<!-- }}} -->
</section>
</partintro>
&language.predefined.closure.construct;
&language.predefined.closure.bind;
&language.predefined.closure.bindto;
</phpdoc:classref>
<!-- 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:"~/.phpdoc/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
-->

View file

@ -0,0 +1,134 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="closure.bind" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Closure::bind</refname>
<refpurpose>
Duplicates a closure with a specific bound object and class scope
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <modifier>static</modifier> <type>Closure</type><methodname>Closure::bind</methodname>
<methodparam><type>Closure</type><parameter>closure</parameter></methodparam>
<methodparam><type>object</type><parameter>newthis</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter>newscope</parameter>
<initializer>'static'</initializer></methodparam>
</methodsynopsis>
<para>
This method is a static version of <methodname>Closure::bindTo</methodname>.
See the documentation of that method for more information.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>closure</parameter></term>
<listitem>
<para>
The anonymous functions to bind.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>newthis</parameter></term>
<listitem>
<para>
The object to which the given anonymous function should be bound, or
&null; for the closure to be unbound.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>newscope</parameter></term>
<listitem>
<para>
The class scope to which associate the closure is to be associated, or
'static' to keep the current one. If an object is given, the type of the
object will be used instead. This determines the visibility of protected
and private methods of the bound object.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a new <classname>Closure</classname> object &return.falseforfailure;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>Closure::bind</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
class A {
private static $sfoo = 1;
private $ifoo = 2;
}
$cl1 = static function() {
return A::$sfoo;
};
$cl2 = function() {
return $this->ifoo;
};
$bcl1 = Closure::bind($cl1, null, 'A');
$bcl2 = Closure::bind($cl2, new A(), 'A');
echo $bcl1(), "\n";
echo $bcl2(), "\n";
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
1
2
]]>
</screen>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><link linkend="functions.anonymous">Anonymous functions</link></member>
<member><methodname>Closure::bindTo</methodname></member>
</simplelist>
</refsect1>
</refentry>
<!-- 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:"~/.phpdoc/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
-->

View file

@ -0,0 +1,160 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="closure.bindto" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Closure::bindTo</refname>
<refpurpose>
Duplicates the closure with a new bound object and class scope
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>Closure</type><methodname>Closure::bindTo</methodname>
<methodparam><type>object</type><parameter>newthis</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter>newscope</parameter>
<initializer>'static'</initializer></methodparam>
</methodsynopsis>
<para>
Create and return a new <link linkend="functions.anonymous">anonymous
function</link> with the same body and bound variables as this one, but
possibly with a different bound object and a new class scope.
</para>
<para>
The “bound object” determines the value <literal>$this</literal> will
have in the function body and the “class scope” represents a class
which determines which private and protected members the anonymous
function will be able to access. Namely, the members that will be
visible are the same as if the anonymous function were a method of
the class given as value of the <parameter>newscope</parameter>
parameter.
</para>
<para>
Static closures cannot have any bound object (the value of the parameter
<parameter>newthis</parameter> should be &null;), but this function can
nevertheless be used to change their class scope.
</para>
<para>
This function will ensure that for a non-static closure, having a bound
instance will imply being scoped and vice-versa. To this end,
non-static closures that are given a scope but a &null; instance are made
static and non-static non-scoped closures that are given a non-null
instance are scoped to an unspecified class.
</para>
<note>
<para>
If you only want to duplicate the anonymous functions, you can use
<link linkend="language.oop5.cloning">cloning</link> instead.
</para>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>newthis</parameter></term>
<listitem>
<para>
The object to which the given anonymous function should be bound, or
&null; for the closure to be unbound.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>newscope</parameter></term>
<listitem>
<para>
The class scope to which associate the closure is to be associated, or
'static' to keep the current one. If an object is given, the type of the
object will be used instead. This determines the visibility of protected
and private methods of the bound object.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the newly created <classname>Closure</classname> object
&return.falseforfailure;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>Closure::bindTo</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
class A {
function __construct($val) {
$this->val = $val;
}
function getClosure() {
//returns closure bound to this object and scope
return function() { return $this->val; };
}
}
$ob1 = new A(1);
$ob2 = new A(2);
$cl = $ob1->getClosure();
echo $cl(), "\n";
$cl = $cl->bindTo($ob2);
echo $cl(), "\n";
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
1
2
]]>
</screen>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><link linkend="functions.anonymous">Anonymous functions</link></member>
<member><methodname>Closure::bind</methodname></member>
</simplelist>
</refsect1>
</refentry>
<!-- 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:"~/.phpdoc/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
-->

View file

@ -0,0 +1,69 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="closure.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Closure::__construct</refname>
<refpurpose>Constructor that disallows instantiation</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<methodname>Closure::__construct</methodname>
<void />
</methodsynopsis>
<para>
This method exists only to disallow instantiation of the
<classname>Closure</classname> class. Objects of this class are created
in the fashion described on the
<link linkend="functions.anonymous">anonymous functions</link> page.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
This method has no return value; it simply emits an error
(of type <constant>E_RECOVERABLE_ERROR</constant>).
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member>
<link linkend="functions.anonymous">Anonymous functions</link>
</member>
</simplelist>
</refsect1>
</refentry>
<!-- 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:"~/.phpdoc/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
-->

View file

@ -15,6 +15,7 @@
&language.predefined.iteratoraggregate;
&language.predefined.arrayaccess;
&language.predefined.serializable;
&language.predefined.closure;
</part>