altmeta Alt key hack, mainly for unix (trunk only)

     Some time ago we received a patch submission which attempted to
handle the Alt key for terminals or emulators which transmit two char
sequence "ESC c" when Alt+c is pressed, but I can't find it.  I don't
remember the details but recall that it had at least once significant
problem (perhaps just that it was unconditional, although it may have
been implemented in a way which interferred with using ESC to cancel).

     This patch reimplements the desired fix, making the new behavior be
conditional on a boolean option:  altmeta.  That option already exists
for the Amiga port, where it deals with low-level keyboard handling but
essentially affects the same thing:  whether Alt+key can be used as a
shortcut for various extended commands.  This one affects how the core
processes commands, and is only available if ALTMETA is defined at
compile time.  I've defined that for Unix and VMS; other ports don't
seem to need it.  (I'm not sure whether "options" created by makedefs
ought to mention it.  So far, it doesn't since this isn't something
users are expected to tweak.  The setting of the non-Amiga altmeta
option doesn't get saved and restored, so won't affect saved data if
someone does toggle ALTMETA and then rebuild.)

     When [non-Amiga] altmeta is set, nethack's core will give special
handling to ESC, but only during top level command processing.  If ESC
is seen while reading a command, it will be consumed and then the next
character seen will have its meta bit set.  This introduces a potential
problem:  typing ESC as a command will result in waiting for another
character instead of reporting that that isn't a valid command.  Since it
isn't a valid command, this shouldn't be a big deal, but starting a count
intended to prefix your next command and then typing ESC after deciding
to abort that count runs into the same situation:  nethack will wait for
another character to complete the two character sequence expected for
"ESC c".  There's not much that can be done with this, other than have
the Guidebook mention that an extra ESC is needed to cancel the pending
count, because digits followed by ESC could actually be a numeric prefix
for Alt+something rather than an attempt to abort the count.

dat/opthelp

@@ -77,6 +77,12 @@ timed_delay    on unix and VMS, use a timer instead of sending
                display effect.  on MSDOS without the termcap
                lib, whether or not to pause for visual effect.    [TRUE]
 
+Boolean option for Amiga, or for others if ALTMETA was set at compile time:
+altmeta        For Amiga, treat Alt+key as Meta+key.              [TRUE]
+altmeta        For unix and VMS, treat two character sequence
+               "ESC c" as M-c (Meta+c, 8th bit set) when nethack
+               obtains a command from player's keyboard.          [FALSE]
+
 Boolean option if USE_TILES was set at compile time (MSDOS protected mode only):
 preload_tiles  control whether tiles get pre-loaded into RAM at the
                start of the game.  Doing so enhances performance

doc/Guidebook.mn

@@ -5,7 +5,7 @@
 .ds vr "NetHack 3.5
 .ds f0 "\*(vr
 .ds f1
-.ds f2 "March 5, 2011
+.ds f2 "April 17, 2011
 .mt
 A Guide to the Mazes of Menace
 (Guidebook for NetHack)
@@ -839,11 +839,16 @@ If your keyboard has a meta key (which, when pressed in combination
 with another key, modifies it by setting the `meta' [8th, or `high']
 bit), you can invoke many extended commands by meta-ing the first
 letter of the command.
-.\" In {\it NT, OS/2, PC\/ {\rm and} ST NetHack},
-.\" the `Alt' key can be used in this fashion;
-.\" on the Amiga set the {\it altmeta\/} option to get this behavior.
-In NT, OS/2, and PC NetHack, the `Alt' key
-can be used in this fashion.
+In \fINT\fP, \fIOS/2\fP, \fIPC\fP and \fIST\fP \fINetHack\fP,
+the `Alt' key can be used in this fashion;
+on the \fIAmiga\fP, set the
+.op altmeta
+option to get this behavior.
+On other systems, if typing `Alt' plus another key transmits a
+two character sequence consisting of an \fBEscape\fP
+followed by the other key, you may set the
+.op altmeta
+option to have nethack combine them into meta+key.
 .lp M-?
 #? (not supported by all platforms)
 .lp M-2
@@ -2398,7 +2403,21 @@ The name of the handler is specified without the .dll extension and without any
 path information.
 Cannot be set with the `O' command.
 .lp altmeta
