How BASIC! Gets Started - RFO-BASIC/Basic GitHub Wiki

Introduction

This is a quick summary of what happens when you start BASIC! I didn't write it for the Wiki; it was a brief answer to some specific questions I was asked. Therefore it lacks detail and consistency and all those other things a good Wiki page needs. However, on the theory that anything is better than nothing, I've reproduced that write-up here, in all its glorious brevity. You deserve better, and, hopefully, some day you'll get it.

From Basic.java to Editor.java

When you start BASIC! from the launcher, the Android runtime starts the class named Basic in Basic.java. There is no explicit constructor, so the Java virtual machine runs Java's default constructor -- that just initializes all the variables,

The Basic class is an Activity, so the Android runtime invokes the method onCreate() in Basic.java. This method does more initialization, then decides if you're trying to run a program in a standalone apk (createForAPK()) or run standard BASIC! (createForSB()). If standard BASIC!, it determines if are you running a program from a shortcut, or running the Editor. Basic might start a background thread (class Loader, a subclass of AsyncTask).

If you're running a program, Basic (or Loader) sends an Intent to start either the AutoRun class in AutoRun.java or the Run class in Run.java. If you're running the Editor, Basic (or Loader) sends an Intent to start the Editor class in Editor.java. Let's say you're running the Editor. [TODO: describe the other start-up paths: standalone APK, launcher short-cut, file browser "share", crash recovery]

Editor is an Activity subclass, so same thing again: Java runs the constructor, Android runs onCreate(). Editor.java has an onResume(), so Android runs that, too. Eventually you get the Editor screen, with a menu. You can write a program, or select LOAD from the menu.

From the Editor to the Interpreter

The Editor menu has a RUN option. When you tap RUN, the menu handler invokes an Editor method called Run(). That invokes a method in Basic.java, loadProgramFromString(). That creates an AddProgramLine object, and then passes each line of the program source to that object.

AddProgramLine squeezes out spaces, forces lowercase, resolves multiple commands on a line (the ':' separators), and so on -- all the preprocessor stuff. It puts the text of each command in a ProgramLine object (defined in Run.java) and puts all of the ProgramLines into the ArrayList called lines (defined in Basic.java). preprocesses the program text and loads it into the Basic.lines array.

After that's done, the Editor launches Run (the Console), found in Run.java, which then creates and runs the Interpreter.

When AddProgramLine is done loading, the Editor sends an Intent to launch the Run Activity, in Run.Java. This is not the interpreter, it's the Console. It's an Activity, so again, Java runs the constructor and Android runs onCreate() and onResume(). (Most of the work in is in onCreate(). onResume() does not do much.)

Run builds the Console UI and then starts the Interpreter. That is, the Run object (the Console) creates a new Interpreter object. The Interpreter class is defined in Run.java. It is not an Activity, but it is a Thread. You can say that the Interpreter runs in a background Thread owned by the Console.

A Thread class must have a method called run(). (There are too many things called "run"!) The Run object (the Console) "runs the Thread". That is, it creates an Interpreter object and invokes its start() method, and the start() method indirectly invokes the run() method.

The Interpreter's run() method runs your program. First it calls PreScan(), to find all of the labels and the READ.DATA statements. Then it calls RunLoop(). RunLoop() loops through the lines of your program (the ProgramLine objects in the Basic.lines ArrayList). For each ProgramLine, RunLoop() calls StatementExecuter(). Your program is up and running.

Wrap-up

Getting the Interpreter to start running your BASIC! program is a long and complicated process. When that process is complete, the Interpreter is running as a background task. It continues to run regardless of which screen controls the User Interface: Console, Graphics, or HTML.

The Console "owns" the Interpreter. The Console always exists, even if another Activity controls the UI. When the other Activity (Graphics or HTML) finishes, Android pulls the previously running Activity off of the backstack and lets it run again.

(Last update: March 30, 2016)