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

   1 .TH Command XDUMP
   2 .NA xdump "Experimental dump of everything under the sun"
   3 .LV Expert
   4 .SY "xdump <STATE-TABLE> <ENTRIES>"
   5 .SY "xdump chr <CONFIG-TABLE>"
   6 .SY "xdump opt"
   7 .SY "xdump ver"
   8 The xdump command displays information on game configuration and state
   9 in machine readable tables.  It is intended for use by clients and
  10 tools.
  11 .s1
  12 .L NOTE
  13 This command is \fIexperimental\fP and thus only available if option
  14 GUINEA_PIGS is enabled.  It may still change in incompatible ways.  It
  15 is released in this early stage of development to show were we are
  16 headed, and to solicit feedback.
  17 .s1
  18 The <STATE-TABLE> argument in
  19 .SY "xdump <STATE-TABLE> <ENTRIES>"
  20 is one of the following game state table names: sect (sectors), ship,
  21 plane, land, nuke, news, treaty, trade, pow (power report), loan,
  22 commodity (commodity market), lost (recently lost items).  Tables
  23 power and nat do not work, yet.  Unique abbreviations of table names
  24 are recognized.
  25 .s1
  26 The <ENTRIES> argument selects table entries to display, in common
  27 Empire syntax for the kind of things in this table.
  28 \" FIXME reference
  29 For example, to dumps all sectors in realm #5, you can use:
  30 .EX xdump sect 0,0
  31 .NF
  32 XDUMP sect 1103018538
  33 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
  34 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
  35 dumped 1
  36 .FI
  37 This dumps all ships with mobility in fleet a:
  38 .EX xdump ship a ?mobil>0
  39 .s1
  40 This dumps all loans:
  41 .EX xdump loan *
  42 .s1
  43 For tables of things that have an owner (sect, ship, plane, land,
  44 nuke), \*Qxdump\*U shows only things you own, unless you are a deity.
  45 .s1
  46 Table columns correspond to selectors used in Empire conditionals (see
  47 \*Qinfo Selector\*U).  Naturally, \*Qxdump\*U shows columns
  48 corresponding to selectors that only deities may access only to
  49 deities.
  50 .s1
  51 .L "FUTURE DIRECTIONS"
  52 We plan to extend the syntax to select columns to be shown.
  53 .s1
  54 The <CONFIG-TABLE> argument in
  55 .SY "xdump chr <CONFIG-TABLE>"
  56 is one of the following game configuration table names: sect (sector
  57 characteristics), ship, plane, land, nuke, news, treaty, item,
  58 infrastructure, product.  Table news does not work, yet.  Unique
  59 abbreviations of table names are recognized.
  60 .s1
  61 .L "FUTURE DIRECTIONS"
  62 We plan to extend the syntax to select rows and columns to be shown.
  63 .s1
  64 Finally,
  65 .SY "xdump opt"
  66 displays game options, and
  67 .SY "xdump ver"
  68 displays configuration parameters.
  69 .s1
  70 The output of \*Qxdump\*U is a table, which consists of two header
  71 lines, the table body and a footer line.
  72 .s1
  73 The first header line is of the form \Q*XDUMP <TABLE-NAME>
  74 <TIMESTAMP>\*U.  It identifies the dump.
  75 .s1
  76 The second header line lists column names.  The name of a column is
  77 the name of the corresponding selector.  If a name is followed by a
  78 decimal number, it applies to that many columns, which form an array.
  79 .s1
  80 The body consists of records; one record per line.
  81 .s1
  82 A record consists of fields separated by a space.  All records have
  83 the same number of fields, which matches the header.
  84 .s1
  85 A field is either in integer, floating-point number or string format.
  86 In no case does it contain space or newline.  All fields in the same
  87 column have the same format.
  88 .s1
  89 Integer fields are in decimal; they can be parsed by scanf %d.
  90 Conversely, if that succeeds, it's an integer field.
  91 .s1
  92 Floating-point fields can be parsed by scanf %g (or equivalents %e,
  93 %f).  Conversely, if that succeeds, it's a floating-point field.
  94 .s1
  95 String fields are in C syntax.  Funny characters including space,
  96 newline and doublequote are shown as octal escape sequences.  Example:
  97 "gold\\040mine".  If a field starts with a double-quote, it's a string
  98 field.  Here's a scanf format string: "\\"%[^\\"]\\"".  You have to
  99 postprocess the value to translate escapes.
 100 .s1
 101 .L "FUTURE DIRECTIONS"
 102 We might decide to use simple escape sequences as well, but never \\".
 103 .s1
 104 Some columns can contain null strings.  A null string is the three
 105 letters nil.  If a field contains nil, it's a string field.
 106 .s1
 107 If you know all the fields and their format, and none of them can be a
 108 null string, you can parse a complete record with a single scanf.  The
 109 null string exception is unfortunate.
 110 .s1
 111 If you don't know field formats, you can still parse field by field.
 112 .s1
 113 .L "FUTURE DIRECTIONS"
 114 We plan to add meta-dumps describing the dumps.  Without such
 115 meta-data, tools have to know the server's internal coding of various
 116 .L BUGS
 117 \*Qxdump\*U discloses all units, regardless of player's tech level.
 118 \*Qxdump\*U fails to suppress empty rows in some tables.
 119 .s1
 120 .SA "dump, ldump, ndump, pdump, sdump, lost, Clients, Communication, LandUnits, Planes, Sectors, Ships"