classes.c-types and classes.struct docs

extra/classes/c-types/c-types-docs.factor

@@ -0,0 +1,69 @@
+! (c)Joe Groff bsd license
+USING: alien arrays classes help.markup help.syntax kernel math ;
+IN: classes.c-types
+
+HELP: c-type-class
+{ $class-description "This metaclass encompasses the " { $link "classes.c-types" } "." } ;
+
+HELP: char
+{ $class-description "A signed one-byte integer quantity." } ;
+
+HELP: direct-array-of
+{ $values
+    { "alien" c-ptr } { "len" integer } { "class" c-type-class }
+    { "array" "a direct array" }
+}
+{ $description "Constructs a direct array over " { $snippet "len" } " elements of type " { $snippet "class" } " located at the referenced location in memory." } ;
+
+HELP: int
+{ $class-description "A signed four-byte integer quantity." } ;
+
+HELP: long
+{ $class-description "A signed integer quantity. On 64-bit Unix platforms, this is an eight-byte quantity; on Windows and on 32-bit Unix platforms, it is four bytes." } ;
+
+HELP: longlong
+{ $class-description "A signed eight-byte integer quantity." } ;
+
+HELP: short
+{ $class-description "A signed two-byte integer quantity." } ;
+
+HELP: single-complex
+{ $class-description "A single-precision complex floating point quantity." } ;
+
+HELP: single-float
+{ $class-description "A single-precision floating point quantity." } ;
+
+HELP: uchar
+{ $class-description "An unsigned one-byte integer quantity." } ;
+
+HELP: uint
+{ $class-description "An unsigned four-byte integer quantity." } ;
+
+HELP: ulong
+{ $class-description "An unsigned integer quantity. On 64-bit Unix platforms, this is an eight-byte quantity; on Windows and on 32-bit Unix platforms, it is four bytes." } ;
+
+HELP: ulonglong
+{ $class-description "An unsigned eight-byte integer quantity." } ;
+
+HELP: ushort
+{ $class-description "An unsigned two-byte integer quantity." } ;
+
+ARTICLE: "classes.c-types" "C type classes"
+"The " { $vocab-link "classes.c-types" } " vocabulary defines Factor classes that correspond to C types in the FFI."
+{ $subsection char }
+{ $subsection uchar }
+{ $subsection short }
+{ $subsection ushort }
+{ $subsection int }
+{ $subsection uint }
+{ $subsection long }
+{ $subsection ulong }
+{ $subsection longlong }
+{ $subsection ulonglong }
+{ $subsection single-float }
+{ $subsection float }
+{ $subsection single-complex }
+{ $subsection complex }
+{ $subsection pinned-c-ptr } ;
+
+ABOUT: "classes.c-types"

extra/classes/c-types/c-types.factor

@@ -1,3 +1,4 @@
+! (c)Joe Groff bsd license
 USING: alien alien.c-types classes classes.predicate kernel
 math math.bitwise math.order namespaces sequences words
 specialized-arrays.direct.alien

extra/classes/struct/struct-docs.factor

