
This file describes the many commands and functions of Liberty BASIC.  
The format goes like this:


Command/Function Name and Syntax  optional items in gray


Description:
    a short, exact specification for the command/function

Usage:
    an example of how to use the function command in a short
    Liberty BASIC program fragment



Explore the included Liberty BASIC source files for more information.


See the section at the end of this file about commands for controlling
the spreadsheet, graphics, and text windows.


NOTE: This file is designed to be dumped to a printer with FF characters
      to place each statement or function at the top of the next page.
      For most, this is accomplished simply enough:

      C:\LIBERTY>type summary.txt > lpt1:

      or you could simply print this file from the Windows Notepad







ASC( n$ )

Description:

  This function returns the ASCII value of the first character of string n$.

Usage:

  print asc( "A" )              produces:  65

  let name$ = "Tim"
  firstLetter = asc(name$)
  print firstLetter             produces:  84

  print asc( "" )               produces:  0

BEEP

Description:

  This command simply rings the system bell, as in CTRL-G

Usage:

  .
  .
[loop]
  input "Give me a number between 1 and 10?"; number
  if number < 1 or number > 10 then beep : print "Out of range!" : goto [loop]
  print "The square of "; number; " is "; number ^ 2
  .
  .


BUTTON #handle, label, return, corner, posx, posy

Description:

  This statement lets you add buttons to windows that you open.  The main 
  program window cannot have buttons added, but any window that you create 
  via the OPEN command can have as many buttons as you want.  In this release 
  of Liberty BASIC, buttons cannot have graphic pictures on them, but only 
  text labels.  This will be remedied in a future release.

Usage:

  Before you actually OPEN the window, each button must be declared with a 
  BUTTON statement.  Here is a brief description for each parameter as listed 
  above:

#handle - any valid file handle may be used.  You must use the same handle
      as will be used for the window that the button will belong to.

label   - Type the label desired for the button here.  Do not bound the word
      with quotes, and do not use a string variable.

return  - Again, use only one word and do not bound it with quotes or use a
      string variable.  If return is set to a valid branch label, then when
      the button is pressed, execution will restart there (just as with
      GOTO or GOSUB), but if return is not a valid branch label, then the 
      value of return is used as input to a specified variable (as in 
      input a$).

corner  - UL, UR, LL, or LR specifies which corner of the window to anchor
      the button to.  For example, if LR is used, then the button will 
      appear in the lower right corner.  UL = upper left, UR = upper 
      right, LL = lower left, and LR = lower right

posx, posy - These two parameters determine how to place the button relative to
      the corner it has been anchored to.  For example if corner is LR, 
      posx is 5, and posy is 5, then the button will be 5 pixels up and 
      left of the lower right corner.  Another way to use posx & posy is
      to use values less than one.  For example, if corner is UL, posx
      is .9, and posy is .9, then the button will be positioned 9/10th of 
      the distance of the window in both x and y from the upper left
      corner (and thus appear to be anchored to the lower right corner). 





BUTTON Continued

Here is a sample program:

  ' this button will be labeled Sample and will be located
  ' in the lower right corner.  When it is pressed, program
  ' execution will transfer to [test]
    button #graph, Sample, [test], LR, 5, 5

  ' this button will be labeled Example and will be located
  ' in the lower left corner.  When it is pressed, the string
  ' "Example" will be returned.
    button #graph, Example, Example, LL, 5, 5

  ' open a window for graphics
    open "Button Sample" for graphics as #graph

  ' print a message in the window
    print #graph, "\This is a test"

  ' get button input
[loop]
  input b$
  if b$ = "Example" then [example]
  goto [loop]

 ' the Sample button has been pressed, ring the terminal bell
 ' and close the window
[test]
  beep
  close #graph
  end

 ' The Example button has been pressed, close the window
 ' without ringing the bell
[example]
  close #graph
  end


CHR$( n )

Description:

  Returns a one character long string, consisting of the character 
  represented on the ASCII table by the value n (0 - 255).

Usage:

  ' print each seperate word in text$ on its own line
  text$ = "now is the time for all great men to rise"
  for index = 1 to len(text$)
      c$ = mid$(text$, index, 1)
      ' if c$ is a space, change it to a carraige return
      if c$ = chr$(32) then c$ = chr$(13)
      print c$ ;
  next index                            Produces:

                now
                is
                the
                time
                for
                all
                great
                men
                to
                rise


CLOSE #handle

Description:

  This command is used to close files and devices.  This is the last step of 
  a file read and/or write, or to close graphic, spreadsheet, or other 
  windows when finished with them.  If when execution of a program is 
  complete there are any files or devices left open, Liberty BASIC will 
  display a dialog informing you that it found it necessary to close the 
  opened files or devices.  This is designed as an aid for you so that you 
  will be able to correct the problem.  If on the other hand you choose to 
  terminate the program early (this is done by closing the program's main 
  window before the program finishes), then Liberty BASIC will close any open 
  files or devices without posting a notice to that effect.

Usage:

  open "Graphic" for graphics as #gWindow       ' open a graphics window
  print #gWindow, "home"                ' center the pen
  print #gWindow, "down"                ' put the pen down
  for index = 1 to 100                  ' loop 100 times
    print #gWindow, "go "; index                ' move the pen foreward
    print #gWindow, "turn 63"           ' turn 63 degrees
  next index
  input "Press 'Return'."; r$           ' this appears in main window
  close #gWindow                        ' close graphic window


CLS

