Compiler docs, interactor tweak

TODO.FACTOR.txt

@@ -1,8 +1,6 @@
 + 0.84:
 
-- update docs for declared effects
 - RT_WORD should refer to XTs not word objects.
-- better listener multi-line expression handling
 - history doesn't work in a good way if you ^K the input
 - services do not launch if factor not running
 - roundoff is still not quite right with tracks

doc/handbook/compiler.facts

@@ -1,3 +1,25 @@
+USING: help compiler parser ;
+
 ARTICLE: "compiler" "The compiler"
-"Foo bar"
-;
+"The Factor compiler transforms word definitions to native machine code and performs a variety of optimizations."
+$terpri
+"Only words for which a stack effect can be inferred will compile. All other words run in the interpreter. See " { $link "inference" } "."
+{ $subsection "compiler-usage" }
+{ $subsection "recompile" } ;
+
+ARTICLE: "compiler-usage" "Compiler usage"
+"The main entry point to the compiler is a single word taking a word as input:"
+{ $subsection compile }
+"The above word throws an error if the word did not compile. Another variant does not:"
+{ $subsection try-compile }
+"The compiler can also compile a single quotation:"
+{ $subsection compile-quot }
+{ $subsection compile-1 } ;
+
+ARTICLE: "recompile" "Automatic recompilation"
+"Factor's compiler performs " { $emphasis "early binding" } "; if a compiled word " { $snippet "A" } " calls another compiled word " { $snippet "B" } " and " { $snippet "B" } " is subsequently redefined, the compiled definition of " { $snippet "A" } " will still refer to the earlier compiled definition of " { $snippet "B" } "."
+$terpri
+"When a word is redefined, you can recompile all affected words automatically:"
+{ $subsection recompile }
+"Normally loading a source file or a module also calls " { $link recompile } ". This can be disabled by wrapping file loading in a combinator:"
+{ $subsection no-parse-hook } ;

doc/handbook/tools.facts

@@ -1,10 +1,12 @@
 USING: definitions errors help image inspector io kernel
 listener memory modules parser prettyprint sequences test
-words ;
+words jedit ;
 
 ARTICLE: "tools" "Development tools"
 "This section covers words which are used during development, and not usually invoked directly by user code."
 $terpri
+"There are two useful development tools which are complex enough that separate sections are devoted to them; see " { $link "inference" } " and " { $link "compiler" } "."
+$terpri
 "Interactive development:"
 { $subsection "listener" }
 { $subsection "debugger" }
@@ -47,8 +49,8 @@ ARTICLE: "sources" "Source files"
 { $subsection run-file }
 "Another way to load a source file is to provide a path relative to the Factor installation directory:"
 { $subsection run-resource }
-"Words remember which source file defines them; this can be used to update word definitions during development:"
-{ $subsection reload }
+"Factor tracks which source files definitions were loaded from; see " { $link "definitions" } "."
+$terpri
 "Details on the Factor source parser itself can be found in " { $link "parser" } "."
 $terpri
 "User-contributed libraries in the " { $snippet "contrib/" } " directory of the Factor distribution should be loaded via the high-level module system instead of the above words (" { $link "modules" } ")." ;
@@ -113,17 +115,33 @@ ARTICLE: "memory" "Object memory"
 { $subsection instances } ;
 
 ARTICLE: "word-introspection" "Word introspection"
-"You can display a word's definition or documentation:"
-{ $subsection see }
-{ $subsection see-help }
-"Find words whose name contains a given string:"
+"Words support the definition protocol; see " { $link "definitions" } " for general tools that work with definitions. A few word-specific tools also exist:"
 { $subsection apropos }
-"List all vocabularies, and list words in a vocabulary:"
 { $subsection vocabs }
 { $subsection words }
-"Display callers of a given word:"
 { $subsection usage. } ;
 
+ARTICLE: "definitions" "Definitions"
+"A " { $emphasis "definition" } " is something read from a source file -- this includes words, methods, and help articles."
+$terpri
+"Words that work with definition take " { $emphasis "definition specifiers" } " as input. A definition specifier is one of the following:"
+{ $list
+    "a word"
+    "a two-element array, holding a class name and a generic word name, naming a method"
+    { "a " { $link link } " instance holding a word or a help topic, naming a piece of documentation" }
+}
+"The following words all accept definition specifiers."
+$terpri
+"Obtaining information about definitions:"
+{ $subsection see }
+{ $subsection where }
+{ $subsection subdefs }
+"Editing definitions:"
+{ $subsection jedit }
+{ $subsection reload }
+"Removing definitions:"
+{ $subsection forget } ;
+
 ARTICLE: "unit-test" "Unit testing code"
 "A unit test is a piece of code which starts with known input values, then compares the output of a word with an expected output, where the expected output is defined by the word's contract."
 $terpri

