---
name: Commands
---

```{index}
single: ipps; commands
single: ipps; :vars
single: ipps; :jit
single: ipps; :time
single: JIT; checking at the prompt
```

# Commands

A line that starts with a colon and a word is a command of `ipps`, not
Perl. `:help` lists them all. A command may be shortened while it
stays unique: `:q` is `:quit`, `:v` is `:vars`.

## Looking at what you have

`:vars` lists the variables of the session with their kind and a
short form of their value:

```text
ipps> my @primes = (2, 3, 5, 7); my %age = (ada => 36, alan => 41); my $name = "ada";
ipps> :vars
%age     hash of 2   (ada => 36, alan => 41)
$ans     undef       undef
@ans     array of 0  ()
$name    string      'ada'
@primes  array of 4  (2, 3, 5, 7)
```

`:scalar` evaluates in scalar context, where a line by itself is in
list context:

```text
ipps> @primes
(2, 3, 5, 7)
ipps> :scalar @primes
4
ipps> :scalar localtime 0
'Thu Jan  1 01:00:00 1970'
```

`:dump` shows a value whole, however large:

```text
ipps> my @big = (1 .. 30);
ipps> \@big
[
  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
  21, 22, 23, 24, ... (6 more)
]
ipps> :dump \@big
[
  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
  21, 22, 23, 24, 25, 26, 27, 28, 29, 30
]
```

`:source` shows the code of a sub, by its name or by an expression
that gives a code reference. The pragmas in force where the sub was
written are part of what it shows:

```text
ipps> sub area { my ($w, $h) = @_; return $w * $h }
ipps> :source area
sub area {
    use warnings;
    use strict 'refs', 'subs';
    my($w, $h) = @_;
    return $w * $h;
}
```

`:which` says where pperl gets a module from, and whether it is
loaded:

```text
ipps> :which List::Util
built into pperl (loaded)
ipps> :which JSON::PP
built into pperl
ipps> :which No::Such
ipps: No::Such: not on the search path
```

A module that is a file on disk is answered with its path.

## Timing a line, and asking the JIT

`:time` runs a line and then shows how long it took, compiling
included. The first number is wall-clock time, the second the
processor time, which the system counts in steps of ten milliseconds:

```text
ipps> :time my $s = 0; $s += $_ for 1 .. 1_000_000; $s
500000500000
wall 17.377 ms, cpu 20.000 ms
```

`:jit` runs a line and then shows what pperl's JIT did while it ran:

```text
ipps> :jit my $t = 0; for my $i (1 .. 1_000_000) { $t += $i * 2 } $t
1000001000000
jit: 1 loop compiled, 1 new loop seen (2 of 71 since the start)
```

The line had one loop, and it was compiled to machine code. The
numbers in parentheses are compiled and seen loops since `ipps`
started, its own code included.

A loop is compiled once it has run often enough, and that can 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:

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

A line whose loop was seen and not compiled looks like this:

```text
ipps> :jit my @w = map { "w$_" } 1 .. 3; scalar @w
3
jit: 0 loops compiled, 1 new loop seen (2 of 72 since the start)
```

The counts say that a loop was compiled. They do not say why another
was not.

## Files and modules

`:load` runs a file in the session. What it declares is there
afterwards; the value of its last statement is not shown.

```text
ipps> :load ~/lib/helpers.pl
```

`:save` writes every line that ran without an error as a script, in
the order you entered them. Commands are not written, the lines they
ran are.

```text
ipps> :save /tmp/session.pl
12 entries saved to /tmp/session.pl
```

Lines you typed only to look at a value are statements of that script
too, and perl warns that such a statement is useless there. Delete
them from the file.

`:install` installs modules from CPAN with pperl's own client, as
`pperl --cpan` does. They can be used at once.

```text
ipps> :install Text::CSV
```

## Commands of your shell

A line that starts with `!` and a space is not a command of `ipps` and
not Perl: it is handed to your shell and runs on the terminal.

```text
ipps> ! ls Cargo.* | wc -l
2
```

The section on running programs in [where a line is not a
file](limits) has the details: the exit status, aliases, and how to
get a command's output into a variable.

## The session itself

`:history` shows the last 20 lines entered, `:history 5` the last
five. On a terminal these include earlier sessions.

`:reset` starts afresh: no `my` variables, the pragmas of a new
session, the package `main`. Subs and package variables belong to the
interpreter and stay.

`:quit` leaves, as Ctrl-D does.

`:set` belongs to the next chapter.

```{note}
A name with two colons in front, such as `::helper`, is Perl - a sub
in `main` - and stays Perl.
```