-(default on, AMIGA NetHack only).
+On Amiga, this option controls whether typing `Alt' plus another key
+functions as a meta-shift for that key (default on).
+.lp altmeta
+On other (non-Amiga) systems where this option is available, it can be
+set to tell nethack to convert a two character sequence beginning with
+ESC into a meta-shifted version of the second character (default off).
+.lp ""
+This conversion is only done for commands, not for other input prompts.
+Note that typing one or more digits as a count prefix prior to a
+command--preceded by \fBn\fP if the
+.op number_pad
+option is set--is also subject to this conversion, so attempting to
+abort the count by typing ESC will leave nethack waiting for another
+character to complete the two character sequence.  Type a second ESC to
+finish cancelling such a count.  At other prompts a single ESC suffices.
 .lp "BIOS    "
 Use BIOS calls to update the screen
 display quickly and to read the keyboard (allowing the use of arrow

doc/Guidebook.tex

@@ -33,7 +33,7 @@
 \begin{document}
 %
 % input file: guidebook.mn
-% $Revision: 1.111 $ $Date: 2011/03/05 10:09:47 $
+% $Revision: 1.112 $ $Date: 2011/03/09 02:30:24 $
 %
 %.ds h0 "
 %.ds h1 %.ds h2 \%
@@ -46,7 +46,7 @@
 %.au
 \author{Eric S. Raymond\\
 (Extensively edited and expanded for 3.5)}
-\date{March 5, 2011}
+\date{April 17, 2011}
 
 \maketitle
 
@@ -1083,11 +1083,13 @@ \section{Commands}
 with another key, modifies it by setting the `meta' [8th, or `high']
 bit), you can invoke many extended commands by meta-ing the first
 letter of the command.
-%- In {\it NT, OS/2, PC\/ {\rm and} ST NetHack},
-%- the `Alt' key can be used in this fashion;
-%- on the Amiga set the {\it altmeta\/} option to get this behavior.
-In {\it NT, OS/2, {\rm and} PC NetHack},
-the `Alt' key can be used in this fashion.
+In {\it NT, OS/2, PC\/ {\rm and} ST NetHack},
+the `Alt' key can be used in this fashion;
+on the {\it Amiga\/}, set the {\it altmeta\/} option to get this behavior.
+On other systems, if typing `Alt' plus another key transmits a
+two character sequence consisting of an {\tt Escape}
+followed by the other key, you may set the {\it altmeta\/}
+option to have nethack combine them into meta\+key.
 \blist{}
 %.lp 
 \item[\tb{M-?}]