library/bootstrap/boot-stage1.factor

@@ -311,6 +311,7 @@ sequences vectors words ;
         "/library/tools/summary.facts"
         "/library/tools/describe.facts"
         "/library/tools/inspector.facts"
+        "/library/tools/jedit.facts"
         "/library/tools/listener.facts"
         "/library/tools/memory.facts"
 

library/generic/classes.factor

@@ -163,6 +163,7 @@ PREDICATE: class union members ;
     classes [ class<map get hash remove-hash ] each-with ;
 
 : forget-class ( class -- )
+    dup subdefs [ forget ] each
     dup "predicate" word-prop [ forget ] each
     dup dup flatten-class typemap get remove-hash forget-word
     dup smaller-classes- bigger-classes- ;

library/help/topics.facts

@@ -65,3 +65,6 @@ $low-level-note ;
 
 HELP: xref-help
 { $description "Update the " { $link parent-graph } ". Usually this is done automatically." } ;
+
+HELP: link
+{ $class-description "Class of help article presentations. Instances can be passed to " { $link write-object } " to output a clickable hyperlink. Also, instances of this class are valid definition specifiers; see " { $link "definitions" } "." } ;

library/test/prettyprint.factor

@@ -32,9 +32,9 @@ unit-test
 
 [ "SBUF\" hello world\"" ] [ SBUF" hello world" unparse ] unit-test
 
-: foo dup * ; inline
+: foo ( a -- b ) dup * ; inline
 
-[ "IN: temporary : foo dup * ; inline\n" ]
+[ "IN: temporary : foo ( a -- b ) dup * ; inline\n" ]
 [ [ \ foo see ] string-out ] unit-test
 
 : bar ( x -- y ) 2 + ;

library/test/tuple.factor

@@ -43,8 +43,6 @@ C: quuux-tuple-2
 ! Make sure we handle changing shapes!
 
 [
-    100
-] [
     FORGET: point
     FORGET: point?
     FORGET: point-x
@@ -57,7 +55,7 @@ C: quuux-tuple-2
     "IN: temporary TUPLE: point x y z ;" eval
     
     point-x
-] unit-test
+] unit-test-fails
 
 TUPLE: predicate-test ;
 : predicate-test drop f ;

library/tools/jedit.factor

@@ -36,8 +36,7 @@ namespaces parser prettyprint sequences strings words shells ;
 : jedit-file ( file -- )
     1array make-jedit-request send-jedit-request ;
 
-: jedit ( spec -- )
-    #! Note that line numbers here start from 1
+: jedit ( defspec -- )
     where first2 >r ?resource-path r> jedit-line/file ;
 
 ! Wire protocol for jEdit to evaluate Factor code.

library/tools/jedit.facts

@@ -0,0 +1,7 @@
+IN: jedit
+USING: help ;
+
+HELP: jedit
+{ $values { "defspec" "a definition specifier" } }
+{ $description "Opens the source file and line number containing the given definition in a running jEdit instance." }
+{ $errors "Throws an error if the " { $snippet "~/.jedit/server" } " file does not exist. jEdit must be running and the edit server feature must be enabled for this word to work." } ;

library/ui/text/interactor.factor

@@ -2,9 +2,10 @@
 ! See http://factorcode.org/license.txt for BSD license.
 IN: gadgets-text
 USING: gadgets gadgets-controls gadgets-panes generic hashtables
-help io kernel namespaces prettyprint styles threads ;
+help io kernel namespaces prettyprint styles threads sequences
+vectors ;
 
-TUPLE: interactor output continuation busy? ;
+TUPLE: interactor output continuation queue busy? ;
 
 C: interactor ( output -- gadget )
     [ set-interactor-output ] keep
@@ -19,7 +20,9 @@ M: interactor graft*
         2drop
     ] [
         t over set-interactor-busy?
-        interactor-continuation schedule-thread-with
+        swap "\n" split <reversed> >vector
+        over set-interactor-queue
+        interactor-continuation schedule-thread
     ] if ;
 
 SYMBOL: structured-input
@@ -56,5 +59,7 @@ interactor H{
 } set-gestures
 
 M: interactor stream-readln
+    dup interactor-queue empty? [
         f over set-interactor-busy?
-    [ over set-interactor-continuation stop ] callcc1 nip ;
+        [ over set-interactor-continuation stop ] callcc0
+    ] when interactor-queue pop ;