```{index} single: Peta::Shell ``` # Peta::Shell ipps, the interactive mode of pperl ## SYNOPSIS ```perl $ 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: ```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](Shell/Session.md) 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](Shell/Printer.md) 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`: ```perl 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](Shell/Complete.md) 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. ```perl 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. ```perl 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](../B/Deparse.md) 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: ```text 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: ```text 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: ```perl 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: ```text ipps> :set shell bash -ic ``` ### Macros and commands of your own `rc.pl` is the place for them: ```perl 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: ```perl $ 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 ```perl 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 ```perl 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](Shell/Session.md) of this shell. ### current ```perl 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 ```perl 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 ```perl 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 ```perl Peta::Shell->set(max_items => 100); ``` Changes a setting, as `:set` does at the prompt. ## Modules - [`Peta::Shell::Complete`](Shell/Complete.md) - what Tab offers in ipps - [`Peta::Shell::Printer`](Shell/Printer.md) - show a Perl value as bounded, readable text - [`Peta::Shell::Session`](Shell/Session.md) - evaluate Perl line by line and keep the state ```{toctree} :hidden: :maxdepth: 1 Shell/Complete Shell/Printer Shell/Session ```