(       Title:  Plain Structures
         File:  plainstruct.fs
      Version:  0.8.1
      Adaptor:  David N. Williams
      License:  Public Domain?
Last revision:  September 21, 2002

This code is based on our understanding of some common practises
for structure words.  In particular, it goes back to Mitch
Bradley's article, "Structured Data with Bitfields", undated but
with "recent" references to articles written in 1983.

ANS Forth compatible except for case sensitivity.
)

decimal


\ *** WORDS
(
  STRUCT  FIELD:  /STRUCT:

uncommentable:
  CHAR-FIELD:  CELL-FIELD:  2CELL-FIELD:
)


\ *** UNNAMED STRUCTURES
(
Structure access syntax resolves to the form:

  <address> <offset+> <fetch|store>

Structures are defined without names.  Field and structure size
names are not reusable.  Explicit sprinkling of ALIGNED may be
required.  With appropriate alignment, structures are nestable.
Structure instances may be named or not.

Note that structure definitions that do not create a structure
size word with /STRUCT: need to terminate with some other word
that removes the running offset from the stack, like DROP.

See the next section for syntax examples.
)

: struct  ( -- 0 )  0 ;

: field:  ( offset size -- offset+size )
  create over , +
DOES>  ( struc -- struc+offset )  @ + ;

: /struct:  ( "sizename" u -- )  aligned constant ;

\ Uncommentable field-defining shorthand:

0 [IF]
: char-field:  ( offset  -- offset+1char )
  create dup , char+
DOES>  ( struc -- struc+offset )  @ + ;

: cell-field:  ( offset  -- offset+1cell )
  create dup , cell+
DOES>  ( struc -- struc+offset )  @ + ;

: 2cell-field:  ( offset  -- offset+2cells )
  create dup , 2 cells +
DOES>  ( struc -- struc+offset )  @ + ;
[THEN]


\ *** EXAMPLE
(
To run this example, also uncomment the word "CELL-FIELD:".
)
0 [IF] decimal

\ structure definition:
struct ( point)
  1 cells field: >x
     cell-field: >y
  1 chars field: >plotchar
        /struct: /point

\ structure instance:
  create mypoint /point allot
    15 mypoint >x !
    22 mypoint >y !
    char o mypoint >plotchar c!

: show-mypoint  ( -- )
  mypoint cr ." mypoint structure instance:"
  cr ." x is " dup >x @ .
  cr ." y is " dup >y @ .
  cr ." the plot character is " >plotchar c@ emit  
  cr ." the structure size is " /point . ;

show-mypoint
[THEN]