Skip to content

Latest commit

 

History

History
105 lines (72 loc) · 7.79 KB

README.md

File metadata and controls

105 lines (72 loc) · 7.79 KB

a2vimode

Introducing a2vimode

Hello, and welcome to a2vimode, which installs vi-inspired prompt-line editing facilities! Created for HackFest 2022, a part of KansasFest 2022 (an annual Apple ][ conference)

Once the HELLO program is run (at startup if you boot from the disk), all text prompts that use the standard firmware prompt routine (DOS, Monitor, BASIC, BASIC Input), will start using vi-mode.

With this routine installed, you can:

  • navigate conveniently within the line you are editing
  • insert or delete text in the middle of a line
  • choose between left-arrow/backspace or the DELETE key for erasing characters.

At the moment, you will also currently give up:

  • including other on-screen text as part of your input But we hope to add this feature back at some point.

Design Goals

The primary design goals, which are in fact to some degree in conflict:

  1. Be as similar to vi(/vim) controls as practical
  2. Be as capable of working on an Apple ][+ as an Apple //e
  3. Be written with 80-column support in mind

Because of the limitations of goal #2, there is one major set of differences between our controls, and those in vi: there are no lowercase controls. You are welcome to type your navigation commands out in lowercase, but they will behave exactly the same as typing capitals. For related reasons, many capital-letter commands you may be accustomed to from vi, have the behavior of their lowercase equivalent.

An even bigger difference: instead of using the ESC key to enter "normal" mode, you should instead use the TAB key. Actually, the ESC key will work if you use it, at least in 40-column mode—but in 80-column mode it won't, because the 80-col firmware intercepts it, and it will likely screw up your prompt's display.

Be sure to read the list of commands from the Normal Mode section.

Usage

Insert Mode

After the routine is installed, whenever a prompt is opened, it begins in "insert" mode. This is a mode for typing characters as input into your prompt. If you never touch the TAB (or ESC) key, your typing experience will be very similar to what you're already familiar with:

  • As you type, characters are visibly added to your input.
  • If you type the left-arrow (backspace) key, characters are removed from input.
  • Typing the RETURN key completes your input line and sends it to the running program.
  • Typing CONTROL-X will abandon the current line prompt and start a new one.

Some differences you may notice:

  • When you backspace over a character, it is removed, and is no longer visible. Thus, you cannot use the right-arrow key to re-insert just-deleted characters.
  • You may also use the DEL key to erase characters.
  • If you type a backspace when you are all the way to the left of your line, the cursor just stops there - it does not reprompt on a new line.

And there are a couple of small, additional features:

  • If you type a Control character that would otherwise be invisibly inserted, vi-mode visibly inserts it, in inverse-video mode. So, if you are in the monitor and type (e.g.) 6 CONTROL-P, you will see the CONTROL-P as an inversed-color P, visible on the screen.
  • If you type CONTROL-V and then any character, the second character will be included literally as input (and displayed on the prompt), even if normally it would have special meaning. So, if you were to type CONTROL-V TAB, it will include a tab character in your input line (displayed as an inverse-video I). This feature can also be used in BASIC to insert carriage-return characters inside your REM statements!

Normal Mode

Normal mode is mainly used for navigating around the line—going forward and backward by characters or words, or to the beginning or end of the input line, so that you can enter new text mid-line, or delete some bits you don't want.

(Why is it called normal mode if the prompt normally starts in input mode? Because in vi it is the normal mode, and is called that, and while for our purposes it might be more accurate to call it "command mode" or "movement mode", "normal mode" is still what I expect is the least-confusing way to refer to it.) 🙂

Within Normal Mode, typing a key does not insert the corresponding character. To go back to inserting things, you must go back to insert mode by typing the I key (which will not be entered); and then you can go back to typing things in as input.

In Normal Mode, the following keys have meaning:

Key ~ vi key Action
H h move left one char
L l move right one char
W w move forward to the start of the next word
E e move forward to the end of this or the next word
B b move back to the start of this or a previous word
0 0 move to the beginning of input
^ ^ move to the first "word character" at the beginning of input
$ $ move to past the end of input
I i return to insert mode (start typing into input)
A a return to insert mode, inserting after the current character
[BS] [BS] (left-arrow/backspace, or DEL) delete back a character
X x delete forward a character

There is currently no support for the "delete"(-movement), "change"(-movement), "substitute", or "replace" commands found in vi; these are planned as future features. For now, you'll have to make do with just left-arrow/DEL and X to handle deletions.

80-Column

To use vi-mode in 80-column mode, first start 80-column mode with PR#3, and then RUN HELLO to reconnect vi-mode. Do not run the HELLO program multiple times with 80-column firmware active - if you want to reboot vi-mode, do another PR#3 followed by RUN HELLO.

And don't touch the ESC key! Use TAB to enter normal mode.

Can I use Vi-Mode with ProDOS?

Not currently. Everything works fine for the prompt itself, but

  1. it interferes with DOS commands in a way I don't yet understand, and
  2. I haven't written the (simple) bootstrapper program for it yet, just hacked it into place to test briefly.

Expect ProDOS support soon!

Why Vi-Like?

Q: "Micah, why on earth did you choose vi as the model? Why not use a single mode for moving and inserting?

A: Because it's my hackfest project, and having vi-mode in the prompt is more fun for me! Plus, I hope to eventually add support for vi's f, t, ,, and ; commands (which a surprising number of vi users appear not to know about, but are among my most-used commands!), and using those definitely warrants having a separate movement mode, in my opinion.

Problems and Short-Comings

  • The ability to go and grab content off the screen is lost now.
  • No PROdos support (yet).
  • 80-column mode is somewhat fragile, and occasionally annoying. This is due chiefly to the fact that 80-col RDKEY automatically a number of things that the standard firmware doesn't, and I wish it wouldn't. I may resolve these issues by avoiding RDKEY in the future, but for now I'm stuck with it.
  • It really wants the d and c commands from vi... and y and p for copy/paste would be nice too. I plan to add these soon.
  • Due to the way a2vimode detects and wrests away control from the firmware GETLN routine, there is a small-but-not-zero chance of mistaking some values on the stack for return addresses, that aren't, and consequently breaking some function up the call stack.

How Does It Work?

a2vimode looks at the stack to see if its immediate caller, or one just behind, is RDCHAR that in turn has been called by GETLN. If it sees them, it disables RDCHAR with a return to an RTS op, and replaces the return to GETLN with a return into our own specialized replacement prompter! 😈