Run BASIC Documentation

Run BASIC Documentation - Build 2.19
Copyright 2007 Shoptalk Systems
http://www.runbasic.com

Contents

What is Run BASIC?
What's so great about Run BASIC?
Differences from desktop programming tools
Session Timeouts
The HTML Statement
Graphics
Files
Statements and Functions
Graphics methods
Quick start guide for BASIC programmers

What is Run BASIC?

Run BASIC is a special programming language just for web programming. It lets you create programs that run in a web page but without the complexity and restrictions of other web programming approaches. With Run BASIC you can create interactive applications without understanding gateway programming (CGI), Perl or PHP, sessions, cookies, and state management, etc. Run BASIC uses a new version of the Liberty BASIC compiler and runtime support. The syntax is based on Liberty BASIC, but some of the commands are not finished and some are just different because of the web programming nature of Run BASIC.

What's so great about Run BASIC?

We're glad you asked. Run BASIC lets you create programs that run in a web browser. You don't need to learn any special web technologies to make this work. If you are familiar with the BASIC programming language you can create web programs quickly and easily.

Differences from desktop programming tools

Run BASIC doesn't do windows (this is not referring to Microsoft Windows). It is a BASIC for programming in a web browser. Your programs appear as part of a web page; an interactive web page.

Run BASIC works on popular web browsers for Windows, Linux and Mac OS X. What about PDAs and smartphones? At this time we don't officially support these, but try yours. It may work!

At this time, the standard style of programming for Run BASIC is the classic BASIC procedural style. Using PRINT and INPUT to interact with the user is the tried and tested way, and we also add an HTML statement which works just like a PRINT statement but which allows you to embed HTML in your output to do some fancy things.

Here is a very short program that would work just as well in QBasic or Run BASIC:

input "Enter first number to add"; firstNum
input "Enter second number to add"; secondNum
print firstNum;"+";secondNum;"=";firstNum+secondNum
end

The ability to add text fields and editors, checkboxes, lists, and other similar GUI things is not supported in this initial release of Run BASIC. This will come in the near future.

What about games and animation? There are plans to support some sort of Ajax-style graphical animation and it may become possible to create some simple games, but the web browser is not best place to create smoothly animated games. Liberty BASIC is much better suited to this sort of thing. See http://www.libertybasic.com

Session Timeouts

Since Run BASIC is hosted on a web server and a lot of people are using it we need to manage memory resources. So if you are using Run BASIC and then you stop using it for 20 minutes your session will time out. If that happens to you and you wanted to keep your code you can usually just click on the back button in your browser until you see your code again. Then copy the code into your clipboard to rescue it from oblivion.

The HTML Statement

Run BASIC has a special variant of PRINT but it's called HTML. The reason for this is because when you PRINT something you expect it to be displayed as straight text. So if we simply output the text straight into the web page then characters like < and & will cause problems for the output. So, we designed the PRINT statement to properly display text without surprises. If you want to put HTML tags or Javascript into the page use the HTML statement. Here's an example:

print "This will not be bold"
html "This will be bold"

When you run this you will see:

This will not be bold.
This will be bold.

Another point to remember is that unlike the PRINT statement, the HTML statement does not permit the use of a trailing semicolon to suppress new line. The reason for this is that Run BASIC assumes when you're using HTML that you want explicit control over output. If you want a new line, just put in a tag like so:

html "Insert a new line here. "

Graphics

Run BASIC has an easy graphics system. You can draw graphics and then just insert them into a page using the RENDER statement.

Here is a simple example:

graphic #counting, 100, 100
#counting size(5)
for x = 1 to 10
#counting set(x*10, x*x)
next x
render #counting
end

This program draws 10 small 5 pixel large black bloxes on a curve. You can render more than one graphic in your program's output. For example if I move the RENDER statement inside the loop as below there will be 10 different graphic images displayed on the web page.

graphic #counting, 100, 100
#counting size(5)
for x = 1 to 10
#counting set(x*10, x*x)
print "graphic "; x
render #counting
next x
end