@@ -0,0 +1,87 @@
+! (c)Joe Groff bsd license
+USING: alien classes help.markup help.syntax kernel libc
+quotations slots ;
+IN: classes.struct
+
+HELP: <struct-boa>
+{ $values
+    { "class" class }
+}
+{ $description "This macro implements " { $link boa } " for " { $link struct } " classes. User code does not need to call this word directly and should use " { $snippet "boa" } " instead." } ;
+
+HELP: <struct>
+{ $values
+    { "class" class }
+    { "struct" struct }
+}
+{ $description "Allocates garbage-collected heap memory for a new " { $link struct } " of the specified " { $snippet "class" } ". The new struct's slots are left uninitialized; to allocate a struct with the slots initialized, call " { $link new } " or " { $link boa } " instead." } ;
+
+{ <struct> malloc-struct memory>struct } related-words
+
+HELP: STRUCT:
+{ $syntax "STRUCT: class { slot type } { slot type } ... ;" }
+{ $values { "class" "a new " { $link struct } " class to define" } { "slots" "a list of slot specifiers" } }
+{ $description "Defines a new " { $link struct } " type. The syntax is nearly identical to " { $link POSTPONE: TUPLE: } "; however, there are some additional restrictions on struct types:"
+{ $list
+{ "Struct classes cannot have a superclass defined." }
+{ "The slots of a struct must all have a type declared. The type must be either another struct class, or one of the " { $link "classes.c-types" } "." } 
+{ { $link read-only } " slots on structs are not enforced, though they may be declared." }
+} } ;
+
+HELP: S{
+{ $syntax "S{ class slots... }" }
+{ $values { "class" "a " { $link struct } " class word" } { "slots" "slot values" } }
+{ $description "Marks the beginning of a literal struct. The syntax is identical to tuple literal syntax with " { $link POSTPONE: T{ } { $snippet " }" } "; in fact, " { $snippet "T{" } " and " { $snippet "S{" } " can be used interchangeably. Structs will always be printed with " { $snippet "S{" } "." } ;
+
+HELP: UNION-STRUCT:
+{ $syntax "UNION-STRUCT: class { slot type } { slot type } ... ;" }
+{ $values { "class" "a new " { $link struct } " class to define" } { "slots" "a list of slot specifiers" } }
+{ $description "Defines a new " { $link struct } " type where all of the slots share the same storage. See " { $link POSTPONE: STRUCT: } " for details on the syntax." } ;
+
+HELP: define-struct-class
+{ $values
+    { "class" class } { "slots" "a sequence of " { $link slot-spec } "s" }
+}
+{ $description "Defines a new " { $link struct } " class. This is the runtime equivalent of the " { $link POSTPONE: STRUCT: } " syntax." } ;
+
+HELP: define-union-struct-class
+{ $values
+    { "class" class } { "slots" "a sequence of " { $link slot-spec } "s" }
+}
+{ $description "Defines a new " { $link struct } " class where all of the slots share the same storage. This is the runtime equivalent of the " { $link POSTPONE: UNION-STRUCT: } " syntax." } ;
+
+HELP: malloc-struct
+{ $values
+    { "class" class }
+    { "struct" struct }
+}
+{ $description "Allocates unmanaged C heap memory for a new " { $link struct } " of the specified " { $snippet "class" } ". The new struct's slots are left uninitialized. The struct should be " { $link free } "d when it is no longer needed." } ;
+
+HELP: memory>struct
+{ $values
+    { "ptr" c-ptr } { "class" class }
+    { "struct" struct }
+}
+{ $description "Constructs a new " { $link struct } " of the specified " { $snippet "class" } " at the memory location referenced by " { $snippet "ptr" } ". The referenced memory is unchanged." } ;
+
+HELP: struct
+{ $class-description "The parent class of all struct types." } ;
+
+{ struct POSTPONE: STRUCT: POSTPONE: UNION-STRUCT: } related-words
+
+HELP: struct-class
+{ $class-description "The metaclass of all " { $link struct } " classes." } ;
+
+ARTICLE: "classes.struct" "Struct classes"
+{ $link struct } " classes are similar to " { $link tuple } "s, but their slots exhibit value semantics, and they are backed by a contiguous structured block of memory. Structs can be used for structured access to C memory or Factor byte arrays and for passing struct values in and out of the FFI. Struct types are defined using a syntax similar to tuple syntax:"
+{ $subsection POSTPONE: STRUCT: }
+"Structs can be allocated with " { $link new } " and " { $link boa } " like tuples. Additional words are provided for building structs from C memory and from existing buffers:"
+{ $subsection malloc-struct }
+{ $subsection memory>struct }
+"Structs have literal syntax like tuples:"
+{ $subsection POSTPONE: S{ }
+"Union structs are also supported, which behave like structs but share the same memory for all the type's slots."
+{ $subsection POSTPONE: UNION-STRUCT: }
+;
+
+ABOUT: "classes.struct"

extra/classes/struct/struct-tests.factor

@@ -1,3 +1,4 @@
+! (c)Joe Groff bsd license
 USING: accessors alien.c-types classes.c-types classes.struct
 combinators inverse kernel math tools.test ;
 IN: classes.struct.tests