---
name: Making it yours
---

```{index}
single: ipps; settings
single: ipps; rc.pl
single: ipps; macros
single: ipps; history file
single: PPERL_HOME
```

# Making it yours

## Settings

`:set` shows the settings, `:set` with a name shows one, and with a
name and a value changes it:

```text
ipps> :set
  max_depth  6          levels shown of a nested structure; 0: all
  max_items  24         elements shown of an array or hash; 0: all
  max_string 240        characters shown of a string; 0: all
  prompt     'ipps> '   the prompt
  prompt2    ' ...> '   the prompt for unfinished input
  shell      '/bin/bash -c' what "! command" runs the command with
  time       off        show the times of every line: on or off
  width      0          columns for a printed value; 0: the terminal's
ipps> :set max_items 5
ipps> [1 .. 30]
[1, 2, 3, 4, 5, ... (25 more)]
```

A prompt in quotes keeps its trailing space:

```text
ipps> :set prompt "perl> "
perl>
```

A setting made this way lasts for the session. To keep it, put it in
the start file.

## The start file

`ipps` keeps two files in `~/.pperl/ipps`, or in `$PPERL_HOME/ipps`
when that variable is set:

`rc.pl`
: Perl that runs in the session before the first prompt. What it
  declares is there when you start typing.

`history`
: The lines you typed, read at the start and written at the end.

`rc.pl` is ordinary Perl, so it can load the modules you always want
and define the subs you always use:

```perl
use List::Util qw(sum max min first);
use JSON::PP ();

sub slurp { my ($file) = @_; open my $fh, '<', $file or die "$file: $!"; local $/; <$fh> }
```

Start `ipps` with `--norc` to leave it out for once.

## Settings, macros and commands in the start file

Three calls reach the prompt itself from `rc.pl`.

A setting:

```perl
Peta::Shell->set(max_items => 100);
Peta::Shell->set(time => 'on');
```

A macro is a word that is replaced when it is the first word of a
line and a space or the end of the line follows it. Given a string,
the word is replaced and the rest of the line stays:

```perl
Peta::Shell->macro(p => 'print');
```

```text
ipps> p "printed by a macro\n"
printed by a macro
```

Given a sub, the macro gets the rest of the line and returns the Perl
to run in its place:

```perl
Peta::Shell->macro(sq => sub { my ($rest) = @_; "($rest) ** 2" });
```

```text
ipps> sq 3 + 4
49
```

A command of your own is called with a colon, like the built-in ones,
and gets the rest of the line:

```perl
Peta::Shell->command(greet => sub { my ($shell, $rest) = @_; print "hello, $rest\n" });
```

```text
ipps> :greet world
hello, world
```

`:help` lists your commands and macros after its own. The names of
the built-in commands are taken.

## Without a terminal

When standard input is not a terminal, `ipps` reads it line by line
without a prompt and prints values and errors the same way. That makes
it usable in a pipe:

```bash
printf 'my @w = split " ", "the quick brown fox";\nscalar @w\njoin "-", reverse @w\n' | pperl --shell
```

```text
4
'fox-brown-quick-the'
```

The commands work there too.