--- name: "Shell::Perl" section: "3pm" platform: "linux" package: "libshell-perl-perl" version: "0.0026-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Shell::Perl" --- # Shell::Perl(3pm) A read-eval-print loop in Perl ## NAME Shell::Perl - A read-eval-print loop in Perl ## SYNOPSYS ``` use Shell::Perl; Shell::Perl->run_with_args; ``` ## DESCRIPTION This is the implementation of a command-line interpreter for Perl. I wrote this because I was tired of using **irb** when needing a calculator with a real language within. Ah, that and because it was damn easy to write it. This module is the heart of the **pirl** script provided with **Shell-Perl** distribution, along with this module. ### 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 ``` ### COMMANDS Most of the time, the shell reads Perl statements, evaluates them and outputs the result. There are a few commands (started by ':') that are handled by the shell itself. - :h(elp) Handy for remembering what the shell commands are. - :q(uit) Leave the shell. The Perl statement `"exit"` will work too. SYNONYMS: :exit, :x - :set out (D\|DD\|DDS\|Y\|P) Changes the dumper for the expression results used before output. The current supported 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 creating the shell, the dump format is searched among the available ones in the order "D", "DD", "DDS", "Y" and "P". That means Data::Dump is preferred and will be used if available/installed. Otherwise, Data::Dumper is tried, and so on. Read more about dumpers at Shell::Perl::Dumper. - :set ctx (scalar\|list\|void\|s\|l\|v\|$\|@\|\_) Changes the default context used to evaluate the entered expression. The default is `'list'`. Intuitively, 'scalar', 's' and '$' are synonyms, just like 'list', 'l', and '@' or 'void', 'v', '\_'. There is a nice way to override the default context in a given expression. Just a '#' followed by one of 'scalar\|list\|void\|s\|l\|v\|$\|@\|\_' at the end of the expression. ``` 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 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 to an empty string, as in ``` :set perl_version '' ``` for the behavior of pirl 0.0023 or earlier. - :reset Resets the environment, erasing the symbols created at the current evaluation package. See the section "ABOUT EVALUATION". ### METHODS Remember this is an alpha version, so the API may change and that includes the methods documented here. So consider this section as implementation notes for a while. In later versions, some of these information may be promoted to a public status. Others may be hidden or changed and even disappear without further notice. - **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, 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. - **dump\_history** ``` $sh->dump_history(); $sh->dump_history($file); ``` Prints the readline history to `"STDOUT"` or the optional file. Used to implement 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. ## 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 \. ## 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 \ ## AUTHORS Adriano R. Ferreira, \ Caio Marcelo, \ Ron Savage, \ ## 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.