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

<refentry xml:id="luasandbox.registerlibrary" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>LuaSandbox::registerLibrary</refname>
  <refpurpose>Register a set of PHP functions as a Lua library</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>void</type><methodname>LuaSandbox::registerLibrary</methodname>
   <methodparam><type>string</type><parameter>libname</parameter></methodparam>
   <methodparam><type>array</type><parameter>functions</parameter></methodparam>
  </methodsynopsis>
  <para>
   Registers a set of PHP functions as a Lua library, so that Lua can call
   the relevant PHP code.
  </para>
  <para>
   For more information about calling Lua functions and the return values,
   see <methodname>LuaSandboxFunction::call</methodname>.
  </para>

 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>libname</parameter></term>
    <listitem>
     <para>
      The name of the library. In the Lua state, the global variable of this
      name will be set to the table of functions. If the table already exists,
      the new functions will be added to it.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>functions</parameter></term>
    <listitem>
     <para>
      An <type>array</type>, where each key is a function name, and each value is a
      corresponding PHP <type>callable</type>.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.void;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Registering PHP functions to call from Lua</title>
    <programlisting role="php">
<![CDATA[
<?php

// create a new LuaSandbox
$sandbox = new LuaSandbox();

// Register some functions in the Lua environment

function frobnosticate( $v ) {
    return [ $v + 42 ];
}

$sandbox->registerLibrary( 'php', [
    'frobnosticate' => 'frobnosticate',
    'output' => function ( $string ) {
        echo "$string\n";
    },
    'error' => function () {
        throw new LuaSandboxRuntimeError( "Something is wrong" );
    }
] );

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><methodname>LuaSandbox::loadString</methodname></member>
    <member><methodname>LuaSandbox::wrapPhpFunction</methodname></member>
   </simplelist>
  </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
-->
