Help

Bubbl Help File

Revision 0.0.9Alpha

Index

Glossary
Alert Instruction
Ask user instruction
Choice instruction
Create instruction
Data types
Delete instruction
Destroy instruction
The Display
DISPLAY table
Edit instruction
Events
Expressions
File format
Filename instruction
For/Next instructions
Formulas
How to ...
How to add 'help' info to programs
How to contact the author
How to display data
How to edit a program
How to play sound
How to search tables
How to store data
How to write a program
How to deploy a program
Common Programming Pitfalls If (then else) instruction
Input instruction
Insert instruction
Instruction Index
Introduction
Let instruction
Looping and iteration
Menu instruction
Notes and comments
Operators
Output mark-ups
Output instruction
Page instruction
PAGE table
Present instruction
Select instruction
Sort instruction
Start and End instructions
Switch instruction
System variables
Update instruction
Wait instruction

Instruction Index

Alert Instruction
Ask user instruction
Choice instruction
Create instruction
Delete instruction
Destroy instruction
Edit instruction
Filename instruction
For/Next instructions
If (then else) instruction
Input instruction
Insert instruction
Let instruction
Menu instruction
Output instruction
Page instruction
Present instruction
Select instruction
Sort instruction
Start and End instructions
Switch instruction
Update instruction
Wait instruction

Glossary

Index

The raw material of information

user	The person at the keyboard/mouse while the program is running
program	A network of one or more instructions which tell the computer what to do if they are 'executed' ('run'). They are essentially state transition diagrams, with flow-charts, representing actions to take, forming a network of links (arcs). The diagram simply specifies how the computer should behave according to it's internal 'state' (c.f. human 'state of mind'). It is a system of behaviour modelling. This is the fundamental concept to apply when programming with BUBBL. Specify the computer's behaviour.
execute	'Run' or 'enact' a program or instruction.
mark-ups	information passed to Output instructions to affect screen position, font, colours etc.
page	A 'window' in which a program's 'output' may be displayed.
output	Information produced by a program for the 'user' to see, read or hear. Examples include writing text or rendering a jpeg or png file, playing a sound clip.
database	One or more 'tables' designed to map onto a particular domain, and used to refer to that domain. For example a telephone directory.
event	A real time occurrence of something relevant, such as a key press or mouse movement. In BUBBL there are built in events for keyboard and mouse input, timing and other uses
table	A data structure consisting of rows and columns of variables to allow very large amounts of data to be expressed or manipulated. In BUBBL columns (also known as fields) are named and rows are numbered. Column values can also be accessed by number: Eg: table[row].col refers to the 'col'th column of the 'row'th row of the table 'table' table[3].2 refers to the second column of the third row of the table 'table'
record	Another name for a row of a table, or single data item with many named 'fields'
variable	A named part of memory used to store data. It can be referred to by its name. The data its stores is called its 'value'
expression	A combination of one or more constants or variable names and operators as a sequence of characters. Expressions can be 'evaluated', meaning that all operators are applied in order of precedence until a constant value remains – the 'returned value'
row	Part of the contents of a table, consisting of a set of associated single values for each column (field) of the table. A whole row of a table is read as a series of comma-separated values, with embedded commas being transposed into '\|' characters.
column	Part of the contents of a table, consisting of the set of all row values for a particular field (column) of the table.
data
field	Refers to a column of a table, or part of a 'tuple' variable or table row. In tables, fields are referred to by name, or by number (1 refers to leftmost). In simple tuple variables they are referred to by number, e.g. “one,two,three”.1 is “one”
instruction	Explicitly codified action or set of actions to be performed by the computer. Instructions are represented as shapes on the screen, with arrowed lines joining them to form a network. The network represents a combination of state and flow control information, yielding an explicit specification of behaviour. Instructions which have characteristically different possible outcomes (e.g. success or failure) have more then one exit link, each link corresponding to a different outcome.
instruction-block	An instruction made up a network of other instructions
parameter	A parameter is an important mechanism used to pass information to or from instructions and instruction blocks. Inside instruction blocks By editing an instruction block's start instruction, one or more parameters may be 'declared' (=made known to the program so that they can be used). They are made visible as editable fields of the instruction-block icons, or as lines within the 'Start Instruction' icon. They are given names, and may be declared to be either input-only or or input and output combined. When a program block is run, the value of the parameter is copied to a local variable with the same name as the parameter. This makes it available to the instruction block. When the instruction block exits, any of these local variables which were declared as output parameters have their values written to the variables used (or 'passed') as the parameter.
iterate	This means to repeat an operation for a number of different objects. To 'iterate over a set' means to take each element of the set (in some arbitrary order) in turn and perform some action with/on it. The For/Next instruction is used to iterate over a set of integers in BUBBL.
link	The connection between two instructions. It is unidirectional (except when going backwards), and when there is more than one link from an instruction they will normally be individually labelled, representing different outcomes from running the instruction.
set	In BUBBL the concept of a set is limited to a set of integers. However this data type is used to hold a set of table row indices, representing a selection or query on a table. This allows many common data manipulation tasks to be undertaken with ease. Sets are expressed as comma-separated ranges of integers inside a pair of curly brackets(braces) E.g. {1..5,14,34} has 7 elements, 1,2,3,4,5,14 and 34
exit link	When programming instruction blocks, it is possible to create multiple links from the instruction block (by editing the start instruction). Within the instruction block each 'end' instruction may be connected to any one of the links. The links are called 'exit links'. They can (and should!) be labelled.
relation	In mathematics this is a formal way of representing the relationships between items of information or data. A relation can be thought of as a table with named columns and numbered rows. The name of the table is the name of the relation, and the column titles are the 'fields' of the relation. Each column, in principle, has some sort of relationship to other columns, and all have a relationship to the 'name' of the relation. E.g. A simple relation used to express personnel details: person(forname,surname,date_of_birth,home_phone) and some members of the relation (or 'tuples'): person(John,Smith,1-12-1990,123456) person(Julie,Snobbit,23-4-1984,102032)
tuple	A tuple is a single member, or row, of a relation.
looping	Looping is a term derived from flow-charts, where a closed loop of linked items is expressed. It is represented in 'structured programming' languages such C and its derivatives by the 'while', 'do-while' and 'for' constructs. The flow chart is not typically encouraged as a design tool within the 'structured' and 'object oriented' programming paradigms, but it is a key conceptual component of BUBBL programming. Its power for expressing algorithms, particularly those with iteration (or 'looping'), is available directly to the BUBBL programmer.

Alert Instruction

Index

This instruction allows the program to give a message to the user.
The user must either press 'Esc', click the 'Ok' button or close the alert pop-up window.
The font, colours etc. used to present the message may be specified in the 'mark-ups' (see 'Output mark-ups ' below).

E.g. The following pops up a box with large (50point) red writing showing the message
'Wake up!' in the middle of the desktop. Adding mark-ups is straightforward and menu-driven (see below).

pops up the following:

Ask user instruction

Index

This instruction prompts the user for a simple Yes/No answer.
The user may also press `Esc`.
Each response results in a different link being followed.
The `mark-ups` allow the user prompt to be placed anywhere on the screen and
different fonts, colours etc. to be used.

E.g. The following instruction will prompt the user with the question 'Should I go on ?”
in large 40-pt text in a pop-up box in the centre of the screen.

Bugs

Index

It has been said that all programs contain bugs. Bugs are errors in the program. They can be described as either errors in specification ('logical' errors), or errors in implementation (the program does not behave as it is supposed to).

In BUBBL bugs can usually be thought of as errors in specification. A BUBBL diagram is both specification and implementation.

These are some useful strategies for fixing bugs, they can be easily used individually or in combination to 'home-in' on a problem

Stepping through the program one instruction at a time, checking that it does what is expected
Using Formula, Table and Variable blocks to 'watch' the value of variables and expressions as the program is stepped through or run.
Stepping backwards through a program until the error 'disappears'
Disconnecting one or more links to 'trap' unexpected program behaviour and then stepping backwards to find the problem.

Call instruction

Index

This is a way of referring to a set of instructions as one thing.

It can make programs readable by simplifying the visual image of the program in meaninful ways. For example, the built-in instructions 'Alert','Edit','Present',and 'File' are each BUBBL programs in their own right (of wideley varying complexity)! These 'programs' are referred to as 'instruction-blocks' or just 'blocks', and are the main way of building BUBBL programs that are easy for humans to read.

User-defined blocks appear in the instruction factory and can be dragged and dropped into a BUBBL diagram like any of the built-in instructions.

Running an instruction-block as a single instruction is known as 'calling' the block.

When a block is 'called' (from another block ) the 'caller' can give it information at the time of calling. This information is organised into named 'parameters'. As the instruction block is entered, the value of a parameter is put into a new variable with the parameter's name, so that it is available within the instruction block.

Parameters may be marked as 'output', so that if a variable is 'passed' as the parameter it's value is updated to whatever the new variable's value is when the block exits (or 'returns control') to the caller.
See also:

Start and End instructions

Choice instruction

Index

This instruction allows the user to be presented with a set of choices from a table column (one field of all records). The instruction operates in one of two modes, the default allows only one item to be selected and assigns the variable with a value equal to the choice's index.. If the user does not make a selection, the 'Esc' link is followed. If the mark-up parameter 'm' is included, multiple selections are allowed, and a set containing the indices of the selected is returned.

The text presented for the user to choose from defaults to values from the first column of the table. Another column may be chosen simply with the '.<column>' table column operator.

Other marks-ups specific to Choice instructions (in addition to the font, colours, positioning etc. mark-ups) are:

fil={set of records to include in the menu presented}

r=<No. of rows to display in menu>

d=<default choice(s)>

E.g. given the table: person(forename,surname), a menu of surnames all the entries with forename 'John' could be presented with the following instructions (note the 'm' mark-up allows zero or more selections to be made).

Note: The index number assigned to the variable ('ch' in the above example) indexes the original table, not the (possibly reduced) menu presented.
See also:
Sort instruction
Delete instruction
Insert instruction
Update instruction
Destroy instruction
Create instruction

Create instruction

Index

This instruction is used to create one or more new tables, replacing any existing tables with the same name(s). The instruction works in one of three ways:-

1. A single empty table, with specified fields is created

2. A single table with the contents of a text file is created

3. One or more tables are imported from a '.ken' (BUBBL database) file. The name(s) of the created (imported) table(s) do not have to be the same as the source table(s), but the field names will be the same.

If any create operation fails, any existing table of the same name will be unchanged.

Note:

Tables may be manually created by dragging a 'new table' Table instruction from the instruction factory into a program and right clicking on it.
To search tables use the `Select` instruction, and to update records use the `Let` instruction to assign directly to indexed records and fields thereof.

Data Types

Index

Data can be one of :

Numeric: E.g. 1, 47, -23.54

