COPYIGHT

  ©1999 Dietmar Eilert. All Rights Reserved.

  Dietmar Eilert
  Mies-v-d-Rohe-Str.31, 52074 Aachen, Germany
  Phone: +49-(0)179-5987061 German/English
  E-Mail: Dietmar.Eilert@post.rwth-aachen.de
  E-Mail: dietmar_eilert@yahoo.de (alternative address)
  WWW:    http://members.tripod.com/golded
  Mirror: http://members.xoom.com/golded

CONTENTS

  This is a description of the physical data format used  for  the  registry,
  preset  files,  sequences,  etc. A description of the logical format can be
  found in the "registry.h" file. Please  note  that  the  information  given
  there describes the current state only; future versions may use a different
  logical format.  The  physical  file  format  described  in  this  text  is
  guaranteed to stay the same.

REGISTRY

  The global  configuration  of  GoldED  Studio  5  (including  the  list  of
  filetypes)  is  saved  to the registry file "golded:etc/registry/registry".
  The registry is loaded during startup. Presets referenced by  the  registry
  are  stored in the directory "golded:etc/registry/presets". These files use
  the same file format.

CONFIGURATION FORMAT

  An object-oriented tree-style format is used for configuration data.  Every
  configurable  option  in  the editor is described by an "object" structure.
  This is how GoldED internally represents objects when loaded into RAM:

  struct Object {

      struct Node Node;

      UWORD                 ID;
      UWORD                 Type;
      struct Class         *Class;

      union {

          ULONG             Number;
          UBYTE            *String;
          struct List      *List;
          APTR              Data;

      } Value;
  };

  /* object types (bit 0-2) */

  #define OBJECT_TYPE_NUMBER     1
  #define OBJECT_TYPE_STRING     2
  #define OBJECT_TYPE_LIST       3
  #define OBJECT_TYPE_DATA       4
  #define OBJECT_TYPE_NAMED      8

  /* special object ID

  #define OBJECT_LOCKED ((UWORD)~0)

  NODE:

  Objects are linked together  via  the  Node  field  and  form  large  trees
  (objects  of  the  type  OBJECT_TYPE_LIST  are  the root of branches). Some
  objects are named (see below): a pointer to the object's name is stored  in
  object->Node.ln_Name. The node's ln_Pri field is used to coordinate access:
  it is set to OBJECT_LOCKED if an object is currently in use and may not  be
  deleted or modified (except by the owner of the object).

  ID:

  ID is  the  object  ID.  Most  objects  have  a  unique  ID.  For  example,
  OBJECT_GLOBAL_FINDTEXT  refers to the object that is used to store the last
  find  string.  Current  ID  definitions  can   be   found   in   the   file
  "include/registry.h".

  TYPE:

  The  object  type.  Four  basic  types  are   available:   Number   objects
  (OBJECT_TYPE_NUMBER)  can  store  a  single number. The number is stored in
  <object->Value.Number>. They can be used  to  store  boolean  values,  too.
  String  objects  (OBJECT_TYPE_STRING)  can  store  strings.  A pointer to a
  0-terminated string is stored in <object->Value.String>. The string pointer
  may   be   NULL  to  indicate  that  the  string  is  empty.  Data  objects
  (OBJECT_TYPE_DATA) can store arbitrary memory  blocks.  A  pointer  to  the
  memory block is stored in <object->Value.Data>. The block size is stored in
  four bytes before the memory block similar to how  AllocVec()  stores  size
  information.  List  objects  (OBJECT_TYPE_LIST)  can  store object lists. A
  non-NULL pointer to the list structure is stored  in  <object->Value.List>.
  The  list's  lh_Head  field  points  to the first child object. The list of
  children may  contain  further  OBJECT_TYPE_LIST  objects  with  their  own
  sublists. There are no nesting limits (recursive programming required).

  Some objects are named. Named objects have the OBJECT_TYPE_NAMED bit set (a
  pointer  to the name is stored in object->Node.ln_Name as mentioned above).
  You have to mask the object type with 0x7 to filter this flag when checking
  the type:

  type = object->Type & 0x7

  CLASS:

  A pointer to the "class"  that  is  reponsible  for  object  handling,  ie.
  creation, disposal, etc.


FILE FORMAT

  The following paragraph describes how the run-time format (linked trees  of
  objects)  is saved to disk: this is a description of the format used by the
  commercial version to save the registry, configuration presets and recorded
  sequences.

  The first four bytes of every data file are  "OOP"  (0-terminated  string).
  The  data  of  a  single object, the "root object", follows: every OOP file
  consists of a single root  object  without  successor.  However,  the  root
  object usually is a OBJECT_TYPE_LIST object: It has no successor but it may
  have an unlimited number of children. The children are stored  sequentially
  directly after the root object.

  The physical format of how the object is stored in the file depends on  the
  object  type but the basic structure is independend of the object type: The
  first two bytes (UWORD) contain the object type and the  object  ID.  These
  values  are combined to a "fat ID" to save disk space. The object ID can be
  found in bit 0-10, the type can be found in bit 11-15 (ID = fatID  &  2047,
  Type = fatID / 2048). Some objects are named and have the OBJECT_TYPE_NAMED
  bit set (in <type>). The name (if the OBJECT_TYPE_NAMED bit is set) follows
  immediately  after  the  fat ID as a 0-terminated string. The object's data
  follows after the name; the format depends on the object type:

  OBJECT_TYPE_NUMBER

     The object's numerical value is stored in the next four bytes (LONG).

  OBJECT_TYPE_STRING

     A 0-terminated byte sequence

  OBJECT_TYPE_DATA

     The block size stored in the next four bytes (ULONG) followed by the
     specified number of raw bytes.

  OBJECT_TYPE_LIST

     The number of children is stored in the next four bytes (ULONG) followed
     by the specified number of child objects. Child objects are saved in the
     same format as root objects: fat ID (type/ID) followed by the  name  (if
     named) followed by the object data.