\input texinfo                  @c -*-texinfo-*-
@c %**start of header
@setfilename myxec.info
@settitle MyXEC User's Guide
@c %**end of header

@ifinfo
Try to write a User's Guide to the X-Empire client MyXEC.

Copyright @copyright{} 1994 Ulrich Drepper.
@end ifinfo

@titlepage
@sp
@center @titlefont{MyXEC}
@sp 1
@subtitle User's Guide
@sp 1
@subtitle $Revision: 1.1 $
@sp 1
@author Ulrich Drepper

@page
@vskip 0pt plus1filll
Copyright @copyright{} 1994 Ulrich Drepper

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.

@end titlepage
@page
@ifinfo
@node Top, Overview, (dir), (dir)
@top MyXEC User's Manual
@noindent $Revision: 1.1 $, describes Myxec-0.2

@noindent Copyright @copyright{} 1994 Ulrich Drepper

This is a try to write a guide to the X-Empire client MyXEC.  It is not
intended be a guide to empire itself.  There are more capable people for
this.  I assume you are familar with the empire commands.  I will
describe which feature of the program triggers what empire command and
how you can overcome the complexity of the game by using the program and
it's extension language.

@end ifinfo

@menu
* Overview::              Global outline of the program and the goal.
* The Window::            Description of the six areas.
* The Extension language: Scheme.
@end menu

@node Overview, The Window, Top, Top
@chapter Overview

When having the first contact with empire you are overwhelmed by the
possibilities of the game but also frustrated by the afford for playing.
If you are not prepared every second command is @code{map}.  You also
almost immediately forget all the number in the @code{resource} and
@code{commodity} tables.

On the other hand one may have played @dfn{Civilization}(tm).  The
complexity and general idea are rather weak (beside there is officially
only a single player version).  But you have a nice graphical interface.
All commands can be given with the mouse you have all information
ready on a mouse click.

This program tries to give Empire an adequate interface for modern
X-Windows workstations.  For the sake of bandwidth the client helds all
information local by gathering from the server responses.  This is very
difficult because of the strange protocol (remember subprompts).  This
is the reason I concentrated fully on one version of Empire, 
Chainsaw, version 3.3.

@node The Window, Scheme, Overview, Top
@chapter The Main Window

Goal of the Interface design was to follow an approved UI style guide (I
used Motif 1.1 Style Guide) wherever possible.  Therefor you hopefully will
intuitively be able to work with the program using your former experiences
with other applications.

After starting the programs shows up a window with six area

@menu
* Menue bar::                   drop-down menu bar.
* Command button field::        collection of command buttons.
* Status field::                display field for sector information.
* Map area::                    scrollable window with graphical map.
* output field::                area for not processed text output.
* SCHEME command edit field::   input field for the extension language.
* Status line::                 shows the status of the last command.
@end menu

As you will remark soon all keyboard input goes to one of the edit
fields.  This is true unless a popup window is activated.  For a more
convenient handling there are some keyboard accelerators which are also
available while the mouse pointer is somewhere inside the main window.

@node Menue bar, Command button field, The Window, The Window
@section The menue bar

(The menueline is @emph{not} fully supported now.)

The menue line has beside the normal entries for @code{File},
@code{Option} and @code{Help} one entry for @code{Commands} and two
fields which implement no menue.

@menu
* Connection Status:      ShowConnect.
* Menue entry @code{File}:     Menue-File.
* Menue entry @code{Options}:  Menue-Options.
* Menue entry @code{Commands}: Menue-Commands.
* Menue entry @code{Help}:     Menue-Help.
* Coordinate tracking:    TrackCoord.
@end menu

@node ShowConnect, Menue-File, Menue bar, Menue bar
@subsection Show connection status

At the very left of the bar one see a small icon which shows whether the
client has an open connection to the server right now.  The icons should
explain themselves.  The connection is shutted down after sending or
receiving no command for an period of time (default: 2min).  When the
next command is send the connection is established automatically.

Comment: this may be unsecure because someone who can read your core
dumps is able to get your country name and password.


@node Menue-File, Menue-Options, ShowConnect, Menue bar
@subsection Menueentry File

The menue entry has two possible selections.  @code{Open...} allows
to load a former saved data dump.  This binary file fully describes the
status of the game when saved.  Most likely not all information is valid
anymore but it is a good starting point.  The other possibility is to
get all the information directly from the server.  This is acceptable
for a local game but for intercontinental communication or private
1200bds telephone lines@dots{}  Instead you can incrementally update your
information and the program will do it's best to gather the information.

The last entry is triggers the quit action.  This is the usual place and
it also standard that it is asked for confirmation.