Boolean: E.g. 1 or 0 (for TRUE or FALSE)

Set: E.g. {4..16}, {1,3,5,8,9}, {-1..3,6..7} (only integers allowed)

String: E.g. “Hello”, “3 and a half”

Tuple: E.g. “one,two,3,the end” - Not really a data type, but comma separated values of other types

Table: E.g. name[row].column or name[record].field

Additionally the following file-based data types are implicitly supported, but the BUBBL programmer only has to deal with the filenames, directories etc.:

Image files: .PNG, .JPEG, and .GIF

Sound files: .WAV, .MID, .OGG

All expressions are represented as strings. The type of a string expression is determined according to its content, and, in the case of expressions, the context: whether from the result of an operation, or from the write destination.

Variables are named pieces of data. They can hold a value of any data type for later use.

Any syntax errors in expressions result in the expression being interpreted as a literal string. This 'feature' allows the programmer to omit the double quotes around some strings!

Tuple Not really a type, but a way of storing multiple types in the same value. It is comma- separated values of any other type(s) such as in a whole table row. Eg. person[1] might be "John,Smith,27" Individual fields are referenced using '.<field number>' Eg. "one,two,four".3 gives "four" or person[1].2 (see above) would be "Smith"

See also:

Operators
Expressions

Delete instruction

Index

This instruction allows a program to delete one or more records from a table. The records are specified by a set of the indices (record or 'row' numbers) of the record(s).
See also:
Insert instruction
Update instruction
Data types
Choice instruction
Sort instruction
Select instruction
Create instruction
Destroy instruction

Destroy instruction

Index

This instruction allows tables to be completely deleted.
See also:

Select instruction
Sort instruction
Choice instruction
Delete instruction
Insert instruction
Update instruction
Create instruction

DISPLAY table

Index

DISPLAY(thing,x,y,width,height,colour,fill,border,data1,data2,tag)

This table variable gives access to each item being shown in the current page. The table index represents the painting order, with the topmost items having the highest indices.
Deleting records from the table removes them from the display, and some fields are similarly mapped through to the displayed objects so that, for example, changing the 'x' field in a DISPLAY record changes the x-position of the corresponding object (displayed item). However, the only way to create new items for display is to use the 'Output' instruction. The fields are interpreted as follows:-

thing	x	y	width	height	colour	fill	border	data1	data2
LINE	x	y	width	height	r,g,b	-	-	-	matrix:m00,m10,m01,m11,m02,m12
EXPR	x	y	width	height	r,g,b	r,g,b	border	expression	font parameters
RECT	x	y	width	height	r,g,b	r,g,b	border	corner-radius	matrix:m00,m10,m01,m11,m02,m12
CIRC	x	y	width	height	r,g,b	r,g,b	border	-	matrix:m00,m10,m01,m11,m02,m12
POLY	x	y	width	height	r,g,b	r,g,b	border	x1,y1,x2,y2...etc	matrix:m00,m10,m01,m11,m02,m12
SECT	x	y	width	height	r,g,b	r,g,b	border	start-angle,turn-angle	matrix:m00,m10,m01,m11,m02,m12
PICT	x	y	width	height	-	-	border	filename	matrix:m00,m10,m01,m11,m02,m12
SCB	x	y	width	height	r,g,b	r,g,b	ver/hor	value	min,max,step
BUT	x	y	width	height	r,g,b	r,g,b	border	text	font parameters
TRANS	x	y	0	0	0,0,0	-	-	params	matrix:m00,m10,m01,m11,m02,m12

Most of the fields beyond 'thing' may be assigned to, however the fields 'width' and 'height' are not writeable for POLY or PIC items. Changing the value of an item field causes a corresponding change in the display when it is next updated. Note that a 'refresh page' or other instruction needs to be executed to cause the display to update. This allows several sequential updates made to the table to change the displayed output simultaneously,

The field 'border' is set to one of 'raise','lower', 'frame' or 'none', determining the style of the graphic. This field is maintained automatically for BUT items. For polygon items it can also be set to 'clip' or 'blank' which have an effect on the following image to be displayed.

Records may only inserted by `Output` instructions

Deletes may be performed as in normal tables (i.e. any except for record 0, the field names)

Edit instruction

Index

This instruction allows a user to edit a table in one of four modes:
   Graphical Image, where the table fields match those of DISPLAY
   Text file, where rows represent free-form simple text
   Grid, where rows and columns are laid out like a spreadsheet, or a database in 'list' view
   Database, where individual rows (records) are presented with field names (column names)
The mode is inferred from the table field-names, but can be overridden with a 'v=<mode>' mark-up where <mode> is one of:

gr	Graphical
tx	Text
db	Database
dbr	Database records

