Editing Atari BASIC (section)

==Description==

===Program editing===
[[Image:AtariBasicError.png|frame|Syntax errors are reported immediately after a line is entered.]]

Atari BASIC is anchored around its [[line editor]]. Program lines can be up to three physical screen lines of 40 characters, 120 characters total. The cursor can be moved freely, with the editor automatically tracking which BASIC program line the current screen line is part of. For instance, if the cursor is currently positioned in line 30 and the user uses cursor-up into line 20, any editing from that point will be carried out on line 20.

Atari BASIC's editor catches many errors are ignored in Microsoft-derived versions. If an error is found, the editor re-displays the line, highlighting the text near the error in [[inverse video]]. Errors are displayed as numeric codes, with the descriptions printed in the manual.{{sfn|Manual|1980|loc=Appendix B}} Because of the way the line editor works, the user can immediately fix the error. In the example pictured above (with <code>PRUNT</code>), the error can be fixed by moving the cursor over the <code>U</code>, typing {{keypress|I}} (the editor only has an overwrite mode), and hitting {{keypress|RETURN}}.

A line entered with a leading number, from 0 to 32767,{{sfn|Crawford|1982|p=10.3}} is inserted in the current program or replaces an existing line. If there's no line number, the interpreter assigns it the number -1 ($8000) and the commands are executed immediately, in "immediate mode". The <code>RUN</code> command executes the stored program from the lowest line number. Atari BASIC allows all commands to be executed in both modes. For example, <code>LIST</code> can be used inside a program, whereas in many interpreters this would be available in immediate mode only.

During entry, keywords can be abbreviated using the pattern set by [[Palo Alto Tiny BASIC]], by typing a period at any point in the word. So <code>L.</code> is expanded to <code>LIST</code>, as is <code>LI.</code>. Only enough letters have to be typed to make the abbreviation unique, so <code>PLOT</code> requires <code>PL.</code> because the single letter P is not unique. To expand an abbreviation, the tokenizer searches through its list of reserved words to find the first that matches the portion supplied. More commonly used commands occur first in the list of reserved words, with <code>REM</code> at the beginning (it can be typed as <code>.</code>). When the program is later <code>LIST</code>ed it will always write out the full words with three exceptions: <code>PRINT</code> has a synonym, <code>?</code>; <code>GOTO</code> has a synonym, <code>GO TO</code>; and <code>LET</code> has a synonym which is the empty string (so <syntaxhighlight lang="basic" inline>10 LET A = 10</syntaxhighlight> and <syntaxhighlight lang="basic" inline>10 A = 10</syntaxhighlight> mean the same thing). These are separate tokens, and so will remain as such in the program listing. MS BASICs also allowed <code>?</code> as a short-form for <code>PRINT</code>, but this used the same token so it expanded back to {{code|PRINT}} when {{code|LIST}}ed, treating it as an abbreviation, not a synonym.

===Tokenizer===
When the user presses {{keypress|RETURN}} while editing, the current line is copied into the BASIC Input Line Buffer in memory between $0580 and $05FF.{{sfn|Crawford|1982|p=10.3}} Atari BASIC's [[token (parser)|tokenizer]] scans the text, converting each keyword to a single-byte token (for example, {{code|PRINT}} is $20),{{sfn|Crawford|1982|p=10.6}} each number to a six-byte floating point value, each variable name to an index into a table, and so on, until the line is fully turned into an easy to interpret format. The result is stored in an output buffer located at the first 256 bytes of the lowest available free memory, pointed to by the LOMEM pointer stored at $80, $81.{{sfn|Crawford|1982|p=10.3}} The output from the tokenizer is then relocated. The program is stored as a [[parse tree]].{{efn|Although the parse tree is implemented as a set of tables, which is really an implementation detail.}}

