Term::...::Zoid(3pm)

Term::ReadLine::Zoid(3pm) — the manual, but make it cute 💖

okay bestie, so this is Term::ReadLine::Zoid(3pm), filed under User Contributed Perl Documentation, and it's basically the readline glow-up you didn't know you needed. another ReadLine package?? yes. and she EATS. 🎀

---

✨ NAME ✨

Term::ReadLine::Zoid — another ReadLine package. that's it. that's the name. iconic brevity. 💅

---

🌸 SYNOPSIS 🌸

like, here's how you actually use her:

# In your app:
use Term::ReadLine;
my $term = Term::ReadLine->new("my app");

my $prompt = "eval: ";
my $OUT = $term->OUT || \*STDOUT;
while ( defined ($_ = $term->readline($prompt)) ) {
    # Think while (<STDIN>) {}
    my $res = eval($_);
    warn $@ if $@;
    print $OUT $res, "\n" unless $@;
}

# In some rc file
export PERL_RL=Zoid

no cap, that's the whole vibe right there. ✨

---

🦋 DESCRIPTION 🦋

so this package hands you a whole little set of modules that together make an interactive input buffer written in plain perl with basically no dependencies (minimal deps, we stay light, we stay unbothered 🧚).

she's got almost all the key-bindings described in the posix spec for the sh(1) utility, plus some extensions of her own like multiline editing. and yes, that includes a vi-command mode with a save-buffer (for copy-pasting, obviously) and an undo-stack. obsessed. truly.

historically this code was part of the Zoidberg shell, but this implementation is complete independent from zoid and uses the Term::ReadLine interface instead, so you can plug her into other perl programs. main character energy, no baggage. 💅

( also, heads up: the docs sometimes say 'the application', and that just means the program using the ReadLine module for input. iykyk. )

---

💜 ENVIRONMENT 💜

the Term::ReadLine interface module uses the PERL_RL variable to decide which module to load. so if you want this module for all your perl applications, do something like:

export PERL_RL=Zoid

and boom, she's everywhere. periodt. 🌈

---

👑 KEY MAPPING 👑

the function name is given between parenthesis — and those are useful for privat key maps too, so keep them in your notes bestie.

🌸 Default keymap 🌸

the default key mapping is as follows:

