git.pond.sub.org Git - empserver/blob - info/xdump.t

   1 .TH Command XDUMP
   2 .NA xdump "Extended dump of everything under the sun"
   3 .LV Expert
   4 .SY "xdump <TYPE|NUMBER> <RECORDS>"
   5 .SY "xdump meta <TYPE|NUMBER>"
   6 .SY "xdump ver"
   7 .SY "xdump meta ver"
   8 The xdump command displays information on game configuration and state
   9 in machine readable format.  It is intended for use by clients and
  10 tools.  This info page gives an overview; see doc/xdump in the source
  11 distribution for complete documentation.
  12 .s1
  13 Game configuration and state consists of a a number of tables or
  14 files.  xdump shows only things that are \fIcertainly\fP visible to
  15 you: sectors you own, ship types known, etc.
  16 .s1
  17 The output of xdump is a table consisting of a header line, the table
  18 body and a footer line.
  19 .s1
  20 The header line is of the form \*QXDUMP <TYPE> <TIMESTAMP>\*U.  <TYPE>
  21 identifies the dump.  The timestamp permits incremental dumps (see
  22 below).
  23 .s1
  24 The body consists of records; one record per line.  A record consists
  25 of fields separated by a space.  All records have the same number of
  26 fields.  Fields match records in the table's meta-table (see below).
  27 .s1
  28 A field is either in integer, floating-point number or string format.
  29 In no case does it contain space or newline.  All fields in the same
  30 column have the same format.
  31 .s1
  32 Integer fields are in decimal; they can be parsed by scanf %d.
  33 Conversely, if that succeeds and consumes the complete field, it's an
  34 integer field.
  35 .s1
  36 Floating-point fields can be parsed by scanf %g (or equivalents %e,
  37 %f).  Conversely, if that succeeds, it's a floating-point field.
  38 .s1
  39 String fields are in C syntax.  Funny characters including space,
  40 newline and double-quote are shown as octal escape sequences.  Example:
  41 "gold\\040mine".  If a field starts with a double-quote, it's a string
  42 field.
  43 .s1
  44 .L "FUTURE DIRECTIONS:"
  45 We might decide to support more C escape sequences, but never \\\(dq.
  46 .s1
  47 Some fields can contain null strings.  A null string is the three
  48 letters \*Qnil\*U.  If a field contains nil, it's a string field.
  49 .s1
  50 Each table has a meta-table, which defines format and meaning of its
  51 fields.  To show the meta-table for <TYPE>, use
  52 .EX xdump meta <TYPE>
  53 .s1
  54 All meta-tables share the same meta-meta-table, which is its own
  55 meta-table.  The command to show it is
  56 .EX xdump meta meta
  57 .s1
  58 Fields correspond to selectors used in Empire conditionals (see
  59 \*Qinfo Selector\*U), and they use the same names.  Naturally, xdump
  60 shows fields corresponding to deity-only selectors only to deities.
  61 .s1
  62 The command to display table <TYPE> is
  63 .EX xdump <TYPE> <RECORDS>
  64 .s1
  65 Argument <RECORDS> selects which records to show, in common Empire
  66 syntax for the kind of things in that table.  \*Q*\*U always shows the
  67 complete table.
  68 .s1
  69 To dump sector -22,2, for example, you can use:
  70 .EX xdump sect -22,2
  71 .s1
  72 This dumps all ships with mobility in fleet a:
  73 .EX xdump ship a ?mobil>0
  74 .s1
  75 This dumps all sectors changes after timestamp 1141068862:
  76 .EX xdump sect * ?timestamp>1141068862
  77 .s1
  78 Use this with a value one less than the timestamp in the xdump header
  79 to get everything that changed since that xdump (incremental dump).
  80 .s1
  81 .L "FUTURE DIRECTIONS:"
  82 We plan to extend the syntax to select fields to be shown.
  83 .s1
  84 The table \*Qtable\*U is the table of (non-meta-)tables.  It contains
  85 table names and numbers.  xdump accepts table numbers as well as
  86 names.
  87 .s1
  88 There's a special pseudo-table \*Qver\*U, which collects configuration
  89 parameters in a single record.  It is not listed in \*Qtable\*U, it
  90 doesn't have a table number, but it does have a meta-table.
  91 .s1
  92 .L BUGS:
  93 Still missing are game state files power, map, bmap; the list of
  94 commands; foreign levels, contact
  95 information, mortal access to sector selector
  96 mines, ship selectors xbuilt, ybuilt, trade selectors xloc, yloc,
  97 commodity selectors xbuy, ybuy, xsell, ysell.  Some information is not
  98 yet available in human-readable form: the lost file, sect-chr selector
  99 nav, ship and land plague status (deity only), plane theta (governs
 100 satellite movement), trade selectors xloc, yloc, commodity selectors
 101 xbuy, ybuy.
 102 .s1
 103 .L "FUTURE DIRECTIONS:"
 104 xdump is still fairly new, and experience with it may lead to changes.
 105 Client writers should be prepared for that.
 106 .s1
 107 .SA "dump, ldump, ndump, pdump, sdump, lost, show, version, Clients, Communication, LandUnits, Planes, Sectors, Ships"