Term::Readline::Gnu - how to use complete_internal (if possible..)?

i know how to use custom completion functions with Term::Readline::Gnu (Perl), e.g.

str     list_completion_function(str text, int state)

http://search.cpan.org/dist/Term-ReadLine-Gnu/Gnu.pm#Custom_Completion https://cnswww.cns.cwru.edu/php/chet/readline/readline.html#SEC47

$attribs->{attempted_completion_function } = sub {
  my ($text, $line, $start, $end) = @_;
  my @cmds = ('one', 'two', 'three');
  $attribs->{completion_word} = \@cmds;
  return $term->completion_matches($text, $attribs->{'list_completion_function'} );
};

..but i absolutely don't get how to use complete_internal:

int     rl_complete_internal(int what_to_do = TAB)

http://search.cpan.org/dist/Term-ReadLine-Gnu/Gnu.pm#Custom_Completion

From the GNU Readline Docs:

A value of ?' means list the possible completions.TAB' means do standard completion. *' means insert all of the possible completions.!' means to display all of the possible completions (...)

https://cnswww.cns.cwru.edu/php/chet/readline/readline.html#SEC47

This sounds to me like gnu-readline has a "cisco-like"/router-cli mode - but maybe i get something completely wrong here? And if there is something like this; how can i pass custom completion data to it using Term::Readline::Gnu?

i searched SO, GitHub Code, Google etc pp and am almost certain to miss(understand) something. it would be great if you could lighten me up.

Solution

Here is an example of how to use rl_complete_internal:

use feature qw(say);
use strict;
use utf8;
use open qw( :std :utf8 );
use warnings;
use Term::ReadLine;

my $term   = Term::ReadLine->new('Test', \*STDIN, \*STDOUT);
$term->ornaments( 0 );
my $attribs = $term->Attribs;
$attribs->{completion_word} = [qw(one two three)];
$attribs->{completion_entry_function} =
    $attribs->{list_completion_function};
$term->add_defun('custom-action', \&my_bind_key_func );
$term->bind_key(ord "\cy", 'custom-action');
my $answer = $term->readline( 'Enter input: ' );
say "You entered: '$answer'";

sub my_bind_key_func {
    my($count, $key) = @_; 
    $term->complete_internal( ord '?' );
    return 0;
}

If you type t at the prompt and then press CTRL-y it will display the two completion candidates, namely two and three. This is because according to the GNU Readline Library documentation, section 2.6:

int rl_complete_internal (int what_to_do)

Complete the word at or before point. what_to_do says what to do with the completion. A value of ? means list the possible completions. TAB means do standard completion. * means insert all of the possible completions. ! means to display all of the possible completions, if there is more than one, as well as performing partial completion. @ is similar to !, but possible completions are not listed if the possible completions share a common prefix.