Peta::Shell#

ipps, the interactive mode of pperl

SYNOPSIS#

$ pperl --shell
ipps> my @list = (1, 2, 3)
(1, 2, 3)
ipps> push @list, 4; scalar @list
4
ipps> for my $n (@list) {
 ...>     print $n * 2, " ";
 ...> }
2 4 6 8
ipps> ^D

From Perl:

use Peta::Shell;
exit Peta::Shell->run(@ARGV);

DESCRIPTION#

ipps reads Perl, runs it, and prints the value of the last statement. Everything a line declares is still there for the next line: my variables, subs, loaded modules, pragmas, the current package. See Peta::Shell::Session for exactly what carries over and how.

At the prompt#

  • A line whose last statement ends in ; prints nothing. Without the ; its value is printed as Peta::Shell::Printer shows it: a number bare, a string in quotes, a list in parentheses, a reference as its structure, nothing for an empty list. A loop or a conditional typed by itself prints nothing either, and neither does a last statement that is a print, printf or say: its value is only whether the output succeeded.

  • When what your code printed does not end in a newline, the prompt starts on the next line and a % in reverse video marks where the output stopped.

  • The value last printed is in $ans, and all of them, when there were several, in @ans:

    ipps> 6 * 7
42
ipps> $ans + 1
43

  • Input that is not finished (an open bracket, an open quote, a here-document without its end) gets a second prompt, ...>, until it is. Blank lines inside it are kept, so pasted code works.

  • Tab completes the word in front of the cursor: a variable of the session, a key of one of its hashes, a method of an object or class, a sub, a module after use, a file name inside a string, a command. With several candidates it completes as far as they agree, and a second Tab lists them. Peta::Shell::Complete says exactly what is offered where. When none of that fits, Tab completes a file name.

  • Ctrl-C at a prompt drops the input typed so far. Ctrl-C while a line runs stops that line; the session goes on.

  • Ctrl-D on an empty prompt ends the session, and so does exit.

  • An error is printed and the session goes on with everything it had.

Commands#

A line that starts with a colon and a word is a command of ipps, not Perl. A command may be shortened while it stays unique: :q, :v.

  • :help

    The list of commands, yours and the macros included.

  • :vars

    The variables of the session: name, kind and value, shortened.

    ipps> my @list = (1, 2, 3); my $name = "ada";
ipps> :vars
@ans   array of 0  ()
$ans   undef       undef
@list  array of 3  (1, 2, 3)
$name  string      'ada'

  • :scalar EXPR

    The value of EXPR in scalar context; a line is otherwise evaluated in list context. :scalar @list is the number of elements. The word scalar is put in front and nothing more, so :scalar 1, 2 is the list scalar(1), 2, as in Perl.

  • :dump EXPR

    The value whole: every element, every level, every character, whatever the settings say and whether or not the line ends in ;.

  • :time LINE

    Runs the line and then shows the wall-clock and the processor time it took, compiling included.

  • :jit LINE

    Runs the line and then shows what the JIT did while it ran: how many loops it compiled to machine code, how many loops the line brought that it had not seen before, and compiled of seen for everything since ipps started, its own code included.

    ipps> :jit my $t = 0; for my $i (1 .. 300_000) { $t += $i } $t
45000150000
jit: 1 loop compiled, 1 new loop seen (1 of 68 since the start)

    A loop is compiled once it has run often enough, and that may be in a later line than the one that wrote it: the loop of a sub is seen where the sub is defined and compiled where a call makes it hot. The counts say that a loop was compiled, not why another was not.

  • :source SUB

    The code of a sub, by name or by an expression that gives a code reference, as B::Deparse writes it.

  • :which MODULE

    The file pperl loads the module from, or built into pperl, and whether it is loaded. A file name works too: :which ExtUtils/typemap.

  • :install MODULE …

    Installs modules from CPAN with pperl’s own client, as pperl --cpan does. They can be used at once.

  • :load FILE

    Runs a file in the session: what it declares is there afterwards. The value of its last statement is not shown.

  • :save FILE

    Writes every line that ran without an error, in order, as a script. Commands are not written, the lines they ran are.

  • set, :

    set NAME, :set NAME VALUE

    Shows all settings, shows one, changes one:

    max_items   elements shown of an array or hash (24); 0: all
