This is Info file myxec.info, produced by Makeinfo-1.55 from the input
file myxec.texinfo.

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

   Copyright (C) 1994 Ulrich Drepper.


File: myxec.info,  Node: Top,  Next: Overview,  Prev: (dir),  Up: (dir)

MyXEC User's Manual
*******************

$Revision: 1.1 $, describes Myxec-0.2

Copyright (C) 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.

* Menu:

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


File: myxec.info,  Node: Overview,  Next: The Window,  Prev: Top,  Up: Top

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 `map'.  You also almost
immediately forget all the number in the `resource' and `commodity'
tables.

   On the other hand one may have played "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.


File: myxec.info,  Node: The Window,  Next: Scheme,  Prev: Overview,  Up: Top

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.

   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.


File: myxec.info,  Node: Menue bar,  Next: Command button field,  Prev: The Window,  Up: The Window

The menue bar
=============

   (The menueline is *not* fully supported now.)

   The menue line has beside the normal entries for `File', `Option'
and `Help' one entry for `Commands' and two fields which implement no
menue.

* Menu:

* Connection Status:      ShowConnect.
* Menue entry `File':     Menue-File.
* Menue entry `Options':  Menue-Options.
* Menue entry `Commands': Menue-Commands.
* Menue entry `Help':     Menue-Help.
* Coordinate tracking:    TrackCoord.


File: myxec.info,  Node: ShowConnect,  Next: Menue-File,  Prev: Menue bar,  Up: Menue bar

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.


File: myxec.info,  Node: Menue-File,  Next: Menue-Options,  Prev: ShowConnect,  Up: Menue bar

Menueentry File
---------------

   The menue entry has two possible selections.  `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...  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.


File: myxec.info,  Node: Menue-Options,  Next: Menue-Commands,  Prev: Menue-File,  Up: Menue bar

Menueentry Options
------------------

   No options for now.


File: myxec.info,  Node: Menue-Commands,  Next: Menue-Help,  Prev: Menue-Options,  Up: Menue bar

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 *now*) commands that allow to determine the arguments in
advance.  Therefor it will not be possible to implement e.g. the
`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 `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 `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 (*Note 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 `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 `Do it' and `Close'.  Close is like the old meaning of
`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 RETURN key is an accelerator for `OK' and `Do it'
resp.  This is standard, too.  TAB is used to change the input focus.
It changes in the order top-to-down.  `Shift-TAB' changes in the
opposite order.

* Menu:

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


File: myxec.info,  Node: All,  Next: Break,  Prev: Menue-Commands,  Up: Menue-Commands

Meta-commands `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):

   * dump

   * census

   * produce

   * map

   * nation

   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.


File: myxec.info,  Node: Break,  Next: Census,  Prev: All,  Up: Menue-Commands

Empire command `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).


File: myxec.info,  Node: Census,  Next: Commodity,  Prev: Break,  Up: Menue-Commands

Empire command `census'
.......................

   After reading in the (range of) coordinates a `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.


File: myxec.info,  Node: Commodity,  Next: Deliver,  Prev: Census,  Up: Menue-Commands

Empire command `commodity'
..........................

   After reading in the (range of) coordinates a `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.


File: myxec.info,  Node: Deliver,  Next: Designate,  Prev: Commodity,  Up: Menue-Commands

Empire command `deliver'
........................

   The deliver selection offers *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 `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 `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.

   `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 `Do it' and `Close'.  You will find this
aceptable because the map area is working and you can examine the
sector as described in *Note Map area::.


File: myxec.info,  Node: Designate,  Next: Explore,  Prev: Deliver,  Up: Menue-Commands

Empire command `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 `META-X' where X is
the usual character for the designation (e.g. `*' for `air field').


File: myxec.info,  Node: Explore,  Next: Level,  Prev: Designate,  Up: Menue-Commands

Empire command `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...

   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 `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).


File: myxec.info,  Node: Level,  Next: Map,  Prev: Explore,  Up: Menue-Commands

Empire command `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.


File: myxec.info,  Node: Map,  Next: Move,  Prev: Level,  Up: Menue-Commands

Empire command `map'
....................

   This serves as a front end to the `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.


File: myxec.info,  Node: Move,  Next: Nation,  Prev: Map,  Up: Menue-Commands

Empire command `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 `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 `move'
command by clicking with `Button-1' on the destination or source
sector.  When succesful you will find the local data corrected.


File: myxec.info,  Node: Nation,  Next: Produce,  Prev: Move,  Up: Menue-Commands

Empire command `nation'
.......................

   When selecting this menue point you won't be ask about parameters.
The `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 `all'
command.


File: myxec.info,  Node: Produce,  Next: Radar,  Prev: Nation,  Up: Menue-Commands

