pei6

Perl empire interface

Usage

pei [-n] [country] [representative] [host] [port] -or-

pei [-n] [gamename]

Overview

Pei is a powerful, fully extendible smart client for playing Empire. Features include:

Tools for managing and feeding civs, auto-exploring, setting dist-paths,

-: calculating the new efficiency of ships/planes/units, reading/sending telegrams and announcements, keeping track of enemy sectors and units, and managing production deltas.

-: Full perl integration. You can type perl commands at the empire prompt.

-: File redirection, piping, exec (read commands from a file), and runfeed (pipe the output of a program to pei).

-: Aliases. You can define your own aliases with arguments.

-: !!, !abc, and ^a^b history substitution

-: Multiple games. You may be connected to more than one game at a time, and switch between them.

-: Function mapping. You can call your own perl functions from within the client by defining your own function maps.

-: Output parsing. Server output is automatically parsed and stored in an internal database. There is a separate database for each game connected to.

-: Interrupt handling. ^C should be handled properly in most cases.

-: If the option -n is specified, then pei will be loaded without any tools. This is useful if you just want to log on quickly and check your mail.

An instance of pei begins by executing commands from the file .peirc in the home directory of the invoker. If a game has not been specified, then the user is presented with a 'Local%' prompt at which they can choose any game that was specifed by an 'addgame' line in .peirc.

Once a game has been specified, pei tries to connect to the game. If it was unable to connect, it will exit with a message explaining what went wrong.

Once connected, pei begins executing commands from the file start.exec in the current directory. Note that 'addgame' lines in .peirc can associate to each game its own directory.

Then pei repeatedly performs the following actions: Lines are read from the server and parsed until a prompt is encountered, then terminal input is parsed until an Empire command is encountered at which point pei sends the command to the server.

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.

Environment

PERLLIB: List of directories searched when locating PERL libraries. Used to find tools.pl, parse.pl, ...

COUNTRY, PLAYER, EMPIREHOST, EMPIREPORT: If specified pei will use these variables to connect to an empire game.

EDITOR: Default editor for pei.

PAGER: Default screen pager to be used in pei.

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

Files

README: Things that users of older versions of pei will need to know about this latest version.

INSTALL: Installation instructions.

BUGS: A list of known bugs.

CHANGES: A record of what got changed with version upgrades.

WISH_LIST: Changes that we hope to implement in the future.

pei: The program you run.

parse.pl: Parses server output into internal database.

tools.pl: Contains tools (nova, cmvr, ...).

mail.pl: Contains mail, wmail, tele, and anno tools.

simu.pl: Contains the "simu" tool.

example.peirc: Stuff for you to put in your ~/.peirc file (NOTE: don't make a ~/.peirc file until pei has had a chance to convert your ~/.eifrc into ~/.peirc).

pei.man: Pei users manual--you can also get this by typing "help pei" from within pei.

tools.man: Manual for pei tools--you can also get this by typing "help tools" from within pei.

hacker.man: Information useful to hackers.

$HOME/.peirc: Pei commands read when pei starts up.

$HOME/.eifrc: Converted to ~/.peirc if ~/.peirc doesn't exist.

$gamedir/start.exec: Commands executed when you first connect to a game.

$gamedir/$gamename.dump: Database of enemy sectors (used by "stat").

$gamedir/$gamename.ships: Database of enemy ships (used by "sstat").

$gamedir/$gamename.planes: Database of enemy planes (used by "pstat").

$gamedir/$gamename.units: Database of enemy land units (used by "lstat").

$gamedir/$gamename.teles: Your mailbox of Empire telegrams (used by "mail").

$gamedir/$gamename.wires: Announcements (used by "wmail").

Releases

Unchanged in 2 releases since Debian 2.1 (Slink).

2.1–2.2