call.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<refentry xml:id="luasandboxfunction.call" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>LuaSandboxFunction::call</refname>
  <refpurpose>Call a Lua function</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type class="union"><type>array</type><type>bool</type></type><methodname>LuaSandboxFunction::call</methodname>
   <methodparam rep="repeat"><type>string</type><parameter>args</parameter></methodparam>
  </methodsynopsis>
  <para>
   Calls a Lua function.
  </para>
  <para>
   Errors considered to be the fault of the PHP code will result in the
   function returning &false; and <constant>E_WARNING</constant>
   being raised, for example, a <type>resource</type> type being used as an
   argument. Lua errors will result in a <classname>LuaSandboxRuntimeError</classname>
   exception being thrown.
  </para>
  <para>
   PHP and Lua types are converted as follows:
  </para>
  <para>
   <itemizedlist>
    <listitem>
     <para>PHP &null; is Lua <literal>nil</literal>, and vice versa.</para>
    </listitem>
    <listitem>
     <para>
      PHP <type>int</type>s and <type>float</type>s are converted to Lua
      numbers. Infinity and <constant>NAN</constant> are supported.
     </para>
    </listitem>
    <listitem>
     <para>
      Lua numbers without a fractional part between approximately <literal>-2**53</literal>
      and <literal>2**53</literal> are converted to PHP <type>int</type>s, with others
      being converted to PHP <type>float</type>s.
     </para>
    </listitem>
    <listitem>
     <para>PHP <type>bool</type>s are Lua booleans, and vice versa.</para>
    </listitem>
    <listitem>
     <para>PHP <type>string</type>s are Lua strings, and vice versa.</para>
    </listitem>
    <listitem>
     <para>
      Lua functions are PHP <classname>LuaSandboxFunction</classname> objects, and vice versa.
      General PHP <type>callable</type>s are not supported.
     </para>
    </listitem>
    <listitem>
     <para>
      PHP <type>array</type>s are converted to Lua tables, and vice versa.
     </para>
     <para>
      <itemizedlist>
       <listitem>
        <para>
         Note that Lua typically indexes arrays from 1, while PHP indexes
         arrays from 0. No adjustment is made for these differing
         conventions.
        </para>
       </listitem>
       <listitem>
        <para>Self-referential arrays are not supported in either direction.</para>
       </listitem>
       <listitem>
        <para>PHP references are dereferenced.</para>
       </listitem>
       <listitem>
        <para>
         Lua <literal>__pairs</literal> and <literal>__ipairs</literal> are processed.
         <literal>__index</literal> is ignored.
        </para>
       </listitem>
       <listitem>
        <para>
         When converting from PHP to Lua, integer keys between
         <literal>-2**53</literal> and <literal>2**53</literal> are represented
         as Lua numbers. All other keys are represented as Lua strings.
        </para>
       </listitem>
       <listitem>
        <para>
         When converting from Lua to PHP, keys other than strings and
         numbers will result in an error, as will collisions when converting
         numbers to strings or vice versa (since PHP considers things like
         <literal>$a[0]</literal> and <literal>$a["0"]</literal> as being equivalent).
        </para>
       </listitem>
      </itemizedlist>
     </para>
    </listitem>
    <listitem>
     <para>
      All other types are unsupported and will raise an error/exception,
      including general PHP <type>object</type>s and Lua userdata and thread types.
     </para>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   Lua functions inherently return a list of results. So on success, this
   method returns an <type>array</type> containing all of the values returned by Lua,
   with <type>int</type> keys starting from zero. Lua may return no results, in
   which case an empty array is returned.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>args</parameter></term>
    <listitem>
     <para>
      Arguments passed to the function.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns an <type>array</type> of values returned by the function, which may be empty,
   &return.falseforfailure;.
  </para>
 </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
-->