# Grid Text Editor

The Grid text editor sits on [text/ed] and adds a visual and interactive
interface through the Grid [io/grid].

The basic idea is that text around current Edbuf selection is always displayed
using the whole grid except for the bottom line (the status line). There are
quick one letter keybindings for frequent and simple movements and
manipulations, but for fancier operations, you go in command mode with ":",
which simply prompts for a line to interpret (in which you'll probably use
commands from [text/ed], but you can also use others).

To use it, you load your EdBuf with some contents and then run "ed", which
enters the grid keybindings loop.

## text/ed bubbling up

Upon invoking "ed", the unit "text/ed" is called so that we bubble up its
convenience layer. [app/edx] has the same behavior.

This is needed to avoid bizarre behavior caused by bubbling up other units
during development. A notable example is [asm/x86] which shadows "dl".

## Visual mode

Pressing "v" toggles the visual mode. When toggled on, current position is
marked and when moving selection afterwards, the range between the mark and the
selection is shown visually.

Some bindings such as "D" only work in visual mode.

## The Gutter

Source code in Dusk doesn't exceed 80 characters per line. Screens with a grid
larger than that need a visual clue to help stay within that limit. That's
called the Gutter.

The Gutter is a vertical line drawn at the position determined by the "gutter"
field in EdBuf, defaulting to 80. You can change that value to move the gutter.

## Navigating buffers

[text/ed] has multiple buffers and this unit has key bindings to efficiently
navigate them.

First of all, there's CTRL+B. It lists all buffers along with their associated
path and size, as well as an index prefix. When it shows them to you, it waits
until you press a key to go back to the regular editing mode. If the key you
press is in the 0-9 range, the buffer corresponding to that index will be
selected. Buffers over the index 9 cannot be selected this way.

CTRL+] cycles through all the buffers, one at a time.

Pressing CTRL+E opens the path under the cursor, if it exists, in a new buffer.
It does so using [fs/utag]'s "utag>path". When the path is already opened in a
buffer, we just make that buffer active, keeping its previous position and
state.

CTRL+D does the same thing, but using "utag>.txt" logic (open help file). But it
also has a special something: it sets the ed find buffer to "\n<term>". This
means that if you use CTRL+D on a word name (which utag>.txt automagically links
to the approriate doc file), then you can press "n" and, if you're lucky, jump
directly to the reference of the word you're looking for. For example, if you
press CTRL+D on the following word, s) , you'll be taken to doc/lib/str.txt.
Then, if you press "n", the editor will jump to the documentation for "s)".

The CTRL+[ key binding opens the previously opened buffer. This is not the
inverse of CTRL+]. Repeatedly invoking CTRL+[ will swap between 2 buffers.

## Keybindings

"C+" means "hold left Control while you press the key".

Descriptions below are kept short because those actions often correspond to
words in [text/ed], which you can use as a complete reference.

q   Quit
h   Go left
j   Go down
k   Go up
l   Go right
J   Activate visual mode, go to "bol", then down one line
K   Activate visual mode, go to "bol", the up one line
H   Move to previous word
L   Move to next word
C+h Go to the beginning of the line
C+l Go to the end of the line or to gutter, whichever comes first
g   Type a number then go to that line (1-indexed)
r   Wait for keypress then replace character at cursor with that key
i   Insert
o   Insert line after
O   Insert line before
\   Join line (jl)
|   Split line (sl)
f   Find
n   Find next
z   zoom
Z   zoom to top. Reframe so selection is on top
v   Toggle visual mode
y   Copy visual selection to clipboard
p   Paste clipboard to current position
D   Delete visually selected text
X   Delete character at cursor
]   move 1 page down
[   move 1 page up
W   Run "edsave", that is, save active buffer to file
:   enter a single line of command that will be interpreted as forth
C+b Print buffer list and maybe select one
C+z Select the first buffer (Buffer Zero)
C+q Close active buffer
C+] Cycle to next buffer in list
C+[ Open the previously active buffer
C+e Enter tag under cursor
C+d Enter documentation of tag under cursor

## Mouse interaction

This application listens to MOUSECLICK [io/mouse] events.

Left click: Moves the caret there.
Right click+drag: Visually select the dragged area.

## API

ed ( -- )
  Clear the screen and run the Grid Editor, displaying current active text/ed
  buffer.

textsel[] ( -- a u )
  Yield a range of the current text selection. Yields a null range if there is
  no selection.

zoom ( -- )
  Reframe the editor so that selection is in the middle of the screen.
