doc: readline document TTY utils

[indutny]

fix #6933

[tjfontaine]

thanks landed in 0ec3770

[TooTallNate]

s/it's/its/

[litmit]

sorry for stupid question, but why this functional resides in readline but not tty module?
IMHO tty must provide the basic functional of terminal including cursor control, keypress event, and, if possible, mouse's events. And readline may use this teminal API for implement self functionality.
And also such teminal API allows to create 'fullscreen' console applications like mc. Why not?

[chjj]

@litmit, the tty module is there to expose the lowlevel happenings of terminals. The tty or pty subsystem of a unix OS is completely unaware of ansi escape codes. That all happens at a higher level. In fact, the unix tty you create might be for a terminal that uses something completely different from ansi control sequences (maybe HTML if you wanted).

[litmit]

@chjj may be you right but I think that separate level of abstraction is needed in any case:
readline -> ANSITerminal -> tty
That allows to use common functional in other manners:
some_console_ui_library -> ANSITerminal -> tty

[TooTallNate]

As an FYI, when I originally extracted these functions from the tty module into the static versions in the readline module, I intentionally left them undocumented, because they were only being used by the readline module. It's also the minimum amount of ANSI escape codes needed to implement the readline module (i.e. the REPL).

However, there's lots of user-land modules that provide a more feature-full experience when it comes to ANSI escape codes, so you're really better off using one of those. ansi.js is mine: https://npmjs.org/package/ansi </self-promotion>

[litmit]

when I originally extracted these functions from the tty module into the static versions in the readline module, I intentionally left them undocumented

.. and I sure with it.
But this issue makes these functions part of public API. And may be is better to put they at once in right place, not readline?

However, there's lots of user-land modules that provide a more feature-full experience when it comes to ANSI escape codes

I looked at few of them. Common problem that they are not worked well on Windows. I think that there is needed some support from Node's core.

[TooTallNate]

I looked at few of them. Common problem that they are not worked well on Windows. I think that there is needed some support from Node's core.

The only feature I know that doesn't work properly is 256 color support (using my ansi module). Which feature doesn't work well that you're trying to use? FYI, libuv already does ansi code translation to Windows API calls when written to stdout.

[litmit]

• ConEmu supports 256 colors, but Node runned under ConEmu does not.
• no mouse events
• not all standard keys processed correctly.

Steps to reproduce:
process.stdin.on('keypress',function(a,key) {console.log(key);})

press F2, output:
{ name: 'f2', ctrl: false, meta: false, shift: false, sequence: '\u001b[[B', code: '[[B' }

press Shift-F2, output (wrong name and shift status):
{ name: 'f12', ctrl: false, meta: false, shift: false, sequence: '\u001b[24~', code: '[24~' }

press Ctrl-F2, output (noname, ctrl false):
{ name: 'undefined', ctrl: false, meta: false, shift: false, sequence: '\u001b[12^', code: '[12^' }

press Alt-F2, output:
{ name: 'f2', ctrl: false, meta: false, shift: false, sequence: '\u001b\u001b[[B', code: '[[B' }

press Ctrl-Alt-F2, not supported at all.

press Alt-Shift-F2, output (wrong name and shift status):
{ name: 'f12', ctrl: false, meta: false, shift: false, sequence: '\u001b\u001b[24~', code: '[24~' }

press Ctrl-Shift-F2, output (noname, wrong ctrl status):
{ name: 'undefined', ctrl: false, meta: false, shift: false, sequence: '\u001b[24^', code: '[24^' }

press Ctrl-Alt-Shift-F2, output (noname, wrong ctrl,shift status)::
{ name: 'undefined', ctrl: false, meta: false, shift: false, sequence: '\u001b\u001b[24^', code: '[24^' }

Win-*-F2 give the same effect as *-F2 (* - any other modifier)

Alt key status missing in the keypress object at all.
Win key is not supported (although this is good choice for meta replacement)

[eugenejscray-zz]

Dumb Question but what is meant by the position x and y? Lets say I had a file would the y position be my line? and would the x position be the character index within the line?