new readline command `export-completions'; update documentation; update translations with new strings; Makefile updates

2026-08-07 18:52:35 +02:00 · 2024-11-21 10:31:38 -05:00
parent fa68e6da80
commit 22417e7881
104 changed files with 23828 additions and 18845 deletions
@@ -153,6 +153,8 @@ static int complete_get_screenwidth (void);

 static char *make_quoted_replacement (char *, int, char *);

+static void _rl_export_completions (char **, char *, int, int);
+
 /* **************************************************************** */
 /*								    */
 /*	Completion matching, from readline's point of view.	    */
@@ -539,6 +541,18 @@ _rl_complete_sigcleanup (int sig, void *ptr)
 /*				    */
 /************************************/

+static inline size_t
+vector_len (char **vector)
+{
+  size_t ret;
+
+  if (vector == 0 || vector[0] == 0)
+    return (size_t)0;
+  for (ret = 0; vector[ret]; ret++)
+    ;
+  return ret;
+}
+
 /* Reset public readline state on a signal or other event. */
 void
 _rl_reset_completion_state (void)
@@ -1301,8 +1315,7 @@ remove_duplicate_matches (char **matches)
  char **temp_array;

  /* Sort the items. */
-  for (i = 0; matches[i]; i++)
-    ;
+  i = vector_len (matches);

  /* Sort the array without matches[0], since we need it to
     stay in place no matter what. */
@@ -2046,7 +2059,9 @@ compare_match (char *text, const char *match)
   `!' means to do standard completion, and list all possible completions if
   there is more than one.
   `@' means to do standard completion, and list all possible completions if
-   there is more than one and partial completion is not possible. */
+   there is more than one and partial completion is not possible.
+   `$' implements a protocol for exporting completions and information about
+   what is being completed to another process via rl_outstream. */
 int
 rl_complete_internal (int what_to_do)
 {
@@ -2103,9 +2118,11 @@ rl_complete_internal (int what_to_do)
    nontrivial_lcd = matches && strcmp (text, matches[0]) != 0;
  if (what_to_do == '!' || what_to_do == '@')
    tlen = strlen (text);
-  xfree (text);

-  if (matches == 0)
+  if (what_to_do != '$')
+    xfree (text);
+
+  if (matches == 0 && what_to_do != '$')	/* we can export no completions */
    {
      rl_ding ();
      FREE (saved_line_buffer);
@@ -2121,7 +2138,7 @@ rl_complete_internal (int what_to_do)
     rl_filename_completion_function does this. */
  i = rl_filename_completion_desired;

-  if (postprocess_matches (&matches, i) == 0)
+  if (postprocess_matches (&matches, i) == 0 && what_to_do != '$')	/* we can export no completions */
    {
      rl_ding ();
      FREE (saved_line_buffer);
@@ -2207,6 +2224,11 @@ rl_complete_internal (int what_to_do)
      do_display = 1;
      break;

+    case '$':
+      _rl_export_completions (matches, text, start, end);
+      xfree (text);
+      break;
+
    default:
      _rl_ttymsg ("bad value %d for what_to_do in rl_complete", what_to_do);
      rl_ding ();
@@ -2772,8 +2794,8 @@ rl_old_menu_complete (int count, int invoking_key)

      RL_UNSETSTATE(RL_STATE_COMPLETING);

-      for (match_list_size = 0; matches[match_list_size]; match_list_size++)
-        ;
+      match_list_size = vector_len (matches);
+
      /* matches[0] is lcd if match_list_size > 1, but the circular buffer
 	 code below should take care of it. */

@@ -2907,8 +2929,7 @@ rl_menu_complete (int count, int ignore)

      RL_UNSETSTATE(RL_STATE_COMPLETING);

-      for (match_list_size = 0; matches[match_list_size]; match_list_size++)
-        ;
+      match_list_size = vector_len (matches);

      if (match_list_size == 0) 
 	{
@@ -3007,3 +3028,55 @@ rl_backward_menu_complete (int count, int key)
     arguments for menu-complete, and vice versa. */
  return (rl_menu_complete (-count, key));
 }
+
+/* This implements a protocol to export completions to another process or
+   calling application via rl_outstream.
+
+   MATCHES are the possible completions for TEXT, which is the text between
+   START and END in rl_line_buffer.
+
+   We print:
+   	N - the number of matches
+   	T - the word being completed
+   	S:E - the start and end offsets of T in rl_line_buffer
+   	then each match, one per line
+
+  If there are no matches, MATCHES is NULL, N will be 0, and there will be
+  no output after S:E.
+
+  Since MATCHES[0] can be empty if there is no common prefix of the elements
+  of MATCHES, applications should be prepared to deal with an empty line
+  preceding the matches.
+*/
+
+static void
+_rl_export_completions (char **matches, char *text, int start, int end)
+{
+  size_t len, i;
+
+  len = vector_len (matches);
+
+  if (RL_ISSTATE (RL_STATE_TERMPREPPED))
+    fprintf (rl_outstream, "\r\n");
+  fprintf (rl_outstream, "%zd\n", len);
+  fprintf (rl_outstream, "%s\n", text);
+  fprintf (rl_outstream, "%d:%d\n", start, end);	/* : because it's not a radix character */
+  for (i = 0; i < len; i++)
+    fprintf (rl_outstream, "%s\n", matches[i]);
+  fflush (rl_outstream);
+}
+
+int
+rl_export_completions (int count, int key)
+{
+  rl_complete_internal ('$');
+
+  /* Clear the line buffer, currently requires a count argument. */
+  if (count > 1)
+    {
+      rl_delete_text (0, rl_end);		/* undoable */
+      rl_point = rl_mark = 0;
+    }
+
+  return 0;
+}
@@ -1,9 +1,9 @@
 This is history.info, produced by makeinfo version 7.1 from
 history.texi.

-This document describes the GNU History library (version 8.3, 15 October
-2024), a programming tool that provides a consistent user interface for
-recalling lines of previously typed input.
+This document describes the GNU History library (version 8.3, 15
+November 2024), a programming tool that provides a consistent user
+interface for recalling lines of previously typed input.

   Copyright © 1988-2024 Free Software Foundation, Inc.

@@ -1430,28 +1430,28 @@ Appendix C Function and Variable Index


 Tag Table:
-Node: Top847
-Node: Using History Interactively1492
-Node: History Interaction2000
-Node: Event Designators4714
-Node: Word Designators6216
-Node: Modifiers8527
-Node: Programming with GNU History10178
-Node: Introduction to History10922
-Node: History Storage12654
-Node: History Functions13834
-Node: Initializing History and State Management14823
-Node: History List Management15626
-Node: Information About the History List18057
-Node: Moving Around the History List19670
-Node: Searching the History List20750
-Node: Managing the History File22696
-Node: History Expansion25166
-Node: History Variables27139
-Node: History Programming Example31281
-Node: GNU Free Documentation License33935
-Node: Concept Index59110
-Node: Function and Variable Index59815
+Node: Top848
+Node: Using History Interactively1493
+Node: History Interaction2001
+Node: Event Designators4715
+Node: Word Designators6217
+Node: Modifiers8528
+Node: Programming with GNU History10179
+Node: Introduction to History10923
+Node: History Storage12655
+Node: History Functions13835
+Node: Initializing History and State Management14824
+Node: History List Management15627
+Node: Information About the History List18058
+Node: Moving Around the History List19671
+Node: Searching the History List20751
+Node: Managing the History File22697
+Node: History Expansion25167
+Node: History Variables27140
+Node: History Programming Example31282
+Node: GNU Free Documentation License33936
+Node: Concept Index59111
+Node: Function and Variable Index59816

 End Tag Table

@@ -918,6 +918,30 @@ EEDDIITTIINNGG CCOOMMMMAANNDDSS
              Identical  to mmeennuu--ccoommpplleettee, but moves backward through the list
              of possible completions, as if mmeennuu--ccoommpplleettee had  been  given  a
              negative argument.  This command is unbound by default.
+       eexxppoorrtt--ccoommpplleettiioonnss
+              Perform  completion  on the word before point as described above
+              and write the list of possible completions to rreeaaddlliinnee's  output
+              stream  using the following format, writing information on sepa-
+              rate lines:
+
+              The number of matches;
+              The word being completed;
+              S:E, where S and E are the start and end offsets of the word
+              in the readline line buffer; then
+              Each match, one per line
+
+              If there are no matches, the first line will be 0, and this com-
+              mand will not print any output after the S:E.  If there is  only
+              a  single  match,  this  prints a single line containing it.  If
+              there is more than one match, this prints the common  prefix  of
+              the  matches,  which  may  be empty, on the first line after the
+              S:E, then the matches on subsequent lines.  In this case, N will
+              include the first line with the common prefix.
+
+              The user or application should be able to accommodate the possi-
+              bility of a blank line.  The intent is that the user or applica-
+              tion reads N lines after the line containing S:E.  This  command
+              is unbound by default.
       ddeelleettee--cchhaarr--oorr--lliisstt
              Deletes  the  character under the cursor if not at the beginning
              or end of the line (like ddeelleettee--cchhaarr).  At the end of the  line,
@@ -6,9 +6,9 @@
 .\"	Case Western Reserve University
 .\"	chet.ramey@case.edu
 .\"
-.\"	Last Change: Thu Oct 10 16:33:40 EDT 2024
+.\"	Last Change: Fri Nov 15 17:57:09 EST 2024
 .\"
-.TH READLINE 3 "2024 October 10" "GNU Readline 8.3"
+.TH READLINE 3 "2024 November 15" "GNU Readline 8.3"
 .\"
 .ie \n(.g \{\
 .ds ' \(aq
@@ -1410,6 +1410,39 @@ of possible completions, as if \fBmenu\-complete\fP had been given a
 negative argument.
 This command is unbound by default.
 .TP
+.B export\-completions
+Perform completion on the word before point as described above
+and write the list of possible completions to \fBreadline\fP's output
+stream using the following format, writing information on separate lines:
+.sp
+.IP
+.RS
+.nf
+The number of matches; 
+The word being completed;
+S:E, where S and E are the start and end offsets of the word
+in the readline line buffer; then
+Each match, one per line
+.fi
+.RE
+.sp
+.IP
+If there are no matches, the first line will be 0, and this command will
+not print any output after the S:E.
+If there is only a single match, this prints a single line containing it.
+If there is more than one match, this prints the common prefix of the
+matches, which may be empty, on the first line after the S:E,
+then the matches on subsequent lines.
+In this case, N will include the first line with the common prefix.
+.PD
+.IP
+.PD 0
+The user or application
+should be able to accommodate the possibility of a blank line.
+The intent is that the user or application reads N lines after the line
+containing S:E to obtain the match list.
+This command is unbound by default.
+.TP
 .B delete\-char\-or\-list
 Deletes the character under the cursor if not at the beginning or
 end of the line (like \fBdelete\-char\fP).
@@ -1,6 +1,6 @@
 This is readline.info, produced by makeinfo version 7.1 from rlman.texi.

-This manual describes the GNU Readline Library (version 8.3, 15 October
+This manual describes the GNU Readline Library (version 8.3, 15 November
 2024), a library which aids in the consistency of user interface across
 discrete programs which provide a command line interface.

@@ -1477,6 +1477,30 @@ File: readline.info,  Node: Commands For Completion,  Next: Keyboard Macros,  Pr
     of possible completions, as if ‘menu-complete’ had been given a
     negative argument.  This command is unbound by default.

+‘export-completions ()’
+     Perform completion on the word before point as described above and
+     write the list of possible completions to Readline's output stream
+     using the following format, writing information on separate lines:
+
+          The number of matches;
+          The word being completed;
+          S:E, where S and E are the start and end offsets of the word
+          in the readline line buffer; then
+          Each match, one per line
+
+     If there are no matches, the first line will be 0, and this command
+     will not print any output after the S:E. If there is only a single
+     match, this prints a single line containing it.  If there is more
+     than one match, this prints the common prefix of the matches, which
+     may be empty, on the first line after the S:E, then the matches on
+     subsequent lines.  In this case, N will include the first line with
+     the common prefix.
+
+     The user or application should be able to accommodate the
+     possibility of a blank line.  The intent is that the user or
+     application reads N lines after the line containing S:E to obtain
+     the match list.  This command is unbound by default.
+
 ‘delete-char-or-list ()’
     Deletes the character under the cursor if not at the beginning or
     end of the line (like ‘delete-char’).  At the end of the line, it
@@ -4937,7 +4961,7 @@ Function and Variable Index
                                                              (line  49)
 * delete-char (C-d):                     Commands For Text.   (line  12)
 * delete-char-or-list ():                Commands For Completion.
-                                                              (line  38)
+                                                              (line  62)
 * delete-horizontal-space ():            Commands For Killing.
                                                              (line  41)
 * digit-argument (M-0, M-1, ... M--):    Numeric Arguments.   (line   6)
@@ -4979,6 +5003,8 @@ Function and Variable Index
                                                              (line  87)
 * expand-tilde:                          Readline Init File Syntax.
                                                              (line 212)
+* export-completions ():                 Commands For Completion.
+                                                              (line  38)
 * fetch-history ():                      Commands For History.
                                                              (line 105)
 * force-meta-prefix:                     Readline Init File Syntax.
@@ -5411,59 +5437,59 @@ Function and Variable Index


 Tag Table:
-Node: Top863
-Node: Command Line Editing1588
-Node: Introduction and Notation2240
-Node: Readline Interaction4596
-Node: Readline Bare Essentials5788
-Node: Readline Movement Commands7600
-Node: Readline Killing Commands8600
-Node: Readline Arguments10627
-Node: Searching11688
-Node: Readline Init File13919
-Node: Readline Init File Syntax15117
-Node: Conditional Init Constructs41509
-Node: Sample Init File45898
-Node: Bindable Readline Commands49023
-Node: Commands For Moving50407
-Node: Commands For History52337
-Node: Commands For Text57542
-Node: Commands For Killing61387
-Node: Numeric Arguments63843
-Node: Commands For Completion64999
-Node: Keyboard Macros67086
-Node: Miscellaneous Commands67791
-Node: Readline vi Mode72115
-Node: Programming with GNU Readline74012
-Node: Basic Behavior74998
-Node: Custom Functions79061
-Node: Readline Typedefs80583
-Node: Function Writing82469
-Node: Readline Variables83775
-Node: Readline Convenience Functions98729
-Node: Function Naming99805
-Node: Keymaps101136
-Node: Binding Keys104298
-Node: Associating Function Names and Bindings109123
-Node: Allowing Undoing112953
-Node: Redisplay115703
-Node: Modifying Text120005
-Node: Character Input121544
-Node: Terminal Management124701
-Node: Utility Functions126588
-Node: Miscellaneous Functions129698
-Node: Alternate Interface133588
-Node: A Readline Example136483
-Node: Alternate Interface Example138401
-Node: Readline Signal Handling142020
-Node: Custom Completers151570
-Node: How Completing Works152290
-Node: Completion Functions155666
-Node: Completion Variables159333
-Node: A Short Completion Example177651
-Node: GNU Free Documentation License190320
-Node: Concept Index215497
-Node: Function and Variable Index217018
+Node: Top864
+Node: Command Line Editing1589
+Node: Introduction and Notation2241
+Node: Readline Interaction4597
+Node: Readline Bare Essentials5789
+Node: Readline Movement Commands7601
+Node: Readline Killing Commands8601
+Node: Readline Arguments10628
+Node: Searching11689
+Node: Readline Init File13920
+Node: Readline Init File Syntax15118
+Node: Conditional Init Constructs41510
+Node: Sample Init File45899
+Node: Bindable Readline Commands49024
+Node: Commands For Moving50408
+Node: Commands For History52338
+Node: Commands For Text57543
+Node: Commands For Killing61388
+Node: Numeric Arguments63844
+Node: Commands For Completion65000
+Node: Keyboard Macros68270
+Node: Miscellaneous Commands68975
+Node: Readline vi Mode73299
+Node: Programming with GNU Readline75196
+Node: Basic Behavior76182
+Node: Custom Functions80245
+Node: Readline Typedefs81767
+Node: Function Writing83653
+Node: Readline Variables84959
+Node: Readline Convenience Functions99913
+Node: Function Naming100989
+Node: Keymaps102320
+Node: Binding Keys105482
+Node: Associating Function Names and Bindings110307
+Node: Allowing Undoing114137
+Node: Redisplay116887
+Node: Modifying Text121189
+Node: Character Input122728
+Node: Terminal Management125885
+Node: Utility Functions127772
+Node: Miscellaneous Functions130882
+Node: Alternate Interface134772
+Node: A Readline Example137667
+Node: Alternate Interface Example139585
+Node: Readline Signal Handling143204
+Node: Custom Completers152754
+Node: How Completing Works153474
+Node: Completion Functions156850
+Node: Completion Variables160517
+Node: A Short Completion Example178835
+Node: GNU Free Documentation License191504
+Node: Concept Index216681
+Node: Function and Variable Index218202

 End Tag Table

@@ -1785,6 +1785,33 @@ of possible completions, as if @code{menu-complete} had been given a
 negative argument.
 This command is unbound by default.

+@item export-completions ()
+Perform completion on the word before point as described above
+and write the list of possible completions to Readline's output stream
+using the following format, writing information on separate lines:
+
+@example
+The number of matches;
+The word being completed;
+S:E, where S and E are the start and end offsets of the word
+in the readline line buffer; then
+Each match, one per line
+@end example
+
+If there are no matches, the first line will be 0, and this command will
+not print any output after the S:E.
+If there is only a single match, this prints a single line containing it.
+If there is more than one match, this prints the common prefix of the
+matches, which may be empty, on the first line after the S:E,
+then the matches on subsequent lines.
+In this case, N will include the first line with the common prefix.
+
+The user or application
+should be able to accommodate the possibility of a blank line.
+The intent is that the user or application reads N lines after the line
+containing S:E to obtain the match list.
+This command is unbound by default.
+
@item delete-char-or-list ()
 Deletes the character under the cursor if not at the beginning or
 end of the line (like @code{delete-char}).
@@ -2,7 +2,7 @@ This is rluserman.info, produced by makeinfo version 7.1 from
 rluserman.texi.

 This manual describes the end user interface of the GNU Readline Library
-(version 8.3, 15 October 2024), a library which aids in the consistency
+(version 8.3, 15 November 2024), a library which aids in the consistency
 of user interface across discrete programs which provide a command line
 interface.

@@ -1475,6 +1475,30 @@ File: rluserman.info,  Node: Commands For Completion,  Next: Keyboard Macros,  P
     of possible completions, as if ‘menu-complete’ had been given a
     negative argument.  This command is unbound by default.

+‘export-completions ()’
+     Perform completion on the word before point as described above and
+     write the list of possible completions to Readline's output stream
+     using the following format, writing information on separate lines:
+
+          The number of matches;
+          The word being completed;
+          S:E, where S and E are the start and end offsets of the word
+          in the readline line buffer; then
+          Each match, one per line
+
+     If there are no matches, the first line will be 0, and this command
+     will not print any output after the S:E. If there is only a single
+     match, this prints a single line containing it.  If there is more
+     than one match, this prints the common prefix of the matches, which
+     may be empty, on the first line after the S:E, then the matches on
+     subsequent lines.  In this case, N will include the first line with
+     the common prefix.
+
+     The user or application should be able to accommodate the
+     possibility of a blank line.  The intent is that the user or
+     application reads N lines after the line containing S:E to obtain
+     the match list.  This command is unbound by default.
+
 ‘delete-char-or-list ()’
     Deletes the character under the cursor if not at the beginning or
     end of the line (like ‘delete-char’).  At the end of the line, it
@@ -2111,30 +2135,30 @@ their use in free software.


 Tag Table:
-Node: Top906
-Node: Command Line Editing1428
-Node: Introduction and Notation2082
-Node: Readline Interaction4439
-Node: Readline Bare Essentials5632
-Node: Readline Movement Commands7445
-Node: Readline Killing Commands8446
-Node: Readline Arguments10474
-Node: Searching11536
-Node: Readline Init File13768
-Node: Readline Init File Syntax14967
-Node: Conditional Init Constructs41360
-Node: Sample Init File45750
-Node: Bindable Readline Commands48876
-Node: Commands For Moving50261
-Node: Commands For History52192
-Node: Commands For Text57398
-Node: Commands For Killing61244
-Node: Numeric Arguments63701
-Node: Commands For Completion64858
-Node: Keyboard Macros66946
-Node: Miscellaneous Commands67652
-Node: Readline vi Mode71977
-Node: GNU Free Documentation License72971
+Node: Top907
+Node: Command Line Editing1429
+Node: Introduction and Notation2083
+Node: Readline Interaction4440
+Node: Readline Bare Essentials5633
+Node: Readline Movement Commands7446
+Node: Readline Killing Commands8447
+Node: Readline Arguments10475
+Node: Searching11537
+Node: Readline Init File13769
+Node: Readline Init File Syntax14968
+Node: Conditional Init Constructs41361
+Node: Sample Init File45751
+Node: Bindable Readline Commands48877
+Node: Commands For Moving50262
+Node: Commands For History52193
+Node: Commands For Text57399
+Node: Commands For Killing61245
+Node: Numeric Arguments63702
+Node: Commands For Completion64859
+Node: Keyboard Macros68130
+Node: Miscellaneous Commands68836
+Node: Readline vi Mode73161
+Node: GNU Free Documentation License74155

 End Tag Table

@@ -5,7 +5,7 @@ Copyright (C) 1988-2024 Free Software Foundation, Inc.
@set EDITION 8.3
@set VERSION 8.3

-@set UPDATED 15 October 2024
-@set UPDATED-MONTH October 2024
+@set UPDATED 15 November 2024
+@set UPDATED-MONTH November 2024

-@set LASTCHANGE Tue Oct 15 16:54:39 EDT 2024
+@set LASTCHANGE Fri Nov 15 17:56:11 EST 2024
@@ -1,6 +1,6 @@
 /* funmap.c -- attach names to functions. */

-/* Copyright (C) 1987-2021 Free Software Foundation, Inc.
+/* Copyright (C) 1987-2024 Free Software Foundation, Inc.

   This file is part of the GNU Readline Library (Readline), a library
   for reading lines of text with interactive input and history editing.      
@@ -90,6 +90,7 @@ static const FUNMAP default_funmap[] = {
  { "end-of-line", rl_end_of_line },
  { "exchange-point-and-mark", rl_exchange_point_and_mark },
  { "execute-named-command", rl_execute_named_command },
+  { "export-completions", rl_export_completions },
  { "fetch-history", rl_fetch_history },
  { "forward-backward-delete-char", rl_rubout_or_delete },
  { "forward-byte", rl_forward_byte },
@@ -27,6 +27,13 @@
 #  include <floss.h>
 #endif

+/* These are needed to get the declaration of 'alarm' when including
+   <unistd.h>. I'm not sure it's needed, but the compiler might require it. */
+#if defined (__MINGW32__)
+#  define __USE_MINGW_ALARM
+#  define _POSIX
+#endif
+
 #if defined (HAVE_CONFIG_H)
 #  include <config.h>
 #endif
@@ -160,6 +160,7 @@ extern int rl_insert_completions (int, int);
 extern int rl_old_menu_complete (int, int);
 extern int rl_menu_complete (int, int);
 extern int rl_backward_menu_complete (int, int);
+extern int rl_export_completions (int, int);

 /* Bindable commands for killing and yanking text, and managing the kill ring. */
 extern int rl_kill_word (int, int);
@@ -909,8 +909,11 @@ wchars (struct DATA *p, wint_t wc)
  memset (&mbs, '\0', sizeof (mbstate_t));
  len = wcrtomb (lbuf, wc, &mbs);
  if (len == (size_t)-1)
-    /* conversion failed; bail now. */
-    return;
+    {
+      free (lbuf);
+      /* conversion failed; bail now. */
+      return;
+    }
  p->width -= len;
  l = lbuf;
  PUT_STRING (l, len, p);