The basics

This article contains general information about RFO-BASIC!.

The language
RFO-BASIC! is an interpreted programming language. That is, when you develop an app in BASIC, it is not "compiled" into machine code but remains in text form. The BASIC interpreter reads statements in sequence and carries out your wishes. (The separate BASIC compiler in fact produces an APK file consisting of your BASIC program and the interpreter.)

Source text
The BASIC program consists of lines. Android devices separate lines using the  character, while some external editors use the sequence ,. Here are general rules about separating a program into lines:
 * A BASIC statement must be on a single line, except that it is usually possible to type  at the end of a line and continue the statement on the next line.
 * You can put more than one BASIC statement on a line, separating them by .  (Certain statements use the   character in their syntax.  In this case, you must be careful that typing multiple statements on a line is not ambiguous.)
 * The IF statement (see Program control below) can be typed on a single line or on multiple lines, and the effects are different.
 * Programs can (and should) contain comments to help you understand them. The traditional   statement is available to introduce a line of comments.  A line starting with   is also a line of comments that is not interpreted when the program is executed.
 * A line starting with  introduces a range of comment lines.  Another such line ends the range.  This is an easy way to disable entire sections of code.  However, it is easy to create bugs that are difficult to solve, either by not terminating the range or by forgetting that you disabled the code.

Capitalization
In general, you can type in capital or lowercase letters and it doesn't make a difference, even when creating labels. For example, the variable  is the same as the variable. Internally, RFO-BASIC! converts everything into lowercase. If a program stops with a syntax error, the line that RFO-BASIC! reports will be converted into lowercase. On the other hand, the Formatter puts RFO-BASIC!'s predefined keywords into capitals, as they are shown in this manual.

There are certain situations where case is important:
 * Case is important inside literals, and RFO-BASIC! never changes it. For example:
 * Case is important when defining or specifying the keys of a bundle. (The key is the name of an element of the bundle.)
 * Case is important when making a query with the SQL statements.
 * Case is important in the names of files on the Android device.   is a different file from  .  (This is not true with files on thumbdrives or microSD cards; these use a different file system that evolved from DOS/Windows.)  An RFO-BASIC! program that lets the user specify filenames ought to post-edit the user to enforce consistent use of capital letters or lowercase.

Data types
RFO-BASIC! has only two data types, numeric and string.
 * Numeric items are always floating-point numbers. They are often used as counting numbers and can be incremented and decremented with exact results.  However, some mathematical operations lead to round-off errors and inexact results.  For example,   is not exactly 0.32.  You should use one of BASIC's rounding functions before testing for an exact numeric value.
 * String items are a sequence of characters. They can contain arbitrary text, including 16-bit UNICODE characters, and can be as long as needed.
 * "Logical items" are numeric items, allowed in certain BASIC statements, where a value of 0 is interpreted as FALSE, and any other value is interpreted as TRUE. For example, the shown in the IF, WHILE, and UNTIL statements can be a logic formula, or you can store the result of that computation  in a numeric variable and you can provide the variable in the statement.

Program control
Unlike classic BASIC, RFO-BASIC! programs do not have line numbers, and adding line numbers to a program will make it fail. The GOTO and GOSUB statements do not specify a line number to jump to, but an alphanumeric statement label that ends with a colon. A routine to be called with GOSUB starts with a statement label (and returns to its caller by executing the RETURN statement). For example:

StatementLabel1:

GOTO and GOSUB statements are not necessary compared to classic BASIC. In addition to traditional loops using FOR and NEXT, you can code loops with the WHILE and REPEAT statements (in which a condition is tested at the start of the loop) and the DO and UNTIL statements (in which a condition is tested at the end of the loop). For each of these pairs, RFO-BASIC! provides a statement that immediately starts the next pass through the loop, and a statement that immediately exits the loop. These statements are preferable to using GOTO or RETURN to jump out of the loop. If you jump out of a loop, RFO-BASIC! does not discard information on the loop from its control stack.

Here is the complete set of looping statements:

The IF statement executes one or more BASIC statements if and only if some logical expression is TRUE: IF i>n THEN i=n : PRINT "i exceeded n"

An IF statement can be followed by ELSE to specify what to do if the logical expression is FALSE: IF i>n THEN larger=i ELSE larger=n

If the keyword THEN is the last thing on the line, then it is a multi-line IF statement. It is followed by a block of BASIC statements. They are all conditional on the value of the logical expression, until the ENDIF statement. The general form of the multi-line IF statement is as follows: IF THEN ELSEIF THEN ELSE ENDIF

Parameters
Many statements take parameters. The parameters are separated by commas. However, take care not to type a comma between the statement keyword and the first parameter. For example, the GR.COLOR statement can take six parameters: GR.COLOR 255,255,255,255,style1,paint1

Usually, you don't need to provide all the parameters. When omitting parameters at the end, you also omit the commas. For example, a GR.COLOR statement might fail to specify a drawing style or a paint: GR.COLOR 255,255,255,255

When omitting parameters in the middle, you must type the commas to show which parameters you are omitting. For example, this GR.COLOR statement changes the red-green-blue values but does not change the opacity: GR.COLOR ,0,0,255

This one changes the opacity and the drawing style but does not change the color: GR.COLOR 64,,,,style1

Usually, omitting a parameter makes no change to that aspect of the statement. There is sometimes a default behavior when you omit a parameter, which is explained in the definition of that statement.

