basic/doc/
introduction.rs

1/*!
2# Introductory Tutorial
3
464K BASIC is interactive just like it was back in 1964 when the idea of an
5ordinary person sitting in front of a terminal and directly interacting
6with a computer was revolutionary. A primary design goal for 64K BASIC
7is to capture that experience. Except with better error reporting and
8a modern input system.
9
10Begin by opening a terminal and running the executable. Double clicking
11the executable from a GUI desktop often works as well. If you get the
12following, you are ready for this tutorial. If not, ask the internet
13how to run command-line programs on your particular operating system.
14
15<pre><code>&nbsp;  64K BASIC
16&nbsp;  READY.
17&nbsp;  █
18</code></pre>
19
20Type CTRL-D to exit 64K BASIC.
21
22When you see the `READY` prompt, 64K BASIC is ready to accept a statement.
23A statement describes the work you want the computer to do. Let's tell the
24computer to print something. For this tutorial, I'll mark lines that you
25type with a "`>`". Go ahead and try your first statement. Type in the
26marked line followed by ENTER.
27
28<pre><code>&nbsp;  READY.
29&nbsp;> print "Hello World"
30&nbsp;  Hello World
31&nbsp;  READY.
32</code></pre>
33
34Entering a statement which executes immediately is called direct mode.
35To solve interesting problems, you'll have to assemble many statements
36together into a program. You put a statement into a program by assigning
37it a line number. To do this, simply precede the statement with any
38decimal integer between 0 and 65529 inclusive.
39
40<pre><code>&nbsp;> 10 print "Hello World"
41</code></pre>
42
43Nothing happens. This is called indirect mode. The statement is saved to
44be executed later. Let's try a couple new statements that you'll use a lot.
45`LIST` will list the program. `RUN` will run the program.
46
47<pre><code>&nbsp;> LIST
48&nbsp;  10 PRINT "Hello World"
49&nbsp;  READY.
50&nbsp;> RUN
51&nbsp;  Hello World
52</code></pre>
53
54Now that we have a program in memory, we can add more lines or edit existing
55lines. To edit a line, type the line number then press TAB. The line will
56be loaded into the input buffer for you to edit.
57
58<pre><code>&nbsp;> 10<i>{TAB}</i>
59&nbsp;> 10 PRINT "Hello World"█
60</code></pre>
61
62Linux users may have already noticed the input system is similar to readline
63and even uses your `inputrc` file. Feel free to explore these capabilities,
64but for now you only need the basics: TAB, BACKSPACE, CTRL-C, CTRL-D,
65and the arrow keys.
66
67You may be working out a problem in direct mode which doesn't succeed on the
68first try. You can access a history of direct mode statements with the up/down arrows.
69
70<pre><code>&nbsp;> PAINT "Hello World"
71&nbsp;  <b>?SYNTAX ERROR</b>
72&nbsp;> <i>{UP}</i>
73&nbsp;> PAINT "Hello World"█
74</code></pre>
75
76You can `SAVE` a program to the filesystem or `LOAD` one that you previously
77saved or downloaded. Filenames are relative to the current directory of your
78operating system when 64K BASIC was started. The `NEW` command erases the
79program in memory.
80
81<pre><code>&nbsp;> 10 print "Hello World
82&nbsp;> save "hello.bas
83&nbsp;  READY.
84&nbsp;> new
85&nbsp;  READY.
86&nbsp;> list
87&nbsp;  READY.
88&nbsp;> load "hello.bas
89&nbsp;  READY.
90&nbsp;> list
91&nbsp;  10 PRINT "Hello World"
92&nbsp;  READY.
93</code></pre>
94
95Let's create a multi-line program for the last example of this tutorial.
96The program will ask the user for a number, print its square root, and repeat
97indefinitely. Because this is an infinite loop, the program will run forever
98or until it's interrupted. Typing CTRL-C interrupts a program.
99
100<pre><code>&nbsp;> 10 input "Your number"; a
101&nbsp;> 20 print "The square root of" a "is" sqr(a)
102&nbsp;> 30 goto 100
103&nbsp;> run
104&nbsp;  <b>?UNDEFINED LINE IN 30:9</b>
105&nbsp;> list 30
106&nbsp;> 30 GOTO <u>100</u>
107&nbsp;  READY.
108&nbsp;> 30 GOTO 10 <i>{Remember you can use TAB here}</i>
109&nbsp;> run
110&nbsp;  Your number? -8
111&nbsp;  The square root of-8 is NaN
112&nbsp;  Your number? 9
113&nbsp;  The square root of 9 is 3
114&nbsp;  Your number? <i>{CTRL-C}</i>
115&nbsp;  <b>?BREAK IN 10</b>
116&nbsp;  READY.
117</code></pre>
118
119Line 30 was intentionally wrong to demonstrate a compiler error. 64K BASIC
120has two types of errors, compiler errors and runtime errors. A lot more
121information is available at compile time which enables underlining the
122offending section when listing a program. Runtime errors will only display
123the line number.
124
125This concludes the introductory tutorial. The remainder of this manual is
126reference material covering everything 64K BASIC can do.
127
128*/