Delete empty unit tests files, remove 1- and 1+, reorder IN: lines in a lot of places...

[factor.git] / basis / combinators / smart / smart-docs.factor

diff --git a/basis/combinators/smart/smart-docs.factor b/basis/combinators/smart/smart-docs.factor
index 69ec3e701304c1e1591e100482232f17bb1dda38..59b65d91cd2128f62497af370d46b4e31df4f894 100644 (file)
--- a/basis/combinators/smart/smart-docs.factor
+++ b/basis/combinators/smart/smart-docs.factor
@@ -1,7 +1,7 @@
 ! Copyright (C) 2009 Doug Coleman.
 ! See http://factorcode.org/license.txt for BSD license.
 USING: help.markup help.syntax kernel quotations math sequences
-multiline ;
+multiline stack-checker ;
 IN: combinators.smart
 
 HELP: input<sequence
@@ -28,7 +28,7 @@ HELP: output>array
     { $example
         <" USING: combinators combinators.smart math prettyprint ;
 9 [
-    { [ 1- ] [ 1+ ] [ sq ] } cleave
+    { [ 1 - ] [ 1 + ] [ sq ] } cleave
 ] output>array .">
     "{ 8 10 81 }"
     }
@@ -48,7 +48,7 @@ HELP: output>sequence
     }
 } ;
 
-HELP: reduce-output
+HELP: reduce-outputs
 { $values
      { "quot" quotation } { "operation" quotation }
      { "newquot" quotation }
@@ -57,7 +57,7 @@ HELP: reduce-output
 { $examples
     { $example
         "USING: combinators.smart kernel math prettyprint ;"
-        "3 [ [ 4 * ] [ 4 / ] [ 4 - ] tri ] [ * ] reduce-output ."
+        "3 [ [ 4 * ] [ 4 / ] [ 4 - ] tri ] [ * ] reduce-outputs ."
         "-9"
     }
 } ;
@@ -71,21 +71,58 @@ HELP: sum-outputs
 { $examples
     { $example
         "USING: combinators.smart kernel math prettyprint ;"
-        "10 [ [ 1- ] [ 1+ ] bi ] sum-outputs ."
+        "10 [ [ 1 - ] [ 1 + ] bi ] sum-outputs ."
         "20"
     }
 } ;
 
+HELP: append-outputs
+{ $values
+     { "quot" quotation }
+     { "seq" sequence }
+}
+{ $description "Infers the number of outputs from " { $snippet "quot" } " and returns a sequence of the outputs appended." }
+{ $examples
+    { $example
+        "USING: combinators.smart prettyprint ;"
+        "[ { 1 2 } { \"A\" \"b\" } ] append-outputs ."
+        "{ 1 2 \"A\" \"b\" }"
+    }
+} ;
+
+HELP: append-outputs-as
+{ $values
+     { "quot" quotation } { "exemplar" sequence }
+     { "seq" sequence }
+}
+{ $description "Infers the number of outputs from " { $snippet "quot" } " and returns a sequence of type " { $snippet "exemplar" } " of the outputs appended." }
+{ $examples
+    { $example
+        "USING: combinators.smart prettyprint ;"
+        "[ { 1 2 } { \"A\" \"b\" } ] V{ } append-outputs-as ."
+        "V{ 1 2 \"A\" \"b\" }"
+    }
+} ;
+
+{ append-outputs append-outputs-as } related-words
+
+
 ARTICLE: "combinators.smart" "Smart combinators"
-"The " { $vocab-link "combinators.smart" } " vocabulary implements " { $emphasis "smart combinators" } ". A smart combinator is one whose behavior depends on the static stack effect of an input quotation." $nl
-"Smart inputs from a sequence:"
+"A " { $emphasis "smart combinator" } " is a macro which reflects on the stack effect of an input quotation. The " { $vocab-link "combinators.smart" } " vocabulary implements a few simple smart combinators which look at the static stack effects of input quotations and generate code which produces or consumes the relevant number of stack values." $nl
+"Call a quotation and discard all output values:"
+{ $subsection drop-outputs }
+"Take all input values from a sequence:"
 { $subsection input<sequence }
-"Smart outputs to a sequence:"
+"Store all output values to a sequence:"
 { $subsection output>sequence }
 { $subsection output>array }
-"Reducing the output of a quotation:"
-{ $subsection reduce-output }
-"Summing the output of a quotation:"
-{ $subsection sum-outputs } ;
+"Reducing the set of output values:"
+{ $subsection reduce-outputs }
+"Summing output values:"
+{ $subsection sum-outputs }
+"Concatenating output values:"
+{ $subsection append-outputs }
+{ $subsection append-outputs-as }
+"New smart combinators can be created by defining " { $link "macros" } " which call " { $link infer } "." ;
 
 ABOUT: "combinators.smart"