@node Menue-Options, Menue-Commands, Menue-File, Menue bar
@subsection Menueentry Options

No options for now.

@node Menue-Commands, Menue-Help, Menue-Options, Menue bar
@subsection Menueentry Commands

This menue entry gives the user the most convenient but perhaps slowest
interface to the empire commands.  Here you find selections for all (but
not @emph{now}) commands that allow to determine the arguments in
advance.  Therefor it will not be possible to implement e.g. the @code{attack}
command this way because no client will ever (with reasonable efford) be
able to determine all the answer for the subprompts.

If you want to
see how complex this can be take a look at the code for the
@code{explore} command.  I used a way to get as much information as
possible from the subprompts because it is very useful when exploring
new terrain.  But the code has to deal with all the subprompt and worse
with possible errors from the server, such as @code{update in progress}.

Most selection show and dialog box which allows the necessary inputs.
If possible the abilities of a GUI are used, e.g. for commodities you
only have to select a toggle button and not to enter a text.  Coordinate
and coordinate range inputs can be given with the mouse on the map
window (@xref{Map area}).  This is possible because the map with it's
scrollbars are usable even after poping up the dialog box (Note: nothing
else is usable).

Most of the dialog boxes have a @cite{action and close} behaviour.  But
this inconvinient for some of them.  Perhaps one may wish to designate
many sectors at once.  Of course you could pop up the dialog each time
but it is inconvenient.  So the behaviour is changed.  The buttons have
the meaning @cite{Do it} and @cite{Close}.  Close is like the old
meaning of @cite{Cancel}.  It closes the popup and returns to normal
mode without any action.  The other button executes the action and
prepares the dislog for a new input (i.e. clears some field and moves
the focus to the first field).

In all dialogs the @key{RETURN} key is an accelerator for @cite{OK}
and @cite{Do it} resp.  This is standard, too.  @key{TAB} is used to change
the input focus.  It changes in the order top-to-down.
@kbd{@key{Shift}-@key{TAB}} changes in the opposite order.

@menu
* All::
* Break::
* Census::
* Commodity::
* Deliver::
* Designate::
* Explore::
* Level::
* Map::
* Move::
* Nation::
* Produce::
* Radar::
* Resource::
@end menu

@node All, Break, Menue-Commands, Menue-Commands
@subsubsection Meta-commands @code{all}

This is not a real empire command.  It is used by the client to gather
all possible information about a sector for installing the database.
For now it sends the server the following commands (in this order):

@itemize
@item
dump
@item
census
@item
produce
@item
map
@item
nation
@end itemize

Dump gives us almost all information but missing are information about
the production process (items needed/produced), the sectors not owned by
yourself, nationwide information like technology level and the
production status (stopped/producing, this is the only reason for the
census command, grrr).

This command should also be used by the user to update the stored data
when it is somewhat outdated.  It is often the case because one will
most of the time be able to play with the stored information because the
client tries to stay up-to-date by examining the result of the commands.

For using this command the program simply asked for a range of sectors.
All information are then stored in the data base.

@node Break, Census, All, Menue-Commands
@subsubsection Empire command @code{break}

This commands is only selectable when the client is convinced your
country is not already broken.  It needs no input so you will be able to
go on immediately.  The only thing you see after a succesful execution
is that your initial sector are now capitols (yes, this picture
means to represent a capitol).

@node Census, Commodity, Break, Menue-Commands
@subsubsection Empire command @code{census}

After reading in the (range of) coordinates a @code{census} command is
send to the server.  The client knows who to process the response and
can incorporate the answer into the internal data base.

@node Commodity, Deliver, Census, Menue-Commands
@subsubsection Empire command @code{commodity}

After reading in the (range of) coordinates a @code{commodity} command is
send to the server.  The client knows who to process the response and
can incorporate the answer into the internal data base.

@node Deliver, Designate, Commodity, Menue-Commands
@subsubsection Empire command @code{deliver}

The deliver selection offers @emph{not} the whole functionality of the
command line version.  This is because we have to avoid subprompts.  A
range of coordinates is therefor only allowed for reading information
(negative threshold) or setting only the threshold (non-paranthesized
threshold).

For the direction field also range are allowed as input but only if the
@code{sector(s)} field has a single sector as argument.  The second
condition is that the second sector must be a adjacent to the source.

The threshold can be given in all three different forms (see @cite{info
deliver} for more information).

The selection of the commodity is simplifies by a group of toggle
buittons.  This allows error-free input.  The selection is remembered
for the next time the window is used.

@code{deliver} is one of the commands that can be executed for many
different arguments one after the other.  Therefor it uses the above
described technique of @cite{Do it} and @cite{Close}.  You will find
this aceptable because the map area is working and you can examine the
sector as described in @xref{Map area}.

