# ANSI escape codes

The unit at [text/ansi.fs] decodes ANSI escape codes (well, a subset of it,
codes that are actually used in the wild). Additionally, it implements hooks to
use in conjuction with [io/grid].

It implements "ansirtype ( a u -- )", to be hooked to RTYPE instead of
"gridrtype". It types to the grid in a regular manner, but when it encounters an
escape code, it applies the corresponding effect to the grid (cursor movement,
color change, etc.)

On the output side, it implements a dummy grid where the grid API pushes ANSI
escape sequences to a [io/stream].

## ansirtype decode logic

With tons of terminals supporting tons of escapes all around, shooting for
feature parity with those implementations is too much. What we do is that we
expect the other side to encode their escape codes using the "ansi" terminfo.

Note that at the moment, we're not quite done implementing those escape codes.

## Debugging buffer

All decoded escape sequences, along with their arguments, get pushed to a
rolling buffer [io/roll] named "escbuf". When it's full, we silently ignore it
and drop the sequence.

This buffers allows debugging of decoded sequence. A ".escbuf" helper word spits
the contents of the buffer to the console.

## UNIX tty setup

For ANSI escape sequences to work well, the other side of the line has to be
properly configured, namely by setting the TERM environment variable to "ansi"
and by setting the grid size. The latter is done through the "stty" command.

For example, if we have a 100x75 grid, we'd want to run:

  stty rows 75 columns 100

To facilitate this, we provide "ttycfgcmd ( -- str )" which generates those
command with the right values interpolated.

## Example usage

If we have a communication line where we get ANSI codes, a UNIX tty for example,
and we'd like to hook into that line using [io/ride] on a system with a
[io/grid] that is already setup, setup would look like this:

  needs io/ride text/ansi
  sttycmd commline puts
  ' ansirtype RTYPE !
  commline ride \ incoming ANSI escapes will drive the grid

## API

### Constants

escbuf
  A [io/roll] buffer where all decoded sequences get pushed, for debugging
  purposes.

### Words

ansirtype ( a u -- )
  Proxies "gridrtype", but when the range "a u" contains ANSI escape code,
  possibly alter the grid before calling "gridrtype".

  Gracefully handles incomplete escape codes, that is, if "a u" begins an escape
  sequence but doesn't finish it, the code is buffered and the next call to
  this routine is expected to complete the code.

  Invalid and unsupported escape codes are silently ignored.

ttycfgcmd ( -- str )
  Generates a string containing commands to run on a UNIX shell so that the
  terminal is properly configured to be driven by Dusk.

.escbuf ( -- )
  Spits contents of "escbuf" to "console" [io/stream].