The editor always uses a page (window) called 'editor', which may be pre-initialised with fonts, colours etc. and/or 'frozen' graphics.
In the graphical mode, text and graphics can be edited by direct manipulation of items on the screen. (e.g. font, size, colours etc). If your program needs to change these during editing, you can put your own formatting instructions on the 'Esc' or 'Event' links. The 'Event' link is used for extending the instruction. Any events (such as 'OFF_PAGE' which you want to use for special actions should be included in the 'Exit events' set. When the specified event occurs, the 'Event' link will be followed. Any items already on the page (including buttons and scrollbars) are ignored by the editor. Buttons and scrollbars will generate USER events which can cause the 'Event' link to be followed. The contents of the table (page) can be displayed as graphics/text, but without editing facilities, with the 'Present' instruction.

See also:

Present instruction
Output mark-ups

Events

Index

Events are the bread and butter of real time programming. They are how the computer tells a program that something happened in the physical world, for example that a key has been pressed by the user.

In BUBBL each possible event has a unique number. Events are processed using a 'wait' instruction. Any irrelevant events are ignored by the 'wait' instruction. But when an event in one of its 'action sets' happens, event processing is suspended (events will be queued until the next 'wait' instruction), and the appropriate link is followed.

The 'wait' instruction allows the programmer to use one or more events to trigger one or more actions. Events are coded as follows:

If the the `zero` key is pressed, event number 0 is sent to the program. The `one` key sends event number 1 and so on.

The `a` key sends event number 10, `b` sends number 11 etc.

Mouse events have their own numbers, as do timer `ticks` (every 1/10th second).

For key events the character corresponding to the key pressed can be accessed by using the variable `CASED_KEY` whose value is the character, taking account of whether the `shift` key was held down at the time the key was pressed.

Key and mouse button 'releases' and an 'un-tick' give -1 minus the event numbers of the corresponding 'press' or 'tick' event (for computer science buffs this is a bitwise complement or 'not' operation). These event numbers can be specified in sets for the `Wait` instruction by preceding the event name with a backslash.
e.g.: {\TICK,TICK} or {\a..\z,a..z}
The Keyboard and Mouse
To specify key events in 'wait' instructions, either the event number is used, or a symbolic representation of the event (e.g. MOUSE_LEFT). Key events may be referred to either by their numbers (starting from 10 for 'a') or by simply quoting the character associated with the key in lower case. Keys with no printable character associated with them are referred to either by the appropriate event number or one of the symbols in the following table:

Keyboard: F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12,

UP, DOWN, LEFT, RIGHT, PGUP, PGDN, HOME, END,

INS, DEL, BACKSPACE, ENTER, TAB, ESC, SPACE,

Mouse: MOUSE_LEFT, MOUSE_MOVE, MOUSE_RIGHT,MOUSE_WHEEL,DRAG,DROP

These events are generated to give the program more information:

FRAME -Generated when the user changes the frame size or position

OFF_PAGE -Generated when the user clicks on a page other than the current output page (CP). This event is always generated before the MOUSE_LEFT or MOUSE_RIGHT event that triggered it.

USER - Generated when the user presses a button or moves a scroll-bar

CLOSE -The user has clicked the 'Close' button on the current page.
Note: convention dictates that the program should close the window when it receives this event. Windows which are not the current window will be closed by the system, but the program is given the responsibility for doing this if it is the currently selected output window. (CP)

TICK and \TICK Timing events, TICK occurs every 100ms, with each \TICK event following 50ms second later

Code/Event	Source	CHR EVENT(=KEY)	Shifted(CASED_KEY)	Un-event
0..9	0-key to 9 key	0..9	Us: )!@#$%^&( Uk: )!”£$%^&(	Y
10..36	A-key to Z-key	a to z	A to Z	Y
37	- key	-	_ (underscore)	Y
38	=key	=	+	Y
39	[ -key	[	}	Y
40	] -key	[	{	Y
41	; -key	;	:	Y
42	' -key	'	Us: “ Uk:@	Y
43	\ -key	\	\|	Y
44	, -key	,	<	Y
45	. -key	.	>	Y
46	/ -key	/	?	Y
47	#	#	#
48	*	*	*	Y
49	SPACE	SPACE		Y
50	Unrecognised key			Y
51..62	Function keys F1..F12	F1 to F12	F1 to F12	Y
63	Enter-key	ENTER	ENTER	N
64	Esc-key	ESC	ESC	Y
65	Tab-key	TAB	TAB	Y
66	Backspace-key	BACKSPACE	BACKSPACE	Y
67	up-arrow	UP	UP	Y
68	down-arrow	DOWN	DOWN	Y
69	left-arrow	LEFT	LEFT	Y
70	right-arrow	RIGHT	RIGHT	Y
71	Home-key	HOME	HOME	Y
72	End-key	END	END	Y
73	PgUp-key	PGUP	PGUP	Y
74	PgDn-key	PGDN	PGDN	Y
75	Ins-key	INS	INS	Y
76	Del-key	DEL	DEL	Y
77	Left mouse button	MOUSE_LEFT	MOUSE_LEFT	Y
78	Right mouse button	MOUSE_RIGHT	MOUSE_RIGHT	Y
79	Mouse moved	MOUSE_MOVE	MOUSE_MOVE	N
80	1/10th second tick	TICK	TICK	Y
81	User resized window	FRAME	FRAME	N
82	Mouse pressed off-page	OFF_PAGE	OFF_PAGE	N
83	User closed window	CLOSE	CLOSE	N
84	User operated UI item	USER	USER	N
85	Program has started running	START	START	N
86	External D/B changed	DB_WRITE	DB_WRITE	N
87	Program Ended	PROG_END	PROG_END	N
88	Top-line menu	MENU	MENU	N
89	Sound clip ended	CLIP_END	CLIP_END	N
90	Key typed	KEY_TYPED	KEY_TYPED	N
91	Drag started/continuing	DRAG	DRAG	N
92	Dragged data dropped	DROP	DROP	N
93	Mouse wheel moved	MOUSE_WHEEL	MOUSE_WHEEL	N
98	unrecognised event	UNKNOWN	UNKNOWN	N
87..96 and 99	Reserved for future use

Expressions

Index

Whenever a variable `assignment` is made (e.g. with a `Let` instruction), the variable is given a `value`. In BUBBL the value is always a 'string' (a sequence of characters), and it is usually the 'result' (or 'evaluation') of an `expression`. An expression is also a string, but it usually contains special characters or sequences of characters called 'operators' (Eg '+' or '>='). Although the computed value of an expression is a string, it may also be interpreted as either a number, a boolean value (1/0 for true/false), a set of integers (e.g. {1..27}) or a variable name, according to its value.

Expressions can be as simple as a single value, with no operators, or complex, with many operators, values and variables. Its evaluation involves applying a corresponding transformation for each operator present in the expression, in order of priority,

The operators transform the expression into the result. Eg.

The expression `4+5` evaluates to `9`

The expression `"This"+"that"` evaluates to "Thisthat.

The expression `"This"+5' evaluates to "This5"

To avoid confusing parts of strings which are intended to be quoted (or used literally) with operators or variable names, strings may be surrounded with double quotes. Any operators or variable names within the quotes will not be interpreted as operators or variables. They remain part of the string. ALL operators in BUBBL are either a) `prefix` operators with one `argument` Eg. `NOT x` - where NOT is the operator and x is the argument) or b) `infix` operators with two arguments Eg `a>b` - where > is the operator and a and b are the arguments. Each operator produces a single result which may be of one or more different 'types' . All operators fall into a single `precedence hierarchy`. This means that in an expression, some will be evaluated before others -much as in formal algebra. Eg `1+3/4` evaluates to `1.75` because the / operator is evaluated before the + operator (it has a higher precedence).

Filename instruction

Index

This instruction pops up a file dialogue for the user to select a file, enter a filename or select a directory, and navigate the directory tree. Multiple selections can be enabled by including 'm' in the mark-ups*. The result for multiple selections is a set of indices into the FILE table.
Other mark-ups allow font, colours etc. to be overridden. After successful file selection, in all cases, the path to the directory selected by the user is in the variable "FILE_PATH".
In addition to normal font, colour etc mark-ups, the following may be used:

Mark-ups	Description
d=	Set default file-name
fil=x	Set filter expression to x
m	Allow multiple selection*
path=x	Set initial file path to x
a=x	Set 'action' text to x (e.g. "Save", default="Open")
cw=x	Set column width to x
ch=x	Set column height to x
*	Note multiple selection still under development:For now use fil="dir" to navigate to directory, then follow with Choice from FILE

File format

Index

A program, along with its data is stored in a simple text file. Each line of the file is formatted as a named relation. The first tuple (relation) for any named relation is interpreted as the field names. Although usually desirable, tuples do not need to have the same arity (number of fields) as the field- names, allowing for variable length records.

Eg. A data-table: MyData(FieldName1,FieldName2)

MyData(Value1,value2)

MyData(34,goose)

Each file has a table: `program(name)`. Entries in this table are interpreted as instruction-block names which are the names of tables which contain instruction-blocks. These tables may not be accessed by the program as normal data tables, and must be in the appropriate form.

Note that, in general, programs may not be self modifying.

Instruction-block tables have the following form:

<program-name>(No,Type,x,y)

where: No = Instruction number -an integer greater than or equal to zero used to reference the instruction by others.

Type = Instruction type (see below)

x = X co-ordinate for drawing instruction in the editor

y = Y co-ordinate for drawing instruction in the editor

Any additional fields are interpreted according to the instruction type (see below). Some instructions are extended with additional 'data' lines which have the same instruction number and the value 'DATA' in the `Type` field.

Summary of BUBBL instruction record formats

<prog>(No,START,x,y,Next instr)

<prog>(No,DATA,I/O/L,input-parameter/output-parameter/Link name)

<prog>(No,LINK,x,y,next instr)

<prog>(No,EXIT,x,y,exit code)

<prog>(No,FOR,x,y,Done instr,Do instr,variable,in-set)

<prog>(No,NEXT,x,y,For instruction)

<prog>(No,IF,x,y,If instr,Else instr,boolean expression)

<prog>(No,WAIT,x,y,name)

<prog>(No,DATA,Event-set,Instr)

<prog>(No,MENU,x,y,Esc instr,params)

<prog>(No,DATA,text,Instr);

<prog>(No,INPUT,x,y,Next instr,Esc instr,variable(s),parameters)

<prog>(No,CHOICE,x,y,Next instr,Esc instr,result variable,table name,params)

<prog>(No,ASKUSER,x,y,No instr,Yes instr,Question,params,Esc instr)

<prog>(No,ASSIGN,x,y,Next instr)

<prog>(No,DATA,variable,expression)

<prog>(No,SWITCH,x,y,Default instr,expression)

<prog>(No,DATA,case set/comma-separated string-list,instr)

<prog>(No,MESSAGE,x,y,message text)

<prog>(No,CALL,x,y,Next instr )

<prog>(No,DATA,P/L,param/Link instr)

<prog>(No,WRITE,x,y,Next instr,<display-item>,parameters...) Note: see below for display items

<prog>(No,PAGE,x,y,Next instr,<page-command>[,parameters]) Note: see below for page commands

<prog>(No,SELECT,x,y,Next instr,result var,table name,selection filter=true/false expression)

<prog>(No,CREATE,x,y,Next instr,table name,field names)

<prog>(No,DELETE,x,y,Next instr,delete set,table name)

<prog>(No,DESTROY,x,y,Next instr,table/variable name)

<prog>(No,INSERT,x,y,Next instr,table name)

<prog>(No,DATA,field,expression)

<prog>(No,FILESYS,x,y,Success instr,Fail inst,<command>,[param 1],[param 2]))

Note:<command> is one of "SAVE","MAKE","DELETE","RENAME","COPY","EXEC","DUMP","APPEND","IMAGE"

<prog>(No,FORMULA,x,y,ID)

<prog>(No,DATA,expression)

<prog>(No,VIEW,x,y,Table,<mark-ups>,<column offsets>,<No. of rows>,Index offset)

<prog>(No,VARS,x,y,<mark-ups>,<column offsets>,<No. of rows>,Index offset)

<prog>(No,EDIT,x,y,<table-name>,Close instr,Esc instr,Event instr)

<prog>(No,PAGE,x,y,Next instr, SELECT,<page>,<params>) Set current page to <page>, <params> specify colours, font etc.

<prog>(No,PAGE,x,y,Next instr,DESTROY) Removes current page, restoring most recent, existing current page (does not remove 'Output').

<prog>(No,PAGE,x,y,Next instr,CLS) Clears the screen. Items written before a FREEZE<true> instruction are not removed.

<prog>(No,PAGE,x,y,Next instr,FREEZE,<true/false>) Switches 'freeze' mode on/off (1=on). When activated, freezes current display items,

preventing their removal or scrolling until de-activated.

<prog>(No,PAGE,x,y,Next instr,DIR,<true/false>) Switches 'direct-write' mode on/off (1=on). When on, nothing is added to display list, instead it is just written to the display.

<prog>(No,PAGE,x,y,Next instr,UPDATE) Causes the page to be refreshed (re-drawn)

<prog>(No,PAGE,x,y,Next instr, FORMAT,<params>) Used to specify size and position and colour of page, and default values for ink, font etc.

Mark-ups are separated by spaces in <params> and are executed in sequence when the instruction is executed. Mark-ups are as follows:

Mark-up Description

x=<int> set x co-ordinate, use x=max for rhs anchor

y=<int> set y co-ordinate, use y=max for bottom screen anchor

c=r,g,b set default drawing colour (INK).

f=<font name> set the default font. Font is one of (at least) Serif, SansSerif, Dialog or MonoSpaced and is plain in style.

s=<Point size> set the default font point size (1 point is 1/72 of an inch)

b make the default font bold

i make the default font font italic

b=r,g,b set the background colour (PAPER).

st=min/norm/max set the 'window' state as minimised/normal/maximised'

fr=scr/fix/res set the 'window' frame as scrollable/fixed-size/resizable

w=width set the 'window' width in points (pixels)

h=height set the 'window' height in points (pixels)

<prog>(No,WRITE,x,y,Next instr,@,cx,cy) Initialise CX and CY

<prog>(No,WRITE,x,y,Next instr,EXPR,<expr>,<params>) Outputs the value of <expr>, updating CX (and CY if new line output).

<prog>(No,WRITE,x,y,Next instr, LINE,dx,dy,<params>) Draws a line from (CX,CY) to (CX+dx,CY+dy). CX and CY are offset by dx and dy.

<prog>(No,WRITE,x,y,Next instr,RECT,w,h,<params>) Draws a rectangle w pixels by h pixels

<prog>(No,WRITE,x,y,Next instr,CIRC,w,h,<params>) Draws an ellipse in a w by h rectangle

<prog>(No,WRITE,x,y,Next instr,POLY,xOffs,yOffs,<params>) Draws a polygon starting at (CX,CY), using vectors (xOffs1,yOffs1), (xOffs2,yOffs2) etc. vector components are separated with vertical bar characters.

<prog>(No,WRITE,x,y,Next instr,SECTOR,w,h,st,an,<params>) Fills the sector of ellipse in rectangle w by h from st deg. anticlockwise to st+an deg. (0 = East)

<prog>(No,WRITE,x,y,Next instr,PIC,<filename>,<params>) Displays the (jpeg or png or GIF) image file

<prog>(No,WRITE,x,y,Next instr,SCB,<horiz>,len,init-val,upp,lwr,step,<params>) Displays a scroll-bar which sources USER events

<prog>(No,WRITE,x,y,Next instr,BUT,<expr>,<params>) Displays a button which sources USER events

<prog>(No,WRITE,x,y,Next instr,CLIP,<audio-file name>) Plays an audio clip

Note: Where <params> contain commas (e.g. 'c=255,200,100') the commas are stored as vertical bar characters to distinguish them from field separators.

For/Next instructions

Index

Sometimes a program needs to repeat the same operation or calculation over and over, either on a number of objects (data records), or on the same object(s). This is variously known as iterating or looping, and BUBBL provides the `For/Next` pair of instructions for this purpose. The `For` instruction takes a set of ordered integers, and assigns the value of each member to the same variable sequentially. For each assigned value the `Do` link of the `For` instruction is followed once -as long as the loop is `closed` by linking to the `Next` instruction. When all values have been used, the `Done` link of the `For instruction is followed. Each `Next` instruction is permanently linked to a `For` instruction, and cannot be changed. For the looping to work properly, the `Do` link must be linked (via one or more useful instructions) to the `Next` instruction. The set of integers might be from a user `Choice` or from a table search (`Select` instruction), or from a set calculation. The set is `frozen` when the `For` instruction is first executed so that changes to the value of the set do not affect the instruction`s iterations. Only the `For` instruction`s `Next` instruction causes iteration. All other links to the `For` instruction cause the iteration to be re-started from the beginning. Some structured programming purists may feel uncomfortable about this, but it is safe for the program to `break out` of the loop by simply not following a link to the `Next` instruction. To allow for one level of nesting, the 'frozen' set is stored locally when the iteration begins, and restored when it is completed.

Formulas

Index

A formula block is a stand-alone entity which allows the programmer or user to see what the value of various variables, expressions or calculations are. It is not intended to be a program instruction, but a tool for use in program development. Each formula block can be thought of as a single-column spreadsheet. Multiple formula blocks can be used in combination for more complex computations. Although formula values may be used in other formula blocks, they may not be used in expressions within ordinary program instructions. To use in expressions the formula block must be given a name. Its formulas can then be referred to using table record notation: <formula-name>[<row>] Rows are numbered from 1. If you do not want the formula itself to show, only its value, the formula should start with an equals sign. Eg. "This"+"that" displays as '"This"+"that" = ThisThat whereas ="This"+"that" displays as ThisThat

How to ...

Index

How to contact the author

How to display data

How to deploy a program

How to edit a program

How to play sound

How to search tables

How to store data

How to write a program

How to add 'help' info to programs

Index

Each user interface instruction has an optional 'Info' button that can be enabled by including the string 'info' in the mark-ups (see UI mark-ups ). When the button is pressed, a URI (Usually an HTML anchor inside an HTML file) is made up from the system variables INFO_KEY and INFO_FILE and passed to the browser (the system variable BROWSER should have the command line invocation for the browser). Help file(s) are then produced using any appropriate HTML editing tools

How to deploy a programs

Index

A program which has been finished and debugged may be made available to others without the 'development' environment (i.e. the 'RUN', "STEP' etc buttons and the desktop). This can be done by assigning a variable on the desktop called 'AUTO_RUN' with the value 1. This value is only picked up from the program file, so changing it while running the program is not straightforward. Also, when this option is active, a program which ends causes the user to be prompted on whether to 'run the program again' or 'exit the system', rather than be presented with the usual desktop.

How to contact the author

Index

You can contact the author at [email protected] This version of BUBBL is released under the terms of the GPL.

Please play with it!

The author is grateful for any suggestions or bug-reports. BUBBL is the result of over 10 years of thinking and 6 years of coding. It is still a bit `rough around the edges` although the documentation is pretty much accurate. Please do not supply it to a third party without the author`s consent.

Happy BUBBLing !

Barney McCabe 24^thSeptember 2010 (author)

Credits: Thanks to: Nesia, Mya, Tafari and Zauditu and Valerie -my long-suffering family, Kev Buckley - making me define it, Irwin Abraham, Jim & Moira Sarsfield for critical feedback ... and for teaching me useful stuff: Andrew James, Chris Scaife, Yogesh Sharma, Ayad Abdullah, Finbar Dineen, Alex Gray et al-University of Wales College Cardiff, Open University, Jan Winter & John Hayter et al-University of Bristol School of Education, Borland International, Sun Microsystems, BBC micro, Sinclair Spectrum

How to display data

Index

Output to the screen is performed via 'pages' (or 'windows'). Page instructions can be used to create, destroy and manipulate pages in a variety of ways.

Only one page at a time can be output to, and this can be selected with the Page instruction. Note that the default page (named "Desktop") cannot be destroyed, so there is always at least one page available for output. However, as the desktop is the main working area when working on a program, the program's output to the desktop is only shown while the program is running, otherwise the desktop shows what is in the currently load program's 'Desktop' instruction block. It is therefore suggested to use other named pages for output while developing programs.

The name of the current page is stored in the system variable 'CP'.

To put things on a page an 'Output' instruction is used as follows:
1. Click on the `Output` instruction in the instruction factory and choose an item from the menu presented. This creates a new instruction in the factory.
2. Drag the new instruction from the factory into your program.
3. Right-click on the new instruction and fill in any data fields necessary to make sense (Eg. if you chose 'Output rectangle', give it a width and a height). You can directly manipulate the object, colours etc. by pressing the 'Interact' button in the editor. Finish editing by clicking on Ok or pressing <Enter>.
4. Left-click on the instruction. This should cause it to be highlighted with a flashing rectangle.
5. Now click the Step or Run button at the lower right of the screen. You should see the effect of your output instruction on the 'current page' (=the last page selected with a 'Page-select' instruction).

How to edit a program

Index

To edit an individual instruction, right-click on it and fill in the form appropriately. This cannot be done in the factory, the instruction must first be dragged into an editor or onto the desktop. To edit instruction blocks, right-click on the instruction in the factory. To copy instructions, do the same `copy` action as you would to an icon, but to an instruction or `boxed group` (see below) selected with the mouse. In Windows(TM) this is holding the `Ctrl' key down whilst dragging the item(s). The copied instruction(s) can then be dragged to a new position in the editor window, or to another edtor window, and `dropped` by releasing the mouse. To move an instruction (or boxed group), left-press the mouse on the instruction and drag it to its new location.

Undoing mistakes

If you accidentally break a link or delete an instruction, you can fix the problem by selecting 'undo' from the 'Edit' menu.

Boxed group

To select a group of instructions, press the right mouse button to drag out a blue box until it surrounds the instructions (for most instructions the centre of the instruction must be inside the box for it to be selected, but non-executing instructions such as a formula tool use the top left corner) Right-clicking inside this box gives a menu of actions, and left- clicking allows the whole group to be moved as one.

Linking instructions

Links are made by left-clicking on the link and dragging the mouse over the instruction to be linked to. If the link is already connected it is automatically disconnected when clicked on. If the link is dropped over a blank area, a new `LINK' instruction is created and left where the mouse was released. This allows the path of the link to have corners. An un-connected link shows as a red circle just outside the edge of an instruction. One or more links which connect to their own instruction appear as a black circle over the centre of the bottom outline of the instruction. When an instruction has more than one link they are labelled appropriately. Although links are drawn according to a precise algorithm, it is usually possible to get pleasing visual results by varying the positions of instructions. This can improve program readability.

Cut and paste

The Edit menu and boxed-group local menu provide copy, cut, delete and paste operations. These are applied to instructions 'selected' in the box (see ' Boxed group' above).

Summary

In BUBBL you are trying to describe the behaviour of the program- this is done with a diagram, rather than carefully indented text. Eg: A program to write the times table (here in pseudo-code):

Input which table (t)
For n=1 to 10 do
  BEGIN FOR LOOP
     WriteLn n+" x "+t+" = "+ n * t
  END FOR LOOP

in BUBBL could be:

How to play sound

Index

Click on the `Output` instruction in the factory and choose `Audio-clip` from the menu given.
Drag the new instruction into your program and right-click on it to give it the filename of the `clip` (Eg '.WAV' or '.FLAC' file) you want to play.
Note: When the program is 'stopped' (i.e. 'activated', but not 'running'), all sound clips are automatically stopped. This can make it seem like there is a problem with the clip when you step through the program. To debug sound playing BUBBL programs, it can be helpful to put a 'Wait' instruction after each sound clip playing instruction, and press 'Run' instead of 'Step' to make sure the clip will play appropriately.
Each time a new clip is played, an entry is inserted in the system table 'CLIP'. Clips can be paused, resumed, stopped and restarted by updating the 'paused' and 'ended' fields with TRUE or FALSE (1 or 0). Records can also be deleted, but other than this, values in the table are read-only.
When a clip finishes playing normally a 'CLIP_END' event is generated. This allows a program (for example) to loop a clip repetitively, or play a sequence of clips in a controlled manner.

How to search tables

Index

There are three built-in ways to search tables in BUBBL:

Using the 'Select' instruction:

The 'Select' instruction returns a set of the indices of all records in a table (or subset of a table) which match its selection criteria. For each record the value of a boolean expression (true/false) is tested, and those record numbers for which the expression returns 'true' (=1) are included in the result. This allows you to find all the records which match your search criteria. A set of all the matching record indices is returned
Using the 'LOOKUP' operator:

The LOOKUP operator is used inside expressions and returns the index of the first record whose first field matches the 'key'. It should be noted that other fields can be searched with LOOKUP by using '<table>.<field>' syntax which gives a 'table view' of a single column of a table. If no match is found, a value of 0 (zero) is returned.
Indexing the table with a string

This is similar to LOOKUP (the first field of the table is searched for a match of the string), however, the subsequent fields of the matching record are returned instead of the index. This is a useful syntactic convenience over using the “LOOKUP” operator, if a little less clear. If no match is found, an empty string is returned. This method of indexing also allows new key-value pairs to be inserted in the table just by assigning to (e.g.) 'table[<key string>]'.

Tables can also, of course, be searched in many different ways by iterating through records one at a time in a program loop.

How to store data

Index

Data is stored or used in BUBBL by giving it a name. A named piece of data is called a variable. The data itself is said to be the variable`s `value`. The value of a variable can be output to the screen, for example. Variables may be separate things or they may be inside a table. A table is an organised form of data with zero or more numbered rows and 1 or more named columns. Whereas a variable is referred to by it`s name, each row of a table is referred to by the table name followed by its number in square brackets.

E.g: MyTable[1]

Individual fields are referred to by following the row name with a dot and then either the field name or field number.

E.g: MyTable[1].type or MyTable[3].6

Additionally a single column of a table can be referenced as if it was a whole table by using the syntax: <table>.<field> This can be useful when looking up values with the LOOKUP operator if the field is not the first in the table.

E.g. MyTable.surname LOOKUP "Johnson"

Rows may be added to a table using the `Insert` instruction, or by editing the table manually (while the program is not running). The following BUBBL instructions may be used to make separate variables or to change any variable`s value:

Let, Select, For, Input, File, Edit and Choice

And these instructions may be used to make and remove rows and tables respectively:

Insert, Delete, Create, Destroy

Notes:

Rows are numbered from 1 upwards, although an imaginary row 0 gives the field names.
Fields can be referred to either by their name, or by their number (numbered from left to right starting with 1)
When a new row is created with the `Insert` instruction it is added to the end of the table.
When rows are removed with the `Delete` instruction, rows with higher numbers are moved down so that there are never any `empty` rows.
When a whole row is referenced, the fields are separated in the value with commas. If the fields contain commas, these are first converted to vertical bar characters to distinguish them from the field separators.
Separate variables may also have multiple fields, by simply including commas in the values assigned to them. The fields are referred to by their number only (1=first). The fields may be assigned to individually.

Eg. The following sequence of assignments:

produces the following output:

Assignments to fields which do not exist -either in table records or separate variables- have no effect

How to write a program

Index

A BUBBL program is a diagram made up of interlinked instructions. The language itself has about 20 such instructions which cover all the things a programmer may tell the computer to do. To build on built-in instructions, a programmer may make his/her own instructions (called 'instruction-blocks') which may be used in programs in just the same way as the built-in ones. All available instructions are shown in the `factory`, and can be dragged into a program. Most instructions require `editing` to give additional information. To edit an instruction, right-click on it after dragging it into the program. The computer runs a program by `executing` (i.e. doing) an instruction, then following one of the instruction`s `links` to another instruction. It keeps doing this until either it gets to an `End`instruction, the user clicks on the STOP button, or it gets to an unconnected link. To start a program click on the instruction you want to start with, and then click the `RUN` button.

To make testing programs easy you can use these three buttons: The `STOP` button stops any running program immediately. The `STEP` button `executes' just one instruction or block and the `BACK` instruction `undoes` the previous instruction or block, running the program backwards. Instruction-blocks are usually treated as a single instruction when stepping or stepping back. However, if an editor window is open, it is 'stepped into', with its own instructions stepped (back) through individually. To further aid program development and testing, formulas, tables and variables may be used to give 'live' information, simply drag the appropriate item from the instruction factory. You can annotate your program by dragging a 'note' into it.

More Debugging tools

The system variable DEBUG when written to, causes the value written to be echoed to standard output (e.g. in the terminal window if that is where Java was run from). This may be useful for debugging real-time program segments.
Assigning a file path and name to the variable "UNDO_DUMP_FILE" will cause the 'undo script' of the last few thousand instructions executed to be output to the specified file. Interpreting this file is beyond the scope of this document, however, the reader is encouraged to discover this for his/herself by careful experimentation!

Common Programming Pitfalls

Index

Deleting rows/records from tables
A common problem arises when incrementally removing records from tables. When a record is deleted, all higher-numbered records 'move down one', so that their index numbers change. If you delete records in a 'FOR' loop this can be disasterous as the wrong records end up being deleted unless care is taken to adjust the indices as lower numbered records disappear. If a single set of records is deleted in one instruction this problem does not arise however, so if you have multiple records or sets of records to delete, first of all combine them with the 'UNION' operator. E.g.

If (then else) instruction

Index

This instruction is used to choose between two paths of execution based on some condition or test. An expression is evaluated (calculated) and the result is interpreted as a 'boolean' (true/false) value. If it is 1 (true) the link labelled with the expression is followed. If it is 0 or anything else (false), The unlabelled link is followed. Note: the words 'if, then and else' do not appear in the instruction, as the question mark is used to suggest a 'decision'.

Input instruction

Index

This instruction allows the program to get typed information directly from the user. The user may also press `Esc`, but his function may be disabled. The program may also provide `info` (like this page) when the user presses the added `info` button. This is done by setting the `mark-up` `info'. The `mark-ups` also allow the user prompt to be placed anywhere on the screen and different fonts, colours etc. to be used.

Update instruction

Index

This instruction is used to modify one or more fields of a set of records (rows) of a table in one go. The records to be updated are selected with a set of their index numbers. Fields to be modified are each assigned an expression. When evaluating the expressions for each record, field names are interpreted as referring to the field values of the current record, as in the 'Select' instruction. Fields not explicitly initialised with the `Update` instruction are left unchanged. For very large sets of records this instruction may be noticeably slow in execution!

Insert instruction

Index

This instruction is used to add a new record (row) to a table. The record is added to the end of the table, i.e. Its index after `Inserting` into <table> will be `COUNT <table>`. Each field of the new record may be assigned to in the instruction. Fields not explicitly initialised with the `Insert` instruction are set to a blank (zero length string).

Introduction

Index

Do it yourself knowledge engineering.

Build your own Artificial Brain!

Behavioural / Beginners'

Universal / User-oriented

Building-

Block

Language

Knowledge ENactment Files

What is it?
1. A simple programming package for Windows/Linux etc..
2. A definition of a literacy for human/computer interaction using relations and 2-dimensional behaviour specification diagrams.
3. A tool for learning the core concepts of computer programming
4. A knowledge engineering tool

What isn't it ?
1.Visual Basic
2.A cross-compiler
3.A distributed business-wide application generator
4.Unnecessarily complicated

What could it be?
A 'toy' for anyone to 'free-play' with images/control/ behaviour etc
A tool for teachers to build interactive knowledge environments
A universal operating system (just fix an interpreter to any database)
A cookie-using web-resident knowledge-base automaton network.
BUBBL embodies the following ideas:
database: named relations, queries, sorting, insert/delete/update
mathematics: formulas and expressions
graphics: pictures geometrical shapes fonts cartesian co-ordinates in 2 dimensions
variables(types): numeric, string, set, tuple, array, table

Philosophy

The cornerstone of the BUBBL philosophy is that all data (including 'source code') can be represented with named relations.
This philosophy is applied to programs and program components ('instruction blocks') which are stored as relations representing a network of instructions. Each instruction or part of instruction is identified with a numeric field. The value of this field is used by(in) other instructions to link to it.

The BUBBL diagram works at the level of behaviour description as well as process definition.
How the program should respond to events, what transformations it should perform on its data are all made explicit in a 'self-documenting' diagram.

From an object-oriented perspective, classes and objects are database entities - simple named relations and tuples respectively.
Methods are operations deriving from and/or on tuples and sets of tuples (relations).
In the case of (e.g) the DISPLAY table, the database entities are mapped onto the 'objects' displayed through reading and writing table values.

Let instruction

Index

This instruction is used to give a value to one or more variables. A variable may be one of the following:

a simple named variable
a field of a multi-field (comma-separated) named variable
an indexed row of a table
a single field of an indexed row of a table
Values are similar to mathematical expressions, but with more non-mathematical operators available. Some operators, notably the plus (+) operator, have different interpretations depending on their arguments. Invalid expressions are interpreted simply as strings, allowing for easy debugging.

Examples of valid variable assignments:

Looping and iteration

Index

For iterating through a predetermined set of objects the 'For/Next' instructions may be used. The For instruction takes a set of integers and assigns them sequentially to a variable. The set would typically be the result of a database 'Select' instruction, or a user interface 'Selection' instruction or other set value (e.g. ALL <table> for all the indices of <table> records).

Where the iteration depends on intermediate calculations or external events, a loop can be realised as a physically looped group of instructions. Normally such a loop would have a 'test' in it - typically an 'If' instruction, which is used to determine when to 'exit' the loop (i.e. when the iteration should end). Such a loop in BUBBL has the advantage over so-called 'structured programming constructs' that more than one exit is possible, allowing the programmer to construct the program in the most appropriate, or elegant way.

Menu instruction

Index

This instruction allows program flow to be chosen by the user. Each menu item is associated with a different link which is followed it the item is selected. The link labelled `Esc` is followed if the `Esc` key is pressed, or nothing is selected. The `mark-ups` may be used to position the menu anywhere on the user`s screen and to specify colours and font, size and style. Also the menu may include icons if the markups contain the string 'icons', in which case the first comma-separated substring of each menu line's text should be the icon's filename.

Notes and comments

A well written program will include some `comments` to guide the reader. The `Note' instruction is not `executed` in the normal way, but allows comments or notes to be included with the `code` -allowing the programmer to annotate the program.

The text can be any colour, size or font and should be used to help increase the readability of the program. To change the style (font, size etc), right click on the text and edit `mark-ups` in the same way as for Output Expression instructions. The 'Interact button' allows direct manipulation of the font and colour.

Operators

Index

Note: Operators are listed in descending order of precedence

Operator

Description

x.y

If x is a table, gives a 1-column table 'view' of column y of x.
If x is a table-row or tuple, gives field y of x (or empty string if y is invalid. It may be an integer or field-name).
If x is a set, gives the y'th ordinal element of the set x (or empty string if y is invalid).
Otherwise, if y is a valid integer, gives the y'th comma-separated sub-string of x.

ENV x

Gives the value of the envrionment variable x, or empty string if x doesn't exist
The following evironment variables are always present, allowing the programmer to query the platform on which BUBBL is running:

Item	Description
"os.name"	Operating system name
"os.arch"	Operating system architecture (e.g. i386)
"os.version"	Operating system version
"user.name"	User's account name
"user.home"	User's home directory
"user.dir"	User's current working directory

ALL x

Set of table x indices, equivalent to 1 TO (CARD x)

NFIELDS x

Gives the number of named fields of the table or tuple x. If x is neither of these it is interpreted as comma-separated values, and the number of commas+1 is returned.

NRECS x

Gives the same as 'CARD x' if x is a table

x LOOKUP y

< P>If x is a table, gives the record number of the first record in x whose first field equals y.
If x is a string, gives the index of the first comma-separated sub-string of x that equals y.
If x is a set containing y (an integer), gives the ordinal number of y in x.
Otherwise gives 0

x TRANSPOSE y

x should be a table column.
If y is a set, gives the rows of x indexed by elements of y as a comma-separated string.
otherwise gives the set of indices of comma separated elements of y in x.

EXISTS x

Gives 1(true) if x is a table, 0 otherwise

CARD x

Gives the cardinality of x:
if x is a set, gives the number of elements of x
if x is a table, gives the number of records in x
if x is a tuple, gives the number of fields in x
if x is an integer, gives 1
otherwise gives the number of comma separated substrings in x

COUNT x

Identical to CARD x -gives the cardinality of x:
if x is a set, gives the number of elements of x
if x is a table, gives the number of records in x
if x is a tuple, gives the number of fields in x
if x is an integer, gives 1
otherwise gives the number of comma separated substrings in x

NSUBSTR x

Gives the number of space-separated sub-strings of x

SGN x

Gives the signum of x (-1 if x is negative, 1 if x is positive,0 if x is 0).

ABS x

Gives the absolute value of x

LOG x

Base 10 logarithm of x if x is a number >0

SQRT x

Floating point or integer square-root

RAD x

Degrees to radians: equivalant to pi/180*x

SIN x

Trigonometric sine of x (x in radians).

COS x

Trigonometric cosine of x (x in radians).

TAN x

Trigonometric tangent of x (x in radians)

ASIN x

Trigonometric arcsine of x (in radians).

ACOS x

Trigonometric arccosine of x (in radians).

ATAN x

Trigonometric arctangent of x (in radians).

ATAN y,x

Trigonometric arctangent of the position vector specified by x and y

DEG x

Radians to degrees: equivalant to 180/pi*x

RANDOM x

Random integer in the range 0 to x-1

Unary plus, gives x

-x

Unary minus, gives 0-x

Binary not. Gives -1-x if x is a number.

x^y

x raised to the power y

x/y

Division, gives x/y.

x DIV y

Integer division

x MOD y

x Modulo y (remainder of x divided by y)

x*y

Multiplication (type depends on the operands-and result !-)

x-y

Floating point or integer subtraction

x+y

Numeric addition or string concatenation

x SUM y

Sums the values of table column x whose record numbers are elements of the set y

x MEAN y

Computes the average of the values of table column x, with indicies in the set y

x MODE y

Computes the mode of the values of table column x, with indicies in the set y

x MEDIAN y

Computes the median of the values of table column x, with indicies in the set y

x MAX y

Gives the highest of the values of table column x, with indices in the set y

x MIN y

Gives the lowest of the values of table column x, with indices in the set y

x VARIANCE y

Computes the variance of table column x of records whose indices are elements of y

x STDEV y

Computes the standard deviation of table column x of records whose indices are elements of y

x SF y

Gives y correct to x significant figures

x DP y

Gives y correct to x decimal places

SCI y

Gives y in scientific notation (e.g. 'SCI 1000' gives '1.0e3'

ROUND x

Gives x rounded to the nearest whole number

MONEY x

Gives the decimal x as a quantity of dollars (including cents)

DOW x

Gives the day of week, x is seconds since 00:00hrs, 1st January 2000 ignoring leap seconds.

DOM x

Gives the day of month, x is sec. since 00:00hrs, 1st Jan 2000

DATE x

Gives the date (day month year) x is seconds since 00:00 1-1-2000

MONTH x

Gives the month, x is seconds since 00:00 1-1-2000

YEAR x

Gives the year, x is sec. since 00:00 1-1-2000

TOD x

Gives the time of day, x is sec. since 1-1-2000

PERCENT x

Gives the decimal x as a percentage

UPPER x

Gives x in upper-case characters

LOWER x

Gives x in lower-case characters

x FROM y

The string x starting from the y'th character

x CHOP y

The string x minus the rightmost y characters

x LEFTMOST y

The y leftmost characters of the string x

x RIGHTMOST y

The y rightmost characters of the string x

LEN x

Identical to LENGTH x, the number of characters in the string x

LENGTH x

The number of characters in the string x

WIDTH x

The width of the string x in graphics units (points or pixels), using current font dimensions

x SUBSTR y

Gives the y'th space separated substring of x

HASHED x

Gives x with spaces replaced with # character

CHR x

Gives character encoded with the number x

UNICHAR x

Gives UNICODE character encoded with the UNICODE x

x ASSOC y

Text following occurrence of y in x up to first space or end. E.g. "x=4" ASSOC "x=" gives "4"'#` characters are transmuted into spaces. Eg. "t=My#Title"ASSOC "t=" gives "My Title"

x HAS y

Gives 1 if x contains y delimited by spaces or end of line, 0 otherwise

x POS y

Gives the index of y in x (1 for 1st, 0 for no match)

x LASTPOS y

Gives the last position of y in x

UNICODE x

The integer UNICODE encoding of the first character of the string x

CODE x

The integer code of the first character of the string x

FILE_EXISTS x

Gives 1 if x is an existing file, 0 otherwise

NOT x

Gives 0 if x=1, 1 otherwise

x TO y

Gives the set {x..y}, gives {} if y<x

x CRC y

Gives a 32-bit CRC calculated from the UNICODE encoding of the charaters of x, and seeded with the value y.

x INTERSECT y

Gives the intersection of the sets x and y

x UNION y

Gives the union of the sets x and y (integers are interpreted as single-element sets).

x EXCLUDE y

Gives the set x intersected with y's complement

x DISTINCT y

Gives the set of row indices of table x which are also in the set y, and whose first field is not duplicated by rows with a lower index. Eg. myTab.fld DISTINCT ALL myTab. It is intended for use in combination with Select instructionin table searches.

x IN y

Gives 1 if the set y contains the integer or set x.
Gives 1 if x is a comma-separated sub-string of y.
Gives 0 otherwise

x ORD y

Gives the ordinal number of y in the set x (1=first, 0 if y not an element of x).

REST x

Identical to TAIL x
If x is a set gives x with first element of x removed
If x is a tuple, gives x with the first field of x removed
Otherwise gives x with the first comma-separated element of x removed

TAIL x

If x is a set gives x with first element of x removed
If x is a tuple, gives x with the first field of x removed
Otherwise gives x with the first comma-separated element of x removed

FIRST x

If x is a set gives the first element of x (or empty string if x is empty)
If x is a tuple, gives the first field of x
If x is a table gives x[1] as a tuple
Otherwise gives the first comma-separated element of x

HEAD x

Identical to FIRST x:
If x is a set gives the first element of x (or empty string if x is empty)
If x is a tuple, gives the first field of x
If x is a table gives x[1] as a tuple
Otherwise gives the first comma-separated element of x

LAST x

If x is a set, gives the highest valued element of the set (or empty string if set is empty).
If x is a table gives the last record of x = x[COUNT x] as a tuple, (or empty string if table is empty)
Otherwise give the last comma-separated sub-string of x

y NEXT x

Gives the lowest valued element of the set x greater than y or, if y is a set, the lowest valued element of the set y greater than x

y PREV x

Gives the highest valued element of the set x less than y or, if y is a set, the highest valued element of the set y less than x

x=y

Gives 1 if true, 0 otherwise

x>y

Gives 1 if true, 0 otherwise

x>=y

Gives 1 if true, 0 otherwise

x<y

Gives 1 if true, 0 otherwise

x<=y

Gives 1 if true, 0 otherwise

x<>y

Gives 1 if true, 0 otherwise

x AND y

Gives 1 if x is 1 (true) and y is also 1 (true), 0 otherwise

x OR y

Gives 1 if x is 1 (true) or y is 1 or both are.

x?y:z

Gives y if x is true, z otherwise.

x >? y

Gives x if x>y, y otherwise

x <? y

Gives x if x<y, y otherwise

EVAL x

Interprets the string x as an expression and returns its evaluation. This operator is not recursive beyond a depth of 2

x CHILD_EVAL y

Uses the program-block x from the child program indexed by CHILD_NO to evaluate y as a local expression in that block. It allows (e.g.) child variables to be evaluated.
This operator is not recursive beyond a depth of 2

STACK_EVAL x

Uses the 'calling' program-block to interpret x as a local expression. It is used by system programs to allow variables from a calling program block to be evaluated.
This operator is not recursive beyond a depth of 2

ENCRYPTED x

Gives an encrypted/decrypted copy of x, depending on the initial value of the system variable SEED, and what has been encrypted since SEED was initialised. SEED is initialised to a 'random' number by assigning a 'password' string to it. The encryption algorithm is symmetrical so that encrypting and decrypting use this same operator, as long as SEED is initialised to the same value in each case.

x REENCRYPTED y

Gives an encrypted/decrypted copy of y, initialising "SEED" to x dircetly. This allows repositioning encryption/decryption within an encryption stream, but cannot replace the initialisation of SEED with the password, as this initialises other 'invisible' variables at the same time.

URL_ENCODE&npsp;x

Gives x encoded for the MIME format: "application/x-www-form-urlencoded"

URL_DECODE&npsp;x

Gives x decoded from the MIME format: "application/x-www-form-urlencoded"

HTML_ENCODE&npsp;x

Gives x encoded as legal HTML, with character entities etc."

HTML_DECODE&npsp;x

Gives the HTML string x decoded to plain text."

Output mark-ups

Index

Most output instructions allow their output to be modified as it is put on the screen. For example the position on the screen, or font size can be changed from the default values. These changes are made through parameters which are part of the instruction. They consist of zero or more space-separated parameters as described below. Spaces may be included in parameter values by using a hash character where a space is required. It is often desirable to store parameters in a string variable. The contents of one or more such variables can be invoked by simply embedding '@<variable-name>' within the parameter string (or using the same as the parameter string).

Positioning control
In general items which use 'windows' (or 'frames') will be positioned relative to the desktop, whereas simple graphical or textual items will be positioned relative to the current page (CP) (ie within a window). The following are available

Set the item's x or y co-ordinate directly: x=<int> y=<int>
Align item with right-hand side of page/desktop: x=max
Align item with bottom edge of page/desktop: y=max
Place item in centre horizontally: cx
Place item in centre vertically: cy
Offset item from 'position so far': dx=<int> dy=<int>
Right-align text (relative to bounding rectangle): rr
Change width of window or graphical item: w=<int>
Change height of window or graphical item: h=<int>

Output mark-ups for Framed (UI) items: (Input, Page, Choice, Menu, Selection, Alert, Ask)
Give frame a title: t=<title>
Make frame closable: cl=1
Make frame not closable: cl=0 (default)
Make frame scrollable: fr=scr
Make frame fixed (not resizable): fr=fix
Make frame resizable: fr=res (default)
Grab keyboard focus for page: foc=1
Don't bother to grab keyboard focus for page: foc=0 (default)
Minimise frame: st=min
Maximise frame: st=max
Make frame normal size: st=norm
Set input prompt text: p=<Prompt(s)>
Set history 'context key' for input instruction: hk=<context>
Show 'Info' button: info
Add 'file' button for Input (e.g. fm="*.WAV"): fm=<mask>
Allow icons in menu instruction: icons
Set initial selection query (e.g. q=RECORD#IN#set) for Choice instruction: q=<query>
Specify field name for choice menu text: tf=<name;>
Specify field name for choice text-colours: cf=<name;>
Specify field name for choice continuation menus: mf=<name;>
Specify number of characters in the input field of input instruction: l=<int>
Number of rows to show: r=<rows>
Allow multiple selection in Choice instruction: m
Specify editing mode for Edit instruction: v=<mode>
   where: <mode>=gr,tx,db or dbr for graphical,text,database or database record.
Specify editing parameters for Edit instruction:
  row=<row>
  col=<column>
  po=<page-offset>
  cxs=<x-coordinates of columns>
  nr=<number of rows>
  h=<height of window>
  ex=<set of event numbers for 'Event' link>
  =<>
  =<>
Specify additional lines of text for 'Alert' and 'Ask user' instructions: aux=<table>
  where <table> is a table with a row for each line of additional text.

Colours mark-ups
Foreground,'INK',text or outline colour: c=<r,g,b>
Background,'PAPER' or fill colour: b=<r,g,b> (Note: values for r,g and b should be in the range 0 to 255)

Text (expressions and buttons)
Specify font name: f=<font name>, font is one of (at least) Serif,SansSerif, Dialog or MonoSpaced
Set font point size (1 point=1/72inch): s=<point size>
Make font italic: i
Make font bold: b
Output a new-line (scrolling the page if necessary): n
Tabbed output of tuples: tabs={tab-stops} (Note tab-stops in points = 1/72inch)
Right justify (e.g. for numeric output): rr (Note: Justifies to box defined by w= parameter)

Text and Graphical items Border styles
raised: bd=raise
lowered: bd=lower
frame: bd=frame
clip region around polygon to transparency: bd=clip
blank region inside polygon to transparency: bd=blank
none: bd=none

Miscellaneous
Append to display without deleting items overwritten or covered from DISPLAY table: a
Add an arrow to a line: ar
Set rounded corner radius for rectangles: cr=<radius>
See also:
Output instruction
Expressions

Output instruction

Index

BUBBL allows simple geometric shapes, text and images to be displayed on a page. It also allows sound-clips to be played. There are 14 sub-functions of the output intstruction:

Sub-function	Description
Output @	Sets CX and CY for the next output.
Write expression	Displays text and/or numbers.
Line	Draws a line
Polygon	Draws a polygon
Rectangle	Draws a rectangle
Circle	Draws a circle or ellipse
Sector	Draws a sector of a circle or ellipse
Button	Creates and draws an event-generating button
Scroll-bar	Creates and draws an event-generating scroll-bar
Picture	Displays an image file
Dump	Dumps a table's contents to a file. No field structure is preserved, each row is simply output as text, with commas within fields appearing as '\|' characters. If the table was created from a 'text' file, this would reproduce the content of that file.
Append	Appends a table's contents to a file as in 'Dump' above.
Audio-clip	Plays a sound file.
Transform	Introduces an affine transform into the display list. All items following it are accordingly transformed until the next 'Transform' item. Transforms can be specified by one or more things such as: ro=<angle (in degrees)> m=<magnification factor> mx or my=<horizontal or vertical magnification factor> x or y=<rotation/magnification centre> tx=m00,m10,m01,m11,m02,m12

Those sub-functions which draw things on the screen can be thought of as `image constructors`. The `objects` they make are available to the program via the `DISPLAY` table system variable, and can be modified by assigning to fields of `DISPLAY` records or, when the program is stopped, by selecting 'Interact' in the instruction editor. The results of such direct manipulations are used to alter the `constructing` instruction`s mark-ups.

Page instruction

Index

This instruction does a single sub-function chosen from a menu when first created. The sub-functions are as follows:-

Sub-function	Description
Select	This selects the 'current' page for output. The variable 'CP' is set to the name of the page. If the page does not exist a new one is created. The page is moved to the front. Output mark-ups are also interpreted to change size etc.
Destroy	This completely removes the current page. The previous current page is made current, or if it does not exist, the front-most page is made current.
Clear	This removes the contents of the current page, subject to whether parts of it were `frozen` (see `Freeze` below)
Freeze	This causes the current contents of the page to be kept intact despite `Clear` instructions or scrolling. It can be used to create a fixed background for other graphical output.
Direct	Switches `direct-mode` on or off. In direct mode outputs to the page are written directly to the screen, so they will not be refreshed by the operating system in the normal way. It can be useful in animation.
Format	This allows the page width, height, position, default font,style and size and `PAPER` and `INK` colours to be set.
Refresh	Normally (when not in direct-mode, see above) the page will be redrawn on the screen when a `Wait` instruction is executed, only if a previous `Output` instruction was executed. This immediately updates the display, and is useful if the page contents was altered via `DISPLAY` table.
Print(,tables)	Prints the current page, or list of tables containing data in the same format as 'DISPLAY'. All currently existing pages are contained in the table 'PAGE', with record 1 being the current page.
Dump	Outputs the contents of the current page as an image file, either '.jpg/jpeg' or '.png', depending on file extention -default is 'jpeg'.

File system instruction

Index

There are 9 types (sub-functions) of file system instruction. Each sub-function may succeed or fail, and the corresponding link is followed. If it fails, the system variable 'FILE_MESSAGE' is set to a message describing the reason for the failure, other wise it is set to "OK". The sub-functions are as follows:-

Sub-function	Description
Save	Saves the current program. If no filename is given it is saved under its current name.
MakeDir	Creates a directory
Delete	Deletes a file or directory. Directories must be empty before being deleted.
Rename	Renames a file or directory
Copy	Copies a file of up to 200MB in length to a given destination
Execute	Passes a command to the underlying operating system.
Dump	Creates or overwrites a file with the contents of a table. The table rows are treated as text strings and are output in the default platform encoding (e.g. Unicode UTF-8).
Append	As 'Dump' above, but any existing file is appended to rather than overwritten
Dump_Image	Creates or overwrites a file with a compressed image file representation of the current output page. The encoding is determined by the given file extension as follows: filenames ending in '.jpg' or '.JPG' will have the image saved in 'JPEG' format, otherwise the image will be in 'PNG' format)

PAGE table

Index

This table contains information about all the currently existing pages. It has the following fields:
name: name of page (used in 'Select' instruction)
x: x-coordinate of top left corner within desktop
y: y-coordinate of top left corner within desktop
width: width of paintable area
height: height of paintable area
state: one of 'showing' or 'icon'
fmt: Mark-ups as included in 'Select Page' instruction, (e.g. f=Font etc.)

Note:

When a page is selected for output (i.e. CP=page name), it is moved to record 1 in PAGE.
See also:
DISPLAY table
Output mark-ups

Present instruction

Index

This instruction displays a table in one of 3 ways, depending on the field names and contents: If the field names match the DISPLAY table, the table is assumed to be 'graphics' from the graphical editor, and is displayed as such. Otherwise it is displayed as a grid of rows(records) and columns(fields), unless there is a single columns with the name 'text' in which case the table rows are displayed a rows of text. When displaying 'graphics', any buttons or scrollbars contained will be activated by this instruction (as long as the program is designed to use them!).
See also:
Edit instruction

Select instruction

Index

Any table may be searched with this instruction. The search comprises a 'selection expression` against which all (or a sub-set of) records in the table are tested for a `match`. The variable is assigned the value of the set of the indices of all matching records. The `filter` (or `where` part) may be any expression which gives a `boolean` (=true or false) result. Eg.
[where] age IN {21..50} AND smoker="No"
[where] MX IN x TO x+width
Any ordinary variable sharing the same name as a field is ignored in evaluating the expression, and instead the value of that field for the record being tested is used. Additionally the system variable RECORD gives the number of the record being tested, and can be used to make relative references to other (e.g. adjacent) records.
Another feature is the 'filter' parameter which may be used to limit the number of records tested to improve efficiency. The filter parameter consists of a set of record numbers to be tested (instead of the default of all records), thereby speeding up the instruction. It can be used to 'narrow down' a selection. See also:
Expressions
Sort instruction
Choice instruction
Delete instruction
Insert instruction
Update instruction
Destroy instruction
Create instruction

Sort instruction

Index

This instructions allow tables to be sorted based on the contents of their data fields. Rows (records) of a table may be sorted on one or more fields (columns). Whether letters are upper or lower case is ignored when sorting, and fields of wholly numeric values are sorted numerically rather than alphabetically. The order and direction in which fields are used for sorting is specified by a comma-separated list of field names, starting with the highest priority field. By default, records are sorted in ascending order, but any field may be used to sort in descending order by prefixing it with a minus sign.
  E.g. "title,-page" would cause sorting on the field 'title', in ascending order. Records with the same value of 'title' would be further sorted in descending order on the field 'page'
It is also possible to specify arbitrary sort orders by following the relevant field name with a colon and then a series of colon-separated values which, when matched by a data item, would cause that item to be ordered accordingly. Each pre-defined value may be ended with ".." in which case, instead of an exact match being required, data items starting with the characters preceding the ".." would be matched.
  E.g. day:Mo..:Tu..:We..:Th..:Fr..:Sa..:Su.. would sort on the field 'day' into day-of-week order for most variants of spelling in English (however capitalised),
  whereas day:Mon:Tue:Wed:Thu:Fri:Sat:Sun would put 'Tue' before "Monday"
See also:

Select instruction
Choice instruction
Delete instruction
Insert instruction
Update instruction
Destroy instruction
Create instruction

Start and End instructions

Index

Each instruction-block has a single `Start` instruction which is the first instruction executed when it is called by another instruction-block. The `Start` instruction is also used to hold information on any `parameters` passed to the instruction-block by the calling instruction-block, and any named links that it has. The instruction-block may have a single unnamed link or as many named links as desired. The `End` instruction is used to choose which link should be followed when the instruction-block finishes (`returns`). The links may be added removed and named by editing the 'Start` instruction and, when more than one link is available, the `End` instructions may be programmed to follow a particular link by right-clicking on the instruction and choosing from the menu.

Wait instruction

Index

A BUBBL program executes a `Wait` instruction when it has nothing to do for a while. The instruction tells the computer to do nothing until something happens to trigger it into action. Such a trigger is known as an `event`, and is caused by one of the following: A key on the keyboard is pressed or released A mouse button is pressed or released The mouse is moved A `tick` or `un-tick` happens (alternate 1/5ths of a second) A display page is resized or closed by the user A button is pressed by the user A scroll-bar is moved by the user The wait instruction allows `set`s of numbered events to trigger particular actions (=follow links). Each type of event has a unique number. When an event occurs the first link whose set contains the number of the event is followed. If no link is tied to the event it is ignored.
Note: To create a new link, click `Add new line` in the editor.
The set of events for each link must be expressed as a set value, not an expression giving a set: Eg. 0..z,SPACE is ok, but 2 TO 32 will not work Surrounding {} are optional.
See also:
Events

Switch instruction

Index

This instruction allows the program to choose one of several links depending on the value of an expression. When the instruction is entered, the expression is evaluated and should give either a number or a string. For a number each link is associated with a set of integers against which the number is compared. The first link whose set contains the number is followed. For a string, each link is associated with a comma-separated set of strings. The first link whose string-set has the string is followed. In either case if there is no such match the link labelled `Default` is followed. To add new links to a switch instruction click the `Add new line` button in the instruction editor.
See also:
Expressions

System variables

Index

The following symbols have the described interpretation (i.e. as `variables`) when used in expressions.

Event information/Miscellaneous

Variable	Access	Description
EVENT	r	This is the event number of the last responded to event
EVENTS	r	This is a comma-separated list of the pending events (the 'queue'). The first number in the list is the next event
UI	r	When a button or scroll-bar is activated by the user, a 'USER' event is raised, and this variable is set to the index in DISPLAY of the button or scroll-bar causing it.
TICKS	r	This gives the count of tick events since one was last acted on
EXTRN_DB	r/w	This may be set to the path of a read-only 'external' database
FREE_MEM	r	Gives the available free memory in bytes
USED_MEM	r	Gives the used memory in bytes
RECORD	r	This variable is only of use within 'Select' instructions where it gives the index of record being tested against the query
SYSTEM	r	Gives 1 (true) if the current instruction block is a system program
TIME	r	Local time in seconds since 00:00 1/1/2000
ENCODING	r/w	Text file encoding to use for Create instruction when reading text file. Default value is taken from the platform. Possible values include (e.g.)'ISO-8859-1', 'UTF-8', 'US-ASCII'.
UTC	r	UTC (or 'GMT') in seconds since 00:00 1/1/2000
USER_NAME	r	Gives the log-in name of the current user
DEBUG	w	Values written to this are echoed to standard output. Useful for real-time debugging.
DUMP	w	Writing a table name to this causes standard output to be buffered in the table. Useful for real-time debugging.
CLIPBOARD(text)	r	Table containing contents of system clipboard if it has a MIME text type available
PAGE(name,x,y...)	r	Table of all the currently active display 'page's ('windows' or 'frames') and various bits of state information
TABLE(name,fields,system,size)	r/w	A table of all the tables in the system. Inserting a record creates a table with the specified number of blank records and fields. Deleting a record will delete the corresponding table if it is not a built-in system table. It does (of course) contain itself
INET	r/w	Converts URL to IP address
HOST	r	Gives the I/D of the network local host
SEED	r/w	Writing with 'password' string initialises ENCRYPTED operator. Reading gives 31 bit encryption seed value which can be used to authenticate 'passwords'
SYS_TABLE	r/w	This variable maps onto a table from the system programs (loaded from 'SYS.ken'). Writing to it selects the table, and accessing it as a table (i.e. using [] operators) accesses the selected table.
USR_TABLE	r/w	This variable maps onto a table from the user programs (loaded from '.ken'). It is generally only used by system programs. Writing to it selects the table, and accessing it as a table (i.e. using [] operators) accesses the selected table.
UNDO_DUMP_FILE	r/w	Writing with file name causes 'undo script' for last few thousand instructions to be written to the file

'Drag and Drop' system

TR>

Variable	Access	Description
DRAGGED(text)	r/w	Table containing data from dragged text MIME type
DSP	r	Gives the page on which a drag operation started. Gives blank if drag originated outside the program.
DRP	r	Gives the page being dragged over. Gives blank if dragged outside the program.
DROP_OK	r/w	May be set to true (1) to allow dragged data to be dropped on the most recent page dragged over. It is cleared automatically when the drag operation leaves the page, so must be set to true again (if desired) on the next 'DRAG' event.
MIME	r/w	Gives the MIME type of current or most recently dragged data. A 'MOUSE_LEFT' event resets the drag and drop system, and may be followed by setting this variable to a valid mime type (e.g. "text/uri-list") or empty string to enable a drag from the BUBBL program. The table 'DRAGGED' should contain the data to be dragged prior to enabling the drag operation (usually in response to a MOUSE_LEFT event).

Key event processing

Variable	Access	Description
ALT	r	Gives 1 (true) if the 'Alt' key was pressed for the current event
CTRL	r	Gives 1 (true) if the 'Ctrl' key was pressed for the current event
CASED_KEY	r	Gives code of the character typed taking account of 'shift' keys etc according to UK Keyboard layout
TYPED	r	Gives the character typed as a character
KEY	r	Gives the event number of the last key pressed
SHIFT	r	Gives 1 (true) if a 'Shift' key was pressed for the current event

Mouse event handling

Variable	Access	Description
MP	r	Gives the name of the page on which the last mouse event occurred
MX	r	Gives the x co-ordinate of the mouse pointer at the last mouse event
MY	r	Gives the y co-ordinate of the mouse pointer at the last mouse event
MW	r	Gives the number of forward or backward(-ve) mouse wheel clicks from the last 'MOUSE_WHEEL' event
MOUSE_OVER	r	Gives a set of the indicies in DISPLAY of the items over which the mouse pointer is
MOUSE_RADIUS	r/w	The distance in pixels used by MOUSE_OVER when testing items
MOUSE_OVERLAY	r	Gives a set of the indicies in OVERLAY of the items over which the mouse pointer is

Display-system state

Variable	Access	Description
CP	r	Gives the name of the page currently selected for output
CX	r	Default X-co-ordinate of next screen output (within page)
CY	r	Default Y-co-ordinate of next screen output (within page)
CURSOR	r/w	Gives the current mouse cursor type, one of N,S,E,W,NE,SE,SW,NW for respective 'outline-dragging' cursors, or one of the following: DEFAULT - system default CROSS - Cross-hairs HAND - Hand MOVE - Dragging WAIT - Waiting TEXT - Text
CURSORS	r	Comma-separated possible values for CURSOR
DISPLAY(thing,x,y...)	r/w	Table of contents of current page (CP)
FOCUS	r	Gives the name of the page with keyboard focus.
PH	r	Height of current page (CP) in pixels
PT	r	Title of current page
PV	r	Gives 1 (true) if the current page is not minimised
PW	r	Width of current page (CP) in pixels
PX	r	Gives the screen x-co-ordinate of the current output page, relative to the BUBBL 'desktop'
PY	r	Gives the screen y-co-ordinate of the current output page, relative to the BUBBL 'desktop'
DH	r	Height of the desktop window in pixels
DW	r	Width of the desktop window in pixels
SH	r	Height of the screen in pixels
SW	r	Width of the screen in pixels
WINDOW	r	Gives the type of of current output page window. Its value is one of res,scr,fix for resizable, scrollable, fixed-sized

Text formatting

Variable	Access	Description
FONT	r	Default font for text output
BOLD	r	Gives 1 if default font is bold, 0 otherwise
ITALIC	r	Gives 1 if default font is italic, 0 otherwise
SIZE	r	Point-size of default font (FONT)
PAPER	r	Background r,g,b colour of current page
INK	r	Default drawing r,g,b colour of CP
FONTNAME(name)	r	Table of available fonts

Printer control

Variable	Access	Description
DIALOGUE	r/w	Set to 1 (true) to pop-up user printer-dialogue before printing
LANDSCAPE	r/w	Set to 1 (true) to force landscape orientation printing
LEFT_MARGIN	r/w	Specify the left margin (non-printing area) in 'points' (=1/72 inch)
RIGHT_MARGIN	r/w	Specify the right margin (non-printing area) in 'points' (=1/72 inch)
TOP_MARGIN	r/w	Specify the top margin (non-printing area) in 'points' (=1/72 inch)
BOTTOM_MARGIN	r/w	Specify the bottom margin (non-printing area) in 'points' (=1/72 inch)
PAPER_WIDTH	r/w	Specify the width of pages for printing (including margins) in 'points' (=1/72 inch)
PAPER_HEIGHT	r/w	Specify the height of pages for printing (inlcuding margins) in 'points' (=1/72 inch)

Environment globals

Variable	Access	Description
PROG_FILE	r	Filename of program currently being run
BROWSER	r/w	Command line for HTML browser for help file viewing
INFO_FILE	r/w	File path of user program info (help) file. Defaults to <working directory>+"BUBBLSys.htm"
INFO_KEY	r/w	Reference id for next user info button press

File-system

Variable	Access	Description
SEPARATOR	r	Gives '/' for Linux operating system, '\' for others
ROOT(name,ext,dir)	r	Table of all the available file system roots. Note: There will only be one record for '/' using operating systems, whereas there will be one for each physical drive for '\' using systems.
FILE_PATH	r/w	File 'path' used to fill FILE table, set initially to user's working directory. When his variable is assigned to, the table 'FILE' is updated to reflect the current contents of the directory indicated by the value assigned.
FILE(name,ext,dir,size,time,hidden,read,write)	r	Table of files in FILE_PATH ext is file-spec from last dot dir is 1 if the file is a directory, 0 otherwise. size is file size in bytes time is time file last updated in seconds since 1st Jan 2000 read is 1 if file is readable, 0 otherwise write is 1 if file is writable, 0 otherwise
USER_HOME	r	User's home directory
WORKING	r	User's working directory
FILE_MESSAGE	r	Gives 'Ok' if last 'FileSys' instruction was successful. If it failed, gives an explanatory message.

Child Program

Variable	Access	Description
CHILD(File,Libs,Progs,Nodes,Steps,Params,State)	r/w	Each row gives the current state of a child program. Inserting a new row creates a new child program if the 'File' field refers to a valid program file.
CHILD_CTL	w	Assiging to this variable controls a child program. The following commands are valid: GOTO,<child>,<lib>,<prog>,<node> RUN,<child> RUN_TO,<child>,<lib>,<prog>,<node> STEP,<child> BACK,<child> BACK_TO,<child>,<lib>,<prog>,<node> STOP,<child> RENEW,<child>,<table>,<prog>(Note: no table indicates program should be deleted)
CHILD_TABLE	r/w	This variable maps onto a table of the child program indexed by 'CHILD_NO'. Writing to it selects the table from the child program. After writing to it, the selected table can be accessed by referring to this variable as a table (e.g. CHILD_TABLE[0]).
CHILD_NO	r/w	Identifies the particular child program with a table mapped to 'CHILD_TABLE'
CHILD_MESSAGE	r	Message from child program corresponding to last 'PROG_END' event

Non-event constants

Variable	Access	Description
DAY	r	Number of seconds in a day=86 400
FALSE	r	=0
TRUE	r	=1
PI	r	=3.14159265358979323846

The Display

Index

The idea of a 'page' is used to organise visual output. Pages can be created and destroyed using `Page-Select` and `Page- Destroy` instructions, and can be printed and dumped to image files.

Some output is subject to 'mark-ups' which can be used to control things like fonts and colours (see Output mark-ups ).

The display management system maintains some variables: CP, CX, CY, INK, PAPER, FONT, ITALIC, BOLD, PX, PY, PW, PH, DW DH, SW, SH. Most of these variables apply to the current page (CP) only. In general they cannot be directly assigned to, but may change as a side effect of some other action such as use of the 'Page-Format' instruction. For example, `CX` and `CY` are modified by the 'Ouput-Expression' and 'Output @' instructions.

Normally the display is maintained using the 'Output' and 'Page` instructions. The standard unit of size is the 'Point' (1/72 of an inch for printing). All screen dimensions and coordinates etc. follow this convention. Additionally everything in the contents of the current page is availble to the program through the table variable `DISPLAY`.

Outputing to pages is affected by the current `mode`: If in `direct-write` mode any program output is displayed immediatley on the page, and anything written in this mode is subject to on-screen corruption by other screen objects (for example other software running on the computer).

Normally however,a list of display items is maintained automatically, and the items persist until expressly overwritten, scrolled or cleared off the screen. A page can also be 'frozen' so that items written to it before the 'Page-Freeze' instruction are not removed or scrolled, creating a static 'background'.

Items added to the display list after any `Page-Freeze on` instruction, or all display items, are subject to the following rules for removal from the display list.

New items are appended to the end of the table (as in table insert instruction).
'Text' items, 'line' items (lines, rectangle, circle and polygon outlines and sectors) and 'area' items (solid rectangles, pictures etc.) are treated differently.
Subject to the behaviour described above, an item will be removed if:
1. A 'clear screen' instruction is executed
2. The list has>2000 items, and the item is number 1
3. It's y-coordinate is -Ve after scrolling
4. It is completely overlapped by a new 'area' object
5. It is a text item and a new text item has the same co-ords

However, an item may be displayed (appended to the table) without affecting others at all if the 'a' (for append) mark-up is used.
See also:
DISPLAY table
Output instruction
Page instruction
System variables
Output mark-ups