@node Designate, Explore, Deliver, Menue-Commands
@subsubsection Empire command @code{designate}

This dialog shows up very colorful (at least in the color version :).
You can select the coordinates as usual and then
toggle the picture button which is desired.

The dialog is one of the kind not closing on execution because you may
find yourself designating one sector after the other.

The command is only send to the server if the sector if the local data
show this sector as an own one.  This may be a problem when the data is
not up-to-date anymore but can be corrected easily by reading the map
for this sector.

For the ease of using you have the possibility of short key strokes for
selecting the new designation.  The is done by @kbd{@key{META}-@var{x}}
where @var{x} is the usual character for the designation (e.g. @samp{*}
for @samp{air field}).

@node Explore, Level, Designate, Menue-Commands
@subsubsection Empire command @code{explore}

This is the far most complex command with respect to the response
parsing of the client.  The reason is that the client sends the single
steps of the exploration on single lines.  This allows to explore the
resources of every sector on the way to the destination.  Especialiy in
the starting pahse of the game, when many explore commands are used,
better information can be a big win.  Because the client memorizes the
values (unlike most humans) you can select your next steps at the base
of the known data.

But this win is bought at a high price: we have to deal with subprompt
mode of the server.  We cannot determine if all path elements are valid
and therefor must be able to recognize errors that the server signals.
But we must not forget about all the other characters we sent as the
path.  These are now not anymore parsed in the subprompt mode and
hopefully describes illegal commands which are rejected by the server
(in fact this is the case for the accepted paths).  The client reads
all the responses to the illegal commands and simple rejects them.

In the current implementation you cannot give the coordinates of the
destination sector as path.  In fact only the paths which the servers
accepts are allowed.  As the deactivated toggle button and input field
show there may be in a future release a computation for best paths to
the destination sector but as I said in a future release@dots{}

But exploration is easy even without this feature.  The dialog popup is
one of the kind which must be dismissed for that it disappears.  This
means can you can explore one sector after the other without closing the
popup.  A typical use is that you klick at the last sector at the route
to the destination you own and then enter the necessary path characters.

After pressing @cite{Do it} the coordinate fields are cleared and the
input focus is on the from sector field.  The field with the number
remains the same.  This is because one uses the same amount for all
sectors (e.g. always one civilian/military in the begining when people
and mobility are low).

@node Level, Map, Explore, Menue-Commands
@subsubsection Empire command @code{level}

Simply sends the level command for the specified sector to the server
and parses the result.  Normally this command won't be used because the
effect of many commands can be achieved alone with dump.

@node Map, Move, Level, Menue-Commands
@subsubsection Empire command @code{map}

This serves as a front end to the @code{map} command.  A region as a the
argument is read in the normal way and can especialy be specified with
the mouse.  The server sends as the result a map which is incorporated
into the local data.  But it is not simply copied but instead compared
whether we have already some better information.  We do not want to
loose this information we get by radar, spying or other means.  It is
also for this command true that it won't be used very frequent because
we most of the time not only want to update the map information but the
whole bunch and there are better commands for this mean.

@node Move, Nation, Map, Menue-Commands
@subsubsection Empire command @code{move}

The move command is again one of the commands which are used several
times one after the other.  You have to explicitly dismiss the dialog to
close it.

The dialog allows the usual input of coordinates with the mouse and the
map.  The commodity selection is less error prone due to the use of
toggle buttons.  The path field allows the usual server syntax i.e. also
a sector coordinate.

After selecting @cite{Do it} a syntax test is done.  If an error occurs
nothing changes and you have the chance to correct.  After this a test
for the quantity of the demanded commdity is done.  In the case
the source sector does not have enough you will get an error message in
the status line.  Else the command is send to the server and the local
data is correct corresponding.  You can view the result of the
@code{move} command by clicking with @kbd{Button-1} on the destination
or source sector.  When succesful you will find the local data corrected.

@node Nation, Produce, Move, Menue-Commands
@subsubsection Empire command @code{nation}

When selecting this menue point you won't be ask about parameters.  The
@code{nation} command is simply send to the server and the output
processed.  You will find the actual values for technology, education
etc in the information field.  This command is also part of the
@code{all} command.

@node Produce, Radar, Nation, Menue-Commands
@subsubsection Empire command @code{produce}

Input for this dialog is a range of sectors for which the production
data is read in.  You can view them by selection the desired sector with
@key{Button-1} on the map and examine the status field.

@node Radar, Resource, Produce, Menue-Commands
@subsubsection Empire command @code{radar}

