NAME
asdfg - a lightweight visual editor optimized for the QWERTY keyboard
SYNOPSIS
asdfg [ -s ] [ -t tab stop ] [ -u | -U ] [file...]
DESCRIPTION
asdfg is an interactive display text editor optimized for users of the
QWERTY keyboard layout.
When run with no file name arguments, asdfg displays a short command
introduction and summary.
asdfg can browse very large read-only files with quick start-up, since
original texts are memory-mapped from files and not duplicated in
memory until they are about to be modified.
OPTIONS
-k Disable keyword highlighting.
-s Use spaces, not tabs, for automatic indentation.
-t 8 Set the tab stop to 8 or to some unreasonable value. This
setting can be overridden on a per-text basis later.
-u Treat files as UTF-8 even if they contain invalid UTF-8
encodings.
-U Don’t treat files as UTF-8 even if they look like it.
INTENTIONALLY MISSING FEATURES
asdfg has no embedded extension language, since it is trivial to pass
regions of text from the editor to any program or script that can read
standard input and write standard output. The shell, sed(1), awk(1),
python(1), and perl(1) are all usable for such scripting. Further,
since asdfg ships will full sources and the rights to modify it, users
can customize it directly.
The editor has only basic syntax highlighting of C and C++ keywords
with subtle color cues that help match up parentheses, brackets, and
braces.
asdfg has no mail or news reader, IRC client, or artificial
intelligence psychologist mode.
There is no X window system interface; that’s what xterm(1) and gnome-
terminal(1) are used for.
BASICS
A text is a sequence of characters to be viewed or edited, such as a
file. If it is not ASCII, the editor will automatically determine
whether it is encoded in legal UTF-8 and do the right thing. The
editor can also automatically detect DOS-style line endings.
A view comprises all or part of a text. A text in the editor has at
least one view, and possibly more.
A window is a rectangular portion of the display, and is always
associated with a single view, a contiguous portion of whose text is
rendered in the window. Not every view has a window.
Each view has a cursor and possibly a selection, which has the cursor
at one end and the mark at the other. The view’s window, if any,
always renders part of the text containing the view’s cursor.
The selection plays a critical role in asdfg. Besides highlighting
regions to be cut or copied, it also serves to supply arguments to some
commands, such as the path name of a file to open.
The clip buffer is not visible in any window. It receives snippets of
data that have been cut or copied out of texts, so that they may be
moved or copied elsewhere. It also supplies the standard input to a
background command launched with ^R (below). There is one clip buffer
shared by all views.
COLOR CUES
asdfg uses colors to convey information without cluttering the display
with status lines or borders between windows.
asdfg uses distinct background colors to distinguish tiled windows.
The active window is always presented in the terminal’s default color
scheme. Color is also used to highlight the current selection (in
cyan) and folded regions (in red).
Needless tabs and spaces are marked in violet. These include any tabs
or spaces before the end of a line, as well as any spaces followed by a
tab or multiple spaces that could be replaced by a tab.
Bracketing characters are presented in alternating colors so that
matching parentheses, brackets, and braces are colored identically.
A red cursor signifies a read-only text, whereas a green cursor
indicates a dirty text (meaning one that needs saving, not one unfit
for young persons).
COMMANDS
asdfg understands the arrow, page up and down, and Delete keys on your
keyboard, so you can actually just use it like a dumb notepad with no
mouse if you don’t want to read any further than the next section,
which tells you how to leave the editor.
In the following sections of the manual, commands are denoted by ^key
to signify the use of Control, Alt, or a preceding Escape key. They
all mean the same thing.
Variant commands always begin with ^Space, or its synonym, ^@. A few
commands take a numeric argument, which is specified by ^Space followed
by a decimal or hexadecimal number, the latter using C language syntax
(0xdeadbeef).
Many commands are sensitive to the presence or absence of a selection.
LEAVING
^Space^\
aborts the editor, leaving no original file modified since the
last time ^W was used.
^Q suspends the editor and returns the terminal to the shell that
invoked it. Use the shell’s foreground command, probably fg, to
resume editing.
^Space^Q
saves all modified texts and terminates the editor.
NAVIGATION
The "backward and forward by unit" commands treat a numeric argument,
if any, as a repeat count.
^G moves the cursor backward by characters.
^H moves the cursor forward by characters.
^Space^G
moves the cursor up a line on the screen.
^Space^H
moves the cursor down a line on the screen.
^K moves the cursor backward by words.
^L moves the cursor forward by words.
^Space^K
moves the cursor backward one sentence.
^Space^L
moves the cursor forward one sentence.
^T moves the cursor back to the beginning of the line. If already
there, it moves back to the beginning of the previous line.
^Y moves the cursor forward to the end of the line. If already
there, it moves forward to the end of the next line.
^Space^T
moves the cursor back to the beginning of the paragraph. If
already there, it moves back to the beginning of the previous
paragraph.
^Space^Y
moves the cursor forward to the end of the paragraph. If
already there, it moves forward to the end of the next
paragraph.
^O moves the window backward by screenfulls.
^P moves the window forward by screenfulls.
^Space^O
moves to the very beginning of the view.
^Space^P
moves to the very end of the view.
^] moves to the corresponding parenthesis, bracket, or brace,
respecting nesting, if the cursor sits atop such a character.
Otherwise, it moves to the nearest enclosing bracketing
character.
^N recenters the window so that the line containing the cursor lies
in the middle of its portion of the display.
^Space^N
causes the current window to occupy the entire display and
recenters the window. With a numeric argument, however, it
simply moves the cursor to the indicated line in the view, with
1 being the number of the first line.
^Space=
(note that = is not a control character) sets a bookmark on the
current selection or cursor position. A numeric argument may be
used to manage multiple bookmarks.
^Space-
(note that - is not a control character) returns to a previously
set bookmark, possibly identified with a numeric argument.
^Space’
(note that the single quote ’ is not a control character) looks
an identifier up the identifier in the TAGS files, which are
sought in the same directory as the current view and then all of
its parents, until one is found that contains the identifier. A
new little window is opened for each of the identifier’s entries
in the TAGS file.
The TAGS files should be generated with the ctags or exuberant-ctags
utilities and their -x output format. If there is a selection, it is
deleted from the view and its entire contents will constitute the
identifier to be looked up; otherwise, the identifier that is
immediately before or around the cursor is sought.
SELECTION
These commands are sensitive to the presence or absence of a current
selection.
^U begins a new selection if non exists, setting its mark at the
current cursor, which is then typically navigated to its
intended other end. ^U in the presence of selection simply
removes the mark.
^Space^U
without a selection causes the entire current line to be
selected by placing the mark at the end of the line and the
cursor at its beginning. It is the same as the command sequence
^Y^U^T with no selection. With a selection present, ^Space^U
exchanges its cursor with its mark.
Note that ^Space^U with a numeric argument unconditionally unsets the
mark, which can be handy in a macro.
^Space^X
with no selection causes all of the contiguous white space
characters surrounding the cursor to be selected, with the
cursor at the beginning so that they can be easily replaced by
retyping.
UNDO
asdfg has infinite undo capabilities.
^Z reverses the effects of the last command, apart from ^Z itself,
that modified the current text in any of its views.
^Space^Z
reverses the effects of the most recent undo. After ^Z, any
other command that modifies the text will permanently commit the
undo(s).
MODIFICATION
In the default mode, characters typed without a command indicator are
inserted at the current cursor position. Further, if the cursor is at
the beginning of a selection, the selection is first cut to the clip
buffer, so that the new text replaces it.
^^ (that’s Control-Shift-6, the caret character, on most keyboards,
and ^6 will probably also work) inserts an otherwise untypeable
control character into the text. The very next key to be
pressed is either taken literally, if it is a control character,
or converted to a control character if it is not, and inserted.
(For example, you can press ^^ and then hit either Control-A or
just a plain A, to get the character code 0x01 inserted.)
^Space^^
with a numeric argument, probably in hexadecimal, inserts the
specified Unicode character into the text in UTF-8 format.
Tab (or ^I) attempts to perform tab completion; if that fails, a TAB
character is inserted. If there is a selection with the cursor
at its end, the editor tries to find an unambiguous continuation
based on path names and words in all the views. A continuation,
if found, is appended to the selection, to facilitate opening a
file with ^E. With no selection, but the cursor immediately
after one or more identifier characters, the editor searches for
an unambiguous continuation using the words in the views. A
continuation, if found, is inserted as the new selection with
the cursor at its end. No tab completion occurs when the cursor
is at the beginning of a selection; in that case, the selection
is cut and replaced with a single TAB character.
^SpaceTab
(or ^Space^I) will align the current line to the indentation of
the previous one. This is equivalent to ^Space^X Enter. With a
numeric argument of 1, it toggles the text’s use of tab
characters for indentation. With a numeric argument between 2
and 20, it will set the tab stop pitch.
Enter (or ^M) inserts a new line into the text without automatic
indentation.
^J (or ^Enter under some good terminal emulators) inserts a new
line into the text with automatic indentation. If ^J is
executed immediately after a { character that does not yet have
a closing }, ^J will also add a properly-indented closing brace.
Backspace
(or more properly, its synonym ^? and sometimes, as in Mac OS
X’s Terminal application, ^/), deletes the character immediately
before the cursor.
^X with no selection deletes the character "under" the cursor.
When a selection exists, ^X moves it into the clip buffer,
discarding any previously clipped text.
^Space^X
with no selection will select surrounding white space, as
described earlier. When a selection exists, ^Space^X moves it
into the clip buffer, putting it before any old text if the
cursor was at its beginning and appending it to the clip buffer
if the cursor was at its end. The intent is for multiple
^Space^X commands to collect data together in the same order in
which they are most likely to have been visited.
A numeric argument to ^Space^X places the indicated number of copies of
the selection into the clip buffer.
^C requires a selection, which is copied into the clip buffer and
then unmarked.
^Space^C
is to ^C what ^Space^X is to ^X. It copies the selection to the
clip buffer, putting it at the beginning or the end in the same
way as ^Space^X (above). A numeric argument to ^Space^C places
the indicated number of copies of the selection into the clip
buffer.
^V with no selection will paste the current clip buffer’s contents.
But in the presence of a selection it performs a more general
function: the contents of the selection and the clip buffer are
exchanged. With a numeric argument, ^V pastes or exchanges with
a numbered register, which is an alternate clip buffer. (The
main clip buffer is the same as register 0.) Besides being a
means for preserving some text for longer periods of editing,
the registers also serve as a means for extracting the text that
matches a parenthesized subpattern in a regular expression
search.
SEARCHING
^_ and its synonyms ^/, ^-, and ^A enter search mode. The many
synonyms are defined because they’re often synonymous or
reserved key sequences in the various window managers and the
screen(1) utility.
(Specifically, ^/ gets mapped to ^_ by many X terminal emulators, while
^- gets mapped to ^_ by the Mac OS X Terminal application. ^A is the
default escape sequence in screen(1).)
The variant version of this command (^Space^_ and its synonyms)
searches for occurrences of POSIX regular expressions. Each non-
command character that is typed thereafter will be appended to the
current search target string and the selection is moved to the next
occurrence thereof.
The case of alphabetic characters is not significant to the search.
Most command characters will automatically take the editor out of
search mode before executing, and the most recently discovered
occurrence of the search target string will be its selection.
A few commands have different meanings in search mode:
Backspace
will remove the last character from the search target and move
the selection back to its previous position.
^U is typically used to leave search mode with the cursor at the
latest hit, with the mark returned to where it was before the
search (if anywhere). This is useful for using search to place
the bounds of a selection.
^_ (or its synonyms) with no characters in the search target string
will cause the last successful search’s target string to be
reused.
^G and ^H cause motion to the previous and next occurrences of the
search target string, not single-character motion.
Enter (and ^_ and its synonyms) simply leaves search mode with the
last hit as the selection.
TEXTS, VIEWS, and WINDOWS
^W saves all modified texts back to their files.
^Space^W
saves just the current text.
^E with no selection inserts, as the new selection, the path name
of the current text. With a selection containing a path name,
possibly constructed with the assistance of tab completion
(above), ^E will raise up a window containing a view into the
indicated file, creating a new text to hold it if one does not
already exist.
^Space^E
with a selection will rename the current text, so that it will
be saved in another file.
^F finds an invisible view and associates it with the current
window, making its current view invisible. Hitting ^F
repeatedly will cycle through all of the views. If there was no
invisible view, ^F creates a new scratch text, as does ^Space;
below.
^Space^F
does the same thing. but will close the window’s current view,
and also its text if it was the last view thereof.
^D splits the current window horizontally, raising up an invisible
or new view in the lower half of the original window.
^Space^D
splits the current window vertically, raising up an invisible or
new view in the right half of the original window.
^S moves to another window.
^Space^S
moves to another window, closing the old one.
^Space;
(note that ; is not a control character) creates a new anonymous
text.
MACROS
^Space^B
commences the recording of your keystrokes as the macro, which
continues until the next ^B or another macro recording.
^SpaceF1-F12
commences the recording of your keystrokes as a new macro for a
function key. Note that F1 and F11 are typically hijacked by
window managers for their own purposes and probably will not be
usable.
^B ends the recording of a macro, if one is in progress.
Afterwards, ^B replays the macro, possibly with a repeat count
as the argument. Note that a failed search in a macro will
terminate its execution.
FOLDING
asdfg supports the "folding" of portions of text into what appear to be
single characters, and the reverse "unfolding" operation. Further, to
provide outline views of texts such as source code that are heavily
indented, asdfg has an automatic nested folding capability.
^Space,
with a selection will fold the selection. Otherwise, it will
repeatedly fold indented regions of the text to provide an
outline view. A numeric value, if any, specifies the number of
leading spaces or equivalent tabs at which code lines will be
folded. The default is 1, causing the folding of any line that
isn’t left-justified.
^Space.
with a selection, or immediately atop a folded section, will
unfold the topmost foldings within it. Otherwise, and if there
is a numeric value, it will completely unfold the entire view.
SHELLS
^R with no selection will launch an interactive shell in a new
scratch text. With a selection, however, ^R will execute the
shell command in the selection with the contents of the clip
buffer, if any, as its standard input, and collect its output
asynchronously in the background to replace the selection. This
allows many helpful UNIX text processing commands to be used
directly. Some handy commands to know:
cat(1) to include another entire file, or to receive writes to a named
pipe
mkfifo(1)
to create a named pipe so that commands in other windows may
direct their output into a text running cat in the background.
cd path
to change the editor’s current working directory (a special case
command that is not actually passed to a shell)
grep(1)
to search for lines containing a pattern
sort(1)
to rearrange lines alphabetically or numerically, possibly
reversed
uniq(1)
to discard duplicated lines
sed(1) as in sed ’s/FROM/TO/g’ to perform unconditional search-and-
replace with regular expressions
tr(1) to convert lower to upper case with a-z A-Z and to remove DOS
carriage returns with -d ’[\r]’
fmt(1) to reformat paragraphs of natural language text
indent -st -kr -i8 -nbbo
to reformat C language source code sensibly
column -t
to realign data nicely into columns
man | colcrt
to read a man page
tailf(1)
to monitor additions to a file such as a log
make(1)
to compile your code
aspell list | sort | uniq | column
to get a list of words that may be misspelled
^Space^R with no selection will terminate the output of any
asynchronous child process that’s still running.
TIPS
* To select the rest of the line after the cursor, use ^U^Y
* It is often faster to retype a bungled word than to fix it,
using ^U^K and then retyping.
* Transposing multiple blocks of text is easy with ^V, which
generalized the usual paste operation into an exchange of the
clip buffer with the selection.
* Incremental search and replacement can be done with a macro or
by clipping the replacement text, and on search hits that are to
be replaced, using ^V^C^/^/ to exchange the hit with the
replacement text, copy it back to the clip buffer, and proceed
to the next occurrence of the search pattern. But when the
replacement text is short, it’s sometimes easiest to just
overwrite the selection by hitting Enter to leave search mode
and immediately retyping it, since the cursor will be placed at
its beginning.
* Reconfigure your keyboards so that the key to the left of A,
which is probably labeled Caps Lock, is interpreted as a Control
modifier instead.
* The gnome-terminal(1) terminal emulator works well with asdfg if
you configure the terminal’s scrollback limit to a relatively
small value.
* To move backward or forward by half a screenfull, use ^O or ^P
and then ^N.
* To insert characters with a repeat count, type the characters
into a new selection, cut into the clip buffer with a repeat
count with ^Space^X, and then paste with ^V.
BUGS
Inevitable; please tell me about any that you find.
ENVIRONMENT
SHELL is used to name the program run by the ^R command.
ROWS and
COLUMNS
may be set to override asdfg’s automatic mechanisms for
determining the size of the display surface.
TERM will, when set to a string beginning with xterm, cause asdfg use
the title bar of the terminal emulator as a status indicator
that displays the path name of the active view and whether or
not it has been saved since last modified.
FILES
file~ is overwritten with the original contents of file.
file# contains the temporary image of the edited file while asdfg is
running, and may be useful in recovery if the editor is killed.
TAGS is found and read in by the ^Space’ command to supply the tags
that are scanned. The search for TAGS begins in the same
directory as the current view’s text and proceeds up through its
parents.
$HOME/.aoeui
holds any new "anonymous" texts created during editing sessions.
SEE ALSO
aoeui(1), ctags(1), exuberant-ctags(1), regex(7)
Helpful commands to use with ^R: aspell(1), cat(1), colcrt(1),
column(1), fmt(1), grep(1), indent(1), mkfifo(1), sed(1), sort(1),
tailf(1), tr(1), uniq(1)
AUTHOR
Peter Klausler <pmk@google.com> wrote asdfg.
February 15, 2009 asdfg(1)