Extensions to Apple BASIC with ampersands

Question

I have a vague recollection of some early software that extended the Apple II BASIC language, though I'm not sure if this was Integer or Applesoft BASIC.

It provided more features for the language by using commands such as &line x1, y1, x2, y2 to augment the rather primitive HLINE and VLINE drawing commands, or &circle x, y, radius for circles. I don't know if they were actual commands (it was forty-plus years ago) but that was the basic idea.

How this was done? Did it require that BASIC be loaded into RAM and patched or was it some sort of built-in hook already in the software? What was the process the BASIC interpreter followed to allow a command to use the new functionality?

Answer 1

After a bit of research, it turns out it was Applesoft.

The interpreter had a feature where, if it encountered an ampersand during execution of the program, it would unconditionally jump to a subroutine at location $3F5.

Extension software could use BLOAD or BRUNto get some code to a specific location and modify the three bytes at that location. This would then cause the code to execute when & was seen.

When that code eventually returned, Applesoft would continue execution after the ampersand.

So, if all you wanted was one simple thing to happen when an ampersand was encountered, that would be enough.

---

In order to allow for more complicated things like &line 1, 1, 20, 50, the code had to access internal memory to both figure out what the command was (so it could read parameters), and to ensure Applesoft skipped those parameters when we returned. The TXTPTR Applesoft variable was used for this.

You could call specific functions from your code to parse the line after the ampersand, using TXTPTR, and adjust it as part of that process, such as with:

; Handles something like "& 12345 * 2, 41"

JSR   $DD67      ;FRMNUM - eval numeric expression -> FAC
JSR   $E752      ;GETADR - place FAC into memory (LINNUM)
JSR   $DEBE      ;CHKCOM - check for comma
JSR   $E6F8      ;GETBYT - eval byte -> X reg

; Do something in here with registers and memory populated above.

RTS

Granted that's fairly simple but you had ways to ensure that the string "line" was the first thing after the ampersand as well (or detect different commands), giving you a variety of options. There was a GETCHR which returned the next character (or token if it was a keyword).

Answer 2

While paxdiablo answered the question confirming that it was AppleSoft, I can point out three things related to it as an extension:

1. When you load your extension, it should attempt to relocate itself as high as it can in the available memory to leave as much free RAM as possible behind. As such, it was common for ampersand extensions to be written with relative addressing if not using jump tables or self-modifying code.
2. It was good practice to make sure that your extension chained control to whatever address was in place previously. In other words, make it possible that more than one ampersand extension could exist; if your extension didn't recognize (say) & FOO, then perhaps the next one in the chain could.
3. There was another, lesser used AppleSoft command USR(x) which would call a machine language routine with the value of x in the accumulator (IIRC). Whatever the routine had in the accumulator when it finished would be passed as the lvalue (e.g. Y = USR(123)).

A few extensions off the top of my head: AmperWorks, ModemWorks, Beagle Basic, Beagle Graphics, and more recently I believe there was a text windowing library created by someone that used ampersand extensions.