Bundle Expressions

hBasic Manual

Bundle Expressions

Introduction	What are Bundle Expressions ?
Syntax
Chained Bundles	Bundles within bundles
Auto-Create	Rules for bundles and keys
Parameter Passing	Passing expressions to functions and commands

Example	An example using Bundle Expressions and chaining
Other
Bundles

Introduction

The interpreter will now accept Bundle Expressions as an alterntative to BUNDLE.GET and BUNDLE.PUT.

e.g

bundle.create myBundle

myBundle.key1    = a    % i.e bundle.put myBundle,"key1",a
myBundle."Key 1"   = a    % i.e bundle.put myBundle,"Key 1",a

a = myBundle.key1       % i.e    bundle.get myBundle,"key1",a
a = myBundle."Key 1"    % i.e    bundle.get myBundle,"Key 1",a

What are Bundle Expressions ?

Expressions that represent a Bundle Item.
Temporary bundle 'variables' which can take the place of real variables in Basic expressions.
Only exist for the lifetime of the instruction.
Do not exist in the real variables symbol table.

Syntax

format	example	type	comment
nvar. key	myBundle.key1	simple key	key always converted to lowercase. No spaces allowed.
nvar. "key"	myBundle."Key 1"	quoted key	key can be mixed case and contain spaces.
nvar.k1{.k2..}	myBundle.k1.k2.k3 myBundle.k1."K2".k3	chained	bundles within bundles leading to final key

Nvars

Expressions must begin with a numeric variable (nvar).
This nvar must contain an existing bundle index.
The nvar must be followed by a dot "." and then the key.

Keys

e.g

mybundle.key1
mybundle."Key 1"

simple key

The first form has no quotes surrounding the key and conforms to rules simiar to variable names;

Will be converted to lowercase,
Cannot have spaces,
Must begin with a letter, but can have numbers.
The only allowable special characters are : "_" or "@" or '#"
A '$' is allowed at the end of the key if it is the only key or last key (see Chained Bundles).

quoted key
The second form has quotes and the key can have any characters, including spaces within the quotes.

Is case sensitive,
Is fully compatible with BUNDLE.PUT/GET (mixed cased keys).
Note that this second form key cannot be substituted with a string expression.
It must be a "literal quoted string constant".

Chained Bundles

e.g

myBundle.k1.k2.k3

Any bundle can contain a numeric item which is an index to another bundle.
Traditionally, this can be done manually;

bundle.put b2,"k2","Hello" % create a bundle item
bundle.put b1,"k1",b2      % put the bundle into another bundle (chain it)

bundle.get b1,"k1",b       % access b1 to get stored bundle index
bundle.get b,"k2",a$       % access final key
PRINT a$                   % "Hello"

The equivalent program using bundle expressions is;

bundle.create b1, b2       % create bundles
b2.k2 = "Hello"
b1.k1 = b2                  % chain b1 to b2

PRINT b1.k1.k2             % access final key k2 "Hello"

You can extend this key chain to any number of intermediate numeric bundle items.
The final key item can be either a number or a string.

Note that for Bundle Expressions, New Bundles are Not Auto-created.

The nvar b1 itself might be auto-created BUT the bundle index (inside b1) is NOT auto-created.

You must create new bundles with either bundle.create or bundle.put. (see Auto-create)

If you do not create these bundles yourself, you will get an error;

e.g "Invalid bundle expr: b1.k1 > b1 has bad index> 0"

For non-quoted bundle expressions, a dollar character ( $ ) is allowed only for the last key.
(this is mainly to accomodate bundle auto-mode)

e.g

% (continue program from above)

b2.k2$ = "World"
PRINT b1.k1.k2;" ";b1.k1.k2$ % Hello World

Auto-Create

Bundles

For Bundle Expressions,

Bundle indices cannot auto-create. The bundle must exist.

To create new bundles - use legacy methods;

Bundles can be created with bundle.create.
Bundles can also be auto-created with bundle.put

Keys

For Bundle Expressions,

Keys can be auto-created for an existing bundle.
Auto-creation for keys can only be done by LET or implicit-LET.

Key Types

For Bundle Expressions,

Key item Types can be changed from a number to string or vice-versa
by assignment or system commands.
eg.

bundle.create b
b.key = "Test"
b.key = 99 % changed to number
SOCKET.MYIP b.key % changed to string
PRINT b.key

Examples

bundle.create b1        % create the bundle index into b1
b1.k1 = "Hello"         % keys (k1) can auto-create by LET

Alternatively,

bundle.put b1,"k1",""   % bundle.put can auto-create both b1 and it's index, and k1
b1.k1 = "Hello"         % keys can auto-create by LET

Parameter Passing

User Defined Functions

Passing bundle expressions as arguments can only be called by value.
The bundle index and key must both exist.
The value will be passed to the local function parameter.
The key item Type must match the type of the receiving parameter.
Bundle Expressions cannot be used in FN.DEF receiving parameters.

e.g

% fn.def f(b1.k1)     % FN.DEF> Bundle expr not allowed

fn.def f(s$)
    fn.rtn len(s$)    % print length of string
fn.end

b.k1 = "Test"
b.k2 = 99
% a = f(&b.k1)        % Call by Ref &bundle_expr not allowed
% a = f(b.k2)        % Parameter Types mismatch at:

a = f(b.k1)           % call by value only
PRINT a               % 4.0

System Commands or Functions

Passing bundle expressions as arguments may be called by value or reference
depending on the command or function.

The value or reference will be passed to the command or function.
The bundle index and key must both exist.
The key item Type might be changed by the command or function.

e.g

bundle.create b
b.key = 99
SOCKET.MYIP b.key % changed to string (call by reference)
PRINT b.key % is a string

Example

bundle.create location, contact, work

location.area = "Westminster"
location.city = "London"

contact.name = "John"
contact.phone = 55556666
contact.assigned = location    % chain to location

work.dog = "humpty"
work.sales = contact           % chain to contact

? work.sales.name;
? " to cover ";
? work.sales.assigned.area     % the key chain to area

! John to cover Westminster