Term::ReadLine(3perl)

💖 Term::ReadLine 💖

okay bestie so this is Term::ReadLine(3perl), straight outta the Perl Programmers Reference Guide, and it's basically the social secretary that sets you up with whatever "readline" package you've got lying around. no cap.

✨ NAME ✨

Term::ReadLine — a Perl interface to various "readline" packages. And if it can't find a real package? It just substitutes stubs instead of the basic functions. fake it till you make it, honestly 🫶

🌸 SYNOPSIS 🌸

  use Term::ReadLine;
  my $term = Term::ReadLine->new('Simple Perl calc');
  my $prompt = "Enter your arithmetic expression: ";
  my $OUT = $term->OUT || \*STDOUT;
  while ( defined ($_ = $term->readline($prompt)) ) {
    my $res = eval($_);
    warn $@ if $@;
    print $OUT $res, "\n" unless $@;
    $term->addhistory($_) if /\S/;
  }

look at that little calculator living its best life 🧮✨

🦋 DESCRIPTION 🦋

so this package is literally just a front end to some other packages. that's the whole vibe. it's a stub that sets up one common interface for all the various ReadLine implementations chillin' on CPAN (they all hang out under the "Term::ReadLine::*" namespace, iykyk).

🎀 Minimal set of supported functions 🎀

first things first: all the supported functions have to be called as methods. meaning either like this:

  $term = Term::ReadLine->new('name');

or like this:

  $term->addhistory('row');

where $term is whatever Term::ReadLine->new() handed back to you. that's your handle, your main character, your girl 💅

• "ReadLine" — returns the actual package that executes the commands. the possible values include "Term::ReadLine::Gnu", "Term::ReadLine::Perl", and "Term::ReadLine::Stub". so you always know who's actually doing the work.
• "new" — returns the handle for all the subsequent calls to the following functions. the argument is the name of the application. optionally you can follow it with two more arguments for the "IN" and "OUT" filehandles, and those arguments should be globs.
• "readline" — gets an input line, possibly with actual "readline" support (fancy!). trailing newline gets removed. returns "undef" on "EOF". bye bestie 👋
• "addhistory" — adds the line to the history of input, from where it can be used if the actual "readline" is present.
• "IN", "OUT" — return the filehandles for input and output, or "undef" if "readline" input and output cannot be used for Perl.
• "MinLine" — if an argument is specified, it's an advice on the minimal size of line to be included into history. "undef" means don't include anything into history. returns the old value.
• "findConsole" — returns an array with two strings that give the most appropriate names for files for input and output using the conventions "<$in", ">out".

heads up: the strings returned may not be useful for 3-argument open().

• Attribs — returns a reference to a hash which describes the internal configuration of the package. the names of the keys in this hash conform to standard conventions with the leading "rl_" stripped.
• "Features" — returns a reference to a hash with keys being features present in the current implementation. several optional features get used in the minimal interface: "appname" should be present if the first argument to "new" is recognized, and "minline" should be present if the "MinLine" method is not dummy. "autohistory" should be present if lines are put into history automatically (maybe subject to "MinLine"), and "addhistory" if the "addhistory" method is not dummy.

and if the "Features" method reports a feature "attribs" as present, then the method "Attribs" is not dummy either. slay.

🌈 Additional supported functions 🌈

so actually "Term::ReadLine" can use some other package that supports a richer set of commands. cute right?

all of these commands are callable via the method interface and have names that conform to standard conventions with the leading "rl_" stripped.

the stub package that comes included with the perl distribution allows some additional methods:

• "tkRunning" — makes the Tk event loop run when it's waiting for user input (i.e., during the "readline" method).
• "event_loop" — registers call-backs to wait for user input (i.e., during the "readline" method). this supersedes tkRunning.

the first call-back registered is the call back for waiting. it's expected that the callback will call the current event loop until there's something waiting to get on the input filehandle. the parameter passed in is the return value of the second call back.

the second call-back registered is the call back for registration. the input filehandle (often STDIN, but not necessarily) will be passed in.

for example, with AnyEvent:

  $term->event_loop(sub {
    my $data = shift;
    $data->[1] = AE::cv();
    $data->[1]->recv();
  }, sub {
    my $fh = shift;
    my $data = [];
    $data->[0] = AE::io($fh, 0, sub { $data->[1]->send() });
    $data;
  });

the second call-back is optional if the call back is registered prior to the call to $term->readline.

deregistration is done in this case by calling event_loop with "undef" as its parameter:

    $term->event_loop(undef);

this will cause the data array ref to be removed, allowing normal garbage collection to clean it up. with AnyEvent, that will cause $data->[0] to be cleaned up, and AnyEvent will automatically cancel the watcher at that time. if another loop requires more than that to clean up a file watcher, that will be up to the caller to handle. not us. we don't do that here 🙈

• "ornaments" — makes the command line stand out by using termcap data. the argument to "ornaments" should be 0, 1, or a string of a form "aa,bb,cc,dd". four components of this string should be names of terminal capacities — the first two will be issued to make the prompt standout, and the last two to make the input line standout. dripped out command line honestly 👑
• "newTTY" — takes two arguments which are an input filehandle and an output filehandle. switches to use these filehandles.

one can check whether the currently loaded ReadLine package supports these methods by checking for corresponding "Features".

✨ EXPORTS ✨

None. nothing. zero. empty. the void. 💀

💜 ENVIRONMENT 💜

the environment variable "PERL_RL" governs which ReadLine clone gets loaded.

• if the value is false, a dummy interface is used.
• if the value is true, it should be the tail of the name of the package to use, such as "Perl" or "Gnu".

as a special case, if the value of this variable is space-separated, the tail might be used to disable the ornaments by setting the tail to be "o=0" or "ornaments=0". the head should be as described above, say

if the variable is not set, or if the head of space-separated list is empty, the best available package is loaded.

  export "PERL_RL=Perl o=0" # Use Perl ReadLine sans ornaments
  export "PERL_RL= o=0"     # Use best available ReadLine sans ornaments

(note that processing of "PERL_RL" for ornaments is in the discretion of the particular used "Term::ReadLine::*" package).

---

and that's the whole page bestie, no notes 🫶 this was perl v5.44.0, dated 2026-10-17, and it's the Term::ReadLine(3perl) page. go forth and readline, you've got this 💅✨