Shell::Perl(3pm)

💖 Shell::Perl — the read-eval-print loop in Perl 💖

okay bestie, so this is Shell::Perl, a page from the User Contributed Perl Documentation, and it's literally a whole vibe: it's the read-eval-print loop in Perl. Come sit with me, we're doing this together. 🫶

---

✨ NAME ✨

Shell::Perl — A read-eval-print loop in Perl. That's it, that's the whole name, and honestly? iconic. 👑

---

✨ SYNOPSYS ✨

(yes the heading is spelled like that in the original, we don't fix it, we respect it 💅)

use Shell::Perl;
Shell::Perl->run_with_args;

---

✨ DESCRIPTION ✨

So this is the implementation of a command-line interpreter for Perl. The author wrote it because he was tired of using irb when he just needed a calculator that also happened to have a real language inside it. And also — no cap — because it was damn easy to write. 😭

This module is the heart of the pirl script that ships with the Shell-Perl distribution, alongside this very module. Two icons, one package. ✨

🌸 EXAMPLE SESSION 🌸

$ pirl
Welcome to the Perl shell. Type ':help' for more information

pirl @> 1+1
2

pirl @> use YAML qw(Load Dump);
()

pirl @> $data = Load("--- { a: 1, b: [ 1, 2, 3] }\n");
{ a => 1, b => [1, 2, 3] }

pirl @> $var = 'a 1 2 3'; $var =~ /(\w+) (\d+) (\d+)/
("a", 1, 2)

pirl @> :q

look at that. look at her go. 🔥

---

✨ COMMANDS ✨

Most of the time, the shell is just reading Perl statements, evaluating them, and printing the result. main character behaviour. 💅

But there are a few commands (they all start with :) that the shell handles itself.

• :h(elp) — so handy when you're sitting there like "wait what were the shell commands again". It reminds you. 🧚
• :q(uit) — leave the shell. And yes, the plain Perl statement exit works too, she's flexible like that.
  • SYNONYMS: :exit, :x
• :set out (D|DD|DDS|Y|P) — changes the dumper used for expression results before they get output. The ones supported right now are:
  • D — Data::Dump
  • DD — Data::Dumper, the good and old core module
  • DDS — Data::Dump::Streamer
  • Y — YAML
  • P — a plain dumper ($ans or @ans)

When the shell is created, the dump format gets searched among the available ones in the order D, DD, DDS, Y and P. Which means Data::Dump is preferred and will be used if it's available/installed. Otherwise Data::Dumper gets tried, and so on down the line. 💫

Read more about dumpers at Shell::Perl::Dumper.

• :set ctx (scalar|list|void|s|l|v|$|@|_) — changes the default context used to evaluate the expression you entered. The default is 'list'.

Intuitively: 'scalar', 's' and '$' are synonyms, just like 'list', 'l', and '@', or 'void', 'v', '_'. Same energy, different spelling. 🎀

And there's a nice way to override the default context in any given expression — just a # followed by one of scalar|list|void|s|l|v|$|@|_ at the end of the expression. Obsessed.

pirl @> $var = 'a 1 2 3'; $var =~ /(\w+) (\d+) (\d+)/
("a", 1, 2)

pirl @> $var = 'a 1 2 3'; $var =~ /(\w+) (\d+) (\d+)/ #scalar
1

• :set perl_version — changes the perl version (and the current feature bundle) used to evaluate each statement. Usage examples are:

:set perl_version 5.008
:set perl_version v5.10
:set perl_version        # current perl version, $]

Default is to use the current perl version, which works like eval "use $];".

Set it to an empty string, like

:set perl_version ''

for the behavior of pirl 0.0023 or earlier. throwback vibes. 🕰️

• :reset — resets the environment, erasing the symbols created at the current evaluation package. See the section "ABOUT EVALUATION" below. 🧼

---

✨ METHODS ✨

Remember this is an alpha version, so the API may change — and that includes the methods documented right here. So for a while, consider this section as implementation notes. 🙈

In later versions, some of this info may get promoted to a public status. Others may get hidden or changed, and could even disappear without further notice. It's giving fluid. 🌊

• new

$sh = Shell::Version->new;

The constructor.

• run_with_args

Shell::Perl->run_with_args;

Starts the read-eval-print loop after reading options from @ARGV. It is a class method.

If an option -v or --version is provided, then instead of starting the REPL, it prints the script identification and exits with 0.

$ pirl -v
This is pirl, version 0.0017 (bin/pirl, using Shell::Perl 0.0017)

• run

$sh->run;

The same as run_with_args but with no code for interpreting command-line arguments. It is an instance method, so that Shell::Perl->run_with_args is kind of:

Shell::Perl->new->run;

• eval

$answer = $sh->eval($exp);
@answer = $sh->eval($exp);

Evaluates the user input given in $exp as Perl code and returns the result. That is the eval part of the read-eval-print loop. 💖

• print

$sh->print(@args);

Prints a list of args at the output stream currently used by the shell.

• help

$sh->help;

Outputs the help as provided by the command :help.

• reset

$sh->reset;

Does nothing by now, but it will. she's working on herself. 💅

• dump_history

$sh->dump_history();
$sh->dump_history($file);

Prints the readline history to STDOUT or to the optional file. Used to implement the experimental command :dump history.

This is experimental code and should change in the future. More control should be added and integrated with other terminal features.

• set_ctx

$sh->set_ctx($context);

Assigns to the current shell context. The argument must be one of ( 'scalar', 'list', 'void', 's', 'l', 'v', '$', '@', '_' ).

• set_package

$sh->set_package($package);

Changes current evaluation package. Doesn't change if the new package name is malformed.

• set_perl_version

$sh->set_perl_version($version);

Changes perl version used to evaluate statements.

• set_out

$sh->set_out($dumper);

Changes the current dumper used for printing the evaluation results. Actually must be one of D (for Data::Dump), DD (for Data::Dumper), DDS (for Data::Dump::Streamer), Y (for YAML) or P (for plain string interpolation).

• prompt_title

$prompt = $sh->prompt_title;

Returns the current prompt, which changes with executable name and context. For example, pirl @>, pirl $>, and pirl >. 🎀

• quit

$sh->quit;

This method is invoked when these commands and statements are parsed by the REPL:

:q
:quit
:x
:exit
quit
exit

It runs the shutdown procedures for a smooth termination of the shell. For example, it saves the terminal history file. so polite. 🌸

---

✨ GORY DETAILS ✨

🦋 ABOUT EVALUATION 🦋

When the statement read is evaluated, this is done at a different package, which is Shell::Perl::sandbox by default.

So:

$ perl -Mlib=lib bin/pirl
Welcome to the Perl shell. Type ':help' for more information

pirl @> $a = 2;
2

pirl @> :set out Y # output in YAML

pirl @> \%Shell::Perl::sandbox::
---
BEGIN: !!perl/glob:
  PACKAGE: Shell::Perl::sandbox
  NAME: BEGIN
a: !!perl/glob:
  PACKAGE: Shell::Perl::sandbox
  NAME: a
  SCALAR: 2

This package serves as an environment for the current shell session, and :reset can wipe it away. 🧽

pirl @> :reset

pirl @> \%Shell::Perl::sandbox::
---
BEGIN: !!perl/glob:
  PACKAGE: Shell::Perl::sandbox
  NAME: BEGIN

---

✨ TO DO ✨

There is a lot to do, as always. Some of the top priority tasks are:

• Accept multiline statements;.
• Refactor the code to promote easy customization of features.

---

✨ BUGS ✨

It is a one-line evaluator by now.

I don't know what happens if you eval within an eval. I don't expect good things to come. (Lorn who prodded me about this will going to find it out and then I will tell you.) 💀

There are some quirks with Term::Readline (at least on Windows).

There are more bugs. I am lazy to collect them all and list them now. 😭

Please report bugs via Github <https://github.com/aferreira/pirl/issues>.

---

✨ SEE ALSO ✨

This project is hosted at Github:

https://github.com/aferreira/pirl

To know about interactive Perl interpreters, there are two FAQS contained in perlfaq3 which are good starting points. Those are

How can I use Perl interactively?
http://perldoc.perl.org/perlfaq3.html#How-can-I-use-Perl-interactively%3f

Is there a Perl shell?
http://perldoc.perl.org/perlfaq3.html#How-can-I-use-Perl-interactively%3f

Also:

• Devel::REPL
• Reply
• A comparison of various REPLs <http://shadow.cat/blog/matt-s-trout/mstpan-17/>

---

✨ AUTHORS ✨

Adriano R. Ferreira, <ferreira@cpan.org>

Caio Marcelo, <cmarcelo@gmail.com>

Ron Savage, <ron@savage.net.au>

---

✨ COPYRIGHT AND LICENSE ✨

Copyright (C) 2007–2017 by Adriano R. Ferreira

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

okay and that's the whole page bestie!! 🫶✨ this beauty came out of perl v5.34.0 and got its little timestamp on 2022-06-17, and it's filed under Shell::Perl(3pm). go forth and REPL, you've got this. 💖🎀🦋