[doc-en] master: readline: Document functions unavailable where feature is not supported (#4923)
| From: | AllenJB via GitHub | Date: | Tue, 01 Sep 2026 14:39:24 +0000 |
| Subject: | [doc-en] master: readline: Document functions unavailable where feature is not supported (#4923) | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-23690@lists.php.net to get a copy of this message | ||
Author: AllenJB (AllenJB)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-09-01T16:39:20+02:00
Commit: https://github.com/php/doc-en/commit/8648d1cda141537b5dbd403a0bf0e6eb8c086e9d
Raw diff: https://github.com/php/doc-en/commit/8648d1cda141537b5dbd403a0bf0e6eb8c086e9d.diff
readline: Document functions unavailable where feature is not supported (#4923)
* readline: Document functions unavailable where feature is not supported (fixes #1482)
* Move callback feature system support notice to an entity
* readline: Document functions unavailable where feature is not supported (fixes #1482)
* readline: reconcile the Windows availability statements
The extension is supported on Windows, but five of its functions are not
present in that build. Say so where the extension-level statement is made,
list the affected functions in the requirements section, and point at
function_exists() and READLINE_LIB so a reader can test their own build.
Changed paths:
M language-snippets.ent
M reference/readline/book.xml
M reference/readline/functions/readline-callback-handler-install.xml
M reference/readline/functions/readline-callback-handler-remove.xml
M reference/readline/functions/readline-callback-read-char.xml
M reference/readline/functions/readline-list-history.xml
M reference/readline/functions/readline-on-new-line.xml
M reference/readline/functions/readline-redisplay.xml
M reference/readline/setup.xml
Diff:
diff --git a/language-snippets.ent b/language-snippets.ent
index 11856a0efe2f..d98bb6831217 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -4572,6 +4572,14 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This
function has been
</informaltable>
'>
+<!-- readline -->
+<!ENTITY readline.system-callback-support '
+ <simpara xmlns="http://docbook.org/ns/docbook">
+ This function is only available if the readline library PHP was built
+ against supports it. It is not available on Windows.
+ </simpara>
+'>
+
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
diff --git a/reference/readline/book.xml b/reference/readline/book.xml
index 2eb6b58dbcc2..59785a9cf9ac 100644
--- a/reference/readline/book.xml
+++ b/reference/readline/book.xml
@@ -19,7 +19,9 @@
<link linkend="features.commandline">command line</link>.
</simpara>
<simpara>
- As of PHP 7.1.0 this extension is supported on Windows.
+ As of PHP 7.1.0 this extension is supported on Windows, where it is built
+ against libedit. Not every function is present in that build; see
+ <link linkend="readline.requirements">the requirements</link>.
</simpara>
<caution>
<simpara>
diff --git a/reference/readline/functions/readline-callback-handler-install.xml
b/reference/readline/functions/readline-callback-handler-install.xml
index 2fa3d1e1d48b..82ef06a3c6a1 100644
--- a/reference/readline/functions/readline-callback-handler-install.xml
+++ b/reference/readline/functions/readline-callback-handler-install.xml
@@ -25,6 +25,7 @@
<function>stream_select</function> as it allows interleaving of IO and
user input, unlike <function>readline</function>.
</simpara>
+ &readline.system-callback-support;
</refsect1>
<refsect1 role="parameters">
diff --git a/reference/readline/functions/readline-callback-handler-remove.xml
b/reference/readline/functions/readline-callback-handler-remove.xml
index 26a3f6664462..fc0c1bfd6cc6 100644
--- a/reference/readline/functions/readline-callback-handler-remove.xml
+++ b/reference/readline/functions/readline-callback-handler-remove.xml
@@ -16,6 +16,7 @@
Removes a previously installed callback handler and restores terminal
settings.
</simpara>
+ &readline.system-callback-support;
</refsect1>
<refsect1 role="parameters">
diff --git a/reference/readline/functions/readline-callback-read-char.xml
b/reference/readline/functions/readline-callback-read-char.xml
index 890c3d989e4f..8d1eb68cb586 100644
--- a/reference/readline/functions/readline-callback-read-char.xml
+++ b/reference/readline/functions/readline-callback-read-char.xml
@@ -18,6 +18,7 @@
<function>readline_callback_handler_install</function> that a line
is ready for input.
</simpara>
+ &readline.system-callback-support;
</refsect1>
<refsect1 role="parameters">
diff --git a/reference/readline/functions/readline-list-history.xml
b/reference/readline/functions/readline-list-history.xml
index 9c901ef9d863..bf090328eb0a 100644
--- a/reference/readline/functions/readline-list-history.xml
+++ b/reference/readline/functions/readline-list-history.xml
@@ -15,6 +15,11 @@
<simpara>
Gets the entire command line history.
</simpara>
+ <simpara>
+ This function is only available if the readline library PHP was built
+ against provides history listing. This is always the case with GNU Readline
+ and on Windows.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
diff --git a/reference/readline/functions/readline-on-new-line.xml
b/reference/readline/functions/readline-on-new-line.xml
index b45bfae13a96..00d80ef3f97b 100644
--- a/reference/readline/functions/readline-on-new-line.xml
+++ b/reference/readline/functions/readline-on-new-line.xml
@@ -15,6 +15,7 @@
<simpara>
Tells readline that the cursor has moved to a new line.
</simpara>
+ &readline.system-callback-support;
</refsect1>
<refsect1 role="parameters">
@@ -29,14 +30,11 @@
</simpara>
</refsect1>
- <refsect1 role="notes">
- &reftitle.notes;
- <note>
- <simpara>
- This function is only available if supported by the underlying readline library.
- It is not supported on Windows.
- </simpara>
- </note>
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><function>readline_callback_handler_install</function></member>
+ </simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/readline/functions/readline-redisplay.xml
b/reference/readline/functions/readline-redisplay.xml
index 330cbdfea91d..dd3ceaf489ea 100644
--- a/reference/readline/functions/readline-redisplay.xml
+++ b/reference/readline/functions/readline-redisplay.xml
@@ -15,6 +15,7 @@
<simpara>
Redraws readline to redraw the display.
</simpara>
+ &readline.system-callback-support;
</refsect1>
<refsect1 role="parameters">
@@ -28,6 +29,13 @@
&return.void;
</simpara>
</refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><function>readline_callback_handler_install</function></member>
+ </simplelist>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
diff --git a/reference/readline/setup.xml b/reference/readline/setup.xml
index cb48466f8ead..3775e54f8334 100644
--- a/reference/readline/setup.xml
+++ b/reference/readline/setup.xml
@@ -18,6 +18,19 @@
licensed and available for download from
<link xlink:href="&url.libedit;">&url.libedit;</link>.
</simpara>
+ <simpara>
+ The two libraries do not provide the same features, so some functions are
+ absent from some builds. The functions driving the callback interface,
+ <function>readline_callback_handler_install</function>,
+ <function>readline_callback_handler_remove</function>,
+ <function>readline_callback_read_char</function>,
+ <function>readline_redisplay</function> and
+ <function>readline_on_new_line</function>, are only present when the
+ underlying library provides them, and are absent on Windows. Calling an
+ absent function throws an <exceptionname>Error</exceptionname>.
+ <function>function_exists</function> tests for a given function, and the
+ <constant>READLINE_LIB</constant> constant reports which library is in use.
+ </simpara>
</section>
<!-- }}} -->