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 LF character, while some external editors use the sequence CR,LF. 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 type several line termination characters in a row — resulting in vertical space in your program — to improve readability.
• You can put more than one BASIC statement on a line, separating them by :. (Certain statements use the : character in their syntax, and the character will not introduce a new BASIC statement.)
• The IF statement (see Program control) can be typed on a single line or on multiple lines, and the rules are different.
• Programs can and should contain comments to help you understand them. The traditional REM 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 I is the same as the variable i. 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: "in September"
• 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. Program1.bas is a different file from program1.bas. (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.

Indentation

In general, you can use spaces to make an RFO-BASIC! program more readable. The exceptions are the same as for capitalization (in the previous section). In these exceptions, text must be exact. Internally, RFO-BASIC! removes unnecessary spaces. If a program stops with a syntax error, the line that RFO-BASIC! reports is that version with the spaces removed. The Formatter does not modify spacing.

You might add spaces to align parameters in consecutive statements to make them easy to compare.

This manual indents a block of statements, such as in the multi-line IF statement discussed shortly, and in user-defined functions. This style is entirely optional; you may prefer more indentation or none at all.

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, 3.2*0.1 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 <lexp> 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 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 (which test a condition at the start of the loop) and the DO and UNTIL statements (which test a condition at the end of the loop).

For each of these pairs, RFO-BASIC! provides a statement that starts the next pass through the loop (effectively, ignoring the remainder of the statements in the loop to reach the statement that ends the loop), and a statement that exits the loop. These statements are preferable to using GOTO or RETURN to jump out of the loop.

Here is the complete set of looping statements:

	Starts the loop	Ends the loop	Starts the next pass through the loop	Exits the loop
While incrementing an index variable	FOR <nvar>=<nexp> TO <nexp>	NEXT <nvar>	F_N.CONTINUE	F_N.BREAK
Testing a condition before looping	WHILE <lexp>	REPEAT	W_R.CONTINUE	W_R.BREAK
Testing a condition after looping	DO	UNTIL <lexp>	D_U.CONTINUE	D_U.BREAK

IF statement

The IF statement executes one or more BASIC statements if and only if some logical expression is true:

IF i>n THEN PRINT "i exceeded n" : i=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

However, single-line IF statements cannot be nested: The statement following the keyword ELSE cannot begin with IF, nor can ELSEIF be used. Such constructions require a multi-line IF statement, discussed next.

Multi-line IF

If a line begins with IF and ends with THEN, 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 <lexp1> THEN
 <statements>
ELSEIF <lexp2> THEN
 <statements>
! There may be additional ELSEIF blocks
ELSE
 <statements>
ENDIF

Performance

Looping is time-consuming and RFO-BASIC often provides a built-in way to do the same thing. For example, to operate on individual characters of a string variable, it is more efficient to use SPLIT to divide the string into an array, operate on the array elements, and then use JOIN to reassemble a string variable. The time spent changing the form of the information is outweighed by the time not spent interpreting BASIC statements.

Parameters

Many statements take parameters. The parameters are separated by commas. For example, the GR.COLOR statement takes 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

Take care not to type a comma instead of a space between the statement keyword and the first parameter. RFO-BASIC! would interpret this as a statement that omits its first paramter, as in the third example above.

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.

Usually, RFO-BASIC! starts by placing you in the edit window. The first time you start RFO-BASIC!, the edit window already contains a file, which welcomes you to the software and gives 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 tap 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. Among the menu options are:

• Exit — This ends the session in BASIC. You can also use the Android 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 Sample_Programs(d). The legend (d) 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 the program you typed 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 where there is no 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 exact filename, including the file type (such as .bas) and type capital and lowercase letters correctly. The program normally resides in the rfo-basic/source directory; the icon normally resides in the rfo-basic/data directory. If this is not the case, you must type a pathname to the correct directory, such as ../icons/MyIcon.png if you have an icons directory that is a sibling of source and data.

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!. The banner at the top of the article contains links to all other articles. 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 <green_nexp>. This doesn't means to type <green_nexp>; instead, 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. It may use 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.