Shepardson referred to this complete-tokenizing concept as a "pre-compiling interpreter".{{sfn|Wilkinson|O'Brien|Laughton|1983|p=5}} The resulting tokenized code eliminates any parsing during runtime, making it run faster. It has the disadvantage that small constants, like 0 or 1, are six bytes each, longer than the original text.

A set of pointers (addresses) indicates various data: variable names are stored in the ''variable name table'' (VNTP &ndash; $82, $83) and their values are stored in the ''variable value table'' (pointed to at VVTP &ndash; $86, $87). By [[indirection|indirecting]] the variable names in this way, a reference to a variable needs only one byte to address its entry into the appropriate table. String variables have their own area (pointed to at STARP &ndash; $8C, $8D) as does the runtime stack (pointed to at RUNSTK &ndash; $8E, $8F) used to store the line numbers of looping statements (<code>FOR...NEXT</code>) and subroutines (<code>GOSUB...RETURN</code>). Finally, the end of BASIC memory usage is indicated by an address stored at MEMTOP &ndash; $90, $91) pointer.

===Math functions===
Atari BASIC includes three trigonometric functions: sine, cosine, and arc tangent. <code>DEG</code> and <code>RAD</code> set whether these functions use radians or degrees, defaulting to radians. Eight additional functions include rounding, logarithms, and square root. The random function, <code>RND</code>, generates a number between 0 and 1; the parameter not being used.

===String handling===
Atari BASIC copied the string-handling system of [[HP Time-Shared BASIC|Hewlett-Packard BASIC]],<ref>{{cite book |title=HP 2000/Access BASIC Reference Manual |publisher=Hewlett Packard |date=May 1976 |pages=e |url=http://bitsavers.org/pdf/hp/2000TSB/22687-90001_AccessBasic9-75.pdf }}</ref> where the basic data type is a single character, and strings are arrays of characters. Internally, a string is represented by a pointer to the first character in the string and its length. To initialize a string, it must be DIMensioned with its maximum length. For example:

<syntaxhighlight lang="basic">
10 DIM A$(20)
20 PRINT "ENTER MESSAGE: ";
30 INPUT A$
40 PRINT A$
</syntaxhighlight>

In this program, a 20 character string is reserved, and any characters in excess of the string length will be truncated. The maximum length of a string is 32,768 characters. There is no support for arrays of strings.

A string is accessed using array indexing functions, or [[array slicing|slicing]]. <code>A$(1,10)</code> returns a string of the first 10 characters of <code>A$</code>. The arrays are 1-indexed, so a string of length 10 starts at 1 and ends at 10. Slicing functions simply set pointers to the start and end points within the existing allocated memory.

Arrays are not initialized, so a numeric array or string contains whatever data was in memory when it was allocated. The following trick allows fast string initialization, and it is also useful for clearing large areas of memory of unwanted garbage. Numeric arrays can only be cleared with a FOR...NEXT loop:

<syntaxhighlight lang="basic">
10 REM Initialize A$ with 1000 characters of X
20 DIM A$(1000)
30 A$="X":A$(1000)=A$:A$(2)=A$
</syntaxhighlight>

String concatenation works as in the following example. The target string must be large enough to hold the combined string or an error will result:

<syntaxhighlight lang="basic">
10 DIM A$(12),B$(6)
20 A$="Hello ":B$="there!"
30 A$(LEN(A$)+1)=B$
40 PRINT A$
</syntaxhighlight>

Values in DATA statements are comma-delimited and untyped. Consequently, strings in DATA statements are not typically enclosed by quote marks. As a result, it is not possible for data items to contain a comma but they can incorporate double-quotes. Numeric values in DATA statements are read as strings or as numbers according to the type of the variable they are read into. The READ statement cannot be used with array variables.

===Input/output===
The Atari [[operating system|OS]] includes a subsystem for [[peripheral]] device input/output (I/O) known as CIO (Central Input/Output).  Most programs can be written independently of what device they might use, as they all conform to a common interface; this was rare on home computers at the time. New device drivers could be written fairly easily that would automatically be available to Atari BASIC and any other program using the Atari OS, and existing drivers could be supplanted or augmented by new ones. A replacement {{mono|E:}}, for example could displace the one in ROM to provide an 80-column display, or to piggyback on it to generate a [[checksum]] whenever a line is returned (such as used to verify a type-in program listing).

Atari BASIC supports CIO access with reserved words {{mono|OPEN&nbsp;#, CLOSE&nbsp;#, PRINT&nbsp;#, INPUT&nbsp;#, GET&nbsp;#, PUT&nbsp;#, NOTE&nbsp;#, POINT&nbsp;#}} and {{mono|XIO&nbsp;#}}. There are routines in the OS for simple graphics drawing functions but not all are available as specific BASIC keywords. {{mono|PLOT}} and {{mono|DRAWTO}} for line drawing are supported while a command providing area fill for primitive linear geometric shapes is not.  The fill feature can be used through the general CIO entry point, which is called using the BASIC command {{mono|XIO}}.

The BASIC statement {{mono|OPEN&nbsp;#}} prepares a device for I/O access:
<syntaxhighlight lang="basic">
10 REM Opens the cassette device on channel 1 for reading in BASIC
20 OPEN #1,4,0,"C:MYPROG.DAT"
</syntaxhighlight>

Here, {{mono|OPEN&nbsp;#}} means "ensure channel 1 is free," call the {{mono|C:}} driver to prepare the device (this will set the cassette tape spools onto tension and advance the heads keeping the cassette tape player "paused"). The {{mono|4}} means "read" (other codes are {{mono|8}} for write and {{mono|12 {{=}} 8 + 4}} for "read-and-write"). The third number is auxiliary information, set to 0 when not needed. The {{mono|C:MYPROG.DAT}} is the name of the device and the filename; the filename is ignored for the cassette driver. Physical devices can have numbers (mainly disks, printers and serial devices), so "{{mono|P1:}}" might be the plotter and "{{mono|P2:}}" the daisy-wheel printer, or "{{mono|D1:}}" may be one disk drive and "{{mono|D2:}}" and so on. If not present, 1 is assumed.

The LPRINT statement sends a string to the printer.

A is read by {{mono|PEEK}}ing memory locations maintained by the keyboard driver or by opening it as a file (e.g. {{code|2=basic|OPEN 1,4,0,"K:":GET #1,A$}}). The latter waits for a keypress.

Typing {{kbd|DOS}} from BASIC exits to the [[Atari DOS]] command menu. Any unsaved programs are lost unless a memory-swapping file feature has been enabled on the current disk. There is no command to display a disk directory from within BASIC; this must be done by exiting to DOS.

===Graphics and sound===
Atari BASIC supports sound, (via the {{mono|SOUND}} statement), graphics ({{mono|GRAPHICS, SETCOLOR, COLOR, PLOT, DRAWTO}}), and controllers ({{mono|STICK, STRIG, PADDLE, PTRIG}}).{{sfn|Manual|1980|p=54}} The {{mono|SOUND}} statement sets one of hardware's 4 square-wave channels with parameters for volume, pitch and distortion.

Advanced capabilities of the hardware such as higher pitch resolution, high-pass filters, digitised sound and waveforms, player/missile graphics ([[sprite (computer graphics)|sprites]]), redefined character sets, scrolling, and custom graphics modes are not supported by BASIC; these will require machine language routines or PEEK/POKE statements. A few of the 16 basic character/graphics modes supported by the hardware cannot be simply accessed from BASIC on the Atari 400/800 as the OS ROMs do not support them. These include some multicolour character modes (ANTIC modes 4 & 5), descender character mode (ANTIC mode 3) and the highest resolution 2 and 4-color modes (ANTIC modes C & E, 160x192 pixels). The only way to access them is via {{mono|PEEK/POKE}} or machine language, setting the ANTIC registers and Display List manually. The OS ROMs on the XL/XE added support for these modes except for ANTIC mode 3, which requires a character set redefined in RAM to operate correctly.<ref>{{cite web|title=ATR: chpt.15: Display Lists|url=http://www.atarimax.com/freenet/freenet_material/12.AtariLibrary/2.MiscellaneousTextFiles/showarticle.php?44}}</ref>

Bitmap modes in BASIC are normally set to have a text window occupying the last four rows at the bottom of the screen so the user may display prompts and enter data in a program. If a 16 is added to the mode number invoked via the GRAPHICS statement, the entire screen will be in bitmap mode (e.g. GRAPHICS 8+16). If bitmap mode in full screen is invoked Atari BASIC will gracefully switch back into text mode when program execution is terminated, avoiding leaving the user with an unresponsive screen that must be escaped by typing a blind command or resetting the computer.

Bitmap coordinates are in the range of 0 to maximum row/column minus one, thus in Mode 6 (160x192), the maximum coordinates for a pixel can be 159 and 191. If Atari BASIC attempts to plot beyond the allowed coordinates for the mode a runtime error occurs.