This file is intended to give a brief summary of the "smart" commands
available in the Python/Tk empire client.

Each of the following commands may be entered as if they were a normal
empire server command.  The client will automatically recognize these
commands and handle them locally, where applicable.

In addition to commands that are typed in on the command line, commands can
also be specified in three built-in configuration files.  The file,
"first.emp" is executed the first time the client connects to the server;
"start.emp" is run every time the client starts up; and the file
"connect.emp" is run each time a connection is made to the server.


Basic commands:
--------------

sync			- Sync server and client.
This command is used to keep the sector/ship/plane/nuke/etc databases
synchronized.  When this command is issued dump/sdump/pdump/ldump/lost
commands will be buffered to the server.  Empire 4.x timestamps will be
used to ensure only recently updated values are returned.  It is a good
idea to use this command instead of manually running dump yourself.

At one time, the server had a bug that causes an empire update to modify
sectors/etc without updating the timestamps.  To circumvent this problem,
'sync' was expanded to use the form 'resync'.  A resync will force the sync
command to ignore timestamps and dump the entire database.  It should no
longer be necessary to use this form of the command.

Additionally, you may preface sync (or resync) with any combination of
'epslno'.  'e' stands for sector dump, 'p' is a plane dump, 's' is a ship
dump, 'l' is a land dump, 'n' is a nuke dump, and 'o' is a lost dump.  When
these selectors are specified, only the corresponding dumps will be sent.
This is useful when you know which databases have changed, and you do not
want to bother syncing all the databases.  For example, you might specify
'elsync' to synchronize just sectors and land units.


null <cmd>		- Run command with no output.
Send CMD to server, and silently ignore all output that is returned.
However, any output received will be parsed by the internal parsers.  For
example, "null map *" will update the graphical display, but will not send
the output to the command line.


<cmd1> ; <cmd2>		- Multi-Command line.
This command allows multiple commands to be sent on the same line.  For
example, "map * ; bmap *" will send "map *" followed by "bmap *".


<cmd> > <file>		- Store output of <cmd> in new file called <file>
<cmd> >> <file>		- Store output of <cmd> at the end of the file <file>
The above commands redirect the output of an empire command.


exec <file>		- Send the contents of <file> to the empire server.
Execute allows commands to be executed from a text file.  Lines beginning
with a "#" are considered comments, and are silently ignored.  All other
lines are interpreted as client or server commands.


alias <cmd> <newcmd>	- Generate a definition for a simple alias.
All future invocations of CMD will automagically be altered to send NEWCMD
instead.  For example, the command "alias mvoe move", would make mvoe
function exactly like move.


Tk Window commands:
------------------

wind <cmd>		- Output command to Tk Window.
Send CMD to server, but redirect output to its own Tk window.  This command
will automatically pop-up a new window on the desktop.
For example, the command "wind info Products" would send that 20 page
manual to its own window with its own scrollbar.  You can then leave this
window up for future reference while still being able to send other empire
commands.


wread			- Graphical correspondence tool.
Sending this command will pop up a graphical telegram window.  THIS IS A
WORK IN PROGRESS!  Currently the graphical telegram tool doesn't work.  It
does, however, allow you to review old telegrams.  (The internal parsers
will automatically store incoming telegrams and announcements.)  Note: If
you are short on disk space, you may have to use this tool to delete old
telegrams and announcements from the database.  Since the client
automatically stores old messages, the database can become rather large
over time.


Map			- Open an additional graphical map window.
This command will pop up a graphical map window using the Tk interface.
An unlimited number of these map windows may be used simultaneously.  Each
map window can have its own origin and scale.  See the file 'gui.txt' for
more information on the map window.


cshow <'ship'|'land'|'plane'> - Hack for show command.
This command will send "show X build; show X cap; show X sta" and rearrange
the output into multiple columns.  A Tk window will pop up with the
resulting formatted display.


Smart commands:
--------------