Empire command `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
Button-1 on the map and examine the status field.


File: myxec.info,  Node: Radar,  Next: Resource,  Prev: Produce,  Up: Menue-Commands

Empire command `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 `?'
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 `unknown enemy sector'.

   This command is also send when the `all' command is selected.

   Note: units are for now *not* shown.  This information in the radar
map is ignored.


File: myxec.info,  Node: Resource,  Prev: Radar,  Up: Menue-Commands

Empire command `resource'
.........................

   The `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) `dump' contains this information, too.


File: myxec.info,  Node: Menue-Help,  Next: TrackCoord,  Prev: Menue-Commands,  Up: Menue bar

Menueentry Help
---------------

   The menu entry `Help' has some of the standard entries of the style
guide.  For now there are:

* Menu:

* Tutorial: Help-Tutorial.
* On Version: Help-OnVersion.


File: myxec.info,  Node: Help-Tutorial,  Next: Help-OnVersion,  Prev: Menue-Help,  Up: Menue-Help

Tutorial
........

   None as yet.


File: myxec.info,  Node: Help-OnVersion,  Prev: Help-Tutorial,  Up: Menue-Help

On Version
..........

   None as yet.


File: myxec.info,  Node: TrackCoord,  Prev: Menue-Help,  Up: Menue bar

Tracking map coordinates
------------------------


File: myxec.info,  Node: Command button field,  Next: Status field,  Prev: Menue bar,  Up: The Window

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.

   *If you* have suggestions for a more important collection of
commands for these button send a mail to the author.


File: myxec.info,  Node: Status field,  Next: Map area,  Prev: Command button field,  Up: The Window

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
Button-1 while on the map (see *Note 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 `<'...`>' 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.


File: myxec.info,  Node: Map area,  Next: output field,  Prev: Status field,  Up: The Window

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 `map', `explore' and `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.

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 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.


File: myxec.info,  Node: output field,  Next: SCHEME command edit field,  Prev: Map area,  Up: The Window

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 `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.


File: myxec.info,  Node: SCHEME command edit field,  Next: Status line,  Prev: output field,  Up: The Window

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 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 (*Note 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 (*Note 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.


File: myxec.info,  Node: Status line,  Prev: SCHEME command edit field,  Up: The Window

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.


File: myxec.info,  Node: Scheme,  Prev: The Window,  Up: Top

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.
*Note Introduction: (r4rs)Top.

   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...)

   The additions can categorized in some sections:

* Menu:

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


File: myxec.info,  Node: Data types,  Next: Variables,  Prev: Scheme,  Up: Scheme

Data types
==========

   There are two new data types in this Scheme implementation:

   * coordinates

   * coordinate ranges

   The syntax for coordinates is (in EBNF)

     [+-][0-9]+,[+-][0-9]+

   For ranges its only slightly more complex:

     [+-][0-9]+{:[+-][0-9]+}?,[+-][0-9]+{:[+-][0-9]+}?

   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 (*Note Map area::).

   There are two predicates for testing for these types: `coord?' and
`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 `lu-coord' and `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.)


File: myxec.info,  Node: Variables,  Next: Retrieval functions,  Prev: Data types,  Up: Scheme

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 (*Note
Status field::) and in processing the data responses.

   The second kind are simply constants.  They serve for accessing
single values inside data structures (*Note Retrieval functions::).

* Menu:

* Status variables::
* Constants::


File: myxec.info,  Node: Status variables,  Next: Constants,  Prev: Variables,  Up: Variables

Status variables
----------------

 - Variable: 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.

 - Variable: online-min
     This variable is a companion of REST-BTU.  All said there is true
     for this, too.

 - Variable: treasury
     Contains the actual value of the treasury.  Sending `nation' or
     `all' command will update the value.  It is a floating point
     variable.


File: myxec.info,  Node: Constants,  Prev: Status variables,  Up: Variables

Constants
---------

   These variables only serve as a version independent interface to
