# 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.

## Navigating inside a buffer

Moving the caret inside a buffer can be done, at its lowest level, through the
famous h/j/k/l keys. This moves the caret by 1 in any direction.

You can move up and down by bigger increments (half a page or something) with
'[' and ']'.

Shift+H and Shift+L move left or right by word increments. CTRL+H and CTRL+L
go to beginning or end of line.

Shift+G lets you enter a number corresponding to the absolute line number to
jump to.

And finally, this editor fancy little feature, 'g'. 'g' is for quickly jumping
on a line currently being displayed on the screen. When you press 'g', a
vertical array of single digits/letters is displayed on the left of the screen.
Press the key of the line you want to jump to.

But that's not it! now, the same thing is going to happen on the row level. At
word boundaries, you'll see a list of digits/letter. Press that digit/letter to
move to that word.

## Mark and Visual mode

Each buffer has what we call a "mark", which is a saved position. You can set
it to current position by pressing "m", and then later jump back to that mark by
pressing "M". Doing so *swaps* position and mark, which means that repeat "M"
presses toggles between two positions in the same buffer.

There is only one mark per buffer.

The concept of marking is closely related to another concept: visual selection.
The mark and current pos can be seen as a range, where the lowest of the two is
the beginning and the highest, the end of that range.

When what we call "Visual mode" is toggled on, that range is visible on screen
by being highlighted. Some key bindings such as "y" and "D" act on that range.
Those binding are only effective when Visual mode is on.

You can toggle Visual mode with "v". When toggling on, "v" resets the mark to
current position so that you can begin a new range. If you prefer to use your
previous mark, use "V", which also toggles Visual mode, but preserves the mark.

Shift+J and Shift+K are a shortcut for toggling visual mode and go one line up
or down.

## 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.

## 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".

## 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
m   Set mark
M   Swap current pos with mark then jump there
v   Toggle visual mode, starting a new selection
V   Toggle visual mode, preserving old selection
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.