eval [<var>=<val>] <sect> <cmd>	- Evaluate an expression for a sector.
This command allows the user to build complex commands that interrogate 
the client database.
NOTE: This command uses the internal database.  If the database is not
synchronized, the results will not be correct!

<sect> is a sector designation of the form x,y.  (Note, if you wish to run
a programmable-command on many sectors, use the foreach command.)

<cmd> is an empire command that contains an arbitrary number of python
expressions embedded within it.  The python expressions must be enclosed
within [ and ] characters (the square brackets).  The python expressions
will be evaluated using a namespace that is comprised of the sector's
attributes.  These attributes are formed using the ids of a standard sector
dump header.  Also, there are three included aliases: sect (A string
containing the sector's x,y pair), dist (A string containing the
dist_x,dist_y pair), and newdes (The new designation for the sector).

An example:
eval 0,0 move mil [dist] [mob/2+1-mil] [sect] ; anti [sect]

In this example, enough mil would be pulled in from sector 0,0's dist
center so that the maximum number of mil usable in an anti command would be
available.  Then the anti command is executed.


foreach <sectors> [<selectors>] <cmd> - Run given command on specified
					sectors.
Similar to the PEI foreach command, this command takes a sector range, an
optional ?<var>=<val>&... selector, and then runs cmd on each sector that
meets the requirements.

NOTE: This command uses the internal database to determine which sectors
apply.  If the database is not synchronized, the results will not be
correct!

<sectors> and <selectors> are similar to the empire server.  <sectors> can
be a range of sectors (x1:x2,y1:y2), an '*' to specify all sectors, or an
empire range.  <selectors> is a series of variable conditions that may be
specified using the form "?<var><cond><var>" where <var> is a either a
constant or a valid empire variable, and <cond> is one of '=', '<', '>' or
'#'.

<cmd> is a string that will be parsed in the same manner as the eval
command.  

An example:
foreach * ?dust=1&d_dist=0 move d [sect] 1 4,7
The above command would move 1 dust to sector 4,7 from all sectors that
have exactly 1 dust and have no dust threshold.

A more complex example:
foreach * ?mil<50 move mil [dist] [50-mil] [sect]
The above would attempt to resupply all sectors from their respective dist
centers, so that all sectors have a minimum of 50 mil.

An insane example:
foreach * move gun [10>gun and dist+' '+`10-gun`+' '+sect or
		    sect+' '+`gun-10`+' '+dist]
The above would move guns around so that exactly 10 guns are in every
sector.  Sectors that have more than 10 guns in them will move guns to
their dist centers; sectors with less than 10 guns will move guns from
their dist sectors.


sect <sects> [<selectors>] - Highlight specified sectors on main map.
This is a hack that supersedes the empire sect command.  In place of
calling the server's sect command, the local sect command will mark the
specified sectors on the main graphical map.

NOTE: This command uses the internal database to determine which sectors
apply.  If the database is not synchronized, the results will not be
correct!

The arguments to sect work in the same manner as the foreach command.

Optionally, you may run the sect command with no arguments at all to erase
the highlights from any past sect commands.


nova <civ|mil> <start sector> [to sector]  - Explore adjacent wilderness
					     sectors.
The start sector has to be an owned sector that contains mobility and
civs/mil.  If [to sector] is specified, it must be an owned sector that is
adjacent to unowned wilderness.  (If [to sector] is not specified then
<start sector> must be adjacent to unowned wilderness.)  Explore commands
will be generated from the start sector to all wilderness sectors.  No best
path is calculated.

WARNING: This command is EXPERIMENTAL, BADLY DESIGNED and BUGGY!
Do not use it in important situations.  It still might be useful in blitzes.
It uses the internal database, which has to be synchronized. 


Information commands:
--------------------

define			- List all online commands
You may obtain a list of all client commands that are currently available by
sending the command "define".


out			- Debugging tool - dumps database.
Don't run this - it is only useful for debugging. (And not very useful at
that.)  It will send the entire database to the empire console.
