LBB

LB Booster

Introduction

• Speed up a Liberty BASIC program by up to ten times.
• Compile a Liberty BASIC program to a compact, standalone executable.
• Overcome many of Liberty BASIC's bugs and limitations.

Benefits

Performance

• Speed is typically increased. For example the ELAPSED.bas program supplied with LB reported an execution time of approximately 2400 milliseconds under LB4 and 200 ms under LBB (twelve times faster) and the SIEVE2.bas program ran in about 250 ms under LB4 and 30 ms under LBB (more than eight times faster).

• Executables are much smaller. For example the supplied example program ContactMgr424.bas, when compiled with LB4 (using the Create Application menu selection), created ten files totalling over 2.8 Megabytes. The same program compiled using LBB created a single file executable of 122 Kilobytes (more than 20 times smaller).

• Floating-point numbers have an increased range (from less than 1E−4000 to more than 1E+4000) and precision (approximately 19 significant figures).

• Scrolling is smoother; text and graphics windows scroll continuously as you drag the scrollbar.

• Executables include the necessary manifest to make them fully Vista, Windows 7, Windows 8/8.1 and Windows 10 compatible.

• Executables include a VERSIONINFO resource, which can be edited by the user.

• Executables can have a multi-format icon (e.g. with different sizes and bit depths); LB4 supports only 32x32 16-color icons.

• LBB and its executables run successfully even if DEP (Data Execution Prevention) is fully enabled.

• Compiled executables are much more secure. The TKN files generated by LB4 are easily reverse-engineered to recover the BASIC program, and even your LB User Name and Password!

• Resource files, e.g. bitmaps, may be embedded in the executable, and will be automatically extracted when it is run.

• You may compile your program as a Console Application, e.g. for running from a command prompt.

• Random Access Files are not limited to a maximum size of 4 Gbytes, and record numbers are not limited to a 32-bit value.

Bugs fixed

• TIMER does not cause the PROMPT statement to misbehave, and you can specify a subroutine to be called instead of a branch label (this option does not work correctly in LB).

• You can successfully pass a GLOBAL variable as a parameter to a SUB or FUNCTION.

• SORT and string comparisons use the conventional ASCII character sequence, and repeating a sort leaves the order unchanged.

• Recursion works reliably (in LB 4.04 it may not work when compiled to an EXE).