Description:

  Clears the main program window of text and sets the cursor back at the 
  upper left hand corner.  Useful  for providing a break to seperate 
  different sections of a program functionally.  Additionally, since the main 
  window doesn't actually discard past information on its own, the CLS 
  command can be used to reclaim memory from your program by forcing the main 
  window to dump old text.

Usage:

  .
  .
  print "The total is: "; grandTotal
  input "Press 'Return' to continue."; r$
  cls
  print "*** Enter Next Round of Figures ***"
  .
  .


CONFIRM string; responseVar

Description:

  This statement opens a dialog box displaying the contents of string and 
  presenting two buttons marked 'Yes' and 'No'.  When the selection is made, 
  the string "yes" is returned if 'Yes' is pressed, and the string "no" is 
  returned if 'No' is pressed.  The result is placed in responseVar.

Usage:

[quit]

  ' bring up a confirmation box to be sure that
  ' the user want to quit
  confirm "Are you sure you want to QUIT?"; answer$
  if answer$ = "no" then [mainLoop]
  end


COS( n )

Description:

  Returns the cosine of the number n.

Usage:

  .
  .
  for c = 1 to 45
    print "The cosine of "; c; " is "; cos(c)
  next c
  .
  .

Note:

  See also SIN( ) and TAN( )


DATE$( )

Description:

  Instead of adopting MBASIC's date$ variable, we decided to use a function 
  instead, figuring that this might give us additional flexibility later.  
  This function returns the current date in long format.

Usage:

  print date$( )

Produces:

  Feb 5, 1991


DIM array(size, size)

Description:

  DIM sets the maximum size of an array.  Any array can be dimensioned to 
  have as many elements as memory allows.  If an array is not DIMensioned 
  explicitly, then the array will be limited to 10 elements, 0 to 9.  Non 
  DIMensioned double subscript arrays will be limited to 100 elements 0 to 9 
  by 0 to 9.

Usage:

  print "Please enter 10 names."
  for index = 0 to 9
    input names$ : name$(index) = name$
  next index

  The FOR . . . NEXT loop in this example is limited to a maximum value of 9 
  because the array names$( ) is not dimensioned, and therefore is limited to 
  10 elements.  To remedy this problem, we can add a DIM statement, like so:

  dim names$(20)
  print "Please enter 20 names."
  for index = 0 to 19
    input names$ : names$(index) = name$
  next index

Double subscripted arrays can store information more flexibly, like so:

  dim customerInfo$(10, 5)
  print "Please enter information for 10 customers."
  for index = 0 to 9
    input "Customer name >"; info$ : customerInfo$(index, 0) = info$
    input "Address >"; info$ : customerInfo$(index, 1) = info$
    input "City >"; info$ : customerInfo$(index, 2) = info$
    input "State >"; info$ : customerInfo$(index, 3) = info$
    input "Zip >"; info$ : customerInfo$(index, 4) = info$
  next index


ELSE

    See IF . . . THEN . . . ELSE


