From 4a1b2d0d77acc70b09731c5de3ef6d2dccca9e5b Mon Sep 17 00:00:00 2001 From: Joe Groff Date: Thu, 13 Aug 2009 17:59:38 -0400 Subject: [PATCH] classes.c-types and classes.struct docs --- extra/classes/c-types/c-types-docs.factor | 69 ++++++++++++++++++ extra/classes/c-types/c-types.factor | 1 + extra/classes/struct/struct-docs.factor | 87 +++++++++++++++++++++++ extra/classes/struct/struct-tests.factor | 1 + 4 files changed, 158 insertions(+) create mode 100644 extra/classes/c-types/c-types-docs.factor create mode 100644 extra/classes/struct/struct-docs.factor diff --git a/extra/classes/c-types/c-types-docs.factor b/extra/classes/c-types/c-types-docs.factor new file mode 100644 index 0000000000..13363f99e8 --- /dev/null +++ b/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" diff --git a/extra/classes/c-types/c-types.factor b/extra/classes/c-types/c-types.factor index 5082e0d2f5..58aa3a1d2f 100644 --- a/extra/classes/c-types/c-types.factor +++ b/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 diff --git a/extra/classes/struct/struct-docs.factor b/extra/classes/struct/struct-docs.factor new file mode 100644 index 0000000000..18c012b61c --- /dev/null +++ b/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: +{ $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: +{ $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." } ; + +{ 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" diff --git a/extra/classes/struct/struct-tests.factor b/extra/classes/struct/struct-tests.factor index 8086f45ebf..3c64b30b25 100644 --- a/extra/classes/struct/struct-tests.factor +++ b/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