Notice to Liberty BASIC programmers: Graphics commands in Run BASIC use the same syntax as Liberty BASIC v5.0 (still in development). Instead of these formats:

print #handle, "command param1 param2"

Or:

#handle "command param1 param2"

There is this new syntax:

#handle command(param1, param2)

The old syntax will also still work. ;-)

Files

This free Run BASIC web site supports a virtualized filesystem. You can open files, read and write to them, and close them. However they are not real files and they do not persist past the session's own life cycle (20 minutes after the last user action).

File paths are also virtualized. If you specify a file named 'c:\mysubdir\myfile.txt' the filename is actually the entire string. The DefaultDir$ variable from Liberty BASIC is unsupported.

Statements and Functions

This section explains briefly material that is not meant to be a tutorial. BASIC programmers will be familiar with most of the material below. If you want to learn the essentials of programming, go to the Run BASIC site and click on the Learn tab for a high level introduction. http://www.runbasic.com/?_page=learn

The following lists are subject to change. Any item that is marked Not implemented yet will probably be implemented before long, but it may be that some may not be included at all on this free site. In some cases the feature is implemented but not completely working. There may be some things from Liberty BASIC that will also be included in Run BASIC that are not listed below. Feel free to inquire about your favorite command if it is missing.

Keywords for statements and functions below are in uppercase, but they do not need to be uppercase when coding.

Statements

CALL subname[, param1[, param2...]] - Invoke subname with one or more parameters
CASE expr1[,expr2...] - Execute the code that follows if one or more expressions match the SELECT expression (See SELECT CASE)
CLOSE #handle - Close the file or object #handle
CLS - Clear the output area of the web page
DATA item1[,item2...] - Define data items for the program
DIM name(size1[, size2...]) - Dimension an array of one or more dimensions of size
ELSE - Specify an ELSE section in an IF THEN/END IF block
END - End execution of program
END IF/SUB/FUNCTION/SELECT- Specify the end of an IF/SUB/FUNCTION/SELECT block
EXIT FOR - Quit executing code in the current FOR/NEXT loop and continue with the code following
EXIT WHILE - Quit executing code in the current WHILE/WEND loop and continue with the code following
FIELD #handle, length1 as var1[, length2 as var2...] - Define fields for a random access file #handle
FILES - Not Yet Implemented
FOR x = a TO b [STEP c] - Loop while counting from a to b with optional counting step of c
FUNCTION fn([param1[, param2...]]) - Define a function named fn with optional parameters
GET #handle, recNum - Read record recNum from open random access file #handle
GETTRIM #handle, recNum - Same as GET but strips leading and trailing spaces from field data
GLOBAL var1[,var2...] - Define one or more variables to be globally visible.
GOSUB label - Transfer control to the code immediately after label (See RETURN)
GOTO label - Transfer control to the code immediately after label
GRAPHIC #handle, width, height - Create a graphic object named #handle of width and height
HTML expr - Escape expr into the display output so that HTML tags are not rendered as plain text
IF expr THEN statement - If expr is true, then execute statement
IF expr THEN - If expr is true then begin an IF THEN/END IF block
INPUT [expr;]var1[,var2...] - Ask the user for data into 1 or more vars. Optionally display expr as a prompt.
INPUT #handle, var1[,var2...] - Read data from file #handle into 1 or more vars.
LINE INPUT var1 - Ask the user for complete line of text to be placed in var1.
LINE INPUT #handle, var1 - Read an entire line of text from file #handle into var1. Not implemented yet
LOADIMAGE #handle|nameExpr$, path$ - Load an image file from path$ naming it #handle or nameExpr$. Not implemented yet
NEXT [x] - Specify end of FOR loop with optional variable identifier
ONERROR label - Specify an error handler label. Not implemented yet
OPEN expr$ FOR mode AS #handle - Open a file or window #handle using expr$ and mode
PRINT expr$[;] - Put expr$ into the display output. An optional semicolon suppresses end of line.
PUT #handle, recNum - Write record recNum into open random access file #handle
READ var1[,var2...] - Get information from DATA statements and place into 1 or more vars
RENDER #handle - Place an image tag into the display output to display the graphic named #handle
RESTORE - Reset the DATA pointer back to the beginning
RETURN - Resume execution after the last GOSUB statement
SELECT CASE expr - Begin a select block using expr (see CASE)
SUB subName[, param1[, param2...]] - Define a subroutine subName with optional parameters
UPLOAD promptExpr$, path$ - Insert an upload widget into the display output. The uploaded file's name is in path$.
WAIT - Stop and wait for an event. Not useful in Run BASIC at this time.
WHILE expr - Begin a WHILE/WEND loop. Loop if and as long as expr evaluates to true (non zero).

