php-doc-en/functions/readline.xml

 <reference id="ref.readline">
  <title>GNU Readline</title>
  <titleabbrev>readline</titleabbrev>

  <partintro>
   <simpara>
    The <function>readline</function> functions implement an interface
    to the GNU Readline library.  These are functions that provide
    editable command lines.  An example being the way Bash
    allows you to use the arrow keys to insert characters or scroll
    through command history.  Because of the interactive nature of this
    library, it will be of little use for writing Web applications, but
    may be useful when writing scripts meant to be run from a shell.
   </simpara>
   <simpara>
    The home page of the GNU Readline project is
    <ulink url="&url.readline;">&url.readline;</ulink>.  It's maintained
    by Chet Ramey, who's also the author of Bash.
   </simpara>
  </partintro>

  <refentry id="function.readline">
   <refnamediv>
    <refname>readline</refname>
    <refpurpose>Reads a line</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>string <function>readline</function></funcdef>
      <paramdef>string <parameter>
       <optional>prompt</optional>
      </parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     This function returns a single string from the user.  You may specify
     a string with which to prompt the user.  The line returned has the 
     ending newline removed.  You must add this line to the history yourself
     using <function>readline_add_history</function>. 
    </para>
     <example>
      <title><function>readline</function></title>
      <programlisting role="php">
//get 3 commands from user
for($i=0; $i < 3; $i++)
{
        $line = readline("Command: ");
        readline_add_history($line);
}

//dump history
print_r(readline_list_history());

//dump variables
print_r(readline_info());
      </programlisting>
	 </example>
   </refsect1>
  </refentry>

  <refentry id="function.readline-add-history">
   <refnamediv>
    <refname>readline_add_history</refname>
    <refpurpose>Adds a line to the history</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>void <function>readline_add_history</function></funcdef>
      <paramdef>string <parameter>line</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     This function adds a line to the command line history.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.readline-clear-history">
   <refnamediv>
    <refname>readline_clear_history</refname>
    <refpurpose>Clears the history</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>boolean <function>readline_clear_history</function></funcdef>
	  <paramdef>void <parameter></parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     This function clears the entire command line history.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.readline-completion-function">
   <refnamediv>
    <refname>readline_completion_function</refname>
    <refpurpose>Registers a completion function</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>boolean <function>readline_completion_function</function></funcdef>
      <paramdef>string <parameter>line</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     This function registers a completion function.  You must supply the name of
     an existing function which accepts a partial command line and returns an array
     of possible matches.  This is the same kind of functionality you'd get if you
     hit your tab key while using Bash.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.readline-info">
   <refnamediv>
    <refname>readline_info</refname>
    <refpurpose>Gets/sets various internal readline variables</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>mixed <function>readline_info</function></funcdef>
      <paramdef>string <parameter>
       <optional>varname</optional>
      </parameter></paramdef>
      <paramdef>string <parameter>
       <optional>newvalue</optional>
      </parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     If called with no parameters, this function returns an array of values
     for all the setting readline uses.  The elements will will be indexed
     by the following values: done, end, erase_empty_line, library_version, 
     line_buffer, mark, pending_input, point, prompt, readline_name, and
     terminal_name.
    </para>
    <para>
     If called with one parameter, the value of that setting is returned.
     If called with two parameters, the setting will be changed to the given
     value.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.readline-list-history">
   <refnamediv>
    <refname>readline_list_history</refname>
    <refpurpose>Lists the history</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>array <function>readline_list_history</function></funcdef>
	  <paramdef>void <parameter></parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     This function returns an array of the entire command line history.
     The elements are indexed by integers starting at zero.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.readline-read-history">
   <refnamediv>
    <refname>readline_read_history</refname>
    <refpurpose>Reads the history</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>boolean <function>readline_read_history</function></funcdef>
      <paramdef>string <parameter>filename</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     This function reads a command history from a file.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.readline-write-history">
   <refnamediv>
    <refname>readline_write_history</refname>
    <refpurpose>Writes the history</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>boolean <function>readline_write_history</function></funcdef>
      <paramdef>string <parameter>filename</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     This function writes the command history to a file.
    </para>
   </refsect1>
  </refentry>

 </reference>

<!-- 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
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->