pei(6)

Lexical Structure

An input line can come from one of three places:
(1) You typed it in.
(2) It was read in from a file (e.g. "start.exec").
(3) It was the value of an alias.

In case (1), if the input line is of one of the following forms, it will undergo history substitution:

!!

Repeat the last command.

![text]

Repeat the last command starting with [text].
e.g. !cen

^[text]^[replace]

Replace [text] with [replace] in last command.
e.g. ^jjh^jnh

#

Input lines beginning with # are comments and are ignored.

Each input line consists of sequence of command lines separated by semicolons (note that semicolons inside single or double quotes don't count):
commandline1; commandline2; commandline3; ...

Before each command line is processed, whitespace at the beginning and end of it is removed. Each command line has the following syntax:

?[scommand]

If we are at a sub-prompt, send [scommand] to it, otherwise, ignore.
e.g. des; ?2,0; ?c

[ecommand]

Send the empire command [ecommand] to the server. If we were expecting ?[scommand], abort the previous command before sending.
e.g. cen 0,0
e.g. move; cen 2,0 (aborts move before doing cen)

:[syscmd]

Send [syscmd] to your operating system.
e.g. :ls

[command] > [filename]

Write the output of [command] to [filename] only if the file does not exist.
e.g. cen #1 > cenfile

[command] >! [filename]

Write the output of [command] to [filename] (if the file exists, overwrite it).
e.g. cen #1 >! cenfile

[command] >> [filename]

Append the output of [command] to [filename].
e.g. spy 3,3 >> spyfile

[command] | [syscmd]

Pipe the output of [command] to the system command [syscmd].
e.g. news | more

Any commandline beginning with "$", "&", "@", "%", "{", "print ", "undef ", or "eval " will be evaluated as a perl expression.

Commands

These commands are "function maps", and may be typed at the pei prompt when you are connected to a game:

exec [filename]

Read input lines from [filename]. If you don't want the commands printed to the terminal, then before the exec, you should have "$quiet = 1".
e.g. exec pei_commands

runfeed [syscmd]

Run the program [syscmd] and pipe the output to pei.
e.g. runfeed mycivmover

history [number]

Print the last [number] input lines. If [number] is ommitted, then $maxhistorysize is used.

Note that any [filename] or [syscmd] may use ~ to refer to the home directory of the user.

Variables

Any pei command may contain perl variables. These variables will be replaced by their values when the command is parsed. For example:
$a = "0,0"
cen $a (evaluates to "cen 0,0")

If you want to isolate a variable name from surrounding text, then you may use {} brackets as in:
$x = "ti"
na${x}on (evaluates to "nation")

Here are some special pei variables which you can define:

$AUTOGAME

If defined in ~/.peirc, then pei will automatically connect to this game when it starts up.

$TIMEOUT

the length of time (in seconds) that pei will wait for data from the server (default is 120). Increase this if you have a bad lag, and decrease it if your link is good.

$beep

default value is 1. If you don't want to get beeped when you receive a telegram in INFORM mode, then put $beep = 0 in your ~/.peirc file.

$maxhistorysize

The number of input lines remembered by pei in the history mechanism (default is 100).

$EDITOR

The editor that you would like to use for composing telegrams and announcements (default is "vi" or environment variable EDITOR if defined).

$PAGER

Program to display output one screenful at a time. (default is "more" or environment variable PAGER if defined).

$PEIPATH

The full pathname of the directory containing all the pei files (you shouldn't need to set this).

$mailflag

If $mailflag = 1 or $mailflag{gamename} = 1, then when you

%mailflag

use "mail" to read your telegrams, pei will send "n" to the server so that your telegrams won't get deleted. Useful for co-rulers.

$debug

If $debug = 1, then pei will display the login conversation between pei and the server when connecting to a game.

Aliases

You can define aliases in pei using the syntax:
alias [name] [stuff]

For example:
alias d- des * ?newd=- +

If you want to put multiple commands in an alias, then you must enclose [stuff] in quotes. For example:
alias cod "res * ?des=o&ocon<10; res * ?des=g&gold<10"

If you put perl variables in [stuff], then they will be evaluated at runtime. For example:
alias ca cen $a
$a = "0,0"
ca (evaluates to "cen 0,0")

The following variables are also defined:

$0

The alias name

$1, $2, $3, ...

Arguments 1, 2, 3, ... that were used when the alias was called

$+

All of the arguments

For example, if you define the alias foo as follows:
alias foo first: $1, second: $2, all: $+, This should be foo: $0

then:
foo a b c d e f

would evaluate to:
first: a, second: b, all: a b c d e f, This should be foo: foo

Here's a more useful example:
alias bridge "build b $1; ?$2; expl c $1 1 ${2}h"

Alias recursion is permitted. For example:
alias xp explore
alias xx xp c 0,0 1
xx jjh (evaluates to "explore c 0,0 1 jjh")

Comparison to eif

For those of you who are used to using eif, I've included this section to describe how eif syntax translates into pei syntax.

The easiest way to see how eif syntax translates into pei syntax is to see how pei converts your ~/.eifrc into ~/.peirc (this is automatically done if pei doesn't find ~/.peirc). For your reference, here is a translation table of eif syntax to pei syntax:

When converting ~/.eifrc to ~/.peirc, the following translations are made:

eif

pei

addgame a b c d e f

addgame a d e b c f

&

?

@

:

setvar name "string"

$name = "string"

${N:+}

${N}

${N:-word}

(tricky -- watch how pei converts it)

These translations you'll have to make by hand:

connect gamename

gamename

unsetvar name

undef $name

$%name

$ENV{'name'}

The following eif syntax should simply be rewritten in perl:
!?str?
${N:?word}
${<:%word}
${name:=word}

The eif syntax !n and !-n is not supported.