Documentation updates

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" } "." ;

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

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 } ;

library/alien/aliens.facts

@@ -3,7 +3,10 @@ USING: help ;
 
 HELP: <displaced-alien> "( 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 <alien> } " 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> alien-address } ;
 
 HELP: alien-address "( c-ptr -- addr )"
@@ -14,6 +17,7 @@ HELP: alien-address "( c-ptr -- addr )"
 HELP: <alien> "( 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 <displaced-alien> 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 -- )"

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." } ;

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: } "." } ;

library/alien/syntax.factor

@@ -8,31 +8,13 @@ sequences syntax words ;
 
 : ALIEN: scan-word <alien> 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

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 <alien> } ;
+
+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 ;" }
+} ;

library/inference/known-words.factor

@@ -384,7 +384,7 @@ sequences strings vectors words prettyprint ;
 \ <byte-array> [ [ integer ] [ byte-array ] ] "infer-effect" set-word-prop
 \ <byte-array> t "flushable" set-word-prop
 
-\ <displaced-alien> [ [ integer c-ptr ] [ alien ] ] "infer-effect" set-word-prop
+\ <displaced-alien> [ [ integer c-ptr ] [ c-ptr ] ] "infer-effect" set-word-prop
 \ <displaced-alien> t "flushable" set-word-prop
 
 \ alien-signed-cell [ [ c-ptr integer ] [ integer ] ] "infer-effect" set-word-prop