• escape, ^[ (switch_mode_command) — drops the line editor into command mode, see Term::ReadLine::Zoid::ViCommand.
• ^C (return_empty_string) — end editing and return an empty string.
• ^D (delete_char_or_eof) — for a single line buffer this ends editing and returns undef if the line is empty, otherwise it deletes a char. for a multiline buffer, it ends editing and returns the lines to the application if the cursor is on the last line and that line is empty — otherwise it deletes a char.

fr fr note: delete_char_or_eof does what delete_char should do, so it stays compatible with the GNU readline lib.

• delete (delete_char)
• backspace, ^H, ^? (backward_delete_char) — delete and backspace kill the current or previous character. the key ^? is by default treated as a backspace because most modern keyboards use that key for the "backspace" key and an escape sequence for the "delete" key. and of course ^H is also considered a backspace. 💀
• tab, ^I (complete) — tries to complete the bigword on the left of the cursor.

there's no default completion included in this package, so unless you define a custom expansion it literally does nothing. see the completion_function option.

uses the PAGER environment variable to find a suitable pager when there are more completions to show than would fit on the screen.

see also the autolist and maxcomplete options.

• return, ^J (accept_line) — end editing and return the edit line to the application, unless the newline is escaped.

if _all_ lines in the buffer end with a single '\', the newline counts as escaped and you can keep typing on the next line. ngl this behaviour can be a bit unexpected, because this module has multiline support and historic readline implementations didn't — historically the escaping of a newline is done by the application, not the library. to suppress this behaviour and let the application do its thing, disable the automultiline option.

to enter the real multiline editing mode, press 'escape m', see Term::ReadLine::Zoid::MultiLine.

• ^O (operate_and_get_next) — return the current buffer to the application but remember where we are in history. great for quickly (re-)executing a series of commands from history. ✨
• ^K (kill_line) — delete from cursor to the end of the line.
• ^L (clear_screen) — clear the entire screen. and in contrast with other readline libraries, the prompt stays at the bottom of the screen. slay.
• ^R (switch_mode_isearch) — enter incremental search mode, see Term::ReadLine::Zoid::ISearch.
• ^U (unix_line_discard) — also known as the "kill" char. deletes all characters on the edit line and puts them in the save buffer. you can paste them back in later with 'escape-p'.
• ^V (quoted_insert) — insert the next key literally, ignoring any key-bindings.

WARNING: control or escape chars in the editline can cause unexpected results. be careful bestie, this one bites.

• ^W (unix_word_rubout) — delete the word before the cursor.
• insert (overwrite_mode) — toggle replace bit.
• home, ^A (beginning_of_line) — move cursor to the begin of the edit line.
• end, ^E (end_of_line) — move cursor to the end of the edit line.
• left, ^B (backward_char)
• right, ^F (forward_char) — these keys move the cursor around in the edit line.
• up, page_up, ^P (previous_history)
• down, page_down, ^N (next_history) — these keys rotate the history. 🌀

🎀 Multi-line keymap 🎀

the following keys are different in mutline mode; the others fall back to the default behaviour.

• return (insert_line) — insert a newline at the current cursor position.
• up (backward_line) — move the cursor one line up.
• down (forward_line) — move the cursor one line down.
• page_up (page_up) — move the cursor one screen down, or to the bottom of the buffer.
• page_down (page_down) — move the cursor one screen up, or to the top of the buffer.

🧚 Unmapped functions 🧚

• return_eof — end editing and return undef.
• return_eof_maybe — end editing and return undef if the buffer is completely empty.
• possible_completions — like complete but only shows the completions without actually doing them.
• redraw_current_line — redraw the current line. this happens all the time automatically, so you'll almost never need to call this one explicitly.

---

🍓 ATTRIBS 🍓

the hash with options can be accessed with the Attribs method. these can be modified from the rc-file (see FILES) or set from the PERL_RL environment variable. for example, to disable the autolist feature you can set PERL_RL='Zoid autolist=0' before you start the application.

( also they can be altered interactively using the mini-buffer of the command mode, see Term::ReadLine::Zoid::ViCommand. cute, right? )

• autohistory — if enabled, lines are added to the history automatically, subject to MinLine. by default enabled.
• autoenv — if enabled, the environment variables COLUMNS and LINES are kept up to date. by default enabled.
• autolist — if set, completions are listed directly when a completion fails; if not set you need to press tab twice to see a list of possible completions. by default enabled.
• automultiline — see return for a description. by default enabled.
• beat — this option can contain a CODE reference. it is called on the heartbeat event. 💓
• bell — this option can contain a CODE reference. the default is print "\cG", which makes the terminal ring a bell.
• comment_begin — this option can be set to a string; if the edit line starts with this string, the line is regarded as a comment and is not returned to the application — but it will still show up in the history if 'autohistory' is also set. defaults to "#".

when there are multiple lines in the buffer, they all need to start with the comment string for the buffer to be regarded as a comment.

• completion_function — this option can contain either a code ref or the name of a function to perform completion. for compatibility with Term::ReadLine::Perl, the global scalar $readline::rl_completion_function will be checked if this option isn't defined.

the function will get the following arguments: $word, $buffer, $start. where $word is the word before the cursor, while $buffer is the complete text on the command line; $start is the offset of $word in $buffer.

the function should return a list of possible completions of $word. the completion list is checked for double entries.

there is no default.

FIXME tell about the meta fields for advanced completion

• default_mode — specifies the mode the buffer starts in when you do a readline(), and other modes also return to this mode if you exit them. the default is 'insert', which is the single-line insert mode. if you always want to edit in multiline mode, set this option to 'multiline'.
• maxcomplete — maximum number of completions to be displayed; when the number of completions is bigger, the user is asked before displaying them. if set to zero, completions are always displayed.

if this option is set to the string 'pager', the user is asked when the number of completions is too big to fit on screen and a pager would be used.

• minline — this option controls which lines are included in the history; lines shorter than this number are ignored. when set to "0" all lines are included in the history, when set to "undef" all lines are ignored. defaults to "0".
• PS2 — this option can contain the prompt to be used for extra buffer lines. it defaults to "> ".

although the PS1 prompt (as specified as an argument to the readline() method) can contain newlines, the PS2 prompt can't.

• RPS1 — this option can contain a string that will be shown on the right side of the screen. this is known as the "right prompt" and the idea is stolen from zsh(1). 💅
• title — used to set the terminal title, defaults to the appname.
• low_latency — changes the escape sequences are read from input. if true, delays evalution of the escape key till the next char is known. by default disabled.

---

...and that's only part 1, bestie — more is coming, don't go anywhere 💖

📁 FILES 📁

okay so on startup this module reads an rc-file, and it goes looking in this order: $HOME/.perl_rl_zoid_rc, then $HOME/.zoid/perl_rl_zoid_rc, then /etc/perl_rl_zoid_rc. 💖

And bestie, that rc-file is a whole perl script. It gets access to the Term::ReadLine::Zoid object through the method current(). So if you want different behaviour for different apps, literally just peek at "$rl->{appname}" and branch on it. iconic.

# in for example ~/.perl_rl_zoid_rc
my $rl = Term::ReadLine::Zoid->current();

# set low latency
$rl->Attribs()->{low_latency} = 1;

# alias control-space to escape
$rl->bindchr( chr(0), 'escape' );

# create an ad hoc macro
$rl->bindkey('^P', sub { $rl->press('mplayer -vo sdl ') } );

---

🛠️ METHODS 🛠️

🌸 ReadLine api 🌸

these are the functions specified by the Term::ReadLine documentation — the standard lil' friend group, no cap.

• new($appname, $IN, $OUT) — the simplest constructor ever. arguments are the application name (which gets used for the default prompt and the title string) plus optional filehandles for input and output. 💅
• ReadLine() — hands you back the name of the current ReadLine module that's actually being used.
• readline($prompt, $preput) — returns a string the user typed in. the final newline gets stripped off, though ngl the string might still have newlines chilling elsewhere.

the prompt only supports the escape ! for the history number of the current line, and if you want a literal ! you use !!. every other escape? you're parsing that yourself before you hand the prompt over, bestie. the prompt defaults to "$appname !> ".

if you wanna do more with your prompt, go look at Env::PS1. ✨

$preput lets you drop some text onto the edit line already. 🎀

• addhistory($line)
• AddHistory($line) — adds a command to the history (subject to the minline option, so watch out 👀). and if autohistory is set, readline will call this method automatically for you.
• IN() — returns the filehandle used for input.
• OUT() — returns the filehandle used for output.
• MinLine($value) — sets the minline option to $value and returns the old value.
• findConsole() — TODO - what uses does this have ?
• Attribs() — returns a reference to the options hash. 🫶
• Features() — returns a reference to a hash with the names of implemented features.

heads up: the naming scheme here is quite arbitrary. this module just uses the same names as Term::ReadLine::Gnu for the common features. so don't come for it.

🦋 Extended api 🦋

• SetHistory(@hist)
• GetHistory() — simple access to the history array. the set function supports both a list and a reference, and the get function uses wantarray. honestly? not sure which behaviour is compatible with T:RL::Gnu. 😭
• TermSize() — returns the number of columns and lines on the terminal.
• continue() — call this to continue the previous readline() call. perfect for building your own custom auto-multiline feature, main character energy. 👑
• current() — returns the current T:RL::Zoid object, for use in rc files — see FILES.
• bindkey($key, $sub, $map) — bind a CODE reference to a key. the function gets called when the key is typed, with the key name as an argument. the $map argument is optional and can be either default, command, isearch or multiline.

if $sub is not a reference, it's treated as an alias — and these aliases are not recursive, periodt.

for alphanumeric characters the name is the character itself, special characters get long speaking names, and control characters are prefixed with a '^'.

binding a combination with the meta- or alt-key? not supported. (see NOTES.) 💀

🙈 Private api 🙈

these are methods for use in overload classes. avoid using these methods from the application, bestie, i'm begging.

• switch_mode($mode) — switch to input mode $mode; changes the key map and reblesses the object if the "_on_switch" key returns a class name.
• reset() — reset all temporary attributes.
• save() — returns a ref with a copy of some temporary attributes. use it with restore to switch between multiple edit lines.
• restore($save) — restores saved attributes.
• set_history($int) — sets history entry $int in the buffer.
• longest_match(@completion) — returns the longest match among the completions followed by the completions itself. used for completion functions. ✨

---

🧚 DEVELOPMENT 🧚

• FIXME minimum subroutines new mode-class
• FIXME how to set up a keymap
• FIXME how to add a keymap/mode

(yeah it's giving "work in progress", and that's okay 🌈)

---

📝 NOTES 📝

with most modern keymappings, combining the meta key (alt) with a letter is identical to an escape character followed by that letter. iykyk. 💅

some functioality may in time be moved to the ::Base package.

---

⭐ TODO ⭐

UTF8 support, or general charset support, would be nice — but rn the author lacks the means to test these things. if anyone has ideas or suggestions about this, please contact them! 🫶

---

💀 BUGS 💀

• line wrap doesn't always display the last character on the line right. no functional bug though, so we're fine.
• if the buffer size exceeds the screen size, some bugs appear in the rendering. 😭

please mail the author if you find any other bugs.

---

👑 AUTHOR 👑

Jaap Karmsenberg || Pardus [Larus] <pardus@cpan.org>

Copyright (c) 2004 Jaap G Karmsenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

🌸 SEE ALSO 🌸

Term::ReadLine::Zoid::ViCommand, Term::ReadLine::Zoid::MultiLine, Term::ReadLine::Zoid::ISearch, Term::ReadLine::Zoid::FileBrowse, Term::ReadLine::Zoid::Base, Term::ReadLine, Env::PS1, Zoidberg

---

and that's a wrap bestie!! 💖 this page ships with perl v5.34.0 and was last touched on 2022-06-17, filed under Term::...::Zoid(3pm) in the User Contributed Perl Documentation. slay, go read the source, ily 🎀✨