Standard combination docs

TODO.FACTOR.txt

@@ -1,5 +1,10 @@
+- UI word wrap: sometimes a space appears at the front
+- need line and paragraph spacing
+- update HTML stream
+- help cross-referencing
+- UI browser pane needs 'back' button
+- tty help
 - if cell is rebound, and we allocate c objects, bang
-- make-image leaks memory if there is an error while parsing files
 - runtime primitives like fopen: check for null input
 - -with combinators are awkward
 - cleanups:

library/bootstrap/boot-stage1.factor

@@ -223,6 +223,7 @@ vectors words ;
         "/library/generic/generic.facts"
         "/library/generic/math-combination.facts"
         "/library/generic/slots.facts"
+        "/library/generic/standard-combination.facts"
         "/library/syntax/parse-stream.facts"
         "/library/syntax/parser.facts"
         "/library/syntax/parse-syntax.facts"

library/generic/standard-combination.factor

@@ -63,15 +63,11 @@ math namespaces sequences vectors words ;
     "methods" word-prop hash-size 3 <= ;
 
 : standard-combination ( word picker -- quot )
-    swap dup tag-generic? [
+    swap {
-        num-tags \ tag big-generic
+        { [ dup tag-generic? ] [ num-tags \ tag big-generic ] }
-    ] [
+        { [ dup small-generic? ] [ small-generic ] }
-        dup small-generic? [
+        { [ t ] [ num-types \ type big-generic ] }
-            small-generic
+    } cond ;
-        ] [
-            num-types \ type big-generic
-        ] if
-    ] if ;
 
 : simple-combination ( word -- quot )
     [ dup ] standard-combination ;

library/generic/standard-combination.facts

@@ -0,0 +1,45 @@
+USING: generic help ;
+
+HELP: standard-combination "( word picker -- quot )"
+{ $values { "word" "a generic word" } { "picker" "a quotation with stack effect " { $snippet "( -- obj )" } } { "quot" "a new quotation" } }
+{ $description
+    "Performs standard method combination:"
+    { $list
+        "the word dispatches on the object produced by the picker,"
+        "only the method with most specific class is invoked."
+    }
+    "There is an additional feature if the picker is " { $snippet "[ dup ]" } ":"
+    { $list
+        "if no suitable method is found, the generic word is called on the object's delegate."
+    }
+}
+{ $examples
+    "A generic word for append strings and characters to a sequence, dispatching on the second stack element:"
+    { $code
+        "G: build-string [ over ] standard-combination ;"
+        "M: string build-string swap nappend ;"
+        "M: integer build-string push ;"
+    }
+}
+{ $see-also POSTPONE: G: define-generic* } ;
+
+HELP: simple-combination "( word -- quot )"
+{ $values { "word" "a generic word" } { "quot" "a new quotation" } }
+{ $description
+    "Performs standard method combination with " { $snippet "[ dup ]" } " as the picker quotation. That is,"
+    { $list
+        "the word dispatches on the top of the stack,"
+        "only the method with most specific class is invoked,"
+        "if no suitable method is found, the generic word is called on the object's delegate."
+    }
+}
+{ $examples "Most generic words in the standard library use this method combination." }
+{ $see-also POSTPONE: GENERIC: define-generic } ;
+
+HELP: define-generic "( word -- )"
+{ $values { "word" "a word" } }
+{ $description "Defines a generic word with the " { $link simple-combination } " method combination. If the word is already a generic word, existing methods are retained." }
+{ $see-also POSTPONE: GENERIC: define-generic* } ;
+
+HELP: simple-generic f
+{ $description "The class of generic words with the " { $link simple-combination } ". They are typically defined by the " { $link POSTPONE: GENERIC: } " parsing word." } ;