PowerD.html - OBJECT definition

Description:
Object is something like field of types or typed memory.
News:
- From 0.02
  - Added unions support.
- From 0.05b
  - Added pad bytes support.
- From 0.15
  - You are allowed to use </> for shorter entry.
- From 0.16
  - You are allowed to use multiple object names.
  - Item names can start with numbers.
- From 0.17
  - Added keywords OFFSET and RELOFS for custom position of items in an object.
    - Each item can have set it's position directly.
  - Again added OOP support, which a bit changes the OBJECT structure.
  - Added C alike unions.
- From 0.19
  - OBJECTs can be now defined also inside the procedures to become local
  - added support for multi dimensional. items (upto 3d)
  - each 'PTR TO ' keyword after the ':' can be replaced by single '[]' before the ':'
Syntax:
```
  OBJECT <name> [ OF <linkname> ]
    <item> [ <[size]> ] [ <:type> ] [ ,
    <item> ]
```
Where <name> is the new OBJECT's name. <linkname> is the OBJECT whose all items will be inserted before items of this new OBJECT. <item> is the new item name. <[size]> means count of elements in the item. Pay attention, that one object's size is limited by 32 kB length. <:type> is one of types.
Item synonyms:
Each item in object can have upto 31 synonyms, all of these must be separated by '|' operator.
```
  OBJECT Point
    X|x|R|r:FLOAT,
    Y|y|G|g:FLOAT,
    Z|z|B|b:FLOAT
```
Short item list entry:
This allows You to enter items in shorter way then eg. the following:
```
  OBJECT vertex
    X|x:FLOAT,
    Y|y:FLOAT,
    Z|z:FLOAT
```
You can simply separate them with '/' operator:
```
  OBJECT vertex
    X|x/Y|y/Z|z:FLOAT
```
This generates completely the same as above, but the count of the this-way-entered-items (including synonyms!) mustn't be higher then 32 items.
Object synonyms:
Each object can have upto 7 synonyms, all of these must be separated by '|' operator.
```
  OBJECT point|vector|vertex|d3d
    x/y/z:FLOAT
```
Note: If You compile module with such object then the produced binary module will contain four objects, not one with four names!!!
Unions:
This is very useful, if you want to use one object to store different types of values in same object but different memory block.
```
  OBJECT Help
    Type:UWORD,             // help type
    NEWUNION AmigaGuide     // amigaguide help
      File:PTR TO UBYTE,    // file name
      Node:PTR TO UBYTE     // node name
    UNION LocalHelp         // inlined help
      Text:PTR TO UBYTE,    // pointer to text
      Length:UWORD          // length of the text
    ENDUNION,               // end of the union
    HelpTitle:PTR TO UBYTE  // title of the help
```
This will generate have length of 14 bytes: Type has 2 bytes, each UNION between NEWUNION and ENDUNION has the same start offset (in this case it is 2). Each UNION starts on even address, so if the address is odd, one byte is skipped. Then PowerD finds the longest UNION and adds it's length to the UNION offset (in this case has AmigaGuide 8 bytes and LocalHelp 6 bytes, 8 bytes used). Next item starts on this address.

ATTENTION: see the commas, they have to be used exactly.
C alike unions:
This feature is finaly added to simplify the C source/header translation.
```
  OBJECT xxx
    x:W,
    CUNION
      a:L,
      b:D,
      [i,j,k]:c
    ENDUNION,
    y:L
```
This setups the offset of 2 (x is 2 bytes long) to all of the CUNION items a, b and c has offset of 2. The y will have offset of 14, it takes the longest item of the union and here it is c (3xlong=12bytes).

Pad bytes:
Each non BYTE/UBYTE item must start on even address:

  OBJECT xxx               // SIZEOF_xxx = 6 bytes
    a:BYTE,                // offset=0
    b:BYTE,                // offset=1
    c:BYTE,                // offset=2
    d:WORD                 // offset=4

Linked objects:

  OBJECT PointList OF Point  // see OBJECT Point above
    Next:PTR TO Point,
    Prev:PTR TO Point

is the same as:

  OBJECT PointList
    X|x|R|r:FLOAT,
    Y|y|G|g:FLOAT,
    Z|z|B|b:FLOAT,
    Next:PTR TO Point,
    Prev:PTR TO Point

Custom item offsets:
OFFSET <x> sets the current offset value to <x>.
RELOFS <x> adds the <x> to current offset value.

It allows You to use for example negative offsets for object items and to share parts of memory.

Important note: Objects, that contains these keywords, MUSTN'T be used as a static objects ([a,b,1,2]:obj), because of different offsets, compiler wouldn't even know, how will be these item used, watch this:
```
  OBJECT test
    a:W,
    OFFSET 4,
    b:W,
    RELOFS -4,
    c:W
```
This will generate an object with items, that has offsets: a=0, b=4 and c=2. Item a is at the top of the object, so it has offset of 0, it is WORD, so we will add 2 bytes to the offset, but now comes keyword OFFSET 4, which sets the offset value to 4, then the item b will be on the address of 4. Now, b is WORD, it has two bytes, the offset raises to 6, but here follows the RELOFS -4 keyword, which adds the -4 to the offset, so it's on address of 2 (6-4).
```
  OBJECT mem
    long:L,
    OFFSET 2,
    word:W,
    OFFSET 3,
    byte:B
```
Pay attention, when You want to use these keywords with OOP!
Simple and short direct offset usage:
This feature must be used with care and is the same as the OFFSET keyword. This has the same function as that keywords, but it's shorter and simplier to use:
```
  OBJECT mem
    long:L,
    word=2:W,
    byte=3:B
```
This does the same as the above example. I hope, it's clear and don't need anything more to explain ;)
Object sizes:
With each object is generates one constant called SIZEOF_xxx, where xxx is object name, this constant contains the object length in bytes.
Number leading items:
From v0.16 You are allowed to use item names like following:
```
  OBJECT xxx
    0:WORD,
    1:LONG,
    3:DOUBLE,
    0name:PTR TO CHAR,
    1name:PTR TO CHAR
```
etc. Pay attention about usage of preprocessor feature a:=.b what is normally converted to a:=a.b this doesn't work if the item begins with number!!!
Multi dimensional items:
From 0.19 alpha 5, is possible to define and use arrays in objects with more then one dimension, You are allowed to use upto three dimensions:
```
  OBJECT test
    array[10,5,2]:UB
```
To access such items, enter:
```
  x:=test.array[5,3,1]
```
it's the same as:
```
  x:=test.array[5*10+3*5+1]
```
OOP and objects:
As You can see, the first item in each object starts at offset of 0. When You attach to this object an OOP method, the first item will start at offset of 4. That's because at the offset of 0 is in this case defined the pointer to the list of all methods attached to the object.
Take care about the OFFSET/RELOFS keyword usage, if some item will start at address, which is occupied by the method pointer list, it will probably crash Your computer. The best way to avoid such problems is to don't use these (lowlevel) keywords at all.