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>

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

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

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 (player->argp[1] && !player->argp[2]) {
-	if (!pq)
+	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)? ",

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},

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

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

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