Name

Term::ReadLine::Perl5 - A Perl5 implementation GNU Readline

Overview

This is a implementation of the GNU Readline/History Library written in Perl5.

GNU Readline reads lines from an interactive terminal with emacs or vi editing capabilities. It provides as mechanism for saving history of previous input.

This package typically used in command-line interfaces and REPLs (Read, Eval, Print, Loop).

Demo program

Another package, Term::ReadLine::Perl5::Demo is available to let you run Term::ReadLine::Perl5 to experiment with its capabilities and show how to use the API.

Synopsis

  use Term::ReadLine::Perl5;
  $term = Term::ReadLine::Perl5->new('ProgramName');
  while ( defined ($_ = $term->readline('prompt>')) ) {
    ...
  }

Variables

Following GNU Readline/History Library variables can be accessed from Perl program. See 'GNU Readline Library Manual' and ' GNU History Library Manual' for each variable. You can access them via the Attribs method. Names of keys in this hash conform to standard conventions with the leading rl_ stripped.

Example:

    $term = Term::ReadLine::Perl5->new('ReadLineTest');
    $attribs = $term->Attribs;
    $v = $attribs->{history_base};      # history_base

Attribute Names

        completion_suppress_append (bool)
        history_base               (int)
        history_stifled            (int)
        max_input_history          (int)
        outstream                  (file handle)

Subroutine

Standard Term::ReadLine Methods

These methods are standard methods defined by Term::ReadLine.

ReadLine

    Readline() -> 'Term::ReadLine::Perl5'

returns the actual package that executes the commands. If this package is used, the value is Term::ReadLine::Perl5.

readline

   $bool = $term->readline($prompt, $default)

The main routine to call interactively read lines. Parameter $prompt is the text you want to prompt with If it is empty string, no preceding prompt text is given. It is undef a default value of "INPUT> " is used.

Parameter $default is the default value; it can be can be omitted. The next input line is returned or undef on EOF.

new

new($name,[IN[,OUT]])

returns the handle for subsequent calls to following functions. Argument is the name of the application. Optionally can be followed by two arguments for IN and OUT file handles. These arguments should be globs.

$name is the name of the application.

This routine may also get called via Term::ReadLine->new($term_name) if you have $ENV{PERL_RL} set to 'Perl5';

At present, because this code has lots of global state, we currently don't support more than one readline instance.

IN

    $term->IN

Returns the input filehandle or undef.

OUT

        $term->OUT

Returns the output filehandle or undef.

newTTY

Term::ReadLine::Perl5->newTTY(IN, OUT)

takes two arguments which are input filehandle and output filehandle. Switches to use these filehandles.

Minline

MinLine([$minlength])>

If $minlength is given, set $readline::minlength the minimum length a $line for it to go into the readline history.

The previous value is returned.

add_history

   $term->add_history>($line1, $line2, ...)

adds the lines, $line1, etc. to the input history list.

AddHistory is an alias for this function.

stifle_history

   $term->stifle_history($max)

Stifle or put a cap on the history list, remembering only $max number of lines.

StifleHistory is an alias for this function.

Features

Features()

Returns a reference to a hash with keys being features present in current implementation. Several optional features are used in the minimal interface:

  • addHistory is present if you can add lines to history list via the addHistory() method

  • appname is be present if a name, the first argument to new() was given

  • autohistory is present if lines are put into history automatically subject to the line being longer than MinLine.

  • getHistory is present if we get retrieve history via the getHistory() method

  • minline is present if the MinLine method available.

  • preput is present if the second argument to readline method can append text to the input to be read subsequently

  • readHistory is present you can read history items previosly saved in a file.

  • setHistory is present if we can set history

  • stifleHistory is present you can put a limit of the nubmer of history items to save via the writeHistory() method

  • tkRunning is present if a Tk application may run while ReadLine is getting input.

  • writeHistory is present you can save history to a file via the writeHistory() method

See also