internal data structures (*Note 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:

CIV-IDX
     index for civiliance

MIL-IDX
     index for military

UW-IDX
     index for uncompensated workers

FOOD-IDX
     index for food

SHELL-IDX
     index for shells

GUN-IDX
     index for guns

PETROL-IDX
     index for petrol

IRON-IDX
     index for iron ore

DUST-IDX
     index for gold dust

BARS-IDX
     index for gold bars

BARREL-IDX
     index for barrels of produced oil

LCM-IDX
     index for light contruction material

HCM-IDX
     index for heavy construction material

RAD-IDX
     index for radioactive material

The second table displays name for resource retrieval:

MIN-IDX
     index the mineral content

GOLD-IDX
     index for gold content

OIL-IDX
     index for oil content

FERT-IDX
     index for fertility content

URAN-IDX
     index for uran content


File: myxec.info,  Node: Retrieval functions,  Next: Operations,  Prev: Variables,  Up: Scheme

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::

   All of these functions can have one or two arguments and return a
list of vectors.  *Note Vectors: (r4rs)Vectors, for details about
accessing vectors.  With two arguments it's a list of single values.


File: myxec.info,  Node: sector resources,  Next: commodity content,  Prev: Retrieval functions,  Up: Retrieval functions

Sector resources
----------------

 - Function: resource-vec COORDINATE [INDEX]
     `resource-vec' allows to observe the resources of the sector,
     specified by 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 INDEX (*Note
     Constants::).

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

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

     for the form with a single argument and

          ((0,0 . 30) (2,0 . 10) (4,0 . 0))

     for the form with a given second argument.


File: myxec.info,  Node: commodity content,  Next: Delivery paths,  Prev: sector resources,  Up: Retrieval functions

Sector content
--------------

 - Function: content-vec COORDINATE [INDEX]
     `content-vec' allows to access the amount of commodities in the
     sector specified by 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 INDEX
     (*Note Constants::).

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

          ((-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)))

     for the form with a single argument and

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

     for the form with a given second argument.


File: myxec.info,  Node: Delivery paths,  Next: Delivery cutoffs,  Prev: commodity content,  Up: Retrieval functions

Sector delivery paths
---------------------

 - Function: del-path-vec COORDINATE [INDEX]
     `del-path-vec' allows to access the delivery paths for the
     different commodities in the sector COORDINATE.  With one argument
     it returns all paths, else only the path for the commodity which is
     selected by INDEX.  Use the constants for the different
     commodities as value for INDEX (*Note Constants::).

     The path is given by a single character.  This character is a
     direction character (Y, U, G, J, N, 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 `car' of the pairs is the
     coordinate of the sector and the `cdr' is the value, i.e. the
     vector or the single value.  This may look like

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

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

     For the two argument form you get results like

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

     Note e.g. the first element of the list.  The direction is `.'.
     You should take a look in the Scheme manual how you type in
     character constants *Note Characters: (r4rs)Characters.



File: myxec.info,  Node: Delivery cutoffs,  Next: Distribution levels,  Prev: Delivery paths,  Up: Retrieval functions

Sector delivery cutoffs
-----------------------

 - Function: del-cutoff-vec COORDINATE [INDEX]
     `del-cutoff-vec' allows to access the delivery cutoffs for the
     different commodities in the sector COORDINATE.  With one argument
     it returns all paths, else only the path for the commodity which is
     selected by INDEX.  Use the constants for the different
     commodities as value for INDEX (*Note Constants::).

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

          ((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)))

     and with two arguments

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

     Tow elements of the vector are always `()' (Null), because you
     cannot deliver civilians and military.



File: myxec.info,  Node: Distribution levels,  Prev: Delivery cutoffs,  Up: Retrieval functions

Sector distribution levels
--------------------------

 - Function: dist-level-vec
     `dist-level-vec' allows to access the distribution level for the
     different commodities in the sector COORDINATE.  With one argument
     it returns all levels, else only the level for the commodity
     addressed by INDEX.  Use the constants for the different
     commodities as value for INDEX (*Note Constants::).

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

          ((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)))

     and with two arguments

          ((2,4 . 0) (0,4 . 100) (3,3 . 250) (1,3 . 0))



File: myxec.info,  Node: Operations,  Next: Examples,  Prev: Retrieval functions,  Up: Scheme

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


File: myxec.info,  Node: Empire Commands,  Next: Local Commands,  Prev: Operations,  Up: Operations

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 `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.


File: myxec.info,  Node: scheme-all,  Next: scheme-break,  Prev: Empire Commands,  Up: Empire Commands

All
...

 - Function: all [RANGE]
     This meta-command can be called with no or one argument.  With no
     argument the effect is the same as if RANGE is set to the whole
     map.

     For more details see *Note All::.



File: myxec.info,  Node: scheme-break,  Next: scheme-census,  Prev: scheme-all,  Up: Empire Commands

Break
.....

 - Function: break
     The effect is the same as empire command of the same name.  `break'
     takes no argument and only has an effect if the country isn't
     broken as yet.



File: myxec.info,  Node: scheme-census,  Next: scheme-dump,  Prev: scheme-break,  Up: Empire Commands

Census
......

 - Function: census RANGE
     The argument describes the range of sectors for which we want to
     get the actual `census' information.  These are incorporated into
     the local data base.  The user won't see any line of this.



File: myxec.info,  Node: scheme-dump,  Next: scheme-map,  Prev: scheme-census,  Up: Empire Commands