@@ -2963,9 +2965,24 @@ \subsection*{Platform-specific Customization options}
 The name of the handler is specified without the .dll extension and without any
 path information.
 Cannot be set with the `{\tt O}' command.
-%.lp 
+%.lp
+\item[\ib{altmeta}]
+On Amiga, this option controls whether typing ``Alt'' plus another key
+functions as a meta-shift for that key (default on).
+%.lp
 \item[\ib{altmeta}]
-(default on, {\it Amiga NetHack \/} only).
+On other (non-Amiga) systems where this option is available, it can be
+set to tell nethack to convert a two character sequence beginning with
+ESC into a meta-shifted version of the second character (default off).
+
+%.lp ""
+This conversion is only done for commands, not for other input prompts.
+Note that typing one or more digits as a count prefix prior to a
+command---preceded by {\tt n} if the {\it number\_pad\/}
+option is set---is also subject to this conversion, so attempting to
+abort the count by typing ESC will leave nethack waiting for another
+character to complete the two character sequence.  Type a second ESC to
+finish cancelling such a count.  At other prompts a single ESC suffices.
 %.lp
 \item[\ib{BIOS}]
 Use BIOS calls to update the screen display quickly and to read the keyboard

doc/fixes35.0

@@ -510,6 +510,7 @@ smartphone: added "Type Cmd" command that allows to type arbitrary commands
 	using phone keypad
 smartphone: added Q(quiver) command to "Attack" layout
 smartphone: fixed F command to prompt for direction
+unix,vms: altmeta option to handle terminals which send "ESC c" for Alt+c
 
 
 Code Cleanup and Reorganization

include/flag.h

@@ -180,6 +180,9 @@ struct instance_flags {
 	int	 menu_headings;	/* ATR for menu headings */
 	int *opt_booldup;	/* for duplication of boolean opts in config file */
 	int *opt_compdup;	/* for duplication of compound opts in config file */
+#ifdef ALTMETA
+	boolean  altmeta;	/* Alt-c sends ESC c rather than M-c */
+#endif
 	boolean  cbreak;	/* in cbreak mode, rogue format */
 	boolean  deferred_X;	/* deferred entry into explore mode */
 	boolean  num_pad;	/* use numbers for movement commands */

include/unixconf.h

@@ -1,5 +1,4 @@
 /* NetHack 3.5	unixconf.h	$Date$  $Revision$ */
-/*	SCCS Id: @(#)unixconf.h 3.5	2007/12/12	*/
 /* Copyright (c) Stichting Mathematisch Centrum, Amsterdam, 1985. */
 /* NetHack may be freely redistributed.  See license for details. */
 
@@ -198,6 +197,12 @@
 #define MAILCKFREQ	50
 #endif	/* MAIL */
 
+/*
+ * Some terminals or terminal emulators send two character sequence "ESC c"
+ * when Alt+c is pressed.  The altmeta run-time option allows the user to
+ * request that "ESC c" be treated as M-c.
+ */
+#define ALTMETA		/* support altmeta run-time option */
 
 
 #ifdef COMPRESS

include/vmsconf.h

@@ -1,5 +1,4 @@
 /* NetHack 3.5	vmsconf.h	$Date$  $Revision$ */
-/*	SCCS Id: @(#)vmsconf.h	3.5	2007/10/27	*/
 /* Copyright (c) Stichting Mathematisch Centrum, Amsterdam, 1985. */
 /* NetHack may be freely redistributed.  See license for details. */
 
@@ -137,6 +136,16 @@
 #define SHELL		/* do not delete the '!' command */
 #define SUSPEND		/* don't delete the ^Z command, such as it is */
 
+/*
+ * Some terminals or terminal emulators send two character sequence "ESC c"
+ * when Alt+c is pressed.  The altmeta run-time option allows the user to
+ * request that "ESC c" be treated as M-c, which means that if nethack sees
+ * ESC when it is waiting for a command, it will wait for another character
+ * (even if user intended that ESC to be standalone to cancel a count prefix).
+ */
+#define ALTMETA		/* support altmeta run-time option */
+
+
 #define RANDOM		/* use sys/share/random.c instead of vaxcrtl rand */
 
 #define FCMASK	0660	/* file creation mask */

src/cmd.c

@@ -6,6 +6,10 @@
 #include "func_tab.h"
 /* #define DEBUG */	/* uncomment for debugging */
 
+#ifdef ALTMETA
+STATIC_VAR boolean alt_esc = FALSE;
+#endif
+
 struct cmd Cmd = { 0 };		/* flag.h */
 
 extern const char *hu_stat[];	/* hunger status from eat.c */
@@ -3364,6 +3368,9 @@ parse()
 	context.move = 1;
 	flush_screen(1); /* Flush screen buffer. Put the cursor on the hero. */
 
+#ifdef ALTMETA
+	alt_esc = iflags.altmeta;		/* readchar() hack */
+#endif
 	if (!Cmd.num_pad || (foo = readchar()) == 'n')
 	    for (;;) {
 		foo = readchar();
@@ -3380,6 +3387,9 @@ parse()
 		    if (!multi && foo == '0') prezero = TRUE;
 		} else break;	/* not a digit */
 	    }
+#ifdef ALTMETA
+	alt_esc = FALSE;			/* readchar() reset */
+#endif
 
 	if (foo == '\033') {   /* esc cancels count (TH) */
 	    clear_nhwindow(WIN_MESSAGE);
@@ -3514,6 +3524,15 @@ readchar()
 	    hangup(0); /* call end_of_input() or set program_state.done_hup */
 #endif
 	    sym = '\033';
+#ifdef ALTMETA
+	} else if (sym == '\033' && alt_esc) {
+	    /* iflags.altmeta: treat two character ``ESC c'' as single `M-c' */
+	    sym = *readchar_queue ? *readchar_queue++ : Getchar();
+	    if (sym == EOF || sym == 0)
+		sym = '\033';
+	    else if (sym != '\033')
+		sym |= 0200;		/* force 8th bit on */
+#endif /*ALTMETA*/
 	} else if (sym == 0) {
 	    /* click event */
 	    readchar_queue = click_to_cmd(x, y, mod);

src/options.c

@@ -53,9 +53,22 @@ static struct Bool_Opt
 } boolopt[] = {
 	{"acoustics", &flags.acoustics, TRUE, SET_IN_GAME},
 #if defined(SYSFLAGS) && defined(AMIGA)
+	/* Amiga altmeta causes Alt+key to be converted into Meta+key by
+	   low level nethack code; on by default, can be toggled off if
+	   Alt+key is needed for some ASCII chars on non-ASCII keyboard */
 	{"altmeta", &sysflags.altmeta, TRUE, DISP_IN_GAME},
 #else
+# ifdef ALTMETA
+	/* non-Amiga altmeta causes nethack's top level command loop to treat
+	   two character sequence "ESC c" as M-c, for terminals or emulators
+	   which send "ESC c" when Alt+c is pressed; off by default, enabling
+	   this can potentially make trouble if user types ESC when nethack
+	   is honoring this conversion request (primarily after starting a
+	   count prefix prior to a command and then deciding to cancel it) */
+	{"altmeta", &iflags.altmeta, FALSE, SET_IN_GAME},
+# else
 	{"altmeta", (boolean *)0, TRUE, DISP_IN_GAME},
+# endif
 #endif
 	{"ascii_map",     &iflags.wc_ascii_map, !PREFER_TILED, SET_IN_GAME},	/*WC*/
 #if defined(SYSFLAGS) && defined(MFLOPPY)

src/windows.c

@@ -1,5 +1,4 @@
 /* NetHack 3.5	windows.c	$Date$  $Revision$ */
-/*	SCCS Id: @(#)windows.c	3.5	2007/02/01	*/
 /* Copyright (c) D. Cohrs, 1993. */
 /* NetHack may be freely redistributed.  See license for details. */
 
@@ -337,6 +336,11 @@ nhwindows_hangup()
 {
     char *FDECL((*previnterface_getmsghistory), (BOOLEAN_P)) = 0;
 
+#ifdef ALTMETA
+    /* command processor shouldn't look for 2nd char after seeing ESC */
+    iflags.altmeta = FALSE;
+#endif
+
     /* don't call exit_nhwindows() directly here; if a hangup occurs
        while interface code is executing, exit_nhwindows could knock
        the interface's active data structures out from under itself */