Documentation updates

README.txt

@@ -13,7 +13,6 @@ implementation. It is not an introduction to the language itself.
 - Running Factor on Mac OS X
 - Running Factor on Windows
 - Source organization
-- Learning Factor
 - Community
 - Credits
 
@@ -24,18 +23,19 @@ Factor is fully supported on the following platforms:
   Linux/x86
   Linux/AMD64
   Mac OS X/PowerPC
-  Solaris/x86
-  Microsoft Windows 2000 or later
 
 The following platforms should work, but are not tested on a
 regular basis:
 
   FreeBSD/x86
   FreeBSD/AMD64
-  Linux/PowerPC
+  Solaris/x86
   Solaris/AMD64
+  Linux/PowerPC
+  Microsoft Windows 2000 or later
 
-Other platforms are not supported.
+Please donate time or hardware if you wish to see Factor running on
+other platforms.
 
 * Compiling Factor
 
@@ -76,9 +76,10 @@ Compilation will yield an executable named 'f'.
 
 * Building Factor
 
-The Factor source distribution ships with three boot image files:
+The Factor source distribution ships with four boot image files:
 
   boot.image.x86
+  boot.image.pentium4 -- uses SSE2, only for Pentium 4 and later
   boot.image.ppc
   boot.image.amd64
 
@@ -89,9 +90,6 @@ The system is bootstrapped with the following command line:
 
 ./f boot.image.<foo>
 
-Additional options may be specified to load external C libraries; see
-the next section for details.
-
 Bootstrap can take a while, depending on your system. When the process
 completes, a 'factor.image' file will be generated. Note that this image
 is both CPU and OS-specific, so in general cannot be shared between
@@ -144,8 +142,8 @@ between PowerPC Macs.
 On Windows, double-clicking f.exe will start running the Win32-based UI
 with the factor.image in the same directory as the executable.
 
-Bootstrap runs in a Windows command prompt, however after bootstrapping
-only the UI can be used.
+Bootstrap runs in a Windows command prompt, however there is no
+terminal listener and after bootstrapping only the UI can be used.
 
 * Source organization
 
@@ -156,15 +154,6 @@ only the UI can be used.
   examples/ - small examples illustrating various language features
   fonts/ - TrueType fonts used by UI
 
-* Learning Factor
-
-The UI has a tutorial and defailed reference documentation. You can
-browse it in the UI or by running the HTTP server (contrib/httpd).
-
-You can browse the source code; it is organized into small,
-well-commented files and should be easy to follow once you have a good
-grasp of the language.
-
 * Community
 
 The Factor homepage is located at http://factorcode.org/.
@@ -179,7 +168,8 @@ The following people have contributed code to the Factor core:
 
 Slava Pestov:       Lead developer
 Alex Chapman:       OpenGL binding
-Doug Coleman:       Mersenne Twister random number generator
+Doug Coleman:       Mersenne Twister RNG, Windows port
+Eduardo Cavazos:    X11 binding
 Mackenzie Straight: Windows port
 Trent Buck:         Debian package
 

TODO.FACTOR.txt

@@ -4,6 +4,9 @@
 [ 1 2 3 4 5 6 7 8 9 10 10 10 10 10 10 10 10 10 10 11 11 11 113 
 ]
 
+- running all help entries:
+  - without a yield UI runs out of memory
+  - leaves array array on the stack
 - x11 title bars are funny
 + httpd:
   - outliners don't work
@@ -11,6 +14,8 @@
 - code walker & exceptions -- test and debug problems
 - another i/o bug: on factorcode eventually all i/o times out
   - bug in pound?
+- factorcode httpd started using 99% CPU, but still received connections;
+  closing read-fds solved it
 - if the listener is running a command when the image is saved, it
   restores to an unresponsive gadget
 - fix top level window positioning

library/bootstrap/boot-stage1.factor

@@ -206,6 +206,7 @@ vectors words ;
         "/library/continuations.facts"
         "/library/errors.facts"
         "/library/kernel.facts"
+        "/library/quotations.facts"
         "/library/threads.facts"
         "/library/words.facts"
         "/library/bootstrap/image.facts"

library/continuations.factor

@@ -5,6 +5,8 @@ USING: vectors ;
 
 : catchstack* ( -- cs ) 6 getenv { vector } declare ; inline
 
+: (continue-with) 9 getenv ;
+
 IN: errors
 USING: kernel kernel-internals ;
 
@@ -44,8 +46,6 @@ TUPLE: continuation data retain call name catch ;
     set-datastack ;
     inline
 
-: (continue-with) 9 getenv ;
-
 : callcc1 [ drop (continue-with) ] ifcc ; inline
 
 : continue-with swap 9 setenv continue ; inline

library/errors.facts