Development environment
When you install RFO-BASIC!, it adds a shortcut to the Android device's home screen. The shortcut says RFO-BASIC! and the icon is a telescope (RFO stands for the Richard Feynman Observatory). Tap this shortcut and RFO-BASIC! starts to run.

The usual mode is to place you into the text editor. The first time you start RFO-BASIC!, the edit window already contains a file; its purpose is to welcome you to the software and give a brief introduction. Thereafter, when you start RFO-BASIC!, the edit window holds a single line (a REMark statement, which you are free to delete in favor of your own program).

You can edit whatever text is displayed using a "soft" (on-screen) keyboard or attach a physical keyboard, if your device has an OTG-style USB port. The arrow keys are useful for navigation, but you can also point to a location in the text to move the cursor there.

Some people prefer to edit BASIC programs on a PC and then load them into the Android device, using USB cable or WiFi. Third-party programs that enable this are listed on this wiki's Main Page.

Pull-down menu
Tapping the three-dot logo in the upper-right corner pulls down a menu. On the menu are:
 * Exit — This ends the session in BASIC. You can also use the task-manager button to dismiss the BASIC task.
 * Preferences — This gives you broad control over BASIC's appearance and function. For example, you can control the colors of the edit window and the size of text.
 * Load — Brings an already-written file into the edit window, which you specify by filename. BASIC displays a list of files.  You can tap the name of one of them, scroll the list, or type a filename not shown on the screen.
 * Run — This is how you start your program running.

If you have made any change to the text in the edit window, and if you command BASIC to do anything (including exit, or run the program) that might cause the text to be lost, BASIC first warns you and gives you the chance to save it in a file whose name you specify.

A good way to get started is to pull down the menu, select Load, and tap on. The legend  means this is not a file but a separate directory (folder). When you tap on it, a new list appears, which is the list of sample programs. Select a program and simply study it to see what an RFO-BASIC! program looks like and how it works. All the sample programs contain comments, and output more comments when you run them, to explain what they are doing.

Execution
When you Run your program, the edit window disappears (but your text is not lost). The Text Console appears. This screen is initially blank, but it may fill up, such as when your program executes a PRINT statement.

The BASIC program runs until it reaches an EXIT or END statement. You can force a program to stop running by pressing the BACK button on the Android device. (However, a BASIC program can intercept this key-press and do something other than stop running.) When the program stops running, any graphics it drew disappear and the Text Console reappears. If the program stops running because it encountered faulty BASIC code (a syntax error), then BASIC writes an error message to the Text Console. Pressing BACK again returns to the edit window. If possible, the point in your program that is in error is highlighted.

Creating shortcuts
When you install RFO-BASIC!, it adds a widget to your Android device. (To see the widget, go to the home screen, long-press it somewhere other than where there is an icon, and select Widgets. Then scroll to the widget with the telescope logo.)

The function of the RFO-BASIC! widget is to let you create shortcuts to BASIC programs you have written. Tapping the shortcut is easier than tapping RFO-BASIC! and using the pull-down menu to select the program to Load and run.

When you tap this widget, a form appears that asks for three pieces of information:
 * The name of the BASIC program to run when you tap the shortcut
 * (Optional) A picture that will serve as the icon for the shortcut
 * (Optional) A text legend to appear beneath the picture.

Unfortunately, there are no menus; you must type the name of the program exactly (including any pathname, if it is not in the  directory, and including capital and lowercase letters correctly). You must type the name of the picture correctly too, including its file type.

You can have as many BASIC shortcuts on the home screen as you like. However, only one RFO-BASIC task can run at any time. This means that, if you tap on a BASIC shortcut but BASIC is already running, it does not load and run the BASIC program you specified but reactivates the BASIC program that was already running.

This manual
This manual describes many of the features of RFO-BASIC!. A table of contents appears at the start of each article. To see if a specific statement is documented here, consult the Statement index.

Synopses
For each RFO-BASIC! statement, this manual gives a synopsis of the syntax (the form) of that statement. The synopsis is in code and is not exactly the way you type the statement. The synopsis follows these rules:
 * Keywords are shown in capital letters and must be typed exactly as they are shown, except that you can type capital or lowercase letters.
 * Braces  and   mean that the material between them is optional.
 * The notation  means that you can repeat the previous item an arbitrary number of times.
 * Commas, and other symbols than described above, are part of the statement and must be typed exactly as they are shown. (However, you can often omit parameters, as discussed above.)

Parameters
In the synopsis and the description, parameters are shown in angle brackets. Each parameter contains a description and a type. For example, the definition of the GR.COLOR statement shows that one of its parameters is . This means you don't type ; you type a numeric expression whose meaning is the desired intensity of the color green.

The type starts with "n" for numeric or "s" for string. There is neither prefix in the small number of cases where either is allowed. The prefix can be "l" to indicate a numeric item used as a logical item (as described above, 0 meaning FALSE and any other value meaning TRUE).

The type ends with "exp" in cases where you can type any expression of the specified type. The type ends with "var" in cases where you must provide a variable. These are the cases where the BASIC statement returns a value to the caller. The type ends with "arr" if you must type the name of an array. In cases where you must also type the  characters, these are shown in the synopsis. For statements that take a data structure such as a bundle, the parameter is "nexp" and the value of the numeric expression specifies the number of the bundle. For statements that create a bundle, the parameter is "nvar"; you must provide a variable to hold the number of the new bundle.