retreat lretreat: Change query syntax to match mission

Optional arguments can save typing.  Mandatory arguments are more
easily discoverable: just run the command and answer its prompts.
Empire traditionally uses optional arguments only for expert features.
Consider mission:

    [0:640] Command : mission
    Ship, plane or land unit (p,sh,la)? s
    ship(s)? 0
    Mission (int, sup, osup, dsup, esc, res, air, query, clear)? int
    operations point? .
    frg  frigate Early Bird(#0) on an interdiction mission, centered on 21,-3, radius 0
    1 ship

Compare retreat:

    [0:638] Command : retreat
    ship(s)? 0
    shp#     ship type       x,y   fl path       as flt?  flags
       0 frg  frigate       21,-3
    1 ship

Arguments are not discoverable this way.

Change retreat to work like mission: make the second argument
mandatory, and if it's 'q', show retreat orders, else treat it as path
and ask for conditions:

    [0:637] Command : retreat
    ship(s)? 0
    Retreat path, or q to query? jj
    Retreat conditions ('?' to list available ones)? i
    shp#     ship type       x,y   fl path       as flt?  flags
       0 frg  frigate       21,-3     jj                  i
    1 ship

To reduce smart client and script breakage, keep retreat with one
argument working as before, but print a deprecation warning.

Signed-off-by: Markus Armbruster <armbru@pond.sub.org>

diff --git a/info/lretreat.t b/info/lretreat.t
index 28743fece5e5ebb77502a3dc0191f4beae251392..8037f5df39396f2917ba673b1cd2e1529e72536b 100644 (file)
--- a/info/lretreat.t
+++ b/info/lretreat.t
@@ -1,7 +1,8 @@
 .TH Command LRETREAT
 .NA lretreat "Set retreat conditions/paths for units or armies"
 .LV Expert
-.SY "lretreat <UNIT/ARMY> [<PATH> <CONDITIONS>]"
+.SY "lretreat <UNIT/ARMY> <PATH> <CONDITIONS>"
+.SY "lretreat <UNIT/ARMY> q"
 The lretreat command allows you to examine or modify the retreat
 paths and conditions of your land units.
 .s1
@@ -9,7 +10,8 @@ The first argument selects land units to view or give orders for.
 If an army designation is given when specifying orders, the orders
 apply to all members of that army.
 .s1
-Without further arguments, current retreat orders are shown.
+With 'q' instead of a retreat path, the current retreat paths and
+conditions will be listed.
 The report format contains the following fields:
 .s1
 .in \w'unit type\0\0'u
@@ -30,15 +32,13 @@ what conditions will trigger retreat.
 .in
 .s1
 For example:
-.EX lretreat *
+.EX lretreat * q
 .NF
 lnd#     unit type       x,y   ar path       as army? flags
    0 cav  cavalry        2,0      jjuuj               I
 1 unit
 .FI
 .s1
-.L Overview
-.s1
 A player may give retreat orders for a land unit or an army.  Retreat
 orders include a set of conditions that determine when the army/unit
 will retreat, and a path that the army/unit will follow.  When a condition

diff --git a/info/retreat.t b/info/retreat.t
index 5ded60683cc45c8b240a0abea1f28579b3ca9e49..a445aa99d1dacb9549cbd49dc5f9c3cee96a9feb 100644 (file)
--- a/info/retreat.t
+++ b/info/retreat.t
@@ -1,7 +1,8 @@
 .TH Command RETREAT
 .NA retreat "Set retreat conditions/paths for ships or fleets"
 .LV Expert
-.SY "retreat <SHIP/FLEET> [<PATH> <CONDITIONS>]"
+.SY "retreat <SHIP/FLEET> <PATH> <CONDITIONS>"
+.SY "retreat <SHIP/FLEET> q"
 The retreat command allows you to examine or modify the retreat
 paths and conditions of your ships.
 .s1
@@ -9,7 +10,8 @@ The first argument selects ships to view or give orders for.
 If a fleet designation is given when specifying orders, the orders
 apply to all members of that fleet.
 .s1
-Without further arguments, current retreat orders are shown.
+With 'q' instead of a retreat path, the current retreat paths and
+conditions will be listed.
 The report format contains the following fields:
 .s1
 .in \w'ship type\0\0'u
@@ -30,15 +32,13 @@ what conditions will trigger retreat.
 .in
 .s1
 For example:
-.EX retreat *
+.EX retreat * q
 .NF
 shp#     ship type       x,y   fl path       as flt?  flags
    0 bb   battleship     2,0      jjuuj               i
 1 ship
 .FI
 .s1
-.L Overview
-.s1
 A player may give retreat orders for a ship or a fleet. Retreat
 orders include a set of conditions that determine when the fleet/ship
 will retreat, and a path that the fleet/ship will follow. When a condition

diff --git a/src/lib/commands/retr.c b/src/lib/commands/retr.c
index 0b08a7454de14ad8eddd7b69621d3c51bf06e3c6..0a81581f5bfffa66cb71326babbeff48f763a681 100644 (file)
--- a/src/lib/commands/retr.c
+++ b/src/lib/commands/retr.c
@@ -84,10 +84,27 @@ retreat(int type)
     if (!snxtitem(&ni, type, player->argp[1], NULL))
        return RET_SYN;
     nunits = 0;
-    if (player->argp[2] != NULL) {
-       pq = getstarg(player->argp[2], "Retreat path? ", buf1);
-       if (!pq)
+
+    if (player->argp[1] && !player->argp[2]) {
+       pr("Omitting the second argument is deprecated and will cease to work in a\n"
+          "future release.  Please use '%s q' to query retreat orders.\n\n",
+          player->combuf);
+       pq = "q";
+    } else {
+       /*
+        * TODO getpath() or similar would be nice once the deprecated
+        * syntax is gone.
+        */
+       pq = getstarg(player->argp[2], "Retreat path, or q to query? ",
+                     buf1);
+       if (!pq || !*pq)
            return RET_SYN;
+    }
+
+    rflags = 0;
+    if (*pq == 'q') {
+       pq = NULL;
+    } else {
        for (i = 0; i < RET_LEN - 1 && pq[i]; i++) {
            if (chkdir(pq[i], DIR_STOP, DIR_LAST) < 0) {
                pr("'%c' is not a valid direction...\n", pq[i]);
@@ -97,11 +114,7 @@ retreat(int type)
        }
        for (i--; i >= 0 && pq[i] == dirch[DIR_STOP]; i--)
            pq[i] = 0;
-    } else
-       pq = NULL;
 
-    rflags = 0;
-    if (pq != NULL) {
     again:
        fl = getstarg(player->argp[3],
                      "Retreat conditions ('?' to list available ones)? ",

diff --git a/src/lib/player/empmod.c b/src/lib/player/empmod.c
index 4405be03984ed0f681df67b04c0903d06f9a08de..0e6c4d0b7bb71113eb2ff66bf180bf31e99b8700 100644 (file)
--- a/src/lib/player/empmod.c
+++ b/src/lib/player/empmod.c
@@ -32,7 +32,7 @@
  *     Thomas Ruschak, 1992
  *     Ken Stevens, 1995
  *     Steve McClure, 1996-2000
- *     Markus Armbruster, 2004-2014
+ *     Markus Armbruster, 2004-2015
  */
 
 /*
@@ -144,7 +144,7 @@ struct cmndstr player_coms[] = {
     {"lookout <SHIPS>", 1, look, 0, NORM + CAP},
     {"lost", 0, lost, 0, NORM},
     {"lradar <UNITS | SECTS>", 1, lrad, C_MOD, NORM + CAP},
-    {"lretreat <UNITS|ARMY> [<PATH> <i|h|b|c>]",
+    {"lretreat <UNITS|ARMY> [q | <PATH> <i|h|b|c>]",
      1, lretr, C_MOD, NORM + CAP},
     {"lstat <UNITS>", 0, lsta, 0, NORM},
     {"ltend <COMM> <tender-SHIPS> <NUM> <UNITS>",
@@ -205,7 +205,7 @@ struct cmndstr player_coms[] = {
     {"report <NATS>", 0, repo, 0, 0},
     {"reset <lot #> <0|price>", 1, rese, C_MOD, NORM + CAP},
     {"resource <SECTS>", 0, reso, 0, NONVIS},
-    {"retreat <SHIPS|FLEET> [<PATH> <i|t|s|h|b|d|u|c>]",
+    {"retreat <SHIPS|FLEET> [q | <PATH> <i|t|s|h|b|d|u|c>]",
      1, retr, C_MOD, NORM + CAP},
     {"route <COMM> <SECTS>", 1, rout, C_MOD, NORM},
     {"sabotage <UNITS>", 1, sabo, C_MOD, NORM + MONEY + CAP},

diff --git a/tests/navi-march/journal.log b/tests/navi-march/journal.log
index a3d51cfbeb1956bae4272d95ead11b19756105ef..27bafa4dc3e7ed6a5cc6ebb480ff49d8aada9d2c 100644 (file)
--- a/tests/navi-march/journal.log
+++ b/tests/navi-march/journal.log
@@ -1491,6 +1491,9 @@
     Play#0 output Play#0 6 0 640
     Play#0 input retr * ?rflags#0
     Play#0 command retreat
+    Play#0 output Play#0 1 Omitting the second argument is deprecated and will cease to work in a
+    Play#0 output Play#0 1 future release.  Please use 'retr * ?rflags#0 q' to query retreat orders.
+    Play#0 output Play#0 1
     Play#0 output Play#0 1 own shp#     ship type       x,y   fl path       as flt?  flags
     Play#0 output Play#0 1   1    4 oe   oil explora    1,1      hhhhn               b
     Play#0 output Play#0 1   2   11 pt   patrol boat    0,0      hhhhn               b
@@ -1598,6 +1601,9 @@
     Play#0 output Play#0 6 0 637
     Play#0 input lret * ?rflags#0
     Play#0 command lretreat
+    Play#0 output Play#0 1 Omitting the second argument is deprecated and will cease to work in a
+    Play#0 output Play#0 1 future release.  Please use 'lret * ?rflags#0 q' to query retreat orders.
+    Play#0 output Play#0 1
     Play#0 output Play#0 1 own lnd#     unit type       x,y   ar path       as army? flags
     Play#0 output Play#0 1   1    1 tra  train          1,1      hhhhn               b
     Play#0 output Play#0 1   1    4 eng  engineer       1,1      hhhhn               b

diff --git a/tests/retreat/01-retreat-1 b/tests/retreat/01-retreat-1
index bf596b0dbf55ed062ede9cfc4e318f82f4605461..c48cd69e28cdb6e1144e27589093a5001486e437 100644 (file)
--- a/tests/retreat/01-retreat-1
+++ b/tests/retreat/01-retreat-1
@@ -18,6 +18,7 @@ __cmd added 1 0 0
 | show retreat orders
 retr
 0/1/2/3/4/7
+q
 || lretreat command
 | garbage path
 lret 0 garbage i
@@ -37,6 +38,7 @@ __cmd added 1 0 0
 | show retreat orders
 lret
 0/1/2/3/4/7
+q
 ||| Ships
 || ships failing to retreat
 | sunk

diff --git a/tests/retreat/journal.log b/tests/retreat/journal.log
index f5b9e07632c98c78fc6abf2e363bd2386297cc60..dfd7a8aff7327605b5b8596d56affc5da08b314c 100644 (file)
--- a/tests/retreat/journal.log
+++ b/tests/retreat/journal.log
@@ -27,7 +27,7 @@
     Play#1 output Play#1 1  y u
     Play#1 output Play#1 1 g   j
     Play#1 output Play#1 1  b n
-    Play#1 output Play#1 1 Usage: retreat <SHIPS|FLEET> [<PATH> <i|t|s|h|b|d|u|c>]
+    Play#1 output Play#1 1 Usage: retreat <SHIPS|FLEET> [q | <PATH> <i|t|s|h|b|d|u|c>]
     Play#1 output Play#1 6 0 640
     Play#1 input __cmd added 0 -1 0
     Play#1 command __cmd
@@ -47,7 +47,7 @@
     Play#1 output Play#1 4 Retreat conditions ('?' to list available ones)?
     Play#1 input junk
     Play#1 output Play#1 1 Bad retreat condition 'j'
-    Play#1 output Play#1 1 Usage: retreat <SHIPS|FLEET> [<PATH> <i|t|s|h|b|d|u|c>]
+    Play#1 output Play#1 1 Usage: retreat <SHIPS|FLEET> [q | <PATH> <i|t|s|h|b|d|u|c>]
     Play#1 output Play#1 6 0 639
     Play#1 input retr 2/3 bgyujnbgyujnbgyujn itshbdu
     Play#1 command retreat
@@ -79,6 +79,8 @@
     Play#1 command retreat
     Play#1 output Play#1 4 ship(s)?
     Play#1 input 0/1/2/3/4/7
+    Play#1 output Play#1 4 Retreat path, or q to query?
+    Play#1 input q
     Play#1 output Play#1 1 shp#     ship type       x,y   fl path       as flt?  flags
     Play#1 output Play#1 1    0 lc   light cruis   -3,1    a
     Play#1 output Play#1 1    1 lc   light cruis   -3,1    a
@@ -95,7 +97,7 @@
     Play#1 output Play#1 1  y u
     Play#1 output Play#1 1 g   j
     Play#1 output Play#1 1  b n
-    Play#1 output Play#1 1 Usage: lretreat <UNITS|ARMY> [<PATH> <i|h|b|c>]
+    Play#1 output Play#1 1 Usage: lretreat <UNITS|ARMY> [q | <PATH> <i|h|b|c>]
     Play#1 output Play#1 6 0 635
     Play#1 input __cmd added 0 -1 0
     Play#1 command __cmd
@@ -111,7 +113,7 @@
     Play#1 output Play#1 4 Retreat conditions ('?' to list available ones)?
     Play#1 input junk
     Play#1 output Play#1 1 Bad retreat condition 'j'
-    Play#1 output Play#1 1 Usage: lretreat <UNITS|ARMY> [<PATH> <i|h|b|c>]
+    Play#1 output Play#1 1 Usage: lretreat <UNITS|ARMY> [q | <PATH> <i|h|b|c>]
     Play#1 output Play#1 6 0 634
     Play#1 input lret 2/3 yujnbgyujnbgyujnbg ihb
     Play#1 command lretreat
@@ -143,6 +145,8 @@
     Play#1 command lretreat
     Play#1 output Play#1 4 land(s)?
     Play#1 input 0/1/2/3/4/7
+    Play#1 output Play#1 4 Retreat path, or q to query?
+    Play#1 input q
     Play#1 output Play#1 1 lnd#     unit type       x,y   ar path       as army? flags
     Play#1 output Play#1 1    0 inf  infantry      -3,1    a
     Play#1 output Play#1 1    1 inf  infantry      -3,1    a
@@ -1596,6 +1600,9 @@
     Play#0 output Play#0 6 0 640
     Play#0 input retr * ?rflags#0
     Play#0 command retreat
+    Play#0 output Play#0 1 Omitting the second argument is deprecated and will cease to work in a
+    Play#0 output Play#0 1 future release.  Please use 'retr * ?rflags#0 q' to query retreat orders.
+    Play#0 output Play#0 1
     Play#0 output Play#0 1 own shp#     ship type       x,y   fl path       as flt?  flags
     Play#0 output Play#0 1   1    2 lc   light cruis   -3,1      bgyujnbgy           itshbdu
     Play#0 output Play#0 1   1    4 lc   light cruis   -5,1    a b          Yes      h
@@ -1697,6 +1704,9 @@
     Play#0 output Play#0 6 0 637
     Play#0 input lretr * ?rflags#0
     Play#0 command lretreat
+    Play#0 output Play#0 1 Omitting the second argument is deprecated and will cease to work in a
+    Play#0 output Play#0 1 future release.  Please use 'lretr * ?rflags#0 q' to query retreat orders.
+    Play#0 output Play#0 1
     Play#0 output Play#0 1 own lnd#     unit type       x,y   ar path       as army? flags
     Play#0 output Play#0 1   1    2 inf  infantry      -3,1      yujnbgyuj           ihb
     Play#0 output Play#0 1   1    4 inf  infantry      -4,0    a b          Yes      h