Functions

ABS(x) - Absolute value of x
ACS(x) - Arccosine of x
ASC(a$) - ASCII value of first character of string a$
ASN(x) - Arcsine of (x)
ATN(x) - Arctangent of (x)
CHR$(x) - String containing character of ASCII value x
COS(x) - Cosine of x
DATE$([v]) - String or number representing a date with optional modifier v
DECHEX$(x) - Hexadecimal string for decimal value of x
EOF(#handle) - Return 1 if open file #handle is at end, else return 0
EVAL$(code$) - Execute BASIC expression in code$ Not implemented yet
EVAL(code$) - Execute BASIC expression in code$ Not implemented yet
EXP(x) - Return e^x. e=2.7182818
HEXDEC(h$) - Decimal number from hexadecimal string
INPUT$(#handle, n) - Next n characters from open file #handle Not implemented yet
INPUTTO$(#handle, d$) - Characters up to delimeter d$ in open file #handle Not implemented yet
INSTR(a$, b$ [,i]) - Index of b$ in a$ with optional starting index i
INT(x) - Integer part of x
LEFT$(a$, i) - First i characters of a$
LEN(a$) - Count of characters in a$
LOC(#handle) - Current position of filestream for open file #handle
LOF(#handle) - Number of characters/bytes for open file #handle
LOG(x) - Natural logarithm of x
LOWER$(a$) - a$ converted to lowercase
MAX(x, y) - The larger of x or y
MID$(a$, x [, y]) - Contents of a$ starting at x, with optional length y
MIN(x, y) - The lesser of x or y
MKDIR(p$) - Create directory path p$. Return 1 or 0 for failure or success respectively. Not implemented yet
RIGHT$(a$, i) - Last i character from string a$
RMDIR(p$) - Delete director path p$. Return 1 or 0 for failure or success respectively. Not implemented yet
RND(n) - Return a pseudorandom value between 0 and 1
SIN(x) - Sine of x
SPACE$(i) - A string containing i space characters
SQR(x) - Square root of x
STR$(x) - String representation of number x
TAN(x) - Tangent of x
TIME$([v]) - Number or string representing time with optional modifier v
TRIM$(a$) - a$ without leading or trailing spaces
UPPER$(a$) - a$ converted to uppercase
USING$(f$, x) - Formatted string of v using f$ as a template.
VAL(a$) - a$ converted to a numeric value
WORD$(a$, n[, d$]) - nth word from a$ using whitespace as delimiter, with optional delimiter d$

Graphic Methods

There are various methods that you can call against a graphics object to perform drawing operations. Turtle graphics operations are supported.

#handle BOX(x, y) - Draw a box from the current position to x, y
#handle CIRCLE(r) - Draw a circle of radius r at the current position
#handle CLS(["color"] | [r, g, b]) - Clear the graphics area to white, or to named color, or to an RBG color
#handle COLOR("color" | [r, g, b]) - Set the drawing color to a named color, or to an RGB color
#handle DOWN() - Set the drawing pen to down (this is the default)
#handle DRAWIMAGE("name", x, y) - Draw the image named "name" at x, y
#handle FILL("color" | [r, g, b]) - Like CLS() but it doesn't actually forget previously drawn graphics
#handle FONT("fontname", pointSize [,"bold"][, "italic"]) - Specify a font by name and size to use for drawing text. Italic and bold are optional
#handle GO(d) - Make the turtle go distance d
#handle LINE(originX, originY, destX, destY) - Draw a line from originX, originY to destX, destY
#handle NORTH() - Tell the turtle to point to the top of the graphic object.
#handle PLACE(x, y) - Set the position to be x, y
#handle SET(x, y) - Draw a point of the currently set size at x, y
#handle SIZE(s) - Set the size of the drawing pen to s pixels
#handle TURN(a) - Turn the turtle a degrees to the right. a can be negative to turn to the left
#handle UP() - Set the drawing pen to up (don't draw)
#handle X() - Return the current position x
#handle Y() - Return the current position y

To draw text at the current position use this form:

#handle "\this text will show up"

Segment related graphics commands

#handle DELSEGMENT(n| "name") - Delete the segment numbered n or named "name"
#handle DISCARD() - Forget all drawing operations in the current segment
#handle FLUSH(["name"]) - Make a new segment from drawing items since the last segment was made, optionally name the segment "name"
#handle REDRAW(["name"]) - Redraw all the drawing segments. Optionally redraw just one named segment.
#handle SEGMENT() - Return the current segment ID

Quick start guide for BASIC programmers

Run BASIC is very similar to other BASICs. Here are some things we've noticed that people are stumbling on when they try Run BASIC. In addition to the items below, also try http://www.runbasic.com/?_page=learn

Comments

Run BASIC is not C so the following are not valid:

    //this is not a valid comment
    /* this is not a valid comment */
    #this is not a valid comment

Instead use either of these:

'this is a comment
rem this is a comment

Line numbers

Run BASIC let's you use line numbers. They are useful for GOTOs or GOSUBs, but they don't have to be in order, so this works:

    30 print "hello"
    20 input "What's your name"; n$
    10 print "Nice to meet you "; n$

The preferred way is to use branch labels. A branch label is a description between [ and ] like so:

    [start]
    [a branch label]
    etc.

So for example:

[start]
 a = a + 1
 print a
 if a < 10 then [start]

INPUT

Don't use a comma before the variable. Use a semicolon like so:

input "Type something and hit Enter"; stuff$

PRINT

Many people like to use commas as shown, but Run BASIC doesn't support these, yet.

    'Don't use commas like this!
    print a, b, c

    'You can use semicolons
    print a; " "; b; " "; c

PRINT USING

Run BASIC has an alternate way of formatting numbers. It looks like this:

print using("###.#####", 1/3)

IF THEN

It isn't okay to specify GOTO without THEN. THEN is required.

'Do it this way
 if a < b then goto 100

 'Or do it this way
 if a < b then 100

 'But... don't do it this way!
 if a< b goto 100

GOTO

The GOTO statement hates to be cut in two. GO TO is not a valid command.

SCREEN and LINE

A lot of people seem to enjoy drawing graphics. The first thing they like to do is use the QBasic SCREEN and LINE commands. These do not work. Instead try the following (and see the Graphics section):

    graphic #area, 320, 200
    #area line(50, 50, 150, 150)
    render #area

Variables

Run BASIC supports two kinds of variables:

Numeric - Numeric variables can have letters and digits (i, counter, exitFlag, etc.). No % allowed (myInt% for example).
String$ - String variables are like numeric variables but end in $ (myName$, buffer$, etc.)

Arrays

Run BASIC uses ( )'s for array syntax, not [ ]'s. For example:

    dim values(10)
    for x = 0 to 9
        values(x) = int(rnd(1)*100)
    next x

RND

In Run BASIC the RND variable doesn't exist. Instead use the RND() function, like so:

value = rnd(1)

Also the RANDOMIZE command is not supported, yet.

WAIT

If you're used to using the WAIT command from Liberty BASIC, this isn't supported at this time. It will be pretty soon though.