Right now I'm describing the common proc argument in two paragraphs just before the first with- procedure:

The following procedures use dynamic-wind when executing their proc procedure argument; if the proc's dynamic extent is escaped, the terminal mode changes of the containing with-or without- procedure are undone, but if the proc's dynamic extent is re-entered, the terminal mode changes of the containing procedure are re-enabled. They all use POSIX tcgetattr() and tcsetattr(), see also the stty command.

The general paradigm for using the following procedures is to set up your application, then run it in the proc provided to them, a procedure that takes the same port arguments in the same order as the containing with- or without- procedure. without-echo is an exception in that it's generally used to enter a password or pass phrase.

If that's OK, I can add the description of values somewhere in there.

- Harold

----- Original message -----
From: John Cowan <xxxxxx@ccil.org>
Date: Thursday, August 22, 2019 4:41 PM

I don't think it matters.  Make it [values], and add a line to each procedure saying that it returns whatever values *proc* returns.  That should be clear enough.

On Thu, Aug 22, 2019 at 3:13 PM <xxxxxx@ancell-ent.com> wrote:

The only problem is how to name it in the specification line, what's going to become "[proc returns]strikes me as awkward and almost but not 100% clear, but I suppose it will do.

- Harold

----- Original message -----
From: John Cowan <xxxxxx@ccil.org>
Date: Thursday, August 22, 2019 12:37 PM

Agreed on all points, except that I don't see what's the matter with returning what the no-longer-a-thunk returns; it seems like the sensible thing.

On Thu, Aug 22, 2019 at 12:38 PM <xxxxxx@ancell-ent.com> wrote:

The with-raw/rare-mode ones need both an input port and an output port, without-echo's needs to be specified as the latter, since changes need to be made the file descriptors behind them.  Per the recent standards, Schemes normally do not have bidirectional tty ports, instead supplying ones for stdin, stdout, and lately stderr.  R7RS, lacking a seek operation, doesn't even have a requirement for a port that can both read and write a file, nor does this SRFI support such in its I/O section.  So this is what I've got now in my version of the SRFI:

(with-raw-mode input-port output-port min time thunk)    →    [thunk returns]       (procedure)       POSIX stty -ECHO -ICANON -IEXTEN -ISIG -BRKINT -ICRNL -INPCK -ISTRIP -IXON -CSIZE -PARENB CS8 -OPOST

(with-rare-mode input-port output-port thunk)    →    [thunk returns]       (procedure)       POSIX stty -ICANON -ECHO VMIN=1 VTIME=0

(without-echo output-port thunk)    →    [thunk returns]       (procedure)       POSIX stty -ECHO -ECHOE -ECHOK -ECHONL 

BTW I'm not happy with the "thunk returns" return specification, and with-raw-mode gets particularly long, plus maybe some of the requirements have been relaxed since the 3rd edition of Stevens and Rago's Advanced Programming in the UNIX® Environment.

The bigger issue is that we might want to change the thunk arguments into procedures that take the above port or ports as supplied to the procedure, otherwise we're requiring that the thunk be defined in the same lexical scope that the with- and without- procedures are called if the user is doing it right.  Which makes the calling bit of code unavoidably longer, and implicit parameter passing is generally to be avoided unless there's a good reason to strongly couple all this together.  And this SRFI's paradigm for these procedures encourages the use of shared globals.

- Harold