basis/alien/structs/structs-docs.factor

   1 IN: alien.structs
   2 USING: alien.c-types strings help.markup help.syntax
   3 alien.syntax sequences io arrays slots.deprecated
   4 kernel words slots assocs namespaces ;
   5
   6 ! Deprecated code
   7 : ($spec-reader-values) ( slot-spec class -- element )
   8     dup ?word-name swap 2array
   9     over slot-spec-name
  10     rot slot-spec-class 2array 2array
  11     [ { $instance } swap suffix ] assoc-map ;
  12
  13 : $spec-reader-values ( slot-spec class -- )
  14     ($spec-reader-values) $values ;
  15
  16 : $spec-reader-description ( slot-spec class -- )
  17     [
  18         "Outputs the value stored in the " ,
  19         { $snippet } rot slot-spec-name suffix ,
  20         " slot of " ,
  21         { $instance } swap suffix ,
  22         " instance." ,
  23     ] { } make $description ;
  24
  25 : slot-of-reader ( reader specs -- spec/f )
  26     [ slot-spec-reader eq? ] with find nip ;
  27
  28 : $spec-reader ( reader slot-specs class -- )
  29     >r slot-of-reader r>
  30     over [
  31         2dup $spec-reader-values
  32         2dup $spec-reader-description
  33     ] when 2drop ;
  34
  35 GENERIC: slot-specs ( help-type -- specs )
  36
  37 M: word slot-specs "slots" word-prop ;
  38
  39 : $slot-reader ( reader -- )
  40     first dup "reading" word-prop [ slot-specs ] keep
  41     $spec-reader ;
  42
  43 : $spec-writer-values ( slot-spec class -- )
  44     ($spec-reader-values) reverse $values ;
  45
  46 : $spec-writer-description ( slot-spec class -- )
  47     [
  48         "Stores a new value to the " ,
  49         { $snippet } rot slot-spec-name suffix ,
  50         " slot of " ,
  51         { $instance } swap suffix ,
  52         " instance." ,
  53     ] { } make $description ;
  54
  55 : slot-of-writer ( writer specs -- spec/f )
  56     [ slot-spec-writer eq? ] with find nip ;
  57
  58 : $spec-writer ( writer slot-specs class -- )
  59     >r slot-of-writer r>
  60     over [
  61         2dup $spec-writer-values
  62         2dup $spec-writer-description
  63         dup ?word-name 1array $side-effects
  64     ] when 2drop ;
  65
  66 : $slot-writer ( reader -- )
  67     first dup "writing" word-prop [ slot-specs ] keep
  68     $spec-writer ;
  69
  70 M: string slot-specs c-type struct-type-fields ;
  71
  72 M: array ($instance) first ($instance) " array" write ;
  73
  74 ARTICLE: "c-structs" "C structure types"
  75 "A " { $snippet "struct" } " in C is essentially a block of memory with the value of each structure field stored at a fixed offset from the start of the block. The C library interface provides some utilities to define words which read and write structure fields given a base address."
  76 { $subsection POSTPONE: C-STRUCT: }
  77 "Great care must be taken when working with C structures since no type or bounds checking is possible."
  78 $nl
  79 "An example:"
  80 { $code
  81     "C-STRUCT: XVisualInfo"
  82     "    { \"Visual*\" \"visual\" }"
  83     "    { \"VisualID\" \"visualid\" }"
  84     "    { \"int\" \"screen\" }"
  85     "    { \"uint\" \"depth\" }"
  86     "    { \"int\" \"class\" }"
  87     "    { \"ulong\" \"red_mask\" }"
  88     "    { \"ulong\" \"green_mask\" }"
  89     "    { \"ulong\" \"blue_mask\" }"
  90     "    { \"int\" \"colormap_size\" }"
  91     "    { \"int\" \"bits_per_rgb\" } ;"
  92 }
  93 "C structure objects can be allocated by calling " { $link <c-object> } " or " { $link malloc-object } "."
  94 $nl
  95 "Arrays of C structures can be created by calling " { $link <c-array> } " or " { $link malloc-array } ". Elements can be read and written using words named " { $snippet { $emphasis "type" } "-nth" } " and " { $snippet "set-" { $emphasis "type" } "-nth" } "; these words are automatically generated by " { $link POSTPONE: C-STRUCT: } "." ;
  96
  97 ARTICLE: "c-unions" "C unions"
  98 "A " { $snippet "union" } " in C defines a type large enough to hold its largest member. This is usually used to allocate a block of memory which can hold one of several types of values."
  99 { $subsection POSTPONE: C-UNION: }
 100 "C union objects can be allocated by calling " { $link <c-object> } " or " { $link malloc-object } "."
 101 $nl
 102 "Arrays of C unions can be created by calling " { $link <c-array> } " or " { $link malloc-array } ". Elements can be read and written using words named " { $snippet { $emphasis "type" } "-nth" } " and " { $snippet "set-" { $emphasis "type" } "-nth" } "; these words are automatically generated by " { $link POSTPONE: C-UNION: } "." ;