max_depth   levels shown of a nested structure (6); 0: all
max_string  characters shown of a string (240); 0: all
width       columns for a printed value; 0: the terminal's
time        on: show the times of every line
prompt      the prompt; quotes keep a space: :set prompt "> "
prompt2     the prompt for unfinished input
shell       what "! command" runs the command with

    To keep a setting, put it in rc.pl: see “set”.

  • history, :

    history N

    The last 20, or N, lines entered. On a terminal these include earlier sessions.

  • :reset

    Starts the session afresh: no my variables, the first pragmas, the package main, no macros, and rc.pl run again. Subs and package variables are not the session’s and stay.

  • :quit

    Leaves, as Ctrl-D does.

::name(...) is Perl, a call into main, and stays Perl.

Commands of your shell#

A line that starts with ! and a space is handed to your shell as it stands and runs on the terminal:

ipps> ! ls -l *.pl
ipps> ! git status

Nothing of such a line is Perl, and its output is not kept. An exit status other than 0 is reported. To have a command’s output in a variable, use Perl’s backticks, which is Perl and works as always:

ipps> my @files = `ls *.pl`

The space matters: !$done and !defined $x are Perl’s negation.

The command runs under $SHELL -c, or /bin/sh -c without $SHELL. Such a shell does not read the start file of an interactive one, so its aliases are unknown to it. The shell setting changes that; for bash’s aliases:

ipps> :set shell bash -ic

Macros and commands of your own#

rc.pl is the place for them:

Peta::Shell->macro(p => 'print');
Peta::Shell->command(pwd => sub { require Cwd; print Cwd::getcwd(), "\n" });

After that p "hello\n" at the prompt runs print "hello\n", and :pwd prints the directory. See “macro” and “command”.

Without a terminal#

When standard input is not a terminal, ipps reads it line by line without prompt or editing and prints values and errors the same way:

$ echo 'my $x = 6; $x * 7' | pperl --shell
42

Files#

Both live under $PPERL_HOME/ipps, by default ~/.pperl/ipps.

  • rc.pl

    Perl run in the session before the first prompt. What it declares is there at the prompt. Not read with --norc.

  • history

    The lines typed at the prompt, read at start and written at the end.

OPTIONS#

  • –norc

    Do not run rc.pl.

METHODS#

run#

my $status = Peta::Shell->run(@arguments);

Runs a session to its end and returns the exit status: 0, or 2 for arguments it does not understand.

new#

my $shell = Peta::Shell->new(%options);

Options: rc (run rc.pl, default true), home (the directory of rc.pl and history), in, out, err (file handles, default the standard three), prompt and prompt2.

loop#

Reads and evaluates until the input ends. Returns the exit status.

session#

The Peta::Shell::Session of this shell.

current#

my $shell = Peta::Shell->current;

The shell that is running, or undef. This is how rc.pl and the lines typed at the prompt reach it.

macro#

Peta::Shell->macro(p  => 'print');
Peta::Shell->macro(ls => sub { my ($rest) = @_; "print map { \"\$_\\n\" } glob('$rest*')" });

Defines a macro: a word that, typed as the first word of a line and followed by a space or the end of the line, is replaced before the line is compiled. A string replaces the word and the rest of the line stays; a code reference gets the rest of the line and returns the Perl to run instead. undef removes the macro. Called on the class, it means the running shell.

command#

Peta::Shell->command(pwd => sub { my ($shell, $rest) = @_; require Cwd; print Cwd::getcwd(), "\n" });

Defines a command of your own, typed as :pwd. It gets the shell and the rest of the line. undef removes it. The names of the built-in commands are taken.

set#

Peta::Shell->set(max_items => 100);

Changes a setting, as :set does at the prompt.

Modules#