• The INPUT statement will accept a string variable as the prompt (the Liberty BASIC Help file says this works, but it doesn't in LB 4.04).

• The RND function is improved compared with the LB 4.04 version, and doesn't suffer from bias.

• The MIDDLEBUTTONMOVE event works correctly (in LB 4.04 it never fires).

• The PIE and PIEFILLED graphics commands work correctly.

• The TRAPCLOSE command works correctly with a TEXT window (in LB the window is unconditionally closed).

• The INPUTCSV statement works correctly even if a record contains embedded quotes.

• Many other Liberty BASIC bugs are fixed in LB Booster.

New features

• You can change the printer font within a page. If you assign a new value to PrinterFont$ it will immediately affect subsequent output with LPRINT, allowing you to mix different fonts and styles (e.g. bold) on the same sheet.

• You can change the current printer (used by LPRINT and the graphics PRINT command) by setting PrinterName$ to the name of the printer, e.g. PrinterName$ = "DoPDF v7".

• A new statement PAGESETUPDIALOG is implemented. This displays the standard Page Setup dialogue box, which allows the user to select the margins and paper orientation (portrait or landscape) that will be used by a subsequent LPRINT.

• Graphics 'stick' (i.e. automatically get redrawn when a window is restored or uncovered) without any extra effort by the programmer.

• The TEXTEDITOR control can be configured for word-wrap using STYLEBITS (LB4's TEXTEDITOR does not support word-wrap at all).

• The unary minus is supported. For example the statement 'y = −x' is valid in LBB.

• USING() supports a much wider range of options than the LB4 version, including trailing minus, leading or trailing plus, leading asterisks, currency ($ and £), thousands separated by commas and scientific notation.

• DATE$() can return the date in many additional formats, such as European day-month ordering, hyphen delimiters or the month name as an abbreviation. For example PRINT date$("dd/mm/yyyy") or PRINT date$("dd-mmm-yyyy").

• Array elements and structure members can be read directly from a DATA statement, e.g. READ array(i), and can be passed by reference to SUBs and functions.

• An entire array may be passed as a parameter to a function or subroutine, making it possible to write general-purpose routines which operate on the contents of any specified array.

• LOADBMP accepts a wider range of BMP files than LB4, including files created by Photoshop and GIMP.

• The HWND() function has been extended to work with files and communication ports as well as windows. It returns the native Windows file handle, making it possible to use file-related API functions on files opened in LBB.

• The background color of (for example) a STATICTEXT control may be selected independently of the background color of its parent window, by changing the value of the BackgroundColor$ variable in between.

• EXIT can exit from nested loops. For example if a FOR...NEXT loop is nested inside a DO loop, an EXIT DO used within the FOR...NEXT loop will exit both loops.

• Sprites can have a linear transparency (alpha mask), allowing the background to show through to varying degrees.

• Unicode text is supported in the mainwin and when outputting to the printer using LPRINT. There is also partial support for displaying Unicode in a GUI control, with the help of some API code.

• Anywhere you can specify a color using one of the preset names (e.g. "brown") you can alternatively specify it using an RGB value (e.g. "0 127 200"). LB4 doesn't allow you to set a GUI color (e.g. BackgroundColor$) that way.

• OPEN can open a parallel port (e.g. open "LPT1:" for output as #lpt), for example in order to send data to a printer that does not have (or need) a printer driver.

• MAPHANDLE can be used with child controls as well as with windows. This allows, for example, the creation of multiple child controls in a loop, something you cannot normally achieve in LB4.

• A TEXTEDITOR control can be used in a DIALOG window, allowing entry of multi-line text (the Enter key moves the cursor to the next line rather than activating the 'default' button).

• The GETBMP command can 'see' graphics which are outside the currently visible window, so if you have a scrollable graphics window you can get its entire contents into a bitmap.

• The !CONTENTS? command also works with STATICTEXT controls.

• The !AUTORESIZE command also works with TEXTBOX and LISTBOX controls.

• You can create three- (and more) dimensional arrays using DIM, for example DIM array$(1,2,3,4), but you cannot subsequently resize the array using REDIM (you can, however, use REDIM with the original dimensions simply as a means of emptying the array).

• You can assign a new value to a sub-string, for example MID$(test$,7,1) = "W" or RIGHT$(hello$,6) = "world!".

• A %mode directive optionally enables a standard INT function and conventional precedence of AND over OR.

• An %options directive controls the character encoding and emulation of the string-slicing functions.

• An 'include' directive supports splitting up a large program into modules, and the use of code libraries.
  The syntax is: 'include filename.bas.

• Native arrays of structures are supported, they may have any number of dimensions.
  To declare an array of structures: STRUCT name(dims), member1 AS type, member2 AS type...
  To access a structure array member: PRINT name(index).member.struct

• Compound assignment operators (+=. ‑=, *=, /=) are provided.

• The RUN statement has an option to wait until the program exits.

• The graphics PRINT command has an option to suppress the dump.

• You can paste text into the mainwin INPUT statement using Ctrl+V.

• Object Oriented Programming (OOP) is supported.

• Structured Exception Handling (SEH) is supported.

• A new reserved word PrinterMargin$ is introduced which controls output from the LPRINT statement. It should be set to a string such as "10,10,10,10" which sets the left, bottom, right and top margins respectively to 10 millimetres (note that this is in addition to any fixed printer margins). PrinterMargin$ also initialises the PAGESETUPDIALOG.

• A new reserved word PrinterColor$ is introduced which controls the color of text output by the LPRINT statement. It may be set to the name of a color such as "red" or to an RGB triplet such as "0 127 200". It will immediately affect subsequent output, allowing you to mix different colors on the same sheet, but will only work after something has already been printed.

• Array arithmetic is supported, for example a() = b() - c()   or  a$() = b$() + "!". You can also initialise an entire array to the same value, for example a() = 42.

• Random Access Files may be opened for output (creating a new file) and for input (i.e. read-only) making it possible for a file to be concurrently open for output in one program and open for input in one or more other programs. This can be valuable in a multi-user environment.

• The FILES statement returns each file's date/time stamp in a standard, sortable, format in column 4 of the array.

Installation

You can, if you wish, create a desktop shortcut to the program by right-dragging the LBB.exe file to your desktop and selecting 'Create shortcut here' from the menu that appears when you release the mouse button. You can create a shortcut in your Start Menu in a similar way.

LBB requires Windows 2000 or later. It is not compatible with Windows 95, Windows 98 or Windows Me. Sprites require a CPU with 'integer SSE' support, i.e. an Intel Pentium III or an AMD Athlon or later.

Compatibility

1. There are no graphics segments; the 'delsegment' and 'segment' commands are ignored. However, on the plus side no special measures are required to make graphics 'stick'; if your program suffers from this problem under LB4 it won't when run under LBB!

2. LBB does not support arbitrary precision arithmetic; integers (whole numbers) are limited to the range −18,446,744,073,709,551,615 to +18,446,744,073,709,551,615. Values outside this range will be stored as floating-point numbers and accuracy may suffer. In addition, the bitwise operations AND, OR and XOR work only with 64-bit integer values.

3. The EVAL function works only with simple expressions containing 'standard' BASIC functions, and may fail if the expression contains variable names starting with a keyword. EVAL doesn't work if the expression contains a structure member, or a function name in mixed-case (e.g. Sqr).

4. Child control handles must be mapped explicitly, e.g. MAPHANDLE #old.te,#new.te; mapping the parent window's handle is not sufficient.

5. When printing a window, the resulting quality on the printer is no better than it is on the screen (but see here).

6. The size of the 'canvas' onto which you can draw in a graphics box is limited (the width is limited to the width of your screen display). You can increase it using the horizscrollbar and/or vertscrollbar commands.

7. The mainwin can hold only about 84 lines of text; if more lines are output the remainder will be 'scrolled off' the top of the window and lost. Also, the mainwin has no menu. You can copy the contents of the mainwin onto the clipboard by typing Ctrl+Tab.

8. If one of the keypad number keys is pressed, two 'when characterInput' events are generated. One is the regular event that LB4 generates, and the other is a 'special key' event (LEN(Inkey$)=2). This makes it possible to distinguish the keypad from the regular number keys.

9. The syntax for serial port parameters is slightly different. The basic options are the same, so for example this works:

   open "COM1:9600,n,8,1" for random as #comm
   

   but when specifying 'handshaking' parameters the syntax accepted by LBB is as follows:

   open "COMn: [baud=b] [parity=p] [data=d] [stop=s]
         [to=on|off] [xon=on|off] [odsr=on|off] [octs=on|off]
         [dtr=on|off|hs] [rts=on|off|hs|tg] [idsr=on|off]"
   

   A full description of these parameters can be found here.

10. In a single-line IF statement LBB may behave differently from LB4 if there are multiple (cascaded) IFs and an ELSE clause. To resolve this recast the code as nested multi-line IFs.

11. RESUME resumes execution at the line (not statement) where the error occurred; if in doubt use only one statement per line. Also, RESUME must be used within the scope of the SUB or FUNCTION (if any) in which the error occurred.

12. Opening a file in BINARY mode does not prevent PRINT outputting a newline (CRLF). To suppress the newline add a trailing semicolon (;) to the PRINT statement; this will not affect the operation of the program in LB4.

13. The maximum length of a DATA statement is approximately 250 characters.

14. There is a limit of 8 on the number of simultaneously-open RANDOM files; however this may be worked around by opening and closing the files for every transaction (GET or PUT).

If, exceptionally, the only way to achieve compatibility is to use different code for LB4 and LBB you can test which platform your program is running under as follows:

if instr(Platform$, "LBB") then
  print "Running under LBB"
else
  print "Running under LB"
end if 

Liberty BASIC 4.5.0

The LBB implementation of INPUTCSV, unlike LB's, accepts all valid CSV files including those in which records contain embedded quote characters ("). It also accepts CSV files with either Windows-style (CRLF) or Unix-style (LF) line terminations, and files using a delimiter other than a comma.

The new LB 4.5.0 functions are made available through the supplied library file lb45func.bas. This file contains BASIC implementations of the after$(), afterlast$(), endswith(), httpget$(), remchar$(), replstr$(), and upto$() functions. If you want to use any of these functions, add the following line at the very end of your program:

'include lb45func.bas

Directives

'include filename.bas

For maximum compatibility with Liberty BASIC Workshop the 'include directive is ignored when it is at the very beginning of the program. See this Wiki article for more information, and for details of how to integrate LBW with LBB.

%mode std

%mode lb4

%options ansi

%options unicode

%options slicing

%options noslicing

! BBC code

!COLOR 1
print "This is red"

Operation

Command line options

The following command line switches are accepted:

-R	Run a BAS file on startup
-D	Debug a BAS file on startup
-T	Translate and tokenise a BAS file to an LBB file
-C	Translate and compile a BAS file to an EXE file
-A	Automatically exit LBB on completion
-M	Minimise LBB on startup

Examples:

LBB program.bas           (loads the program)
LBB -R -A -M program.bas  (runs the program)
LBB -T -A -M program.bas  (generates program.lbb)

The title bar

The menu bar

The toolbar

From the File menu: New, Load, Save and Print.
From the Edit menu: Undo, Redo, Cut, Copy, Paste, Find and Replace.
From the Run menu: Run Program, Debug Program and Make Executable.

The toolbar also contains a combobox which lists all the branch labels, SUBs and FUNCTIONs in the currently-loaded program. Selecting one of these from the list causes the editor to scroll directly to the appropriate line. You can choose whether the list is sorted alphabetically or according to the order in which the labels etc. appear in the program.

The status bar

At the right-hand end of the status bar are displayed the current Encoding (ANSI or Unicode), the Insert/Overtype status, the Caps Lock setting, the Num Lock setting and the Line number of the line containing the text cursor (caret), starting at line 1.

The File menu

New

Load

You can alternatively load a .TKN file created by Liberty BASIC. This can be very useful if you have deleted or mislaid a program, but still have a TKN file generated from it. Note that you must know the original user's Name and LB Password; it is not possible to load a TKN file created by Just BASIC or an unregistered copy of Liberty BASIC.

If the current program has been modified and not saved, you are first prompted to save it.

Save

Save As

The program is saved either as ANSI/ASCII text or with UTF-8 encoding, depending on the current setting of the Unicode Support option.

Insert

Compare

To scroll down to the next difference press F8; to scroll up to the previous difference press F7. Note that if your program contains Unicode text this will not display correctly. When you have finished studying the differences you can hide the right-hand pane using the Show LBB pane selection in the Options menu.

Page Setup

Print

Recent files

Exit

The Edit menu

Undo

Redo

Cut

Copy

Paste

Delete

Select All

Find

Find Next

Find Previous

Replace

Go To

The Run menu

Run Program

Debug Program

Profile Program

Make Executable

You are prompted to supply a filename and location for the executable; by default it will be stored in the same directory as the Liberty BASIC program but with the extension '.exe'. LBB incorporates a manifest in the executable, to enable the use of Windows XP Visual Styles and improve compatibility with Windows™ Vista, Windows™ 7, Windows™ 8/8.1 and Windows™ 10.

The following additional options are available:

• The program's icon may be changed by clicking on the Change Icon button in the dialogue box. You can select an icon either from an existing executable file, or from a separate icon file (for example as produced by an icon editor). If the file contains a number of different icons, you can select the one you want to use. Please respect Copyright, and use only an icon which you have generated yourself or have legitimately obtained for this purpose.

  If the selected icon contains multiple variants with different resolutions (e.g. 16x16, 32x32, 48x48) and/or different color depths (e.g. 8 bits, 32 bits) all the variants will be stored in the compiled executable file. The version used will be the one most suited to the current display settings. Note that such an icon can significantly increase the size of the executable.

• You can embed resource files needed by your program, for example bitmap files or sound files; these will automatically be extracted when the executable is run. This may make it unnecessary to use a separate installer utility, and can be particularly useful in allowing your program to be run directly from a website. Do not incorporate files which your program needs to modify, since any changes will be overwritten the next time the program is run!

  To embed resource files in the executable click the Add button; you may select multiple files. The files can be either in the directory containing your program, or in a subdirectory (the subdirectory will be created when the program is run, if necessary). To remove resource files highlight them in the list and click Remove. Note that if your program is installed in a 'protected' location, administrative privileges will be required the first time it is run, to allow the embedded files to be extracted; thereafter it may be run normally.

  To embed resource files which will be extracted to the target PC's temporary directory (%TEMP%) - or a subdirectory thereof - click the Add Temp button. The files must be copied to your own temporary directory before the program can be compiled, but you are likely to want to do that anyway for the purposes of testing in the IDE.

• You can create a Console Application by selecting the checkbox. Such an application uses the console terminal instead of the mainwin; output which would normally go to the mainwin will instead go to the console (stdout) and input which would normally be entered in the mainwin will instead be read from the console (stdin). To forcibly close a console application type Ctrl+Break.

• You can edit the Version Information which will be embedded in the executable. There are three checkboxes (Debug, Patched and Prerelease) and eight text fields. Two of those fields (File version and Product version) are expected to contain a numeric version number in the format n.n.n.n (e.g. 5.94.123.678); if you use a different format a warning is issued but the creation of the executable proceeds normally.

Make *.LBB file

Kill BASIC Programs

In the current version of LBB you cannot choose which programs to kill.

The Options menu

Show LBB Pane

This option is also used to dismiss the differences listing generated by the File... Compare command.

Emulate Slicing

Unicode Support

Syntax Coloring

Auto Indenting

Set Font

Set Printer Font

Set Colors

Note that the window background color is set, as usual, in your Windows display preferences (for example right-click on the desktop and select Properties or Personalize).

The Help menu

Help Topics

Email

Website

Discussion group

Message board

Wiki

About LB Booster

The Editing Pane

Keyboard commands

Key	Operation
Insert	Toggle between insert and overtype mode. In overtype mode any character typed will over-write the existing character at that position on the line. In insert mode any character typed will 'push' the rest of the line to the right to make room.
Delete	Delete the character to the immediate right of the cursor (caret) and move the rest of the line left to fill the gap.
Home	Move the cursor (caret) to the start of the current program line, and scroll the display horizontally (if necessary) to ensure that the cursor is visible.
Ctrl+Home	Move the cursor (caret) to the start of the program, and scroll the display horizontally and/or vertically (if necessary) to ensure that the cursor is visible.
End	Move the cursor (caret) to the end of the current program line, and scroll the display horizontally (if necessary) to ensure that the cursor is visible.
Ctrl+End	Move the cursor (caret) to the end of the program, and scroll the display horizontally and/or vertically (if necessary) to ensure that the cursor is visible.
Page Up	Display the previous 'page' of the program by scrolling the display down by one screenful (less one line) or until the first line of the program is visible, whichever is less. If the first line of the program is already in view, Page Up has no effect.
Page Down	Display the next 'page' of the program by scrolling the display up by one screenful (less one line) or until the last line of the program is visible, whichever is less. If the last line of the program is already in view, Page Down has no effect.
	Move the cursor (caret) one character to the left, and scroll the display horizontally (if necessary) to ensure that the cursor remains visible. If Shift is held down, select (or de-select) a character.
	Move the cursor (caret) one character to the right, and scroll the display horizontally (if necessary) to ensure that the cursor remains visible. If Shift is held down, select (or de-select) a character.
	Move the cursor (caret) up one line, and scroll the display vertically (if necessary) to ensure that the cursor remains visible. If Shift is held down, select (or de-select) a line. If the cursor is already on the first line, the key has no effect.
	Move the cursor (caret) down one line, and scroll the display vertically (if necessary) to ensure that the cursor remains visible. If Shift is held down, select (or de-select) a line. If the cursor is already on the last line, the key has no effect.
Backspace	Delete the character immediately to the left of the cursor (caret), and move the cursor left one position. The rest of the line, to the right of the cursor, is moved left to fill the gap. If the cursor is at the beginning of a line, delete the preceding 'new line' and concatenate the contents of the present line onto the end of the previous line.
Return (Enter)	Insert a 'new line' at the current position of the cursor (caret). Everything to the right of the cursor will be moved onto the next line, and the rest of the program is moved down one line to make space. By this means you can split an existing line into two or more lines
Ctrl+	Move the cursor (caret) one word to the left, and scroll the display horizontally (if necessary) to ensure that the cursor remains visible. If Shift is also held down, select (or de-select) a word.
Ctrl+	Move the cursor (caret) one word to the right, and scroll the display horizontally (if necessary) to ensure that the cursor remains visible. If Shift is also held down, select (or de-select) a word.
Tab	Enter space characters so as to move the text cursor (caret) to the next multiple-of-four column. For correct alignment on the screen and/or the printer a fixed-pitch (monospaced) font must be selected.
Ctrl+Backspace	Delete the previous word (i.e. to the left of the cursor) and move the rest of the line left to fill the gap.
Ctrl+Delete	Delete the next word (i.e. to the right of the cursor) and move the rest of the line left to fill the gap.

The 'printing' keys (letters, numbers and symbols) cause the appropriate character to be entered at the position of the cursor (caret), and the cursor position is then updated. If any text is selected (highlighted) when the key is pressed, it is first deleted.

Mouse commands

Action	Operation
Left click	Clicking in the editing pane with the left mouse button causes the text cursor (caret) to be moved to the character position nearest to the mouse pointer. If Shift is held down, the region between the previous position of the text cursor and the new position will be selected.
Left double-click	Double-clicking in the editing pane with the left mouse button causes the word under the mouse pointer (and the following space, if any) to be selected. The selected word can then be cut, copied, deleted or dragged.
Left triple-click	Triple-clicking in the editing pane with the left mouse button causes the entire line under the mouse pointer to be selected. The selected line can then be cut, copied, deleted or dragged.
Left drag	Holding down the left mouse button and 'dragging' the mouse pointer over the program displayed in the editing pane causes a section of the program to be selected.
Right click	Clicking in the editing pane with the right mouse button causes the Context Menu to be displayed.
Wheel	Operating the mouse wheel causes the editing pane to scroll vertically, usually by three lines per 'notch'.
Ctrl+Wheel	Holding down the Ctrl key and operating the mouse wheel causes the editing pane to zoom; note that this will not work if you have selected the System Fixed Font (FixedSys).

Drag and Drop

Alternatively, if you hold down the Ctrl key before releasing the left button the selected text is copied to the location where the button was released (a plus sign appears next to the mouse pointer indicating a copy rather than a move). This is equivalent to a copy-and-paste operation via the clipboard. If you want to cancel the Drag and Drop operation you can do that by pressing the ESCape key before you release the left button, or by releasing the button when the pointer is inside the selected area.

Context Menu

The context menu contains the same items as the Edit menu except in the following circumstances:

• If you right-click on a label, SUB name or FUNCTION name (or press Shift+F10 when the text cursor is in one of these) the menu will contain the additional item 'Jump to' at the top. Selecting that item will cause the editing pane to scroll so that the label, subroutine or function is visible.

• If you have previously executed a 'Jump to' the menu will contain the additional item 'Go back'. Selecting that item will scroll the editing pane back to where it was before the jump took place. Up to 16 jumps may be reversed in this way.

Scroll bars

• Dragging the scroll box (thumb) along the bar causes the display to scroll accordingly. The size of the scroll box indicates the proportion of the entire program which is displayed within the editing pane - the larger the scroll box the more of the program which is visible.

• Clicking on one of the arrow buttons causes the display to scroll in units of one character (horizontally) or one line (vertically).

• Clicking in the shaded regions between the scroll box and the arrow buttons causes the display to scroll by one page (less one line) vertically, or by one window's width horizontally.

• If your mouse has a 'wheel', rotating the wheel causes the display to scroll vertically, usually by three lines per 'notch'.

• If you have a touch screen, you can scroll by 'flicking' in the appropriate direction. Alternatively you can scroll vertically by dragging with a single-finger and horizontally by dragging with two-fingers.

Language summary

Statements

BEEP

BMPBUTTON #window[.ext], bmpfile$, handler, anchor, posx, posy

BMPSAVE "bitmap", bmpfile$

BUTTON #window[.ext], "text", handler, anchor, xpos, ypos [, width, height]

CALL subname [parameter {, parameter}]

CALLBACK addressvar, funcname(type {, type}), returntype

CALLDLL #dllhandle, "FunctionName" {, param AS type}, returnvar AS type

CASE ELSE | expression {,expression}

CATCH

CHECKBOX #window[.ext], "Caption", sethandler, resethandler, xpos, ypos, width, height

CLASS classname [INHERITS parentclass]

CLOSE #handle

CLS

COLORDIALOG color$, chosen$

COMBOBOX #window[.ext], array$(), handler, xpos, ypos, width, height

CONFIRM question$; replyvar$

CURSOR cursortype

DATA [constant {, constant}]

DIM array(size{,size}) {, array(size{,size})}

DISCARD object

DO [WHILE | UNTIL condition]

DUMP

ELSE

END

END CLASS | FUNCTION | IF | SELECT | SUB | TRY

EXIT FOR | WHILE | DO | FUNCTION | SUB

FIELD #file, length AS var {, length AS var}

FILEDIALOG "Title", template$, returnvar$

FILES path$, [filter$,] array$()

FONTDIALOG fontspec$, returnvar$

FOR loopvar = start TO finish [STEP increment]

FUNCTION name([[BYREF] parameter {, [BYREF] parameter}])

GET #file, recordnumber

GETTRIM #file, recordnumber

GOSUB destination

GLOBAL variable {, variable}

GOTO destination

GRAPHICBOX #window.ext, xpos, ypos, width, height

GROUPBOX #window[.ext], "label", xpos, ypos, width, height

IF condition THEN

INPUT ["prompt";] returnvar {, returnvar}

INPUT #handle, returnvar {, returnvar}

INPUTCSV [delim$,] #file, returnvar$ {, returnvar$}

KILL filespec$

LET variable = expression

LINE INPUT ...

LISTBOX #window.ext, array$(), handler, xpos, ypos, width, height

LOADBMP "bitmap", bmpfile$ | handle

LOCATE column, row

LOOP [WHILE | UNTIL condition]

LPRINT [[TAB(n);] expression {, | ; [TAB(n);] expression} [, | ;]]

MAINWIN columns [rows]

MAPHANDLE #oldhandle, #newhandle | newhandle$

MENU #handle, "title", "text", handler {, "text", handler}

NAME oldspec$ AS newspec$

NEW object[(dim [,dim])] AS class [parm {, parm}]

NEXT [loopvar]

NOMAINWIN

NOTICE string$ | number

ONCOMERROR [handler]

ON ERROR GOTO destination | 0

OPEN device$ FOR type AS #handle [LEN=reclen]

OUT port, data

PAGESETUPDIALOG

PLAYMIDI midifile$, length

PLAYWAVE wavfile$ [, mode ]

POPUPMENU "text", handler {, "text", handler}

PRINT [[TAB(n);] expression {, | ; [TAB(n);] expression} [, | ;]]

PRINT #handle, expression [;]

PrinterColor$ = "color"

PRINTERDIALOG

PrinterFont$ = "Font_Name points style"

PrinterMargin$ = "left, bottom, right, top"

PrinterName$ = "New printer name"

PRIVATE

PROMPT "prompt string"; replyvar$

PUT #file, recordnumber

RADIOBUTTON #handle.ext, "label", sethandler, resethandler, xpos, ypos, width, height

RANDOMIZE [seed]

READ variable {, variable}

READJOYSTICK 1 | 2

REDIM array(size{,size}) [, array(size{,size})]

REM remark

RESTORE [destination]

RESUME

RETURN

RUN command$ [, state]

SCAN

SEEK #handle, position

SELECT CASE [testexpression]

SORT array(), start, end [, column]

STATICTEXT #handle[.ext], "title", xpos, ypos, width, height

STOP

STOPMIDI

STRUCT name[(size{,size})], member AS type {, member AS type}

STYLEBITS #handle[.ext], addbits, removebits, addextendedbits, removeextendedbits

SUB name [[BYREF] parameter {, [BYREF] parameter}]

TEXTBOX #handle.ext, xpos, ypos, width, height

TEXTEDITOR #handle.ext, xpos, ypos, width, height

THROW errnumber [, errstring$]

TIMER milliseconds, handler | 0

TITLEBAR title$

TRACE 0 | 1 | 2

TRY

UNLOADBMP "bitmap"

UNTIL

WAIT

WEND

WHILE condition

Functions

ABS(numeric)

ACS(numeric)

ASC(string$)

ASN(numeric)

ATN(numeric)

CHR$(numeric)

COS(numeric)

DATE$([format$ | dayno])

DECHEX$(numeric)

EOF(#handle)

EVAL(string$)

EVAL$(string$)

EXP(numeric)

HBMP("bitmap")

HEXDEC(hex$)

HWND(#handle[.ext])

INP(numeric)

INPUT$(count)

INPUT$(#handle, count)

INPUTTO$(#handle, char$))

INSTR(searchin$,searchfor$[,startat])

INT(numeric)

LEFT$(string$,count)

LEN(string$ | structname.struct)

LOC(#handle)

LOF(#handle)

LOG(numeric)

LOWER$(string$)

MAX(numeric,numeric)

MID$(left$,start[,count])

MIDIPOS()

MIN(numeric,numeric)

MKDIR(path$)

NOT(numeric)

RIGHT$(string$,count)

RMDIR(path$)

RND([n])

SIN(numeric)

SPACE$(n)

SQR(numeric)

STR$(numeric)

TAN(numeric)

TIME$([format$])

TRIM$(string$)

UPPER$(string$)

USING(template$, numeric)

VAL(string$)

WINSTRING(pointer)

WORD$(string$, number [, delim$])

Operators

numeric AND numeric

numeric MOD numeric

numeric OR numeric

numeric XOR numeric

Graphics commands

BACKCOLOR color

BOX xpos ypos

BOXFILLED xpos ypos

CIRCLE radius

CIRCLEFILLED radius

CLS

COLOR color

DISCARD

DOWN

DRAWBMP bitmap x y

ELLIPSE width height

ELLIPSEFILLED width height

FILL color

FLUSH [segment]

FONT typeface [width] height {style}

GETBMP bitmap xpos ypos width height

GO distance

GOTO xpos ypos

HOME

HORIZSCROLLBAR on | off [min max]

LINE x1 y1 x2 y2

NORTH

PIE width height start sweep

PIEFILLED width height start sweep

PLACE xpos ypos

POSXY xvar yvar

PRINT [size [nodump]]

REDRAW [segment]

RULE code

SET xpos ypos

SIZE thickness

STRINGWIDTH? string$ retvar

TURN degrees

UP

VERTSCROLLBAR on | off [min max]

WHEN event handler

leftButtonDown
leftButtonUp
leftButtonDouble
leftButtonMove
rightButtonDown
rightButtonUp
rightButtonDouble
rightButtonMove
middleButtonDown
middleButtonUp
middleButtonDouble
middleButtonMove
mouseMove
characterInput

\text string

Text commands

!BACKCOLOR color

!CLS

!CONTENTS string$ | #filehandle

!CONTENTS? string$

!COPY

!CUT

!FIND string$

!FINDBACK string$

!FONT typeface [width] height {style}

!FORECOLOR color

!INSERT string$

!LINE n string$

!LINES retvar

!MODIFIED? answer$

!ORIGIN column row

!ORIGIN? colvar rowvar

!PASTE

!RESETFIND

!SELECT column row

!SELECTALL

!SELECTION? string$

Other GUI commands

AUTORESIZE

BITMAP bitmap

DISABLE

ENABLE

HIDE

LOCATE xpos ypos [width height]

REFRESH

RELOAD

RESET

RESIZEHANDLER handler

SELECT string

SELECTINDEX index

SELECTION? string$

SELECTIONINDEX? retvar

SET

SETFOCUS

SHOW

SINGLECLICKSELECT [handler]

TRAPCLOSE handler

VALUE? retvar$

Sprite commands

ADDSPRITE sprite bitmap { bitmap}

BACKGROUND bitmap

BACKGROUNDXY x y

CENTERSPRITE sprite

CYCLESPRITE sprite dir [once]

DRAWSPRITES

REMOVESPRITE sprite

SPRITECOLLIDES sprite list$

SPRITEIMAGE sprite bitmap

SPRITEMOVEXY sprite xshift yshift

SPRITEOFFSET sprite xoff yoff

SPRITEORIENT sprite orientation

SPRITEROUND sprite

SPRITESCALE sprite scale

SPRITETOBACK sprite

SPRITETOFRONT sprite

SPRITETRAVELXY sprite x y speed handler

SPRITEVISIBLE sprite on | off

SPRITEXY sprite xpos ypos

SPRITEXY? sprite retx rety

Reserved names

BackgroundColor$, Com, ComboboxColor$, ComError$, ComErrorNumber, CommandLine$, ComPortNumber, DefaultDir$, DisplayHeight, DisplayWidth, Drives$, Err, Err$, ForegroundColor$, Inkey$, Joy1button1, Joy1button2, Joy1x, Joy1y, Joy1z, Joy2button1, Joy2button2, Joy2x, Joy2y, Joy2z, ListboxColor$, MouseX, MouseY, Platform$, PrintCollate, PrintCopies, PrinterColor$, PrinterFont$, PrinterMargin$, PrinterName$, StartupDir$, TextboxColor$, TexteditorColor$, UpperLeftX, UpperLeftY, Version$, WindowHeight, WindowWidth.

Object Oriented Programming

Below is a brief syntax description, but for more details and examples see this article at the LBB Wiki.

Instantiating an object

NEW object AS class [parm {, parm}]                ' calls constructor [with parameters]
NEW objarr(dimensions) AS class                    ' calls default constructors (if any)

Calling object methods

CALL object::method [parameter {, parameter]}]     ' subroutine-like method
lvalue = object::method([parameter {, parameter}]) ' function-like method
CALL objarr(indices)::method [parm {, parm]}]      ' subroutine-like method
lvalue = objarr(indices)::method([parm {, parm}])  ' function-like method

Discarding an object

DISCARD object                                     ' calls destructor (if any)
DISCARD objarr()                                   ' calls destructor in each (if any)

Defining a class

The class properties (variables and arrays) are private to the class: they can be accessed only from the methods in the same class; this is similar to the scope of variables within ordinary SUBs and FUNCTIONs except that class properties 'remember' their values from one call of a method to the next. Unlike conventional arrays, class property arrays are not global.

The properties should be declared first, using a special form of the DIM statement, followed by the methods. The default constructor(s), if any, have the same name as the class; the destructor (if any) has the name of the class prefixed with a tilde ~.

To call a method in the same class, prefix its name with this::, a PRIVATE method can only be called this way.

CLASS class [INHERITS class]
  ' class properties are automatically private
  DIM var | var$ | array(n) | array$(n) | child AS class {, ....}

  SUB class
    ' default constructor (optional)
  END SUB

  SUB ~class
    ' destructor (optional)
  END SUB

  SUB class parm {, parm]}
    ' constructor with parameter(s)
  END SUB

  [PRIVATE] SUB method [parm {, parm}]
    ' subroutine-like or setter method
    CALL this::method [parameter {, parameter]}]    ' call another method in this class
    lvalue = this::method([parameter {, parameter}])' function-like method in this class
    CALL child::method [parameters]                 ' call method in child class
    lvalue = child::method [parameters]             ' function in child class
    lvalue = property                               ' read property variable
    property = rvalue                               ' write property variable
  END SUB

  [PRIVATE] FUNCTION method [parm {, parm}]
    ' function-like or getter method
  END FUNCTION
END CLASS

OOP notes

• Methods can't take BYREF parameters which aren't variables or arrays.

• Methods are overloaded using the number of parameters as a signature.

• An object name cannot be the same as a STRUCT name.

• The default constructor (with no parameters) is always called (first) if present.

• The constructor/destructor in a parent class is not called automatically if the descendent class has one.

• Constructors/destructors in a child class aren't called automatically.

Structured Exception Handling

This is the structure of the TRY clause:

TRY
  ' Code which might fail
CATCH
  ' Code to execute if an error occurs in the TRY clause
END TRY

for n = -3 to 3
  try ' code to try
    print "The reciprocal of "; n ; " is ",
    print 1/n, 
    print "(successful)"
  catch ' code to run on an error
    print Err$;
    print " (failed: code "; Err; ")"
  end try ' end of try clause
next n

The reciprocal of -3 is     -0.333333333  (successful)
The reciprocal of -2 is     -0.5          (successful)
The reciprocal of -1 is     -1            (successful)
The reciprocal of 0 is      Division by zero at line 4 (failed: code 11)
The reciprocal of 1 is      1             (successful)
The reciprocal of 2 is      0.5           (successful)
The reciprocal of 3 is      0.333333333   (successful)

throw 88, "My custom error"

throw 88

Debugging

A small, resizable, debugging window will open, having a toolbar and a scrollable listbox. The listbox displays the variables in your program, updating as their values change and new ones are created. Initially it will contain the 'reserved' variables (e.g. DefaultDir$ and Drive$) and any globals defined in your program. If you want to monitor the value of a specific variable you can click on it; it will then be highlighted and the list will be scrolled automatically to keep it in view. To deselect that variable click in the title bar of the debugging window.

The toolbar contains 'Resume', 'Pause', 'Step into' and 'Step over' buttons (hovering your mouse over a button will indicate its function in a tooltip). 'Resume' causes execution of the program to continue at full speed until it encounters a WAIT or TRACE 2 statement, stops to receive user input (e.g. INPUT or PROMPT), hits a breakpoint (see below) or the 'Pause' button is clicked. If your program executes a WAIT statement whilst in a paused state, you may need to 'unpause' it (click on 'Resume') and pause it again before it will respond to an event such as a TIMER tick, button press etc.

The 'Step into' and 'Step over' buttons are active only when the program is paused. 'Step into' causes a single statement to be executed; you may find that some statements require it to be clicked more than once. If the statement transfers control into a function or subroutine 'Step into' will cause execution to pause within that module. 'Step over' causes execution to pause again only on the next line, so if the statement transfers control into a function or subroutine it will run at full speed until it returns, and if the statement terminates a loop (e.g. a NEXT or WEND) execution will continue at full speed until the loop is complete. It is not usually desirable to use 'Step over' on an END FUNCTION, END SUB or RETURN statement.

You can insert temporary breakpoints in your program by double-clicking in the left margin of the editing pane, a small square will appear there as a marker; to remove the breakpoint double-click again (to clear all breakpoints right-click in the margin and select the appropriate menu item). When a breakpoint is encountered during execution the program will pause, as if you had clicked on the 'Pause' button in the debugging window's toolbar; breakpoints have no effect if you use Run rather than Debug. Breakpoints are linked to the line number, so if you insert or delete any lines above a breakpoint it will move in relation to the code. You cannot add or remove breakpoints once the program is running.

A 'permanent' breakpoint can be inserted by means of a TRACE 2 statement; this has the same effect as a temporary breakpoint but can be saved as part of the program. It will only pause the program when you are debugging it, but you are recommended to remove TRACE 2 statements once your program is fully tested since their presence may cause execution to be slowed slightly. Note that TRACE 1 has a different function in LB Booster from that in LB 4.04: it causes line numbers to be logged to the mainwin during execution. LBB has no equivalent of LB's animate mode, since the variable list and statement highlighting continue to be refreshed even when the program is running at full speed.

Troubleshooting

• If your program uses the graphics command discard, and does not run properly in LBB, try changing the discard to redraw:

  #w "redraw"
  

• Compatibility with LBB may be impaired if you draw graphics using the Windows API, without periodically executing a wait statement. For example, rather than calling the Sleep API (or simply having an 'infinite loop' containing a scan statement) use a timer/wait combination:

  timer 40, [loop]
  wait
  
  [loop]
  ' do the graphics drawing here
  wait
  

• If you receive the error message 'Bad use of array' check that your program doesn't attempt to access an array before it is DIMensioned. This code, taken from FreeForm404.bas, runs (but doesn't do anything useful) under LB4, but LBB reports an error:

  font$(1)=dFont$
  ...
  dim font$(3)
  

• If you receive the error message 'Handle used for incompatible devices' it means you have used the same handle name for both a file and a window (or a DLL and a window, etc.). LBB needs each handle name to refer to only one kind of device. To fix the problem change one of the handles.

• If you receive the error message 'Duplicate structure with ambiguous member' it means you have used the same name for two different STRUCTs, which share a member having the same name but a different type. To fix the problem change one of the structure or member names.

• If your program uses string slicing (i.e. the LEFT$, MID$ or RIGHT$ functions), and it is giving unexpected results, try selecting Emulate Slicing in the Options menu.

• LBB-compiled programs reserve 500 Mbytes of virtual address space (not the same thing as 500 Mbytes of memory!). If, exceptionally, your virtual memory is heavily fragmented, or if you have disabled VM in your Windows settings, this allocation may fail. In that case add a line similar to this in the [settings] section of LBB.ini (which can be found in your %appdata% folder):

  memory=100000000
  

How It Works

LBB is a hybrid translator and emulator. The translator automatically converts Liberty BASIC syntax to the equivalent BBC BASIC syntax. This translation takes place when you first issue the Run Program or Make Executable command.

The emulator (LBLIB) implements at run-time those aspects of Liberty BASIC which aren't part of the standard BASIC language and which have no direct equivalent in BBC BASIC; principally these are the Graphical User Interface elements (windows, controls, graphics and sprites). The emulator is itself written in BBC BASIC.

When you issue the Make Executable command LBB creates a single-file standalone executable containing the BBC BASIC for Windows run-time engine, the LBLIB emulator and a tokenised/compressed version of the translated BASIC program.

Formal Stuff

LB Booster is the Copyright © 2023 of R. T. Russell.

BBC BASIC for Windows is the Copyright © 2001-2022 of R. T. Russell. The name BBC BASIC is used with the permission of the British Broadcasting Corporation.

Liberty BASIC is the trademark of Carl Gundel trading as Shoptalk Systems.

Liberty BASIC Workshop is the Copyright © 2010 of Alyce Watson.

The aPLib compression library is used with permission. Copyright © 1998-2014 by Joergen Ibsen, All Rights Reserved.