The client has the ability to incorporate the informations gained by the
radar systems into the internal map.  This is useful for sectors that
are not owned by yourself.  If any of the radars can determine the type
of a sector the undetermined fact from other radar (means the @code{?}
sign) will not overwrite this information.  If no radar can determine
the type and no formaer information exist the enemy sector will show up
as a @cite{unknown enemy sector}.

This command is also send when the @code{all} command is selected.

Note: units are for now @emph{not} shown.  This information in the radar
map is ignored.

@node Resource,  , Radar, Menue-Commands
@subsubsection Empire command @code{resource}

The @code{resource} command determines the quntity of the remaining
resources of a given range of sectors.  This is normally not necessary
because a) immediately after you explored a sector the quantities are
determined and b) @code{dump} contains this information, too.

@node Menue-Help, TrackCoord, Menue-Commands, Menue bar
@subsection Menueentry Help

The menu entry @code{Help} has some of the standard entries of the style
guide.  For now there are:

@menu
* Tutorial: Help-Tutorial.
* On Version: Help-OnVersion.
@end menu

@node Help-Tutorial, Help-OnVersion, Menue-Help, Menue-Help
@subsubsection Tutorial

None as yet.

@node Help-OnVersion,  , Help-Tutorial, Menue-Help
@subsubsection On Version

None as yet.

@node TrackCoord,  , Menue-Help, Menue bar
@subsection Tracking map coordinates


@node Command button field, Status field, Menue bar, The Window
@section The Command Button field

These nine buttons are simply for convenience.  They simply trigger the
most important entry of the command menu.  For even more faster access
they have key accelerators.  They are Meta-1 to Meta-9, numbered from
left to right and top to bottom.

@emph{If you} have suggestions for a more important collection of
commands for these button send a mail to the author.

@node Status field, Map area, Command button field, The Window
@section Status field

The status field is placed under the command buttons. The information
displayed here consists first of the general game data (as given by the
nation command etc) and sector information.  When the program starts it
contains the data of the (0,0) sector.  Whenever the user presses
@key{Button-1} while on the map (see @xref{Map area}) this will change
to the sector the mouse cursor is over.

Looking the game data of a sector is also very useful for recognizing
these incredible icons used on the map :).

Beside the icon is the coordinate and the sector designate as text
given.  In the next line there is possibly the information about a
stopped sector.  Following are information about resource, avail
workers, percentage of working people, distribution center etc given.

After this the most important information is given in table form.  You
get for all commodities information of quantity, delivery, distribution,
usage and production.  Usage and production are displayed in the same
columns but the production is always only displayed in one line has has
angle @code{<}@dots{}@code{>} around the value.  The table is kept spare
when possible.  The value of zero is not shown when not necessary.

As a second part of the information the game data values of technology,
research etc are shown.  The last to columns show the production and the
first the actual value as for the commodities.  The second column shows
different values for all rows.  For technology it shows the technology
factor, for research the plague factor and for happiness the happiness
needed.

The rest is self exlained: treasury save population, military reserve
and maximum population.

@node Map area, output field, Status field, The Window
@section Map area

This is the central display of the game.  You get a picture of the world
which is based on all the information that the program ever gathered
from the command replies of the server.  There are many sources but
mainly @code{map}, @code{explore} and @code{radar}.

The map is normally much bigger than the window but you have scrollbars
to display the part you are interested in in the moment.  The map
contains hexagons which can be seen as the unit of measure of the empire
map.

@subsection Color version

In the color version you have many colorful icons to learn.  If you
cannot guess the meaning of one of them click with @key{Button-1} on it
and look at the description in the status field.

The icons may have various borders.  With now border they are yours.  If
they have black borders they are highlighted.  With a white color you
have no knowledge whether this sectors belongs to somebody.  With a red
border it's an enemies sector.

@node output field, SCHEME command edit field, Map area, The Window
@section Text output field

In this field all text output that are not processed internally by the
client are displayed.  This includes output from commands which directly
went to the server (quoted commands) or output from Scheme commands.

This field is read-only (for programmers: in fact append-only) and only
allows scrolling and selecting.  The ouput is always appended at the end
of the buffer.

Because the Athena Widget set does not have a @cite{circular text
buffer} widget this buffer grows steadily in size.  One of the plans for
the program is to build such a circular buffer but for now it is not
available and you should pay attention for it.  You should restart the
client from time to time if often you use the buffer.  But 1000 lines
are really not many.

@node SCHEME command edit field, Status line, output field, The Window
@section SCHEME command edit field

Beside the command menue and command buttons this is the main focus of
action.  You can use the underlying language Scheme for retrieving
information, send commands or work on the Scheme environment, or you
can send commands directly to the server.  This is as you would have the
simplest client which allows to send commands but you have history for
the commands and the output.

