Liberty BASIC for OS/2 Notes
--------------------------------------------------------------------------------------


Design of the Language:

Liberty BASIC is designed to feel familiar to Microsoft BASIC programmers.
By this I mean the versions of BASIC named MBASIC and GWBASIC.  I wanted 
to create a tool that made long time BASIC programmers feel comfortable 
writing Windows and OS/2 programs.  To do this I tried to add windowing 
commands whose syntax that felt as much like BASIC as possible.  Liberty 
BASIC programs are similar (but not necessarily compatible) to 
MBASIC/GWBASIC programs.


The Intended Market:

Liberty BASIC is marketed as shareware.  I wanted to create an inexpensive 
package that would appeal to the casual BASIC programmer, as a protyping 
tool,  and to school teachers.  To do this, I made my it primary goal to 
produce a tool that is SIMPLE first of all.  Liberty BASIC is designed 
to work well with most school textbook examples in the BASIC programming 
language.

Because the software is created using Smalltalk/V (an extremely powerful 
tool), it is sizeable.  If you require great speed or diminutive size, 
look elsewhere.

Software developed in Liberty BASIC can be distributed royalty free if 
you register to receive the runtime engine.


Hardware requirements:

Liberty BASIC is comfortable on any machine that runs OS/2 comfortably.  
In other words you need 8 or more megabytes or RAM, and at least a few 
free megabytes of free disk space.  Liberty BASIC works best with a mouse.
There are no other special requirements.


Compatility / Incompatibility:

Much of MBASIC / GWBASIC is there, and when something isn't there I will
strive to add it, but the graphics stuff is completely different.

  Some of what's there:

    FOR . . . NEXT
    WHILE . . . WEND
    FIELD, GET, PUT (slightly modified though, and better)
    IF . . . THEN . . . ELSE . . .

  Some of what's not there:

    ON . . . GOTO . . .
    READ, DATA
    ON ERROR . . .
    LOCATE

  In the works . . .

    Communications support
    DEFFN( )   - multi-line functions with local vars


The PRINT and INPUT statements are there, and simple text-mode programs
can be written, but take a look at the included DRAW.BAS and CONTACT.BAS
programs for some handily written GUI programs.

Some have asked me for PEEK and POKE.  I have not included them because 
OS/2 and PM take care of the low level stuff, and those statements are 
really not appropriate (or safe) in a virtualized GUI environment.  
However the ability to make API calls and to access external DLLs is 
definitely in the list of future improvements.


Variables and Arrays:

Liberty BASIC has very simple variable typing.  Both variableName and
variableName$ conventions are supported, but variables are actually
untyped.  Explicitly defined integers and double precision variables are
not supported.

Numeric types are automatically truncated to integer types if there is no
fraction part for efficiency, and when a number is a float, an available
math coprocessor is automatically used.  Integers can be HUGE (try the
FACTORIL.BAS program)!!

Strings can be as large as available memory!

Arrays are typed.  They expect a numeric data type if there is no $ 
character on the end of the array name, and they expect a string type 
if there is a $ character.  Arrays can be single and double dimensioned 
only (no three or four dimensional arrays, sorry), but they can be as 
large as available memory!

A powerful SORT command provides a knockout easy way to sort single and 
double dimensioned arrays.  When a double dimensioned array is sorted, 
you pick the column, and each row of data is sorted by its information 
in that column.  This gives you lightning fast, database-like sorting 
cabability.


Line Numbers:

Line numbers are optionally supported in Liberty BASIC.  You can number 
program lines in the completely traditional way (ie. 10, 20, 30, etc) or 
you can dispense with line numbers and use alphanumeric branch labels 
instead.  Instead of GOTO 1435, your code might read GOTO [response], or 
maybe GOTO [redrawGraphic].  A branch label can be any unique combination 
of letters and digits inside a pair of square braces.  No spaces are 
allowed.  The sample programs included use this convention.


File handling:

File handle names can be any alphanumeric combination of letters and
digits following a # character, for example here is #data as the file
handle:

  OPEN "custdata.dat" for random as #data

Now anywhere in Microsoft BASIC where the file handle is used, the #
character is omitted, but you must remember to use the # character when
referring to file handles in Liberty BASIC.  For example, see the FIELD
statement example below.

Sequential file handling is as expected.  Random access looks almost just
like Microsoft's, but is easier.  Here we dispense with LSET and RSET and
all those crazy functions for moving information in and out of FIELD 
statement variables.

In Liberty BASIC, a FIELD statement looks like this:

  FIELD #data, 10 as orderCode$, 7 as idNumber, 20 as customer$, . . . 

Before a PUT, simply assign orderCode$ to be a string value, assign
idNumber to be a numeric type, and assign customer$ to be a string type. 
When PUT is performed, it will place ASCII, eye readable representations 
of these values into the file at the specified record number.

