php-doc-en/functions/readline.xml

<?xml encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
 <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 &lt; 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>bool <function>readline_clear_history</function></funcdef>
      <void/>
     </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>bool 
       <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
     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>
      <void/>
     </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>bool 
       <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>bool 
       <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:
-->