From e284e735e193be3d78f0077f2202f1cadb9ed98d Mon Sep 17 00:00:00 2001 From: slava Date: Mon, 27 Mar 2006 02:08:02 +0000 Subject: [PATCH] Documentation updates --- doc/handbook/syntax.facts | 9 +++- library/alien/alien-callback.facts | 2 +- library/alien/alien-invoke.facts | 2 +- library/alien/aliens.facts | 23 +++++++++- library/alien/malloc.facts | 32 +++++++++++++ library/alien/structs.facts | 6 +++ library/alien/syntax.factor | 22 +-------- library/alien/syntax.facts | 69 ++++++++++++++++++++++++++++ library/inference/known-words.factor | 2 +- 9 files changed, 141 insertions(+), 26 deletions(-) create mode 100644 library/alien/malloc.facts create mode 100644 library/alien/structs.facts create mode 100644 library/alien/syntax.facts diff --git a/doc/handbook/syntax.facts b/doc/handbook/syntax.facts index 137a13865d..79bee5403f 100644 --- a/doc/handbook/syntax.facts +++ b/doc/handbook/syntax.facts @@ -115,7 +115,8 @@ $terpri { $subsection "syntax-booleans" } { $subsection "syntax-strings" } { $subsection "syntax-sbufs" } -{ $subsection "syntax-lists" } ; +{ $subsection "syntax-lists" } +{ $subsection "syntax-aliens" } ; GLOSSARY: "number" "an instance of the " { $link number } " class" ; @@ -255,3 +256,9 @@ ARTICLE: "syntax-lists" "Quotation syntax" { $subsection POSTPONE: [ } { $subsection POSTPONE: ] } "Quotations are documented in " { $link "quotations" } "." ; + +ARTICLE: "syntax-aliens" "Alien interface objects" +"These literal forms mainly exist for print-outs, and should not be input unless you know what you are doing." +{ $subsection POSTPONE: DLL" } +{ $subsection POSTPONE: ALIEN: } +"The alien interface is documented in " { $link "alien" } "." ; diff --git a/library/alien/alien-callback.facts b/library/alien/alien-callback.facts index 0714b3c753..71c1795b96 100644 --- a/library/alien/alien-callback.facts +++ b/library/alien/alien-callback.facts @@ -4,7 +4,7 @@ USING: errors help ; HELP: alien-callback "( return parameters quot -- alien )" { $values { "return" "a C return type" } { "parameters" "a sequence of C parameter types" } { "quot" "a quotation" } { "alien" "an alien address" } } { $description - "Defines a callback from C to Factor which accepts the given set of parameters from the C caller, pushes them on the data stack, calls the quotation, and passes a return value back to the C caller." + "Defines a callback from C to Factor which accepts the given set of parameters from the C caller, pushes them on the data stack, calls the quotation, and passes a return value back to the C caller. A return type of " { $snippet "\"void\"" } " indicates that no value is to be returned." $terpri "This word only runs when it is called from within a " { $emphasis "compiled" } " word, with all three parameters as literal inputs. See " { $link "compiler" } "." $terpri diff --git a/library/alien/alien-invoke.facts b/library/alien/alien-invoke.facts index 4d64195045..873e4bff78 100644 --- a/library/alien/alien-invoke.facts +++ b/library/alien/alien-invoke.facts @@ -3,7 +3,7 @@ USING: help ; HELP: alien-invoke "( ... return library function parameters -- ... )" { $values { "return" "a C return type" } { "library" "a logical library name" } { "function" "a C function name" } { "parameters" "a sequence of C parameter types" } } -{ $description "Calls a C library function with the given name. Input parameters are taken from the data stack, and the return value is pushed on the data stack after the function returns." +{ $description "Calls a C library function with the given name. Input parameters are taken from the data stack, and the return value is pushed on the data stack after the function returns. A return type of " { $snippet "\"void\"" } " indicates that no value is to be expected." $terpri "This word only runs when it is called from within a " { $emphasis "compiled" } " word, with all four parameters as literal inputs. See " { $link "compiler" } "." } { $see-also alien-callback } ; diff --git a/library/alien/aliens.facts b/library/alien/aliens.facts index 53e581e3dd..d62c2e99fb 100644 --- a/library/alien/aliens.facts +++ b/library/alien/aliens.facts @@ -3,7 +3,10 @@ USING: help ; HELP: "( displacement c-ptr -- alien )" { $values { "displacement" "an integer" } { "c-ptr" "an alien, byte array, or " { $link f } } { "alien" "a new alien" } } -{ $description "Creates a new alien address object, wrapping a raw memory address. The alien points to a location in memory which is offset by " { $snippet "displacement" } " from the address of " { $link "c-ptr" } ". Passing a value of " { $link f } " for " { $snippet "c-ptr" } " creates an alien with an absolute address." } +{ $description "Creates a new alien address object, wrapping a raw memory address. The alien points to a location in memory which is offset by " { $snippet "displacement" } " from the address of " { $link "c-ptr" } "." } +{ $notes "Passing a value of " { $link f } " for " { $snippet "c-ptr" } " creates an alien with an absolute address; this is how " { $link } " is implemented." +$terpri +"Passing a zero absolute address does not construct a new alien object, but instead makes the word output " { $link f } "." } { $see-also alien-address } ; HELP: alien-address "( c-ptr -- addr )" @@ -14,6 +17,7 @@ HELP: alien-address "( c-ptr -- addr )" HELP: "( address -- alien )" { $values { "address" "a non-negative integer" } { "alien" "a new alien address" } } { $description "Creates an alien object, wrapping a raw memory address." } +{ $notes "Alien objects are invalidated between image saves and loads." } { $see-also alien-address } ; HELP: c-ptr f @@ -29,9 +33,24 @@ HELP: library "( name -- library )" } } ; +HELP: dlopen "( path -- dll )" +{ $values { "path" "a path name string" } { "dll" "a DLL handle" } } +{ $description "Opens a native library and outputs a handle which may be passed to " { $link dlsym } " or " { $link dlclose } "." } +{ $errors "Throws an error if the library could not be found, or if loading fails for some other reason." } +{ $notes "This is the low-level facility used to implement " { $link load-library } ". Use the latter instead." } ; + +HELP: dlsym "( name dll -- alien )" +{ $values { "name" "a C symbol name" } { "dll" "a DLL handle" } { "alien" "an alien pointer" } } +{ $description "Looks up a symbol in a native library. If " { $snippet "dll" } " is " { $link f } " looks for the symbol in the runtime executable." } +{ $errors "Throws an error if the symbol could not be found." } ; + +HELP: dlclose "( dll -- )" +{ $values { "dll" "a DLL handle" } } +{ $description "Closes a DLL handle created by " { $link dlopen } ". This word might not be implemented on all platforms." } ; + HELP: load-library "( name -- dll )" { $values { "name" "a string" } { "dll" "a DLL handle" } } -{ $description "Loads a library by logical name. If the library is already loaded, returns the existing handle." } +{ $description "Loads a library by logical name and outputs a handle which may be passed to " { $link dlsym } " or " { $link dlclose } ". If the library is already loaded, returns the existing handle." } { $errors "Throws an error if the library could not be found, or if loading fails for some other reason." } ; HELP: add-library "( name path abi -- )" diff --git a/library/alien/malloc.facts b/library/alien/malloc.facts new file mode 100644 index 0000000000..b27fae40a3 --- /dev/null +++ b/library/alien/malloc.facts @@ -0,0 +1,32 @@ +IN: libc +USING: help ; + +HELP: malloc "( size -- alien )" +{ $values { "size" "a non-negative integer" } { "alien" "an alien address" } } +{ $description "Allocates a block of " { $snippet "size" } " bytes from the operating system. The contents of the block are undefined." +$terpri +"Outputs " { $link f } " if memory allocation failed, so calls to this word should be followed by a call to " { $link check-ptr } "." } +{ $warning "Don't forget to deallocate the memory with a call to " { $link free } "." } ; + +HELP: calloc "( count size -- alien )" +{ $values { "count" "a non-negative integer" } { "size" "a non-negative integer" } { "alien" "an alien address" } } +{ $description "Allocates a block of " { $snippet "count * size" } " bytes from the operating system. The contents of the block are initially zero." +$terpri +"Outputs " { $link f } " if memory allocation failed, so calls to this word should be followed by a call to " { $link check-ptr } "." } +{ $warning "Don't forget to deallocate the memory with a call to " { $link free } "." } ; + +HELP: realloc "( alien size -- newalien )" +{ $values { "alien" "an alien address" } { "size" "a non-negative integer" } { "newalien" "an alien address" } } +{ $description "Allocates a new block of " { $snippet "size" } " bytes from the operating system. The contents of " { $snippet "alien" } ", which itself must be a block previously returned by " { $link malloc } " or " { $link realloc } ", are copied into the new block, and the old block is freed." +$terpri +"Outputs " { $link f } " if memory allocation failed, so calls to this word should be followed by a call to " { $link check-ptr } "." } +{ $warning "Don't forget to deallocate the memory with a call to " { $link free } "." } ; + +HELP: memcpy "( dst src size -- newalien )" +{ $values { "dst" "an alien address" } { "src" "an alien address" } { "size" "a non-negative integer" } } +{ $description "Copies " { $snippet "size" } " bytes from " { $snippet "src" } " to " { $snippet "dst" } "." } +{ $warning "As per the BSD C library documentation, the behavior is undefined if the source and destination overlap." } ; + +HELP: check-ptr "( c-ptr -- checked )" +{ $values { "c-ptr" "an alien address, byte array, or " { $link f } } { "checked" "an alien address or byte array with non-zero address" } } +{ $description "Throws an error if the input is " { $link f } ". Otherwise the object remains on the data stack." } ; diff --git a/library/alien/structs.facts b/library/alien/structs.facts new file mode 100644 index 0000000000..c1658a1a61 --- /dev/null +++ b/library/alien/structs.facts @@ -0,0 +1,6 @@ +IN: alien +USING: help ; + +HELP: c-struct? "( type -- ? )" +{ $values { "type" "a string" } { "?" "a boolean" } } +{ $description "Tests if a C type is a structure defined by " { $link POSTPONE: BEGIN-STRUCT: } "." } ; diff --git a/library/alien/syntax.factor b/library/alien/syntax.factor index d765c838ac..20787bda36 100644 --- a/library/alien/syntax.factor +++ b/library/alien/syntax.factor @@ -8,31 +8,13 @@ sequences syntax words ; : ALIEN: scan-word swons ; parsing -! usage of 'LIBRARY:' and 'FUNCTION:' : -! -! LIBRARY: gl -! FUNCTION: void glTranslatef ( GLfloat x, GLfloat y, GLfloat z ) ; -! -! should be the same as doing: -! -! : glTranslatef ( x y z -- ) -! "void" "gl" "glTranslatef" [ "GLfloat" "GLfloat" "GLfloat" ] alien-invoke ; -! -! other forms: -! -! FUNCTION: void glEnd ( ) ; -> : glEnd ( -- ) "void" "gl" "glEnd" [ ] alien-invoke ; -! -! TODO: show returns in the stack effect - : LIBRARY: scan "c-library" set ; parsing : FUNCTION: scan "c-library" get scan string-mode on [ string-mode off define-c-word ] [ ] ; parsing -: TYPEDEF: - #! TYPEDEF: old new - scan scan typedef ; parsing +: TYPEDEF: scan scan typedef ; parsing : BEGIN-STRUCT: ( -- offset ) scan "struct-name" set 0 ; parsing @@ -43,7 +25,7 @@ sequences syntax words ; : END-STRUCT ( length -- ) define-struct-type ; parsing -: C-UNION: ( -- max ) +: C-UNION: scan "struct-name" set string-mode on [ string-mode off diff --git a/library/alien/syntax.facts b/library/alien/syntax.facts new file mode 100644 index 0000000000..4b9f996ad4 --- /dev/null +++ b/library/alien/syntax.facts @@ -0,0 +1,69 @@ +IN: syntax +USING: alien help ; + +HELP: DLL" "path\" +{ $values { "path" "a path name string" } } +{ $description "Constructs a DLL handle at parse time." } +{ $see-also dlopen } ; + +HELP: ALIEN: "address" +{ $values { "address" "a non-negative integer" } } +{ $description "Creates an alien object at parse time." } +{ $notes "Alien objects are invalidated between image saves and loads." } +{ $see-also } ; + +HELP: LIBRARY: "name" +{ $values { "name" "a logical library name" } } +{ $description "Sets the logical library for consequent " { $link POSTPONE: FUNCTION: } " definitions that follow." } ; + +HELP: FUNCTION: "return name ( parameters )" +{ $values { "return" "a C return type" } { "name" "a C function name" "parameters" "a comma-separated sequence of type/name pairs; " { $snippet "type1 arg1, type2 arg2, ..." } } } +{ $description "Defines a new word " { $snippet "name" } " which calls a C library function with the same name, in the logical library given by the most recent " { $link POSTPONE: LIBRARY: } " declaration." +$terpri +"The new word must be compiled before being executed; see " { $link "compiler" } "." } +{ $examples +"For example, suppose the " { $snippet "foo" } " library exports the following function:" +{ $code + "void the_answer(char* question, int value) {" + " printf(\"The answer to %s is %d.\n\",question,value);" + "}" +} +"You can define a word for invoking it:" +{ $example + "LIBRARY: foo\nFUNCTION: the_answer ( char* question, int value ) ;\n\ the_answer compile\n\"the question\" 42 the-answer" "The answer to the question is 42." +} } +{ $notes "Note that the parentheses and commas are only syntax sugar and can be omitted; they serve no purpose other than to make the declaration slightly easier to read:" +{ $code + "FUNCTION: void glHint ( GLenum target, GLenum mode ) ;" + "FUNCTION: void glHint GLenum target GLenum mode ;" +} } ; + +HELP: TYPEDEF: "old new" +{ $values { "old" "a C type" } { "new" "a C type" } } +{ $description "Alises the C types " { $snippet "old" } " and " { $snippet "old*" } " under the names " { $snippet "new" } " and " { $snippet "new*" } ", respectively." } +{ $see-also (typedef) typedef } ; + +HELP: BEGIN-STRUCT: "name" +{ $values { "name" "a new C type name" } } +{ $description "Begins reading a C struct definition. This word must be followed by one or more " { $link POSTPONE: FIELD: } " declarations, terminating in " { $link POSTPONE: END-STRUCT } "." } ; + +HELP: FIELD: "type name" +{ $values { "type" "a C type" } { "name" "a field name" } } +{ $description "Adds a field to the C structure currently being read. This word can only be used inside a " { $link POSTPONE: BEGIN-STRUCT: } "/" { $link POSTPONE: END-STRUCT } " pair." } ; + +HELP: END-STRUCT f +{ $description "Ends a structure definition. Only valid after a " { $link POSTPONE: BEGIN-STRUCT: } "." } ; + +HELP: C-UNION: "name members..." +{ $values { "name" "a new C type name" } { "members" "a sequence of C types" } } +{ $description "Defines a new C type sized to fit its largest member." } +{ $examples { $code "C-UNION: event active-event keyboard-event mouse-event ;" } } ; + +HELP: C-ENUM: "words..." +{ $values { "words" "a sequence of word names" } } +{ $description "Creates a sequence of compound definitions in the current vocabulary. Each word pushes an integer according to its index in the enumeration definition. The first word pushes 0." } +{ $notes "This word emulates a C-style " { $snippet "enum" } " in Factor. While this feature can be used for any purpose, using integer constants is discouraged unless it is for interfacing with C libraries. Factor code should use symbolic constants instead." } +{ $examples + "The following two lines are equivalent:" + { $code "C-ENUM: red green blue ;" ": red 0 ; : green 1 ; : blue 2 ;" } +} ; diff --git a/library/inference/known-words.factor b/library/inference/known-words.factor index 8261174ce9..1100ba8c18 100644 --- a/library/inference/known-words.factor +++ b/library/inference/known-words.factor @@ -384,7 +384,7 @@ sequences strings vectors words prettyprint ; \ [ [ integer ] [ byte-array ] ] "infer-effect" set-word-prop \ t "flushable" set-word-prop -\ [ [ integer c-ptr ] [ alien ] ] "infer-effect" set-word-prop +\ [ [ integer c-ptr ] [ c-ptr ] ] "infer-effect" set-word-prop \ t "flushable" set-word-prop \ alien-signed-cell [ [ c-ptr integer ] [ integer ] ] "infer-effect" set-word-prop