@@ -4,6 +4,10 @@ HELP: >c "( continuation -- )"
 { $values { "continuation" "a continuation" } }
 { $description "Pushes an exception handler continuation on the catch stack. The continuation must have been reified by " { $link callcc1 } "." } ;
 
+HELP: c> "( -- continuation )"
+{ $values { "continuation" "a continuation" } }
+{ $description "Pops an exception handler continuation from the catch stack." } ;
+
 HELP: throw "( error -- )"
 { $values { "error" "an object" } }
 { $description "Saves the current continuation in the " { $link error-continuation } " global variable and throws an error. Execution does not continue at the point after the " { $link throw } " call. Rather, the innermost catch block is invoked, and execution continues at that point." }
@@ -39,3 +43,22 @@ HELP: rethrow "( error -- )"
 HELP: error. "( error -- )"
 { $values { "error" "an object" } }
 { $contract "Prints an error in human-readable form." } ;
+
+HELP: condition "( error restarts -- restart )"
+{ $values { "error" "an object" } { "restarts" "a sequence of pairs" } { "restart" "an object" } }
+{ $description "Throws a restartable error. The " { $snippet "restarts" } " parameter is a sequence of pairs where the first element in each pair is a human-readable description and the second is an arbitrary object. If the error reaches the top-level error handler, the user will be presented with the list of possible restarts, and upon invoking one with the " { $link :res } " word, execution will continue after the call to " { $link condition } " with the object associated to the chosen restart on the stack." }
+{ $examples
+    "Try invoking one of the two restarts which are offered after the below code throws an error:"
+    { $code
+        ": restart-test"
+        "    \"Oops!\" { { \"One\" 1 } { \"Two\" 2 } } condition"
+        "    \"You restarted: \" write . ;"
+        "restart-test"
+    }
+} ;
+
+HELP: compute-restarts "( error -- seq )"
+{ $values { "error" "an object" } { "seq" "a sequence" } }
+{ $description "Outputs a sequence of triples, where each triple consists of a human-readable string, an object, and a continuation. Resuming a continuation with the corresponding object restarts execution immediately after the corresponding call to " { $link condition } "."
+$terpri
+"This word recursively travels up the delegation chain to collate restarts from nested and wrapped conditions." } ;

library/kernel.facts

@@ -1,4 +1,5 @@
-USING: generic help kernel kernel-internals memory sequences ;
+USING: generic help kernel kernel-internals math memory
+sequences ;
 
 HELP: eq? "( obj1 obj2 -- ? )"
 { $values { "obj1" "an object" } { "obj2" "an object" } }