EOF(#handle)

Description:

  Used to determine when reading from a sequential file whether the end of 
  the file has been reached.  If so, -1 is returned, otherwise 0 is returned.

Usage:

  open "testfile" for input as #1
  if eof(#1) < 0 then [skipIt]
[loop]
  input #1, text$
  print text$
  if eof(#1) = 0 then [loop]
[skipIt]
  close #1


END

Description:

  Used to immediately terminate execution of a program.  If any files or 
  devices are still open (see CLOSE) when execution is terminated, then 
  Liberty BASIC will close them for you and present you with a dialog 
  expressing this fact.  It is good programming practice to close files and 
  devices before terminating execution.

  Note:  The STOP statement is functionally identical to END and is 
  interchangable

Usage:

  .
  .
  print "Preliminary Tests Complete."
[askAgain]
  input "Would you like to continue (Y/N) ?"; yesOrNo$
  yesOrNo$ = left$(yesOrNo$, 1)
  if yesOrNo$ = "y" or yesOrNo$ = "Y" then [continueA]
  ifYesOrNo$ = 'n" or yesOrNo$ = "N" then end
  print "Please answer Y or N."
  goto [askAgain]
[continueA]
  .
  .


FOR . . . NEXT

Description:

  The FOR . . . NEXT looping construct provides a way to repeatedly execute 
  code a specific amount times.  A starting and ending value are specified 
  like so:

  for var = 1 to 10
    {BASIC code}
  next var

  In this case, the {BASIC code} is executed 10 times, with var being 1 the 
  first time, 2 the second, and on through 10 the tenth time.  Optionally 
  (and usually) var is used in some calculation(s) in the {BASIC code}.  
  For example if the {BASIC code} is  print var ^ 2, then a list of squares 
  for var will be displayed upon execution.

  The specified range could just as easily be 2 TO 20, instead of 1 TO 10, 
  but since the loop always counts +1 at a time, the first number must be 
  less than the second.  The way around this limitation is to place STEP n 
  at the end of for FOR statement like so:

  for index = 20 to 2 step -1
    {BASIC code}
  next index

  This would look from 19 times returning values for index that start with 
  20 and end with 2.  STEP can be used with both positive and and negative 
  numbers and it is not limited to integer values.  For example:

  for x = 0 to 1 step .01
    print "The sine of "; x; " is "; sin(x)
  next x




Note:

  It is not recommended to pass control of a program out of a FOR . . . NEXT
loop using GOTO (GOSUB is acceptable).  Liberty BASIC may behave unpredictably.


GOSUB label

Description:

  GOSUB causes execution to proceed to the program code following the label
if it exists,  using the form 'GOSUB label'.  The label can be either a
traditional line number or a branch label in the format [???????] where the
?'s can be any upper/lowercase letter combination.  Spaces and numbers are
not allowed.

Here are some valid branch labels:  [mainMenu]  [enterLimits]  [repeatHere]
Here are some invalid branch labels:  [enter limits]  mainMenu  [1moreTime]

  After execution is transferred to the point of the branch label, then each 
  statement will be executed in normal fashion until a RETURN is encountered.  
  When this happens, execution is transferred back to the statement 
  immediately after the GOSUB.  The section of code between a GOSUB and its 
  RETURN is known as a 'subroutine.'  One purpose of a subroutine is to save 
  memory by having only one copy of code that is used many times throughout a 
  program.

Usage:

  .
  .
  print "Do you want to continue?"
  gosub [yesOrNo]
  if answer$ = "N" then [quit]
  print "Would you like to repeat the last sequence?"
  gosub [yesOrNo]
  if answer$ = "Y" then [repeat]
  goto [generateNew]

[yesOrNo]
  input answer$
  answer$ = left$(answer$, 1)
  if answer$ = "y" then answer$ = "Y"
  if answer$ = "n" then answer$ = "N"
  if answer$ = "Y" or answer$ = "N" then return
  print "Please answer Y or N."
  goto [yesOrNo]
  .
  .

  You can see how using GOSUB [yesOrNo] in this case saves many lines of code 
  in this example.  The subroutine [yesOrNo] could easily be used many other 
  times in such a hypothetical program, saving memory and reducing typing 
  time and effort.  This reduces errors and increases productivity.  See also 
  GOTO


GOTO label

Description:

  GOTO causes Liberty BASIC to proceed to the program code following the label 
  if one exists,  using the form 'GOTO label'.  The label can be either a 
  traditional line number or a branch label in the format [???????] where the 
  ?'s can be any upper/lowercase letter combination.  Spaces and digits are 
  not allowed.

Here are some valid branch labels:  [mainMenu]  [enterLimits]  [repeatHere]
Here are some invalid branch labels:  [enter limits]  mainMenu  [1moreTime]

Usage:

  .
  .
[repeat]
  .
  .
[askAgain]
  print "Make your selection (m, r, x)."
  input selection$
  if selection$ = "M" then goto [menu]
  if selection$ = "R" then goto [repeat]
  if selection$ = "X" then goto [exit]
  goto [askAgain]
  .
  .
[menu]
  print "Here is the main menu."
  .
  .
[exit]
  print "Okay, bye."
  end

Notes:

  In the lines containing IF . . . THEN GOTO, the GOTO is optional.  
  The expression IF . . . THEN [menu]  is just as valid as 
  IF . . . THEN GOTO [menu].  But in the line GOTO [askAgain], the GOTO 
  is required. 

  See also GOSUB


IF expression THEN expression(s)

Description:

  The purpose of IF . . . THEN is to provide a mechanism for your computer 
  software to make decisions based on the data available.  A decision-making 
  mechanism is used in very simple situations and can be used in combinations 
  to engineer solutions to problems of great complexity.

  The expression (see above) is a boolean expression (meaning that it 
  evaluates to a true or false condition).  In this expression we place the 
  logic of our decision-making process.  For example, if we are writing a 
  inventory application, and we need to know when any item drops below a 
  certain level in inventory, then our decision-making logic might look like 
  this:

  .
  .
  if level <= reorderLevel then expression(s)
  next BASIC program line
  .
  .

  The 'level <= reorderLevel' part of the above expression will evaluate to 
  either true or false.  If the result was true, then the expression(s) part 
  of that line (consisting of a branch label or any valid BASIC statements) 
  will be executed.  Otherwise execution will immediately begin at the next 
  BASIC program line.

  The following are permitted:

  if a < b then [lessThan]      

  This causes program execution to begin at branch label [lessThan]
if a is less than b

  if sample < lowLimit or sample > highLimit then beep : print"Out of range!"

  This causes the terminal bell to ring and the message Out of range! to be 
  displayed if sample is less than lowLimit or greater then highLimit.


IF expression THEN expression(s)1 ELSE expression(s)2

Description:

  This extended form of IF . . . THEN adds expressiveness and simplifies 
  coding of some logical decision-making software.  Here is an example of its 
  usefulness.

  Consider:

[retry]
  input"Please choose mode, (N)ovice or e(X)pert?"; mode$
  if len(mode$) = 0 then print "Invalid entry! Retry" : goto [retry]
  mode$ = left$(mode$, 1)
  if instr("NnXx", mode$) = 0 then print "Invalid entry! Retry" : goto [retry]
  if instr("Nn", mode$) > 0 then print "Novice mode" : goto [main]
  print "eXpert mode"
[main]
  print "Main Selection Menu"

  Look at the two lines before the [main] branch label.  The first of these 
  two lines is required to branch over the next line.  These lines can be 
  shortened to one line as follows:

  if instr("Nn",mode$)> 0 then print "Novice mode" else print "eXpert mode"

  Some permitted forms are as follows:

  if a < b then statement else statement
  if a < b then [label] else statement
  if a < b then statement else [label]
  if a < b then statement : statement else statement
  if a < b then statement else statement : statement
  if a < b then statement : goto [label] else statement
  if a < b then gosub [label1] else gosub [label2]

  Any number of variations on these formats are permissible.  The a < b 
  boolean expression is of course only a simple example chosen for convenience.  
  You must replace it with the correct expression to suit your problem.


INPUT  #handle  "string expression";  variableName

Description:

  This command has three possible forms:

  input var             - stop and wait for user to enter data in the program's
          main window and press the 'Return' key, then assign
          the data entered to var.

  input "enter data"; var   - display the string "enter data" and then stop
          and wait for user to enter data in the program's main window
          and press 'Return', then assign the data entered to var.

  input #name, var    - or -    input #name, var1, var2

   - Get the next data item from the open file or device using handle named 
     #handle and assign the data to var.  If no device or file exists that 
     uses the handle named #handle, then return an error.  In the second case, 
     the next two data items are fetched and assigned to var1 and var2.

Usage:

  'Display a text file
  input "Please type a filename >";  filename$
  open filename$ for input as #text
[loop]
  if eof(#text) <> 0 then [quit]
  input #text, item$
  print item$
  goto [loop]
[quit]
  close #text
  print "Done."
  end


Note:  In Liberty BASIC release 1.0, INPUT cannot be used to input data 
directly into arrays, only into the simpler variables.

  input a$(1)                   - is illegal
  input string$ : a$(1) = string$       - use this instead

This shortcoming will be addressed in a future release.  This should not be a 
problem anyway if you will be checking the input for validity before 
ultimately accepting it.

INPUT (continued)

Most versions of Microsoft BASIC implement INPUT to automatically place a 
question mark on the display in front of the cursor when the user is prompted 
for information like so:

  input "Please enter the upper limit"; limit

  produces:

    Please enter the upper limit ? |

Liberty BASIC permits you the luxury of deciding for yourself whether the 
question mark appears at all.

  input "Please enter the upper limit :"; limit

  produces:

    Please enter the upper limit: |

  and:    input limit    produces simply:

    ? |

In the simple form input limit, the question mark is inserted automatically,  
but if you do specify a prompt, as in the above example, only the contents of 
the prompt are displayed, and nothing more.  If for some reason you wish to 
input without a prompt and without a question mark, then the following will 
achieve the desired effect:

  input ""; limit 

Additionally, in most Microsoft BASICs, if INPUT expects a numeric value and 
a non numeric or string value is entered, the user will be faced with a 
comment something like 'Redo From Start', and be expected to reenter.  
Liberty BASIC does not automatically do this, but converts the entry to a zero 
value and sets the variable accordingly.  This is not considered a problem but 
rather a language feature, allowing you to decide for yourself how your 
program will respond to the situation.

One last note:  In Liberty BASIC input prompt$; limit is also valid. Try:

  prompt$ = "Please enter the upper limit:"
  input prompt$; limit


INPUT$(#handle, items)

Description:

  Permits the retrieval of a specified number of items from an open file or 
  device using #handle.  If #handle does not refer to an open file or device 
  then an error will be reported.

Usage:

  'read and display a file one character at a time
  open "c:\autoexec.bat" for input as #1
[loop]
    if eof(#1) <> 0 then [quit]
    print input$(#1, 1);
    goto [loop]
[quit]
    close #1
    end

For most devices (unlike disk files), one item does not refer a single 
character, but INPUT$( ) may return items more than one character in length.  
In most cases, use of INPUT #handle, varName works just as well or better for 
reading devices.


INSTR(string1, string2, starting)

Description:

  This function returns the position of string2 within string1.  If string2 
  occurs more than once in string 1, then only the position of the leftmost 
  occurance will be returned.  If starting is included, then the search for 
  string2 will begin at the position specified by starting.

Usage:

  print instr("hello there", "lo")

  produces:    4

  print instr("greetings and meetings", "eetin")

  produces:    3

  print instr("greetings and meetings", "eetin", 5)

  produces:    16

If string2 is not found in string1, or if string2 is not found after starting,
then INSTR( ) will return 0.

  print instr("hello", "el", 3)

  produces:    0

  and so does:

  print instr("hello", "bye")INT(number)

Description:

  This function removes the fractional part of number, leaving only the whole
  number part behind.

Usage:

[retry]
  input "Enter an integer number>"; i
  if i<>int(i) then bell: print i; " isn't an integer! Re-enter.": goto [retry]


LEFT$(string, number)

Description:

  This function returns from string the specified number of characters starting
  from the left.  So if  string is "hello there", and number is 5, then "hello"
  would be the result.

Usage:


[retry]
  input "Please enter a sentence>"; sentence$
  if sentence$ = "" then [retry]
  for i = 1 to len(sentence$)
    print left$(sentence$, i)
  next i

Produces:

  Please enter a sentence>That's all folks!
  T
  Th
  Tha
  That
  That'
  That's
  That's_
  That's a
  That's al
  That's all
  That's all_
  That's all f
  That's all fo
  That's all fol
  That's all folk
  That's all folks
  That's all folks!

Note:

  If number is zero or less, then "" (an empty string) will be returned.  If 
  the number is greater than the number of characters in string, then string
  will be returned.

  See also MID$( ) and RIGHT$( )


LEN( string )

Description:

  This function returns the length in characters of string, which can be any 
  valid string expression.

Usage:

  prompt "What is your name?"; yourName$
  print "Your name is "; len(yourName$); " letters long"


LET assignment expression

Description:

  LET is an optional prefix for any BASIC assignment expression.  Most do leave
  the word out of their programs, but some prefer to use it.

Usage:

  Either is acceptable:

  let name$ = "John"    
or
  name$ = "John"

  Or yet again:

  let c = sqr(a^2 + b^2)
or
  c = sqr(a^2 + b^2)


MID$(string, index, number)

Description:

  Permits the extraction of a sequence of characters from string starting at 
  index.  If number is not specified, then all the characters from index to the
  end of the string are returned.  If number is specified, then only as many
  characters as number specifies will be returned, starting from index.

Usage:

  print mid$("greeting Earth creature", 10, 5)

Produces:

  Earth

And:

  string = "The quick brown fox jumped over the lazy dog"
  for i = 1 to len(string$) step 5
    print mid$(string$, i, 5)
  next i

Produces:

  The_q
  uick_
  brown
  _fox_
  jumpe
  d_ove
  r_the
  _lazy
  _dog


Note:

  See also LEFT$( ) and RIGHT$( )NEXT var

    see  FOR . . . NEXT


OPEN string FOR purpose AS #handle

Description:

  This statement has many functions.  It can be used to open disk files, or to
  open windows of several kinds.

Disk files:

  A typical OPEN used in disk I/O looks like this:

  OPEN "\autoexec.bat" for input as #read

  This example illustrates how we would open the autoexec.bat file for reading.  
  As you can see, string in this case is "\autoexec.bat", purpose is input, and 
  #handle is read.

  string - this must be a valid pathname.  If the file does not exist, it will 
       be created.

  purpose - must be input, output, or random

  #handle - use a unique descriptive word, but must start with a #.  
        This special handle is used to identify the open file in later 
        program statements

Windows:

  A typical OPEN used in windows looks like this:

  OPEN "Customer Statistics Chart" for graphics as #csc

  This example illustrates how we would open a window for graphics.  Once the 
  window is open, there are a wide range of commands that can be given to it 
  (see chapter ? - Liberty BASIC Graphics for more about this).  As you can 
  see, string in this case is "Customer Statistics Chart", which is used as 
  the title of the window, purpose is graphics (open a window for graphics), 
  and the #handle is #csc (derived from Customer Statistics Chart), which will 
  be used as an identifier when sending commands to the window.

  string - can be any valid BASIC string.  used to label the window
  purpose - there are a several of possibilities here:
        graphics, spreadsheet, text
        any of these can end in _fs, _nsbars (or other suffixes)
  #handle - as above, must be a unique, descriptive word starting with #


Note:  Any opened file or window must be closed before program execution is 
finished.  See CLOSE


PRINT #handle, pression ; expression(s) ;

Description:

  This statement is used to send data to the main window, to a disk file, or 
  to other windows.  A series of expressions can follow PRINT (there does not 
  need to be any expression at all), each seperated by a semicolon.  Each 
  expression is displayed in sequence.  If the data is being sent to a disk 
  file, or to a window, then #handle must be present.

PRINTing to a the main window:
  When the expressions are displayed, then the cursor (that blinking vertical 
  bar | ) will move down to the next line, and the next time information is 
  sent to the window, it will be placed on the next line down.  If you do not 
  want the cursor to move immediately to the next line, then add an additional 
  semicolor to the end of the list of expressions.  This prevents the cursor 
  from being moved down a line when the expressions are displayed.  The next 
  time data is displayed, it will be added onto the end of the line of data 
  displayed previously.

Usage:                  Produces:

  print "hello world"           hello world

  print "hello ";               hello world
  print "world"
  
  age = 23
  print "Ed is "; age; " years old"     Ed is 23 years old

When sending to a disk file and in regard to the use of the semicolon at the 
end of the expression list, the rules are similar (only you don't see it 
happen on the screen).  When printing to a window, the expressions sent are 
usually commands to the window (or requests for information from the window).  
For more information, see chapter ?, Liberty BASIC Graphics.


PROMPT string; responseVar

Description:

  The PROMPT statement opens a dialog box, displays string, and waits for the 
  user to type a response and press 'Return' (or press the OK or Cancel 
  button).  The entered information is placed in responseVar.  If Cancel is 
  pressed, then a string of zero length is returned.  If responseVar is set to 
  some string value before PROMPT is executed, then that value will become the 
  'default' or suggested response.  This means that when the dialog is opened, 
  the contents of responseVar will already be entered as a response for the 
  user, who then has the option to either type over that 'default' response, to 
  to press 'Return' and accept it.

Usage:

  .
  .
  response$ = "C:"
  prompt "Search on which Drive? A:, B:, or C:"; response$
[testResponse]
  if response$ = "" then [cancelSearch]
  if len(response$) = 2 and instr("A:B:C:", response$) > 0 then [search]
  prompt "Unacceptable response.  Please try again. A:, B:, or C:"; again$
  goto [testResponse]

[search]
  print "Starting search . . . "
  .
  .


REM comment

Description:

  The REM statement is used to place comments inside of code to clearly 
  explain the purpose of each section of code.  This is useful to both the 
  programmer who writes the code or to anyone who might later need to modify 
  the program.  Use REM statements liberally.  There is a shorthand way of 
  using REM, which is to use the ' (apostrophe) character in place of the word 
  REM.  This is cleaner to look at, but use whichever you prefer.  Unlike other 
  BASIC statements, with REM you cannot add another statement after it on the 
  same line using a colon ( : ) to seperate the statements.  The rest of the 
  line becomes part of the REM statement.

Usage:

  rem  let's pretend that this is a comment for the next line
  print "The mean average is "; meanAverage

Or:

  ' let's pretend that this is a comment for the next line
  print "The strength of the quake was "; magnitude

This doesn't work:

  rem  thank the user : print "Thank you for using Super Stats!"

    (even the print statement becomes part of the REM statement)


Note:

  When using ' instead of REM at the end of a line, the statement seperator :
is not required to seperate the statement on that line from its comment.  

For example:

  print "Total dollar value: "; dollarValue : rem  print the dollar value

Can also be stated:

  print "Total dollar value: "; dollarValue  ' print the dollar value

Notice that the : is not required in the second form.


RETURN

    See  GOSUB


RIGHT$(string, number)

Description:

  Returns a sequence of characters from the right hand side of string using 
  number to determine how many characters to return.  If  number is 0, 
  then "" (an empty string) is returned.  If number is greater than the number 
  of characters in string, then string will itself be returned.

Usage:

  print right$("I'm right handed", 12)

Produces:

  right handed

And:

  print right$("hello world", 50)

Produces:

  hello world

Note:

  See also LEFT$( ) and MID$( )


RND(number)

Description:

  This function returns a pseudo random number between 0 and 1.  This can be 
  useful in writing games and some simulations.  The particular formula used 
  in this release might more accurately be called an arbitrary number generator 
  (instead of random number generator), since if a distribution curve of the 
  output of this function were plotted, the results would be quite uneven.  
  Nevertheless, this function should prove more than adequate (especially for 
  game play).

  In MBASIC it makes a difference what the value of parameter number is, but 
  in Liberty BASIC, it makes no difference.  The function will always return 
  an arbitrary number between 0 and 1.

Usage:

  ' print ten numbers between one and ten
  for a = 1 to 10
      print int(rnd(1)*10) + 1
  next a
  
SIN(number)

Description:

  This function return the sine of number.

Usage:

  .
  .
  for t = 1 to 45
    print "The sine of "; t; " is "; sin(t)
  next t
  .
  .

Note:

  See also COS( ) and TAN( )


STR$(numericExpression)

Description:

  This function returns a string expressing the result of  numericExpression.  
  In MBASIC, this function would always return a string representation of the 
  expression and it would add a space in front of that string.  For example 
  in MBASIC:

  print len(str$(3.14))

  Would produce the number 5 (a space followed by 3.14 for a total of 5 
  characters).

  Liberty BASIC leaves it to you to decide whether you want that space or not.  
  If you don't want it, then you need not do anything at all, and if you do 
  want it, then this expression will produce the same result under Liberty 
  BASIC:

  print len(" " + str$(3.14))

Usage:

  .
  .
[kids]
  ' use str$( ) to validate entry
  input "How many children do you have?"; qtyKids
  qtyKids$ = str$(qtyKids)
  ' if the entry contains a decimal point, then the response is no good
  if instr(qtyKids$, ".") > 0 then print "Bad response. Reenter." : goto [kids]
  .
  .


TAN(number)

Description:

  This function return the tangent of number.

Usage:

  .
  .
  for t = 1 to 45
    print "The tangent of "; t; " is "; tan(t)
  next t
  .
  .

Note:

  See also SIN( ) and COS( )
TIME$( )

Description:

  This function returns a string representing the current time of the system 
  clock in 24 hour format.  This function replaces the time$ variable used in 
  MBASIC.  See also DATE$( ).

Usage:

  .
  .
  ' display the opening screen
  print "Main selection screen             Time now: "; time$( )
  print
  print "1. Add new record"
  print "2. Modify existing record"
  print "3. Delete record"
  .
  .


TRACE number

Description:

  This statement sets the trace level for its application program.  This is 
  only effective if the program is run using the Debug menu selection 
  (instead of RUN).  If Run is used, then any TRACE statements are ignored by 
  the interpreter.

  There are three trace levels: 0, 1, and 2.  Here are the effects of these 
  levels:

  0 = single step mode or STEP
  1 = animated trace or WALK
  2 = full speed no trace or RUN

  When any Liberty BASIC program first starts under Debug mode, the trace
  level is always initially 0.  You can then click on any of the three buttons
  (STEP, WALK, RUN) to determine what mode to continue in.   When a TRACE
  statement is encountered, the trace level is set accordingly, but you can
  recover from this new trace level by clicking again on the desired button.

  If you are having trouble debugging code at a certain spot, then you can add 
  a TRACE statement (usually level 0) just before that location, run in Debug 
  mode and then click on RUN.  When the TRACE statement is reached, then the 
  debugger will kick in at that point.

Usage:

  .
  .
  'Here is the trouble spot
  trace 0  ' kick down to single step mode
  for index = 1 to int(100*sin(index))
    print #graph, "go "; index ; " "; int(100*cos(index))
  next index
  .
  .


TRIM$(stringExpression)

Description:

  This function removes any spaces from the start and end of the string in 
  stringExpression.  This can be useful for cleaning up data entry among other 
  things.


Usage:

  sentence$ = "  Greetings  "
  print len(trim$(sentence$))

Produces:

  9


USING(templateString, numericExpression)

Description:

  This function formats numericExpression as a string using templateString.  
  The rules for the format are like those in MBASIC's PRINT USING statement, 
  but since USING( ) is a function, it can be used as part of a larger BASIC 
  expression instead of being useful only for output directly.


Usage:

  ' print a column of ten justified numbers
  for a = 1 to 10
      print using("####.##",  rnd(1)*1000)
  next a


VAL(stringExpression)

Description:

  This function returns a numeric value for stringExpression is 
  stringExpression represents a valid numeric value or if it starts out as 
  one.  If not, then zero is returned.  This function lets your program take 
  string input from the user and carefully analyze it before turning it into 
  a numeric value if and when appropriate. 

Usage:

  print 2 * val("3.14")         Produces:       6.28

  print val("hello")            Produces:       0

  print val("3 blind mice")     Produces:       3


WHILE expression . . . WEND

Description:

  These two statements comprise the start and end of a control loop.  Between 
  the WHILE and WEND statements place code (optionally) that will be executed 
  repeatedly while expression evaluates the same.  Expression can be a boolean, 
  numeric, or string expression.

Usage:

  ' loop until midnight (go read a good book)
  while time$ <> "00:00:00"
      ' some action performing code might be placed here
  wend

Or:

  ' loop until a valid response is solicited
  while val(age$) = 0
     input "How old are you?"; age$
     if val(age$) = 0 then print "Invalid response.  Try again."
  wend

Or:

  ' generate a list of ten non-consecutive random numbers
  for count = 1 to 10
    while random : random = int(rnd(1)*10)+1 : wend
    print random
  next count

WORD$( stringExpression, n )

Description:

  This function returns the nth word in stringExpression.  The leading and
  trailing spaces are stripped from stringExpression and then it is broken
  down into 'words' at the remaining spaces inside.  If n is less than 1 or
  greater than the number of words in stringExpression, then "" is returned.

Usage:

  print word$("The quick brown fox jumped over the lazy dog", 5)

Produces:

  jumped

And:

  ' display each word of sentence$ on its own line
  sentence$ = "and many miles to go before I sleep."
  tkn$ = "?"
  while tkn$ <> ""
      index = index + 1
      tkn$ = word$(sentence$, index)
      print tkn$
  wend

Produces:

  and
  many
  miles
  to
  go
  before
  I
  sleep.

  Summary of Window Device Commands
  --------------------------------------------------------------------

  In Liberty BASIC windows are treated like files, and we can refer
  to anything in this class as a BASIC 'Device'.  To open a window
  we use the OPEN statement, and to close the window we use the
  CLOSE statement.  To control the window we 'print' to it, just as
  we would print to a file.  The commands are sent as strings to the
  device.  As a simple example, here we will open a graphics window,
  center a pen (like a Logo turtle), and draw a simple spiral.  We
  will then pause by opening a simple dialog.  When you confirm the
  exit, we will close the window:

    button #graph, Exit, [exit], LR, 5, 5    'window will have a button 
    open "Example" for graphics as #graph    'open graphics window
    print #graph, "up"                     'make sure pen is up
    print #graph, "home"                   'center the pen
    print #graph, "down"                   'make sure pen is down
    for index = 1 to 30                    'draw 30 spiral segments
      print #graph, "go "; index           'go foreward 'index' places
      print #graph, "turn 118"             'turn 118 degrees
    next index                             'loop back 30 times
    print #graph, "flush"                  'make the image 'stick'

  [inputLoop]
    input b$ : goto [inputLoop]            'wait for button press

  [exit]
    confirm "Close Window?"; answer$       'dialog to confirm exit
    if answer$ = "no" then [inputLoop]     'if answer$ = "no" loop back
    close #graph

  end


  Here we used only a few of the commands available to us.  Here are
  three seperate lists, one for Graphics, one for Spreadsheet, and one
  for Text windows:



  GRAPHICS
  ------------------------------------------------------------------------
  

  print #handle, "cls"

    Clear the graphics window to white, erasing all drawn elements


  print #handle, "fill COLOR"

    Fill the window with COLOR.  For a list of accepted colors see
    the color command below.


  print #handle, "home"

    Center (or re-center) the pen in the window.


  print #handle, "up"

    Lift the pen up from the drawing surface.  All go or goto commands
    will only move to their new positions without drawing when the pen
    is up.


  print #handle, "down"

    Just the opposite of up.  This command causes lines to be drawn
    when the pen is moved.


  print #handle, "color COLOR"

    Set the pen's color to be COLOR.

    Here is a list of valid colors (in alphabetical order):

      black, blue, brown, cyan, darkblue, darkcyan, darkgray,
      darkgreen, darkpink, darkred, green, lightgray, palegray,
      pink, red, white, yellow


  print #handle, "goto X Y"

    Move the pen to position X Y.  Draw if the pen is down.


  print #handle, "place X Y"

    Position the pen at X Y.  Do not draw even if the pen is down.


  print #handle, "go D"

    Go foreward D distance from the current position using the current
    direction.


  print #handle, "north"

    Set the current direction to 270 (north).  Zero degrees points to the
    right (east), 90 points down (south), and 180 points left (west).


  print #handle, "turn A"

    Turn from the current direction using angle A and adding it to the
    current direction.  A can be positive or negative.


  print #handle, "line X1 Y1 X2 Y2"

    Draw a line from point X1 Y1 to point X2 Y2.  If the pen is up, then
    no line will be drawn, but the pen will be positioned at X2 Y2.


  print #handle, "circle r"

    Draw a circle whose center is the location of the pen and whose radius
    is r.


  print #handle, "posxy"

    Return the current position of the pen in X & Y.  This command must
    be followed by:

    input #handle, xVar, yVar

    which will assign the pen's position to xVar & yVar


  print #handle, "size S"

    Set the size of the pen to S.  The default is 1.


  print #handle, "flush"

    This ensures that the drawn graphics 'stick'.  Make sure to issue this
    command at the end of a drawing sequence to ensure that when the window
    is resized or  overlapped and redrawn, its image will be retained.


  print #handle, "print"

    Send the plotted image to the Windows Print Manager for output.


  print #handle, "font facename width height"

    Set the pen's font to the specified face, width and height.  If an
    exact match cannot be found, then Liberty BASIC will try to find a
    close match, with size being of more prominance than face.


  SPREADSHEET  
  ----------------------------------------------------------------------

  The spreadsheet used in Liberty BASIC is composed of 35 rows of 26
  columns labeled from A to Z.  The upper-left-most cell is A1 and
  the lower-right-most cell is Z35.  Each cell can contain one of three
  types of data:  string, number, or formula.  To enter one of these
  three types into any cell, simply move the selector over the cell on
  the spreadsheet and begin typing.  When done entering that cell's
  contents, press 'Return'.

   A string is entered by preceding it with an apostrophe '.  Each cell
   is 11 characters wide so if the string is longer than 11 characters
   it will run into the next cell to its right.

   A number is entered by entering its value, either an integer or a
   floating point number.

   A formula is a simple mathematical expression, using numbers (see
   above) or cell references.  The result of the formula is displayed
   in the cell's position. Any arithmetic precedence is ignored, so
   any formula is always evaluated from left to right and parenthesis
   are not permitted (They aren't needed).

     A sample formula to compute the average of 3 cells might be:    
     a1 + a2 + a3 / 3       

  The spreadsheet is a very special widget.  Alone it is a very simple
  but complete spreadsheet.  But being able to send it commands and data
  and to be able to read back data from it via Liberty BASIC makes it
  a very powerful tool.  For examples, see GRAPHER.BAS and CUSTOMER.BAS.

  Modes:
  The spreadsheet has two modes, manual and indirect.  Manual mode means
  that the operator can freely move about from cell to cell using the
  arrow keys.  He/she can also insert formulas in manual mode.  Using
  indirect mode, the user can only move between cells defined by the
  controlling application, which also decides what type of data is
  contained by each cell, either string or number.


  Here are the commands:


  print $handle, "manual"

    The manual mode is the default setting.  This mode permits the
    user to move the cell selector wherever he/she wants and to
    enter any of three data types into any cell: number, string, formula


  print #handle, "format COLUMN right|fixed|none"

    This command lets the application control formatting for an individual
    column (COLUMN can be any letter A .. Z).  

    right - right justify column
    fixed - assume 2 decimal places for numbers, and right justify also
    none - left justify, default


  print #handle, "indirect"

    The indirect mode is the most useful when using a spreadsheet for
    data entry.  It enables the application to control which cells the
    user has access to, and what kind of information they can contain.


  print #handle, "cell ADDRESS CONTENTS"

    Place CONTENTS into the cell at ADDRESS.  ADDRESS can be any cell
    address from A1 to Z35.  The letter A to Z must be in uppercase.
    CONTENTS can be any valid string, number or formula (see above).


  print #handle, "user ADDRESS string|number"
  
    Set aside the cell at ADDRESS (same rules apply as for ADDRESS in
    command cell, above) as a user cell and specify the data it
    contains to be either a string or a number (data entered will be
    automatically converted to correct type).  This command is only
    effective when indirect mode is in effect (see above).


  print #handle, "select ADDRESS"

    Place the selector over the cell at ADDRESS (again, same rules).
    It is important to place the selector over the first cell that
    the user will edit.


  print #handle, "result? ADDRESS"

    Answer the result or value of the cell at ADDRESS (again, same
    rules).  If ADDRESS is not a valid cell address, then an empty
    string will be returned.  This command must be followed by:

    input #handle, var$  (or  input #handle, var  if number expected)

    which will leave the desired cell's contents in var$  (or var)


  print #handle, "formula? ADDRESS"

    Answer the formula of the cell at ADDRESS (again, same rules).
    This command must also be followed with:

    input #handle, var$  (should always be a string returned)

    which will leave the desired cell's formula in var$


  print #handle, "flush"

    This commands forces the spreadsheet to display its most up to
    date results.



  TEXT WINDOW
  ------------------------------------------------------------------------

  The text window works a little differently.  Whatever you print to a
  text window is displayed exactly as sent.  The way to send commands to
  a text window is to make the ! character the first character in the
  string.  For example:

  open "Example" for text as #1        'open a text window
    print #1, "Hello World"            'print Hello World in the window
    print #1, "!font helv 16 37"       'change the text window's font 
    print #1, "!line 1"                'read line 1
    input #1, string$
    print "The first line of our text window is:"
    print string$
    input "Press 'Return'"; r$
  close #1                             'close the window


  There are only four commands supported for text windows to date:


  print #handle, "!cls"

    Clears the text window of all text.


  print #handle, "!font faceName width height"

    Sets the font of the text window to the specified face of width and
    height.  If an exact match cannot be found, then Liberty BASIC will
    try to match as closely as possible, with size figuring more
    prominently than face in the match.


  print #handle, "!line #"

    Returns the text at line #.  If # is less than 1 or greater than the
    number of lines the text window contains, then "" (an empty string)
    is returned.  After this command is issued, it must be followed by:

    input #handle, string$

    which will assign the line's text to string$


  print #handle, "!lines"

    Returns the number of lines in the text window.  After this command
    is issued, it must be followed by:

    input #handle, countVar

    which will assign the line count to countVar




  TIPS
  ------------------------------------------------------------------------
  
  Once the techniques are mastered, the spreadsheet becomes a much better
  mechanism for data entry than do plain INPUT statements in a BASIC
  program's host window.  This is especially true when many items need to
  be entered.  In this case, making the spreadsheet the control center
  for your application might be a good idea.  Just add buttons to the
  spreadsheet to perform needed functions after data is entered.

  Remember, any window can have buttons (except for the host window, which
  is for some applications best kept minimized).  Take advantage of this.
  Release 0.9 does not have user definable pull down menus, but this will
  not be a problem for registered users.

  Don't forget to take advantage of the PROMPT and CONFIRM statements,
  which borrow the syntax from the INPUT statement, but do their thing in
  Windows dialogs.  These simple statements can help make your programs
  more Windows-like.

  When running GRAPHER.BAS, try pulling down the command menu and
  selecting Open.  Two .ABC files will be offered.  Load one of these
  and click on the Graph button.