This field is line-orientated.  This means the given commands can only
span a single line.  When @key{RETURN} is pressed the whole line is
regarded as input not only from the beginning of the line to cursor
position.  For using the text fields it is useful to know about the
cursor commands.  They are described in the Athena Widget manuals but in
short one can say they are orientated at the Emacs editor.

The Scheme language and its extension for Empire is described in another
part of this document (@xref{Scheme}) but we should describe
the case where the command is directly sent.  This is done when the
first non-space character is a quote character (').  This only means a
minimal restriction in the Scheme languages as explained in the
corresponding section.  Every other line is sent to the Scheme
interpreter.  You will most likely get error messages from the
interpreter when you miss the quote (@xref{Status line}).

For the command edit field is also true that no circular buffer is
available as yet.  Therefor the buffer can grow without bound but the
commands have to be typed in one after the other only filling one line
each.  This is why the argument does not count so much in this case.

@node Status line,  , SCHEME command edit field, The Window
@section Status line

The status line shows normally only the current on-line time and
remaining BTUs.  Both come from the information in the last prompt.

If an error occurs you will find the information appended in this line.
It remains there until next command completes and clear the line or
display another error.

@node Scheme,  , The Window, Top
@chapter Scheme

As a command, macro, or extension language (as you like) for this
program Scheme was chosen.  This has a very simple reason: Scheme is a
very powerful language, easy to learn, nice to implement and (almost)
without quirks like most other languages.  It is also important that with
libscheme, a library written in C which implements the actual Scheme
standard, there is the possibility to embed the language fully in the
program.

This manual is not about Scheme and therefor we won't explain it here
but you should have received with this document another info file.
@xref{Top, , Introduction, r4rs, Revised(4) Report on the Algorithmic Language Scheme}.

In the following text the extensions for use as an embedded language are
describes.  These allow to control the program by Scheme programs.

(Well, I hope it will be someday like this.  As yet it is much
less@dots{})

The additions can categorized in some sections:

@menu
* Data types::
* Variables::
* Retrieval functions::
* Operations::
* Examples::             some examples on programming.
@end menu

@node Data types, Variables, Scheme, Scheme
@section Data types

There are two new data types in this Scheme implementation:

@itemize @bullet
@item
coordinates

@item
coordinate ranges

@end itemize

The syntax for coordinates is (in EBNF)

@example
[+-][0-9]+,[+-][0-9]+
@end example

For ranges its only slightly more complex:

@example
[+-][0-9]+@{:[+-][0-9]+@}?,[+-][0-9]+@{:[+-][0-9]+@}?
@end example

As can be seen easy every coordinates is also a range.  This is
sometimes used in the code.

This data type is necessary for the empire commands which use
coordinates as arguments.  It would not be helpful if we use a different
syntax for the direct empire commands or the Scheme commands, esp. when
we use the paste option of the map area (@xref{Map area}).

There are two predicates for testing for these types: @code{coord?} and
@code{range?}.  Both take one argument and return a boolean value.

A range is contructed by two coordinates which define the upper left and
the lower right corner.  You can access these two values by the two
functions @code{lu-coord} and @code{rl-coord} which return these values
as coordinates.  The arguments have of course to be ranges.

(Further functions which allow arithmetic on coordinates will follow.)

@node Variables, Retrieval functions, Data types, Scheme
@section Additional Scheme variables

There are some kinds of variables added.  Some represent real values
which describe the game.  These are also used in the display
(@xref{Status field}) and in processing the data responses.

The second kind are simply constants.  They serve for accessing single
values inside data structures (@xref{Retrieval functions}).

@menu
* Status variables::
* Constants::
@end menu

@node Status variables, Constants, Variables, Variables
@subsection Status variables

@defvar rest-btu
The variable always contains the number of the remaining BTUs.  It is
the same as the one displayed in the status line.  The value will be
updated each time a prompt data record arrives from the server.
@end defvar

@defvar online-min
This variable is a companion of @var{rest-btu}.  All said there is true
for this, too.
@end defvar

@defvar treasury
Contains the actual value of the treasury.  Sending @code{nation} or
@code{all} command will update the value.  It is a floating point variable.
@end defvar

@node Constants,  , Status variables, Variables
@subsection Constants

These variables only serve as a version independent interface to
internal data structures (@xref{Retrieval functions}).  So we will only list
them here without giving any values or further description.  More is
said in the section where the data structures are described.

The first table describes indices for commodities:

@vtable @var
@item civ-idx
index for civiliance

@item mil-idx
index for military

@item uw-idx
index for uncompensated workers

@item food-idx
index for food

@item shell-idx
index for shells

@item gun-idx
index for guns

@item petrol-idx
index for petrol

@item iron-idx
index for iron ore

@item dust-idx
index for gold dust

@item bars-idx
index for gold bars

@item barrel-idx
index for barrels of produced oil

@item lcm-idx
index for light contruction material

@item hcm-idx
index for heavy construction material

@item rad-idx
index for radioactive material
@end vtable

@noindent
The second table displays name for resource retrieval:

@vtable @var
@item min-idx
index the mineral content

@item gold-idx
index for gold content

@item oil-idx
index for oil content

@item fert-idx
index for fertility content

@item uran-idx
index for uran content
@end vtable

@node Retrieval functions, Operations, Variables, Scheme
@section Additional functions for information retrieval

Of major interest in programs or macros is the content of a sector.
There are five different categories:

@menu
* Resources:            sector resources.
* Content:              commodity content.
* Delivery paths::
* Delivery cutoffs::
* Distribution levels::
@end menu

All of these functions can have one or two arguments and return a list
of vectors.
@xref{Vectors, , Vectors, r4rs, Revised(4) Report on the Algorithmic
Language Scheme}, for details about accessing vectors.  With two
arguments it's a list of single values.

@node sector resources, commodity content, Retrieval functions, Retrieval functions
@subsection Sector resources

@defun resource-vec coordinate [index]

@code{resource-vec} allows to observe the resources of the sector,
specified by @var{coordinate}.  With one argument it returns all
resource, else only the resource specified by the index.  Use
the constants for the different
resources as value for @var{index} (@xref{Constants}).

The return value is a list of pairs.  The @code{car} of the pairs is the
coordinate of the vector and the @code{cdr} is the value, i.e. the
vector or the single value.  This may look like

@example
((0,0 . #(100 100 100 100 100)) (-2,0 . #(0 10 20 0 90)))
@end example

for the form with a single argument and

@example
((0,0 . 30) (2,0 . 10) (4,0 . 0))
@end example

for the form with a given second argument.
@end defun

@node commodity content, Delivery paths, sector resources, Retrieval functions
@subsection Sector content

@defun content-vec coordinate [index]

@code{content-vec} allows to access the amount of commodities in the
sector specified by @var{coordinate}.  With one argument it returns all
content amounts, else only the amount of the commodity selected.  Use
the contants for the different commodities as value for @var{index}
(@xref{Constants}).

The return value is a list of pairs.  The @code{car} of the pairs is the
coordinate of the sector and the @code{cdr} is the value, i.e. the
vector or the single value.  This may look like

@example
((-3,-3 . #(229 0 179 0 0 0 0 0 55 0 410 1000 0 0))
 (-5,-3 . #(711 0 0 0 0 0 0 695 0 0 0 0 0 0)))
@end example

for the form with a single argument and

@example
((-5,-1 . 0) (-7,-1 . 9990) (-6,-2 . 200))
@end example

for the form with a given second argument.
@end defun

@node Delivery paths, Delivery cutoffs, commodity content, Retrieval functions
@subsection Sector delivery paths

@defun del-path-vec coordinate [index]

@code{del-path-vec} allows to access the delivery paths for the
different commodities in the sector @var{coordinate}.  With one argument
it returns all paths, else only the path for the commodity which is
selected by @var{index}.  Use the constants for the different
commodities as value for @var{index} (@xref{Constants}).

The path is given by a single character.  This character is a direction
character (@var{y}, @var{u}, @var{g}, @var{j}, @var{n}, @var{m}) or a
period.  This may lead to strange looking expression as you can see in
the examples.

The return value is a list of pairs.  The @code{car} of the pairs is the
coordinate of the sector and the @code{cdr} is the value, i.e. the
vector or the single value.  This may look like

@example
((-5,-3 . #(() () . . . . . y j . j . . .))
 (-4,-4 . #(() () . . . . . . . . n n . .)))
@end example

As you can see two elements of the array have to value
@code{()}, i.e. Null.  This is because you cannot deliver civilians nor
military.

For the two argument form you get results like

@example
((4,0 . .) (2,0 . y) (3,-1 . g) (1,-1 . y) (4,-2 . .) (2,-2 . .))
@end example

Note e.g. the first element of the list.  The direction is @code{.}.
You should take a look in the Scheme manual how you type in character constants
@xref{Characters, , Characters, r4rs, Revised(4) Report on the Algorithmic
Language Scheme}.

@end defun

@node Delivery cutoffs, Distribution levels, Delivery paths, Retrieval functions
@subsection Sector delivery cutoffs

@defun del-cutoff-vec coordinate [index]

@code{del-cutoff-vec} allows to access the delivery cutoffs for the
different commodities in the sector @var{coordinate}.  With one argument
it returns all paths, else only the path for the commodity which is
selected by @var{index}.  Use the constants for the different
commodities as value for @var{index} (@xref{Constants}).

The return value is a list of pairs.  The @code{car} of the pairs is the
coordinate of the sector and the @code{cdr} is the value, i.e. the
vector or the single value.  This may look like

@example
((0,4 . #(() () 0 16 0 0 0 0 0 0 0 0 0 0))
 (-2,4 . #(() () 0 0 16 40 0 0 0 0 0 8 0 0)))
@end example

and with two arguments

@example
((4,0 . 0) (2,0 . 8) (3,-1 . 0) (1,-1 . 40) (4,-2 . 0) (2,-2 . 16))
@end example

Tow elements of the vector are always @code{()} (Null), because
you cannot deliver civilians and military.

@end defun

@node Distribution levels,  , Delivery cutoffs, Retrieval functions
@subsection Sector distribution levels

@defun dist-level-vec

@code{dist-level-vec} allows to access the distribution level for the
different commodities in the sector @var{coordinate}.  With one argument
it returns all levels, else only the level for the commodity addressed
by @var{index}.  Use the constants for the different commodities as
value for @var{index} (@xref{Constants}).

The return value is a list of pairs. The @code{car} of the pairs is the
coordinate of the sector and the @code{cdr} is the value, i.e. the
vector of the single value.  This may look like

@example
((3,3 . #(0 0 0 0 0 0 0 0 0 0 0 250 0 0))
 (0,4 . #(0 0 0 0 0 1 0 0 0 0 1 100 200 0)))
@end example

and with two arguments

@example
((2,4 . 0) (0,4 . 100) (3,3 . 250) (1,3 . 0))
@end example

@end defun

@node Operations, Examples, Retrieval functions, Scheme
@section Additional functions for operating on data

The additional functions can be divided into two parts:

@menu
* Empire Commands::   which correspond to the real commands.
* Local Commands::    which change the local status
@end menu

@node Empire Commands, Local Commands, Operations, Operations
@subsection Empire commands

The Empire commands have a Scheme version, too.  For people who don't
like changing between mouse and keyboard and for a faster interface.
Like for the commands triggered by the menue the server output is
processed by the client so that the user won't see it.  The syntax of
the commands should be nearly the same as for the normal commands.

As mention above not all commands can be processed by the server.
Commands like @code{attack} will probably never be parsed by the client
because of the complexity in their commandline parameters.  The
available commands are:

@menu
* All:      scheme-all.
* Break:    scheme-break.
* Census:   scheme-census.
* Dump:     scheme-dump.
* Map:      scheme-map.
* Nation:   scheme-nation.
* Radar:    scheme-radar.
* Resource: scheme-resource.
@end menu

@node scheme-all, scheme-break, Empire Commands, Empire Commands
@subsubsection All

@defun all [range]

This meta-command can be called with no or one argument.  With no
argument the effect is the same as if @var{range} is set to the whole
map.

For more details see @ref{All}.

@end defun

@node scheme-break, scheme-census, scheme-all, Empire Commands
@subsubsection Break

@defun break

The effect is the same as empire command of the same name.  @code{break}
takes no argument and only has an effect if the country isn't broken as
yet.

@end defun

@node scheme-census, scheme-dump, scheme-break, Empire Commands
@subsubsection Census

@defun census range

The argument describes the range of sectors for which we want to get the
actual @code{census} information.  These are incorporated into the local
data base.  The user won't see any line of this.

@end defun

@node scheme-dump, scheme-map, scheme-census, Empire Commands
@subsubsection Dump

@defun dump range

The argument describes the range of sectors for which we want to get the
actual @code{dump} information.  These are incorporated into the local
data base.  The user won't see any line of this.

@end defun

@node scheme-map, scheme-nation, scheme-dump, Empire Commands
@subsubsection Map

@defun map range

The argument describes the range of sectors for which we want to get the
actual @code{map} information.  These are incorporated into the local
data base.  The user won't see any line of this.

@end defun

@node scheme-nation, scheme-radar, scheme-map, Empire Commands
@subsubsection Nation

@defun nation

The @code{nation} command does not take any argument.  It updates the
values for technology level, education etc.

@end defun

@node scheme-radar, scheme-resource, scheme-nation, Empire Commands
@subsubsection Radar

@defun radar range

The server will send all radar images from the radar @emph{stations} in
the given @var{range}.  The client tries to grab as much information as
possible from this images and incorporates them in the local map which
is then displayed.

@end defun

@node scheme-resource,  , scheme-radar, Empire Commands
@subsubsection resource

@defun resource range

The argument describes the range of sectors for which we want to get the
actual @code{resource} information.  These are incorporated into the local
data base.  The user won't see any line of this.

@end defun

@node Local Commands,  , Empire Commands, Operations
@subsection Local commands

These commands fall into two categories:

@itemize
@item
Scheme environment manipulation

@item
Empire environment manipulation
@end itemize

As yet there are the following commands
@menu
* Edit::             or create a Scheme closure.
* Save::             a Scheme closure.
* Add-hilit::        add sector to set to be highlighted.
* Hilit::            enable/disable highlighting.
* Clear-hilit::      clear highlighting set.
@end menu

@node Edit, Save, Local Commands, Local Commands
@subsubsection Edit Scheme closure

@defun edit closure

The normal way of writing Scheme code should be to use an external
editor.  This can be loaded with the Scheme command @code{load} and then
be used.

The editing takes place in another top-levl window which stays
independent beside the main window until it is closed.

But sometimes one only wants to write a little helper function.  For
this case there is the Scheme command @code{edit}.  It's argument is a
closure name (@emph{not} a string).  If this closure exists it will be
displayed in the edit window.  If it does not exist the beginning of a
closure definition will be displayed, with the given name inserted.

The edit widget has two text fileds and three buttons.  The button
@code{Test} and the lower text field have as yet no function.  The
@code{OK} button leads to the evaluation of the current content of the
dit field and then closes the window.  If the code in the window is
correct it will be incorporated in the top-level frame of the
interpreter. Otherwise you will see an error message in the status line.

If the @code{Cancel} button is selected no evaluation takes place and
the current content is discarded because the window is closed.

@end defun

@node Save, Add-hilit, Edit, Local Commands
@subsubsection Save Scheme closure

@defun save file-name closure

The @var{closure} will be saved in a pretty (means readable) format in
the file named by the string @var{file-name}.  The file can be read in
the interpreter later or can be edited.  The format is chosen for that
the code can be read in later without loss of information.

@end defun

@node Add-hilit, Hilit, Save, Local Commands
@subsubsection @code{add-hilit}

@defun add-hilit list-of-range @dots{}

The arguments of @code{add-hilit} are lists of ranges.  Note that
coordinates are a special case of ranges and therefor also can be given
as argument.

All sectors in this ranges are included in the list.  After all are
included the actual selection of sectors are displayed highlighted.
For an example see @ref{Examples}.

@end defun

@node Hilit, Clear-hilit, Add-hilit, Local Commands
@subsubsection @code{hilit}

@defun hilit [ #t | #f ]

If the argument is @var{#t} the actual sector selection is displayed
highlighted.  When it is @var{#f} the highlighting is removed and the
sectors are normally.  In any case the list of selected sectors is
@emph{NOT} removed.  You can enable and disable the highlighting as
often as you like.

@end defun

@node Clear-hilit,  , Hilit, Local Commands
@subsubsection @code{clear-hilit}

@defun clear-hilit

This function takes no argument and clears the list of highlighted
sectors.  A selected deletion is not possible.  If in the current map
the sectors are displayed highlighted they will first be reversed tyo
their normal appearence.

After this command a call to @code{hilit} won't change anything.

@end defun

@node Examples,  , Operations, Scheme
@section Programming examples

It is useful to show some examples.  One can learn better by seeing the
effects of them.  But first define some useful functions.

@subsection Helper functions

You can find the source code in the file @file{filter.scm}.  The first
function is a filter, a function often used in functional programming
languages.  This version is designed to work with the list returned by
the here called @ref{Retrieval functions}.

@lisp
(define (filter p l)
  (if (null? l)
    ()
    (if (p (cdar l))
      (cons (caar l) (filter p (cdr l)))
      (filter p (cdr l)))))
@end lisp

With the help of the Scheme Report it should be possible to guess the
meaning of this code.  @var{p} is the predicate, used to filter out the
not wanted elements.  A possible predicate is

@lisp
(define (>0 x) (> x 0))
@end lisp

@subsection Where are resources ?

This is a possible question which might arise esp in the later game.
Often you seek oil and here is how to display the sectors in question.

@lisp
(filter >0 (resource-vec 10:40,-10:10 oil-idx))
@end lisp

This will give a list of coordinates for all sectors in the range
@code{10:40,-10:10} which have oil resources.  This list can be used to
highlight these sectors in the map.  A command sequence of general use
is

@lisp
(add-hilit (filter >0 (resource-vec 10:40,-10:10 oil-idx)))
@end lisp
