basis/combinators/smart/smart-docs.factor

   1 ! Copyright (C) 2009 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel quotations math sequences
   4 multiline stack-checker ;
   5 IN: combinators.smart
   6
   7 HELP: input<sequence
   8 { $values
   9      { "quot" quotation }
  10      { "newquot" quotation }
  11 }
  12 { $description "Infers the number of inputs, " { $snippet "n" } ", to " { $snippet "quot" } " and calls the " { $snippet "quot" } " with the first " { $snippet "n" } " values from a sequence." }
  13 { $examples
  14     { $example
  15         "USING: combinators.smart math prettyprint ;"
  16         "{ 1 2 3 } [ + + ] input<sequence ."
  17         "6"
  18     }
  19 } ;
  20
  21 HELP: output>array
  22 { $values
  23      { "quot" quotation }
  24      { "newquot" quotation }
  25 }
  26 { $description "Infers the number or outputs from the quotation and constructs an array from those outputs." }
  27 { $examples
  28     { $example
  29         <" USING: combinators combinators.smart math prettyprint ;
  30 9 [
  31     { [ 1 - ] [ 1 + ] [ sq ] } cleave
  32 ] output>array .">
  33     "{ 8 10 81 }"
  34     }
  35 } ;
  36
  37 HELP: output>sequence
  38 { $values
  39      { "quot" quotation } { "exemplar" "an exemplar" }
  40      { "newquot" quotation }
  41 }
  42 { $description "Infers the number of outputs from the quotation and constructs a new sequence from those objects of the same type as the exemplar." }
  43 { $examples
  44     { $example
  45         "USING: combinators.smart kernel math prettyprint ;"
  46         "4 [ [ 1 + ] [ 2 + ] [ 3 + ] tri ] V{ } output>sequence ."
  47         "V{ 5 6 7 }"
  48     }
  49 } ;
  50
  51 HELP: reduce-outputs
  52 { $values
  53      { "quot" quotation } { "operation" quotation }
  54      { "newquot" quotation }
  55 }
  56 { $description "Infers the number of outputs from " { $snippet "quot" } " and reduces them using " { $snippet "operation" } ". The identity for the " { $link reduce } " operation is the first output." }
  57 { $examples
  58     { $example
  59         "USING: combinators.smart kernel math prettyprint ;"
  60         "3 [ [ 4 * ] [ 4 / ] [ 4 - ] tri ] [ * ] reduce-outputs ."
  61         "-9"
  62     }
  63 } ;
  64
  65 HELP: sum-outputs
  66 { $values
  67      { "quot" quotation }
  68      { "n" integer }
  69 }
  70 { $description "Infers the number of outputs from " { $snippet "quot" } " and returns their sum." }
  71 { $examples
  72     { $example
  73         "USING: combinators.smart kernel math prettyprint ;"
  74         "10 [ [ 1 - ] [ 1 + ] bi ] sum-outputs ."
  75         "20"
  76     }
  77 } ;
  78
  79 HELP: append-outputs
  80 { $values
  81      { "quot" quotation }
  82      { "seq" sequence }
  83 }
  84 { $description "Infers the number of outputs from " { $snippet "quot" } " and returns a sequence of the outputs appended." }
  85 { $examples
  86     { $example
  87         "USING: combinators.smart prettyprint ;"
  88         "[ { 1 2 } { \"A\" \"b\" } ] append-outputs ."
  89         "{ 1 2 \"A\" \"b\" }"
  90     }
  91 } ;
  92
  93 HELP: append-outputs-as
  94 { $values
  95      { "quot" quotation } { "exemplar" sequence }
  96      { "seq" sequence }
  97 }
  98 { $description "Infers the number of outputs from " { $snippet "quot" } " and returns a sequence of type " { $snippet "exemplar" } " of the outputs appended." }
  99 { $examples
 100     { $example
 101         "USING: combinators.smart prettyprint ;"
 102         "[ { 1 2 } { \"A\" \"b\" } ] V{ } append-outputs-as ."
 103         "V{ 1 2 \"A\" \"b\" }"
 104     }
 105 } ;
 106
 107 { append-outputs append-outputs-as } related-words
 108
 109
 110 ARTICLE: "combinators.smart" "Smart combinators"
 111 "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
 112 "Call a quotation and discard all output values:"
 113 { $subsection drop-outputs }
 114 "Take all input values from a sequence:"
 115 { $subsection input<sequence }
 116 "Store all output values to a sequence:"
 117 { $subsection output>sequence }
 118 { $subsection output>array }
 119 "Reducing the set of output values:"
 120 { $subsection reduce-outputs }
 121 "Summing output values:"
 122 { $subsection sum-outputs }
 123 "Concatenating output values:"
 124 { $subsection append-outputs }
 125 { $subsection append-outputs-as }
 126 "New smart combinators can be created by defining " { $link "macros" } " which call " { $link infer } "." ;
 127
 128 ABOUT: "combinators.smart"