Dump
....

 - Function: dump RANGE
     The argument describes the range of sectors for which we want to
     get the actual `dump' information.  These are incorporated into
     the local data base.  The user won't see any line of this.



File: myxec.info,  Node: scheme-map,  Next: scheme-nation,  Prev: scheme-dump,  Up: Empire Commands

Map
...

 - Function: map RANGE
     The argument describes the range of sectors for which we want to
     get the actual `map' information.  These are incorporated into the
     local data base.  The user won't see any line of this.



File: myxec.info,  Node: scheme-nation,  Next: scheme-radar,  Prev: scheme-map,  Up: Empire Commands

Nation
......

 - Function: nation
     The `nation' command does not take any argument.  It updates the
     values for technology level, education etc.



File: myxec.info,  Node: scheme-radar,  Next: scheme-resource,  Prev: scheme-nation,  Up: Empire Commands

Radar
.....

 - Function: radar RANGE
     The server will send all radar images from the radar *stations* in
     the given 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.



File: myxec.info,  Node: scheme-resource,  Prev: scheme-radar,  Up: Empire Commands

resource
........

 - Function: resource RANGE
     The argument describes the range of sectors for which we want to
     get the actual `resource' information.  These are incorporated
     into the local data base.  The user won't see any line of this.



File: myxec.info,  Node: Local Commands,  Prev: Empire Commands,  Up: Operations

Local commands
--------------

   These commands fall into two categories:

   * Scheme environment manipulation

   * Empire environment manipulation

   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.


File: myxec.info,  Node: Edit,  Next: Save,  Prev: Local Commands,  Up: Local Commands

Edit Scheme closure
...................

 - Function: edit CLOSURE
     The normal way of writing Scheme code should be to use an external
     editor.  This can be loaded with the Scheme command `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 `edit'.  It's argument
     is a closure name (*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
     `Test' and the lower text field have as yet no function.  The `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 `Cancel' button is selected no evaluation takes place and
     the current content is discarded because the window is closed.



File: myxec.info,  Node: Save,  Next: Add-hilit,  Prev: Edit,  Up: Local Commands

Save Scheme closure
...................

 - Function: save FILE-NAME CLOSURE
     The CLOSURE will be saved in a pretty (means readable) format in
     the file named by the string 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.



File: myxec.info,  Node: Add-hilit,  Next: Hilit,  Prev: Save,  Up: Local Commands

`add-hilit'
...........

 - Function: add-hilit LIST-OF-RANGE ...
     The arguments of `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 *Note Examples::.



File: myxec.info,  Node: Hilit,  Next: Clear-hilit,  Prev: Add-hilit,  Up: Local Commands

`hilit'
.......

 - Function: hilit [ #T | #F ]
     If the argument is #T the actual sector selection is displayed
     highlighted.  When it is #F the highlighting is removed and the
     sectors are normally.  In any case the list of selected sectors is
     *NOT* removed.  You can enable and disable the highlighting as
     often as you like.



File: myxec.info,  Node: Clear-hilit,  Prev: Hilit,  Up: Local Commands

`clear-hilit'
.............

 - Function: 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 `hilit' won't change anything.



File: myxec.info,  Node: Examples,  Prev: Operations,  Up: Scheme

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.

Helper functions
----------------

   You can find the source code in the 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 *Note Retrieval functions::.

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

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

     (define (>0 x) (> x 0))

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.

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

   This will give a list of coordinates for all sectors in the range
`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

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



Tag Table:
Node: Top193
Node: Overview937
Node: The Window2000
Node: Menue bar3190
Node: ShowConnect3765
Node: Menue-File4385
Node: Menue-Options5206
Node: Menue-Commands5369
Node: All7678
Node: Break8804
Node: Census9243
Node: Commodity9576
Node: Deliver9920
Node: Designate11154
Node: Explore12041
Node: Level14261
Node: Map14594
Node: Move15340
Node: Nation16408
Node: Produce16827
Node: Radar17160
Node: Resource17905
Node: Menue-Help18295
Node: Help-Tutorial18591
Node: Help-OnVersion18728
Node: TrackCoord18850
Node: Command button field18975
Node: Status field19499
Node: Map area21294
Node: output field22344
Node: SCHEME command edit field23240
Node: Status line25002
Node: Scheme25423
Node: Data types26512
Node: Variables27743
Node: Status variables28274
Node: Constants28941
Node: Retrieval functions30165
Node: sector resources30831
Node: commodity content31730
Node: Delivery paths32696
Node: Delivery cutoffs34215
Node: Distribution levels35291
Node: Operations36189
Node: Empire Commands36556
Node: scheme-all37481
Node: scheme-break37813
Node: scheme-census38111
Node: scheme-dump38464
Node: scheme-map38807
Node: scheme-nation39146
Node: scheme-radar39406
Node: scheme-resource39798
Node: Local Commands40141
Node: Edit40672
Node: Save42062
Node: Add-hilit42506
Node: Hilit43010
Node: Clear-hilit43454
Node: Examples43903

End Tag Table
