From 3d7a486566e304e64975a78ee59de3b8429f5349 Mon Sep 17 00:00:00 2001
From: Dave Barr <dave@php.net>
Date: Wed, 25 Aug 2004 04:38:38 +0000
Subject: [PATCH] - Document Wez's new readline callback functions.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@167219 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../readline-callback-handler-install.xml     | 107 ++++++++++++++++++
 .../readline-callback-handler-remove.xml      |  61 ++++++++++
 .../functions/readline-callback-read-char.xml |  56 +++++++++
 3 files changed, 224 insertions(+)
 create mode 100644 reference/readline/functions/readline-callback-handler-install.xml
 create mode 100644 reference/readline/functions/readline-callback-handler-remove.xml
 create mode 100644 reference/readline/functions/readline-callback-read-char.xml

diff --git a/reference/readline/functions/readline-callback-handler-install.xml b/reference/readline/functions/readline-callback-handler-install.xml
new file mode 100644
index 0000000000..ca9e15f205
--- /dev/null
+++ b/reference/readline/functions/readline-callback-handler-install.xml
@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.1 $ -->
+  <refentry id="function.readline-callback-handler-install">
+   <refnamediv>
+    <refname>readline_callback_handler_install</refname>
+    <refpurpose>Initializes the readline callback interface and terminal, prints the prompt and returns immediately</refpurpose>
+   </refnamediv>
+   <refsect1>
+    &reftitle.description;
+     <methodsynopsis>
+      <type>bool</type><methodname>readline_callback_handler_install</methodname>
+      <methodparam><type>string</type><parameter>prompt</parameter></methodparam>
+      <methodparam><type>callback</type><parameter>callback</parameter></methodparam>
+     </methodsynopsis>
+    <para>
+     Sets up a readline callback interface then prints
+     <parameter>prompt</parameter> and immediately returns. The
+     <parameter>callback</parameter> function takes one parameter; the user
+     input returned. Calling this function twice without removing the previous
+     callback interface will automatically and conveniently overwrite the old
+     interface.
+    </para>
+    <para>
+     The callback feature is useful when combined with
+     <function>stream_select</function> as it allows interleaving of IO and
+     user input, unlike <function>readline</function>.
+    </para>
+   </refsect1>
+   <refsect1>
+    &reftitle.returnvalues;
+    <para>
+     &return.success;
+    </para>
+   </refsect1>
+   <refsect1>
+    &reftitle.examples;
+    <para>
+     <example>
+      <title>Readline Callback Interface Example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+function rl_callback($ret)
+{
+    global $c, $prompting;
+
+    echo "You entered: $ret\n";
+    $c++;
+
+    if ($c > 10) {
+        $prompting = false;
+        readline_callback_handler_remove();
+    } else {
+        readline_callback_handler_install("[$c] Enter something: ", 'rl_callback');
+    }
+}
+
+$c = 1;
+$prompting = true;
+
+readline_callback_handler_install("[$c] Enter something: ", 'rl_callback');
+
+while ($prompting) {
+    $n = stream_select($r = array(STDIN), $w = null, $e = null, null);
+    if ($n && in_array(STDIN, $r)) {
+        // read a character, will call the callback when a newline is entered
+        readline_callback_read_char();
+    }
+}
+
+echo "Prompting disabled. All done.\n";
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
+   </refsect1>
+   <refsect1>
+    &reftitle.seealso;
+    <para>
+     <function>readline_callback_handler_remove</function>,
+     <function>readline_callback_read_char</function>&listendand;
+     <function>stream_select</function>.
+    </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:"../../../../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
+-->
diff --git a/reference/readline/functions/readline-callback-handler-remove.xml b/reference/readline/functions/readline-callback-handler-remove.xml
new file mode 100644
index 0000000000..3cbc887dbe
--- /dev/null
+++ b/reference/readline/functions/readline-callback-handler-remove.xml
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.1 $ -->
+  <refentry id="function.readline-callback-handler-remove">
+   <refnamediv>
+    <refname>readline_callback_handler_remove</refname>
+    <refpurpose>Removes a previously installed callback handler and restores terminal settings</refpurpose>
+   </refnamediv>
+   <refsect1>
+    &reftitle.description;
+     <methodsynopsis>
+      <type>bool</type><methodname>readline_callback_handler_remove</methodname>
+      <void/>
+     </methodsynopsis>
+    <para>
+     Removes a previously installed callback handler and restores terminal
+     settings.
+    </para>
+   </refsect1>
+   <refsect1>
+    &reftitle.examples;
+    <para>
+     See <function>readline_callback_handler_install</function> for an example
+     of how to use the readline callback interface.
+    </para>
+   </refsect1>
+   <refsect1>
+    &reftitle.returnvalues;
+    <para>
+     Returns &true; if a previously installed callback handler was removed, or
+     &false; if one could not be found.
+    </para>
+   </refsect1>
+   <refsect1>
+    &reftitle.seealso;
+    <para>
+     <function>readline_callback_handler_install</function>, and
+     <function>readline_callback_read_char</function>.
+    </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:"../../../../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
+-->
diff --git a/reference/readline/functions/readline-callback-read-char.xml b/reference/readline/functions/readline-callback-read-char.xml
new file mode 100644
index 0000000000..97d896c182
--- /dev/null
+++ b/reference/readline/functions/readline-callback-read-char.xml
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.1 $ -->
+  <refentry id="function.readline-callback-read-char">
+   <refnamediv>
+    <refname>readline_callback_read_char</refname>
+    <refpurpose>Reads a character and informs the readline callback interface when a line is received</refpurpose>
+   </refnamediv>
+   <refsect1>
+    &reftitle.description;
+     <methodsynopsis>
+      <type>void</type><methodname>readline_callback_read_char</methodname>
+      <void />
+     </methodsynopsis>
+    <para>
+     Reads a character of user input. When a line is received, this function
+     informs the readline callback interface installed using
+     <function>readline_callback_handler_install</function> that a line
+     is ready for input.
+    </para>
+   </refsect1>
+   <refsect1>
+    &reftitle.examples;
+    <para>
+     See <function>readline_callback_handler_install</function> for an example
+     of how to use the readline callback interface.
+    </para>
+   </refsect1>
+   <refsect1>
+    &reftitle.seealso;
+    <para>
+     <function>readline_callback_handler_install</function>, and
+     <function>readline_callback_handler_remove</function>.
+    </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:"../../../../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
+-->