@@ -48,7 +49,7 @@ HELP: hashcode "( obj -- n )"
 { $values { "obj" "an object" } { "n" "a fixnum" } }
 { $contract "Outputs the hashcode of the object. The hashcode operation must satisfy the following properties:"
 { $list
-    "the hashcode must be a fixnum. Returning a bignum will not cause any problems other than potential performance degradation. Returning other types will result in type errors."
+    "the hashcode should be a fixnum, however returning a bignum will not cause any problems other than potential performance degradation."
     { "if two objects are equal under " { $link = } ", they must have equal hashcodes" }
     "the hashcode is only permitted to change if the object is mutated in some way"
     { "the word must satisfy the " { $link POSTPONE: flushable } " contract" }
@@ -144,6 +145,14 @@ HELP: os "( -- os )"
     { $code "freebsd" "linux" "macosx" "solaris" "win32" "unix" }
 } ;
 
+HELP: windows? "( -- ? )"
+{ $values { "?" "a boolean" } }
+{ $description "Tests if Factor is running on Windows." } ;
+
+HELP: macosx? "( -- ? )"
+{ $values { "?" "a boolean" } }
+{ $description "Tests if Factor is running on Mac OS X." } ;
+
 HELP: call "( quot -- )"
 { $values { "quot" "a quotation" } }
 { $description "Push the current callframe on the callstack, and set the callframe to the given quotation. Conceptually, calls the quotation, as if its definition was substituted at the location of the call." }
@@ -232,6 +241,17 @@ HELP: literalize "( obj -- wrapper )"
 { $values { "obj" "an object" } { "wrapper" "a wrapper or the original object" } }
 { $description "Turns non-self-evaluating objects (words and wrappers) into wrappers that push those objects, and is a no-op on everything else." } ;
 
+HELP: declare "( spec -- )"
+{ $values { "spec" "an array of classes" } }
+{ $description "Declares that the elements at the top of the stack are instances of the classes in " { $snippet "spec" } "." }
+{ $warning "The compiler blindly trusts declarations, and false declarations can lead to crashes, memory corruption and other undesirable behavior." }
+{ $examples
+    "The optimizer cannot do anything with the below quotation:"
+    { $example "[ 2 + 10 * ] f dataflow." "[ 2 + 10 * ]" }
+    "However, if we declare that the top of the stack is a " { $link float } ", then type checks and generic dispatch are eliminated, and the compiler can use unsafe intrinsics:"
+    { $example "[ { float } declare 2 + 10 * ] f dataflow." "[ 2.0 float+ 10.0 float* ]" }
+} ;
+
 HELP: array-capacity "( array -- n )"
 { $values { "array" "an array" } { "n" "a non-negative fixnum" } }
 { $description "Low-level array length accessor." }
@@ -247,6 +267,18 @@ HELP: set-array-nth "( elt n array -- )"
 { $description "Low-level array element mutator." }
 { $warning "This word is in the " { $snippet "kernel-internals" } " vocabulary because it is unsafe. It does not check types or array bounds, and improper use can corrupt memory." } ;
 
+HELP: cell "( -- n )"
+{ $values { "n" "a positive integer" } }
+{ $description "Outputs the pointer size in bytes of the current CPU architecture." } ;
+
+HELP: win32? "( -- ? )"
+{ $values { "?" "a boolean" } }
+{ $description "Tests if Factor is running on 32-bit Windows." } ;
+
+HELP: win64? "( -- ? )"
+{ $values { "?" "a boolean" } }
+{ $description "Tests if Factor is running on 64-bit Windows." } ;
+
 HELP: generations "( -- n )"
 { $values { "n" "a positive integer" } }
 { $description "Outputs the number of generations partitioning the heap." } ;

library/quotations.factor

@@ -28,7 +28,7 @@ M: object literalize ;
 M: word literalize <wrapper> ;
 M: wrapper literalize <wrapper> ;
 
-: curry ( obj quot -- quot ) >r literalize unit r> append ;
+: curry ( obj quot -- quot ) swap literalize add* ;
 
 : alist>quot ( default alist -- quot )
     [ [ first2 swap % , , \ if , ] [ ] make ] each ;

library/quotations.facts

@@ -0,0 +1,46 @@
+IN: kernel
+USING: arrays help strings vectors ;
+
+HELP: >quotation "( seq -- quot )"
+{ $values { "seq" "a sequence" } { "quot" "a quotation" } }
+{ $description "Outputs a freshly-allocated quotation with the same elements as a given sequence." }
+{ $see-also >array >string >sbuf >vector } ;
+
+HELP: make-dip "( quot n -- newquot )"
+{ $values { "quot" "a quotation" } { "n" "a non-negative integer" } { "newquot" "a quotation" } }
+{ $description "Constructs a quotation which retains the top " { $snippet "n" } " stack items, and applies " { $snippet "quot" } " to what is underneath." }
+{ $examples
+    { $example "[ 3 + ] 2 make-dip ." "[ >r >r 3 + r> r> ]" }
+} ;
+
+HELP: unit "( obj -- quot )"
+{ $values { "obj" "an object" } { "quot" "a quotation" } }
+{ $description "Constructs a quotation holding one element." }
+{ $notes
+    "The following two phrases are equivalent:"
+    { $code "\\ reverse execute" }
+    { $code "\\ reverse unit call" }
+}
+{ $see-also 1array } ;
+
+HELP: literalize "( obj -- wrapped )"
+{ $values { "obj" "an object" } { "wrapped" "an object" } }
+{ $description "Outputs an object which evaluates to " { $snippet "obj" } ". If " { $snippet "obj" } " is not self-evaluating (for example, it is a word), then it will be wrapped." }
+{ $examples
+    { $example "5 literalize ." "5" }
+    { $example "[ + ] [ litealize ] map ." "[ \\ + ]" }
+}
+{ $see-also curry <wrapper> } ;
+
+HELP: curry "( obj quot -- newquot )"
+{ $values { "obj" "an object" } { "quot" "a quotation" } { "newquot" "a quotation" } }
+{ $description "Constructs a new quotation which first pushes " { $snippet "obj" } " and then calls " { $snippet "quot" } ". If " { $snippet "obj" } " is not self-evaluating, it will be wrapped." }
+{ $examples
+    { $example "5 [ . ] curry ." "[ 5 . ]" }
+    { $example "\\ = [ see ] curry ." "[ \\ = see ]" }
+} ;
+
+HELP: alist>quot "( default assoc -- quot )"
+{ $values { "default" "a quotation" } { "assoc" "a sequence of quotation pairs" } { "quot" "a quotation" } }
+{ $description "Constructs a quotation which calls the first quotation in each pair of " { $snippet "assoc" } " until one of them outputs a true value, and then calls the second quotation in the corresponding pair. Quotations are called in reverse order, and if no quotation outputs a true value then " { $snippet "default" } " is called." }
+{ $notes "This word is used to implement compile-time behavior for " { $link cond } ", and it is also used by the generic word system. Note that unlike " { $link cond } ", the constructed quotation performs the tests starting from the end and not the beginning." } ;

library/syntax/early-parser.factor

@@ -14,8 +14,7 @@ SYMBOL: line-text
 SYMBOL: column
 
 : check-vocab ( name -- vocab )
-    dup vocab
-    [ ] [ " is not a vocabulary name" append throw ] ?if ;
+    dup vocab [ "No such vocabulary" throw ] unless* ;
 
 : use+ ( string -- ) check-vocab use get push ;
 

library/tools/memory.factor

@@ -82,8 +82,7 @@ M: object each-slot ( obj quot -- )
     pprint " instances" print ;
 
 : heap-stats. ( -- )
-    heap-stats dup hash-keys
-    [ [ word-name ] 2apply <=> ] sort [
+    heap-stats dup hash-keys natural-sort [
         ( hash hash key -- )
         [ [ pick hash ] keep pick hash ] keep heap-stat.
     ] each 2drop ;

library/words.factor

@@ -1,15 +1,11 @@
 ! Copyright (C) 2004, 2006 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
 IN: words
-USING: errors graphs hashtables kernel kernel-internals
+USING: arrays errors graphs hashtables kernel kernel-internals
 math namespaces sequences strings vectors ;
 
 M: word <=>
-    2dup [ word-vocabulary ] 2apply <=> dup zero? [
-        drop [ word-name ] 2apply <=>
-    ] [
-        2nip
-    ] if ;
+    [ dup word-name swap word-vocabulary 2array ] 2apply <=> ;
 
 GENERIC: definer ( word -- word )
 

library/words.facts

@@ -121,6 +121,10 @@ HELP: define-symbol "( word -- )"
 { $values { "word" "a word" } }
 { $description "Defines the word to push itself on the stack when executed." } ;
 
+HELP: intern-symbol "( word -- )"
+{ $values { "word" "a word" } }
+{ $description "If the word is undefined, makes it into a symbol which pushes itself on the stack when executed. If the word already has a definition, does nothing." } ;
+
 HELP: define-compound "( word def -- )"
 { $values { "word" "a word" } { "def" "a quotation" } }
 { $description "Defines the word to call a quotation when executed." } ;
@@ -135,12 +139,30 @@ HELP: reset-generic "( word -- )"
 { $description "Reset word declarations and generic word properties." }
 $low-level-note ;
 
+HELP: <word> "( name vocab -- word )"
+{ $values { "name" "a string" } { "vocab" "a string" } { "word" "a word" } }
+{ $description "Creates an uninterned word with the specified name and vocabulary. Note that this does not create the vocabulary, nor does it add the word to an existing vocabulary with that name. In most cases, " { $link create } " should be used instead." } ;
+
 HELP: gensym "( -- word )"
 { $values { "word" "a word" } }
 { $description "Creates an uninterned word that is not equal to any other word in the system. Gensyms have an automatically-generated name based on a prefix and an incrementing counter." }
 { $examples { $example "gensym ." "G:260561" } }
 { $notes "Gensyms are often used as placeholder values that have no meaning of their own but must be unique. For example, the compiler uses gensyms to label sections of assembly code." } ;
 
+HELP: define-temp "( quot -- word )"
+{ $values { "quot" "a quotation" } { "word" "a word" } }
+{ $description "Creates an uninterned word that will call " { $snippet "quot" } " when executed." }
+{ $notes
+    "The following phrases are equivalent:"
+    { $code "[ 2 2 + . ] call" }
+    { $code "[ 2 2 + . ] define-temp execute" }
+} ;
+
+HELP: completions "( string words -- seq )"
+{ $values { "string" "a string" } { "words" "a sequence of words" } { "seq" "a sequence of words" } }
+{ $description "Outputs a sequence of words whose name contains " { $snippet "string" } "." }
+{ $examples "This word is used to implement " { $link apropos } "." } ;
+
 HELP: definer "( word -- definer )"
 { $values { "word" "a word" } { "definer" "a word" } }
 { $description "Outputs the parsing word that defines the given word." }
@@ -212,8 +234,13 @@ HELP: constructor-word "( name vocab -- word )"
 
 HELP: forget "( word -- )"
 { $values { "word" "a word" } }
-{ $description "Removes the word from its vocabulary. The word becomes uninterned." }
-{ $see-also POSTPONE: FORGET: } ;
+{ $description "Removes a word from its vocabulary. The word becomes uninterned." }
+{ $see-also POSTPONE: FORGET: forget-vocab } ;
+
+HELP: forget-vocab "( vocab -- )"
+{ $values { "vocab" "a string" } }
+{ $description "Removes a vocabulary. All words in the vocabulary become uninterned." }
+{ $see-also forget } ;
 
 HELP: target-word "( word -- target )"
 { $values { "word" "a word" } { "target" "a word" } }