basis/combinators/smart/smart-docs.factor

   1 ! Copyright (C) 2009 Doug Coleman.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: classes.tuple help.markup help.syntax kernel math
   4 quotations sequences stack-checker arrays ;
   5 IN: combinators.smart
   6
   7 HELP: input<sequence
   8 { $values
   9     { "seq" sequence }
  10     { "quot" 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     { "array" array }
  25 }
  26 { $description "Infers the number of 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     { "seq" sequence }
  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 }
  55 { $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." }
  56 { $examples
  57     { $example
  58         "USING: combinators.smart kernel math prettyprint ;"
  59         "3 [ [ 4 * ] [ 4 / ] [ 4 - ] tri ] [ * ] reduce-outputs ."
  60         "-9"
  61     }
  62 } ;
  63
  64 HELP: sum-outputs
  65 { $values
  66     { "quot" quotation }
  67     { "n" integer }
  68 }
  69 { $description "Infers the number of outputs from " { $snippet "quot" } " and returns their sum." }
  70 { $examples
  71     { $example
  72         "USING: combinators.smart kernel math prettyprint ;"
  73         "10 [ [ 1 - ] [ 1 + ] bi ] sum-outputs ."
  74         "20"
  75     }
  76 } ;
  77
  78 HELP: append-outputs
  79 { $values
  80     { "quot" quotation }
  81     { "seq" sequence }
  82 }
  83 { $description "Infers the number of outputs from " { $snippet "quot" } " and returns a sequence of the outputs appended." }
  84 { $examples
  85     { $example
  86         "USING: combinators.smart prettyprint ;"
  87         "[ { 1 2 } { \"A\" \"b\" } ] append-outputs ."
  88         "{ 1 2 \"A\" \"b\" }"
  89     }
  90 } ;
  91
  92 HELP: append-outputs-as
  93 { $values
  94     { "quot" quotation } { "exemplar" sequence }
  95     { "seq" sequence }
  96 }
  97 { $description "Infers the number of outputs from " { $snippet "quot" } " and returns a sequence of type " { $snippet "exemplar" } " of the outputs appended." }
  98 { $examples
  99     { $example
 100         "USING: combinators.smart prettyprint ;"
 101         "[ { 1 2 } { \"A\" \"b\" } ] V{ } append-outputs-as ."
 102         "V{ 1 2 \"A\" \"b\" }"
 103     }
 104 } ;
 105
 106 { append-outputs append-outputs-as } related-words
 107
 108 HELP: drop-outputs
 109 { $values { "quot" quotation } }
 110 { $description "Calls a quotation and drops any values it leaves on the stack." } ;
 111
 112 HELP: keep-inputs
 113 { $values { "quot" quotation } }
 114 { $description "Calls a quotation and preserves any values it takes off the stack." } ;
 115
 116 { drop-outputs keep-inputs } related-words
 117
 118 HELP: dropping
 119 { $values
 120     { "quot" quotation }
 121     { "quot'" quotation }
 122 }
 123 { $description "Outputs a quotation that, when called, will have the effect of dropping the number of inputs to the original quotation." }
 124 { $examples
 125     { $example
 126         "USING: combinators.smart math prettyprint ;
 127 [ + + ] dropping ."
 128 "[ 3 ndrop ]"
 129     }
 130 } ;
 131
 132 HELP: input<sequence-unsafe
 133 { $values
 134     { "seq" sequence }
 135     { "quot" quotation }
 136 }
 137 { $description "An unsafe version of " { $link input<sequence-unsafe } "." } ;
 138
 139 HELP: map-reduce-outputs
 140 { $values
 141     { "quot" quotation } { "mapper" quotation } { "reducer" quotation }
 142 }
 143 { $description "Infers the number of outputs from " { $snippet "quot" } " and, treating those outputs as a sequence, calls " { $link map-reduce } " on them." }
 144 { $examples
 145     { $example
 146 "USING: math combinators.smart prettyprint ;
 147 [ 1 2 3 ] [ sq ] [ + ] map-reduce-outputs ."
 148 "14"
 149     }
 150 } ;
 151
 152 HELP: nullary
 153 { $values
 154     { "quot" quotation }
 155 }
 156 { $description "Infers the number of inputs to a quotation and drops them from the stack." }
 157 { $examples
 158     { $code
 159         "USING: combinators.smart kernel math ;
 160 1 2 [ + ] nullary"
 161     }
 162 } ;
 163
 164 HELP: preserving
 165 { $values
 166     { "quot" quotation }
 167 }
 168 { $description "Calls a quotation and leaves any consumed inputs on the stack beneath the quotation's outputs." }
 169 { $examples
 170     { $example
 171         "USING: combinators.smart kernel math prettyprint ;
 172 1 2 [ + ] preserving [ . ] tri@"
 173 "1
 174 2
 175 3"
 176     }
 177 } ;
 178
 179 HELP: smart-apply
 180 { $values
 181     { "quot" quotation } { "n" integer }
 182 }
 183 { $description "Applies a quotation to the datastack " { $snippet "n" } " times, starting lower on the stack and working up in increments of the number of inferred inputs to the quotation." }
 184 { $examples
 185     { $example
 186         "USING: combinators.smart prettyprint math kernel ;
 187 1 2 3 4 [ + ] 2 smart-apply [ . ] bi@"
 188 "3
 189 7"
 190     }
 191 } ;
 192
 193 HELP: smart-if
 194 { $values
 195     { "pred" quotation } { "true" quotation } { "false" quotation }
 196 }
 197 { $description "A version of " { $link if } " that takes three quotations, where the first quotation is a predicate that preserves any inputs it consumes." } ;
 198
 199 HELP: smart-if*
 200 { $values
 201     { "pred" quotation } { "true" quotation } { "false" quotation }
 202 }
 203 { $description "A version of " { $link if } " that takes three quotations, where the first quotation is a predicate that preserves any inputs it consumes, the second is the " { $snippet "true" } " branch, and the third is the " { $snippet "false" } " branch. If the " { $snippet "true" } " branch is taken, the values are left on the stack and the quotation is called. If the " { $snippet "false" } " branch is taken, the number of inputs inferred from predicate quotation is dropped and the quotation is called." } ;
 204
 205 HELP: smart-unless
 206 { $values
 207     { "pred" quotation } { "false" quotation }
 208 }
 209 { $description "A version of " { $link unless } " that takes two quotations, where the first quotation is a predicate that preserves any inputs it consumes and the second is the " { $snippet "false" } " branch." } ;
 210
 211 HELP: smart-unless*
 212 { $values
 213     { "pred" quotation } { "false" quotation }
 214 }
 215 { $description "A version of " { $link unless } " that takes two quotations, where the first quotation is a predicate that preserves any inputs it consumes and the second is the " { $snippet "false" } " branch. If the " { $snippet "true" } " branch is taken, the values are left on the stack. If the " { $snippet "false" } " branch is taken, the number of inputs inferred from predicate quotation is dropped and the quotation is called." } ;
 216
 217 HELP: smart-when
 218 { $values
 219     { "pred" quotation } { "true" quotation }
 220 }
 221 { $description "A version of " { $link when } " that takes two quotations, where the first quotation is a predicate that preserves any inputs it consumes and the second is the " { $snippet "true" } " branch." } ;
 222
 223 HELP: smart-when*
 224 { $values
 225     { "pred" quotation } { "true" quotation }
 226 }
 227 { $description "A version of " { $link when } " that takes two quotations, where the first quotation is a predicate that preserves any inputs it consumes and the second is the " { $snippet "true" } " branch. If the " { $snippet "true" } " branch is taken, the values are left on the stack and the quotation is called. If the " { $snippet "false" } " branch is taken, the number of inputs inferred from predicate quotation is dropped." } ;
 228
 229 HELP: smart-with
 230 { $values
 231     { "param" object } { "obj" object } { "quot" { $quotation "( param ..a -- ..b )" } } { "curry" curry } }
 232 { $description "A version of " { $link with } " that puts the parameter before any inputs the quotation uses." } ;
 233
 234 HELP: smart-reduce
 235 { $values { "reduce-quots" sequence } }
 236 { $description "A version of " { $link reduce } " that takes a sequence of " { $snippet "{ identity reduce-quot }" } " pairs, returning the " { $link reduce } " result for each pair." } ;
 237
 238 HELP: smart-map-reduce
 239 { $values { "map-reduce-quots" sequence } }
 240 { $description "A version of " { $link map-reduce } " that takes a sequence of " { $snippet "{ map-quot reduce-quot }" } " pairs, returning the " { $link map-reduce } " result for each pair." } ;
 241
 242 HELP: smart-2reduce
 243 { $values { "2reduce-quots" sequence } }
 244 { $description "A version of " { $link 2reduce } " that takes a sequence of " { $snippet "{ identity 2reduce-quot }" } " pairs, returning the " { $link 2reduce } " result for each pair." } ;
 245
 246 HELP: smart-2map-reduce
 247 { $values { "2map-reduce-quots" sequence } }
 248 { $description "A version of " { $link 2map-reduce } " that takes a sequence of " { $snippet "{ 2map-quot 2reduce-quot }" } " pairs, returning the " { $link 2map-reduce } " result for each pair." } ;
 249
 250 HELP: smart-loop
 251 { $values { "quot" { $quotation ( ..a -- ..b ? ) } } }
 252 { $description "A version of " { $link loop } " that runs until the " { $snippet "quot" } " returns " { $link f } " and leaves the result of the quotation on the stack." } ;
 253
 254 ARTICLE: "combinators.smart" "Smart combinators"
 255 "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
 256 "Take all input values from a sequence:"
 257 { $subsections
 258     input<sequence
 259     input<sequence-unsafe
 260 }
 261 "Store all output values to a sequence:"
 262 { $subsections
 263     output>sequence
 264     output>array
 265 }
 266 "Reducing the set of output values:"
 267 { $subsections
 268     reduce-outputs
 269     map-reduce-outputs
 270 }
 271 "Applying a quotation to groups of elements on the stack:"
 272 { $subsections smart-apply }
 273 "Summing output values:"
 274 { $subsections sum-outputs }
 275 "Concatenating output values:"
 276 { $subsections
 277     append-outputs
 278     append-outputs-as
 279 }
 280 "Drop the outputs after calling a quotation:"
 281 { $subsections drop-outputs }
 282 "Cause a quotation to act as a no-op and drop the inputs:"
 283 { $subsection nullary }
 284 "Preserve the inputs below or above the outputs of the quotation:"
 285 { $subsections preserving keep-inputs }
 286 "Versions of if that infer how many inputs to keep from the predicate quotation:"
 287 { $subsections smart-if smart-when smart-unless }
 288 "Versions of if* that infer how many inputs to keep from the predicate quotation:"
 289 { $subsections smart-if* smart-when* smart-unless* }
 290 "New smart combinators can be created by defining " { $link "macros" } " which call " { $link infer } "." ;
 291
 292 ABOUT: "combinators.smart"