Discussion about possible syntax changes

As of v3.0, with-simulated-input will support the following values for KEYS:

string: Represents a key sequence. Empty string means no input (i.e. signal an error if BODY tries to read input)
character: Represents a single keypress; equivalent to a string of length 1 containing the character. (Note that characters in Elisp are integers between 0 and (max-char) inclusive)
list: Each element is either a string, a character, or a lisp expression to be evaluated during the input process that will do something like insert text or execute a keyboard macro. Return values of the expressions are ignored. Note that nil (the empty list) is equivalent to the empty string (i.e. no input).
symbol: Must be the name of a variable whose value is a string, a character, or nil, which is treated as above

Note that when KEYS is a list, any constant/pure/side-effect-free expressions in KEYS have no effect at all, since their return values are discarded. Hence, while it is syntactically legal to put a pure expression in KEYS like this, it is a likely indicator that the programmer has misunderstood the macro and is expecting the return value to be used as a key sequence. A warning is therefore generated whenever the code is able to detect such expressions.

In addition, the following are deprecated, but still supported for backward compatibility:

quoted list: Same as list above; exactly the same as if the quote was omitted.
symbol with non-string value: A symbol whose value as a variable is a list, which is treated as above, though the handling of variable scope is a bit inconsistent.
a list where the car is a function or macro other than quote: This is treated as a single lisp expression to be evaluated, whose value must be one of the above (except a symbol).

This last case, the list that is interpreted as a function call, is required for backward compatibility, but is dangerous and potentially inconsistent since it only triggers if the first element satisfies functionp or macrop at the time the macro is expanded. Technically, there is also the potential that when KEYS is a list, it could be interpreted either as a function call or a list of key sequences. However, this can only happen when the first element is a constant expression, so it doesn't conflict with any legitimate use of a key list. Still, this is a precarious balance.

In a future version, support for these deprecated forms will be dropped entirely, opening the potential for new syntax to be added that would otherwise conflict with them. The purpose of this issue is to suggest and discuss possible useful extensions to the syntax of KEYS. Any such extensions must not conflict with the first list above, but may conflict with the list of deprecated forms, since they will be removed. Some suggestions are already in #12.

DarwinAwardWinner / with-simulated-input

Discussion about possible syntax changes #15