empire/empserver
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update to current command syntax, cover meta. Refer to doc/xdump (to

Browse source 
be written).  Less detail on output.  Document current shortcomings.
This commit is contained in:
Markus Armbruster 2006-02-27 20:58:26 +00:00
parent 433bcb0d19
commit c9d883e78b
1 changed files with 81 additions and 91 deletions
Download patch file Download diff file Expand all files Collapse all files

172
info/xdump.t
View file

@ -1,117 +1,107 @@
.TH Command XDUMP
.NA xdump "Experimental dump of everything under the sun"
.NA xdump "Extended dump of everything under the sun"
.LV Expert
.SY "xdump <STATE-TABLE> <ENTRIES>"
.SY "xdump chr <CONFIG-TABLE>"
.SY "xdump <TYPE|NUMBER> <RECORDS>"
.SY "xdump meta <TYPE|NUMBER>"
.SY "xdump ver"
.SY "xdump meta ver"
The xdump command displays information on game configuration and state
in machine readable tables. It is intended for use by clients and
tools.
in machine readable format. It is intended for use by clients and
tools. This info page explains little more than command syntax; see
doc/xdump in the source distribution for complete documentation.
.s1
.L NOTE
This command is \fIexperimental\fP and thus only available if option
GUINEA_PIGS is enabled. It may still change in incompatible ways. It
is released in this early stage of development to show were we are
headed, and to solicit feedback.
Game configuration and state consists of a a number of tables or
files. xdump shows only things that are \fIcertainly\fP visible to
you: sectors you own, ship types known, etc.
.s1
The <STATE-TABLE> argument in
.SY "xdump <STATE-TABLE> <ENTRIES>"
is one of the following game state table names: sect (sectors), ship,
plane, land, nuke, news, treaty, trade, pow (power report), loan,
commodity (commodity market), lost (recently lost items). Tables
power and nat do not work, yet. Unique abbreviations of table names
are recognized.
The output of xdump is a table consisting of a header line, the table
body and a footer line.
.s1
The <ENTRIES> argument selects table entries to display, in common
Empire syntax for the kind of things in this table.
\" FIXME reference
For example, to dumps all sectors in realm #5, you can use:
.EX xdump sect 0,0
.NF
XDUMP sect 1103018538
owner xloc yloc des effic mobil terr terr1 terr2 terr3 xdist ydist avail work newdes min gold fert ocontent uran oldown off civil milit shell gun petrol iron dust bar food oil lcm hcm uw rad c_dist m_dist s_dist g_dist p_dist i_dist d_dist b_dist f_dist o_dist l_dist h_dist u_dist r_dist c_del m_del s_del g_del p_del i_del d_del b_del f_del o_del l_del h_del u_del r_del fallout access road rail dfense
1 0 0 5 100 127 0 0 0 0 8 0 6440 100 5 77 0 0 0 42 1 0 9900 1 0 0 0 0 1 0 50 0 0 0 0 0 0 0 0 0 0 0 1 0 50 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1078505792 0 0 99
dumped 1
.FI
This dumps all ships with mobility in fleet a:
.EX xdump ship a ?mobil>0
The header line is of the form \*QXDUMP <TYPE> <TIMESTAMP>\*U. <TYPE>
identifies the dump. The timestamp permits incremental dumps (see
below).
.s1
This dumps all loans:
.EX xdump loan *
.s1
For tables of things that have an owner (sect, ship, plane, land,
nuke), \*Qxdump\*U shows only things you own, unless you are a deity.
.s1
Table columns correspond to selectors used in Empire conditionals (see
\*Qinfo Selector\*U). Naturally, \*Qxdump\*U shows columns
corresponding to selectors that only deities may access only to
deities.
.s1
.L "FUTURE DIRECTIONS"
We plan to extend the syntax to select columns to be shown.
.s1
The <CONFIG-TABLE> argument in
.SY "xdump chr <CONFIG-TABLE>"
is one of the following game configuration table names: sect (sector
characteristics), ship, plane, land, nuke, news, treaty, item,
infrastructure, product. Table news does not work, yet. Unique
abbreviations of table names are recognized.
.s1
.L "FUTURE DIRECTIONS"
We plan to extend the syntax to select rows and columns to be shown.
.s1
Finally,
.SY "xdump ver"
displays configuration parameters.
.s1
The output of \*Qxdump\*U is a table, which consists of two header
lines, the table body and a footer line.
.s1
The first header line is of the form \*QXDUMP <TABLE-NAME>
<TIMESTAMP>\*U. It identifies the dump.
.s1
The second header line lists column names. The name of a column is
the name of the corresponding selector. If a name is followed by a
decimal number, it applies to that many columns, which form an array.
.s1
The body consists of records; one record per line.
.s1
A record consists of fields separated by a space. All records have
the same number of fields, which matches the header.
The body consists of records; one record per line. A record consists
of fields separated by a space. All records have the same number of
fields. Fields match records in the table's meta-table (see below).
.s1
A field is either in integer, floating-point number or string format.
In no case does it contain space or newline. All fields in the same
column have the same format.
.s1
Integer fields are in decimal; they can be parsed by scanf %d.
Conversely, if that succeeds, it's an integer field.
Conversely, if that succeeds and consumes the complete field, it's an
integer field.
.s1
Floating-point fields can be parsed by scanf %g (or equivalents %e,
%f). Conversely, if that succeeds, it's a floating-point field.
.s1
String fields are in C syntax. Funny characters including space,
newline and doublequote are shown as octal escape sequences. Example:
newline and double-quote are shown as octal escape sequences. Example:
"gold\\040mine". If a field starts with a double-quote, it's a string
field. Here's a scanf format string: "\\"%[^\\"]\\"". You have to
postprocess the value to translate escapes.
field.
.s1
.L "FUTURE DIRECTIONS"
We might decide to use simple escape sequences as well, but never \\".
.L "FUTURE DIRECTIONS:"
We might decide to support more C escape sequences, but never \\".
.s1
Some columns can contain null strings. A null string is the three
letters nil. If a field contains nil, it's a string field.
Some fields can contain null strings. A null string is the three
letters \*Qnil\*U. If a field contains nil, it's a string field.
.s1
If you know all the fields and their format, and none of them can be a
null string, you can parse a complete record with a single scanf. The
null string exception is unfortunate.
Each table has a meta-table, which defines format and meaning of its
fields. To show the meta-table for <TYPE>, use
.EX xdump meta <TYPE>
.s1
If you don't know field formats, you can still parse field by field.
All meta-tables share the same meta-meta-table, which is its own
meta-table. The command to show it is
.EX xdump meta meta
.s1
.L "FUTURE DIRECTIONS"
We plan to add meta-dumps describing the dumps. Without such
meta-data, tools have to know the server's internal coding of various
.L BUGS
\*Qxdump\*U discloses all units, regardless of player's tech level.
\*Qxdump\*U fails to suppress empty rows in some tables.
Fields correspond to selectors used in Empire conditionals (see
\*Qinfo Selector\*U), and they use the same names. Naturally, xdump
shows fields corresponding to deity-only selectors only to deities.
.s1
.SA "dump, ldump, ndump, pdump, sdump, lost, Clients, Communication, LandUnits, Planes, Sectors, Ships"
The command to display table <TYPE> is
.EX xdump <TYPE> <RECORDS>
.s1
Argument <RECORDS> selects which records to show, in common Empire
syntax for the kind of things in that table. \*Q*\*U always shows the
complete table.
.s1
To dump sector -22,2, for example, you can use:
.EX xdump sect -22,2
.s1
This dumps all ships with mobility in fleet a:
.EX xdump ship a ?mobil>0
.s1
This dumps all sectors changes after timestamp 1141068862:
.EX xdump sect * ?timestamp>1141068862
.s1
Use this with a value one less than the timestamp in the xdump header
to get everything that changed since that xdump (incremental dump).
.s1
.L "FUTURE DIRECTIONS:"
We plan to extend the syntax to select fields to be shown.
.s1
The table \*Qtable\*U is the table of (non-meta-)tables. It contains
table names and numbers. xdump accepts table numbers as well as
names.
.s1
There's a special pseudo-table \*Qver\*U, which collects configuration
parameters in a single record. It is not listed in \*Qtable\*U, it
doesn't have a table number, but it does have a meta-table.
.s1
.L BUGS:
Still missing are game state files power, map, bmap; the list of
commands; foreign relations and levels, contact and reject
information, budget priorities; mortal access to sector selector
mines, ship selectors xbuilt, ybuilt, trade selectors xloc, yloc,
commodity selectors xbuy, ybuy, xsell, ysell. Some information is not
yet available in human-readable form: the lost file, sect-chr selector
nav, ship and land plague status (deity only), plane theta (governs
satellite movement), trade selectors xloc, yloc, commodity selectors
xbuy, ybuy.
.s1
.L "FUTURE DIRECTIONS:"
xdump is still fairly new, and experience with it may lead to changes.
Client writers should be prepared for that.
.s1
.SA "dump, ldump, ndump, pdump, sdump, lost, show, version, Clients, Communication, LandUnits, Planes, Sectors, Ships"