Later if a GET is performed, the information is read straight back into 
the variables, and numeric fields are automatically converted to numeric 
type.   There aren't any conversion steps necessary.  See CONTACT.BAS for 
an example.


Windows:

Liberty BASIC treats windows like files.  You use the OPEN command to 
open a window and you use the CLOSE command to close it.  To add controls 
to a window, you list the controls before you open the window.  Once the 
window is open, you can send commands by PRINTing to the controls, and 
you can get information from the controls by INPUTing from them.

Here's a short example:

    ' CHECKBOX.BAS
    ' This code demonstrates how to use checkboxes in your
    ' Liberty BASIC programs

    ' no main text mode window, please
    nomainwin

    ' list all the controls for our dialog box window
    button #1, " &Ok ", [quit], UL, 120, 90
    checkbox #1.cb, "I am a checkbox", [set], [reset], 10, 10, 130, 20
    button #1, " Set ", [set], UL, 10, 50
    button #1, " Reset ", [reset], UL, 50, 50
    textbox #1.text, 10, 90, 100, 24

    ' set the size for our window
    WindowWidth = 180
    WindowHeight = 160

    ' open the window
    open "Checkbox test" for dialog as #1

    ' intercept the close message and goto [quit]
    print #1, "trapclose [quit]"


[inputLoop]    ' this is where we sit idle, waiting for the user to click

    input r$ 
    stop

[set]    ' the user clicked on the Set button, set the checkbox

    print #1.cb, "set"
    goto [readCb]


[reset]    ' the user clicked on the Reset button, clear the checkbox
    print #1.cb, "reset"
    goto [readCb]


[readCb]    ' set the contents of the textbox

    ' query the checkbox for its state
    print #1.cb, "value?"
    input #1.cb, t$

    ' set the contents of our textbox
    print #1.text, "I am "; t$

    goto [inputLoop]


[quit]    ' check to see if we should quit

    confirm "Do you want to quit?"; answer$
    if answer$ <> "yes" then [inputLoop]

    ' disable trapping of close message so we can close the window
    print #1, "trapclose"
    close #1
    end


In the above example we show just how easy it can be to program for 
Presentation Manager (the Windows version works exactly the same way).  
We have a small dialog box with a checkbox, a textbox (aka entryfield), 
and three buttons.  The Tab key and Alt-key combinations are all effective.  
All the controls are listed before we open the window, and the checkbox 
and textbox are given subhandles of the window so that we can address them.

The buttons are the simplest to program.  We give them a label, a branch 
label, and a position.  When the user clicks on the button, the BASIC 
program branches to that label (as in GOTO) and continues execution.

The checkbox is similar, but it has two possible states.  We give it a 
subhandle (in this case #1.cb) so we can PRINT to it and INPUT from it.  
When we click on it, it also has a branch label to follow, like the 
button above.

The textbox (aka entryfield) lets us enter information (reading it with 
INPUT), and also display it (with the PRINT statement).

The trapclose command is sent to the dialog box so that when the user 
tries to close the dialog, we can control how this occurs.  See how the 
[quit] routine is automatically invoked, so that the user can confirm 
the action.

This simple method of window control is used throughout.  No API calls 
are needed to write useful Presentation Manager applications.


The Debugger:

Liberty BASIC comes with a source level debugger, so you can watch 
variables change, and single step through your code.  To use it, pick 
the Debug option instead of Run on the Source pull-down menu.

The Trace Window appears with two text panes.  The pane on the top shows 
each variable change values.  The pane below shows your program's code, 
and highlights each line as it executes.

Three modes are available, and there is a button for each at the bottom 
of the Trace Window.  The Step mode executes one line at a time, 
highlighting as it goes, the Walk mode runs the program continuously, 
highlighting each line, and the Run mode runs without tracing.

You must close the Trace Window yourself when done with it.


Runtime Distribution:

When I begin asking for registrations, I will begin shipping a runtime 
engine (which already exists) as an incentive to register.  This runtime 
engine will run tokenized programs, and will be largely compatible with 
the Windows version of Liberty BASIC and its runtime engine.  This will 
allow development of a single source and tokenized file that will run on 
either platform with little or no modification.  It will not be 
necessary to ship the source code with the program.

The runtime engine features a compile-on-demand technique that only 
compiles BASIC statements as it needs them, and once any statement has 
been compiled, it will run again without needing to be recompiled.  
This allows even large Liberty BASIC programs to 'start right up', 
avoiding long compile times for runtime apps.

----------------------------------------------------------------

Contact Information:

For more information, contact me at the address, phone # or CIS # below:

Shoptalk Systems
Carl Gundel
P.O. Box 1062
Framingham, MA  01701
(508) 872-5315
CIS 71231,1532
