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