--- gforth/struct.fs	1997/03/21 12:21:13	1.10
+++ gforth/struct.fs	2007/12/31 18:40:24	1.25
@@ -1,12 +1,12 @@
 \ data structures (like C structs)
 
-\ Copyright (C) 1995 Free Software Foundation, Inc.
+\ Copyright (C) 1995,1997,2000,2003,2007 Free Software Foundation, Inc.
 
 \ This file is part of Gforth.
 
 \ Gforth is free software; you can redistribute it and/or
 \ modify it under the terms of the GNU General Public License
-\ as published by the Free Software Foundation; either version 2
+\ as published by the Free Software Foundation, either version 3
 \ of the License, or (at your option) any later version.
 
 \ This program is distributed in the hope that it will be useful,
@@ -15,70 +15,94 @@
 \ GNU General Public License for more details.
 
 \ You should have received a copy of the GNU General Public License
-\ along with this program; if not, write to the Free Software
-\ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+\ along with this program. If not, see http://www.gnu.org/licenses/.
 
-
-\ Usage example:
-\
-\ struct
-\     1 cells: field search-method
-\     1 cells: field reveal-method
-\ end-struct wordlist-map
-\
-\ The structure can then be extended in the following way
-\ wordlist-map
-\     1 cells: field enum-method
-\ end-struct ext-wordlist-map \ with the fields search-method,...,enum-method
-
-: nalign ( addr1 n -- addr2 )
-\ addr2 is the aligned version of addr1 wrt the alignment size n
+: naligned ( addr1 n -- addr2 ) \ gforth
+\g @var{addr2} is the aligned version of @var{addr1} with respect to the
+\g alignment @var{n}.
  1- tuck +  swap invert and ;
 
-: field ( offset1 align1 size align -- offset2 align2 )
-\ note: this version uses local variables
-    [IFDEF]  (Field) (Field)  [ELSE]  Header reveal dofield: cfa,  [THEN]
-	>r rot r@ nalign  dup ,  ( align1 size offset )
-	+ swap r> nalign ;
-
-: end-struct ( size align -- )
- 2constant ;
-
-0 1 chars end-struct struct
-
-\ : field  ( offset1 align1 size align -- offset2 align2 )
-\    create-field
-\    does> ( addr1 -- addr2 )
-\	@ + ;
-
-\ I don't really like the "type:" syntax. Any other ideas? - anton
-\ Also, this seems to be somewhat general. It probably belongs to some
-\ other place
-: cells: ( n -- size align )
-    cells cell ;
-
-: doubles: ( n -- size align )
-    2* cells cell ;
-
-: chars: ( n -- size align )
-    chars 1 chars ;
-
-: floats: ( n -- size align )
-    floats 1 floats ;
-
-: dfloats: ( n -- size align )
-    dfloats 1 dfloats ;
-
-: sfloats: ( n -- size align )
-    sfloats 1 sfloats ;
+' naligned alias nalign \ old name, obsolete
 
-: struct-align ( size align -- )
-    dp @ swap nalign dp !
+: dozerofield ( -- )
+    \ a field that makes no change
+    \ to enable accessing the offset with "['] <field> >body @" this
+    \ is not implemented with "['] noop alias"
+    latest
+    if
+	immediate
+    then
+does> ( name execution: -- )
     drop ;
 
-: struct-allot ( size align -- addr )
-    over swap struct-align
+: field, ( align1 offset1 align size --  align2 offset2 )
+    swap rot over nalign dup , ( align1 size align offset )
+    rot + >r nalign r> ;
+
+: create-field ( align1 offset1 align size --  align2 offset2 )
+    create field, ;
+
+: field ( align1 offset1 align size "name" --  align2 offset2 ) \ gforth
+    \g Create a field @var{name} with offset @var{offset1}, and the type
+    \g given by @var{align size}. @var{offset2} is the offset of the
+    \g next field, and @var{align2} is the alignment of all fields.@*
+    \g @code{name} execution: @var{addr1} -- @var{addr2}.@*
+    \g @var{addr2}=@var{addr1}+@var{offset1}
+    2 pick 
+    if \ field offset <> 0
+	[IFDEF]  (Field)
+	    (Field)
+	[ELSE]
+	    Header reveal dofield: cfa,
+	[THEN]
+    else
+	create dozerofield
+    then
+    field, ;
+
+: end-struct ( align size "name" -- ) \ gforth
+\g Define a structure/type descriptor @var{name} with alignment
+\g @var{align} and size @var{size1} (@var{size} rounded up to be a
+\g multiple of @var{align}).@*
+\g @code{name} execution: -- @var{align size1}@*
+    over nalign \ pad size to full alignment
+    2constant ;
+
+1 chars 0 end-struct struct ( -- align size ) \ gforth
+\g An empty structure, used to start a structure definition.
+
+\ type descriptors
+1 aligned   1 cells   2constant cell% ( -- align size ) \ gforth
+1 chars     1 chars   2constant char% ( -- align size ) \ gforth
+1 faligned  1 floats  2constant float% ( -- align size ) \ gforth
+1 dfaligned 1 dfloats 2constant dfloat% ( -- align size ) \ gforth
+1 sfaligned 1 sfloats 2constant sfloat% ( -- align size ) \ gforth
+cell% 2*              2constant double% ( -- align size ) \ gforth
+
+\ memory allocation words
+' drop alias %alignment ( align size -- align ) \ gforth
+\g The alignment of the structure.
+' nip alias %size ( align size -- size ) \ gforth
+\g The size of the structure.
+
+: %align ( align size -- ) \ gforth
+    \G Align the data space pointer to the alignment @var{align}. 
+    drop here swap nalign here - allot ;
+
+: %allot ( align size -- addr ) \ gforth
+    \g Allot @var{size} address units of data space with alignment
+    \g @var{align}; the resulting block of data is found at
+    \g @var{addr}.
+    tuck %align
     here swap allot ;
 
-: struct-allocate ( size align -- addr ior )
-    drop allocate ;
+: %allocate ( align size -- addr ior ) \ gforth
+    \g Allocate @var{size} address units with alignment @var{align},
+    \g similar to @code{allocate}.
+    nip allocate ;
+
+: %alloc ( align size -- addr ) \ gforth
+    \g Allocate @var{size} address units with alignment @var{align},
+    \g giving a data block at @var{addr}; @code{throw} an ior code
+    \g if not successful.
+    %allocate throw ;