basis/generalizations/generalizations-docs.factor

   1 USING: help.syntax help.markup kernel sequences quotations
   2 math arrays combinators ;
   3 IN: generalizations
   4
   5 HELP: nsum
   6 { $values { "n" integer } }
   7 { $description "Adds the top " { $snippet "n" } " stack values." } ;
   8
   9 HELP: npick
  10 { $values { "n" integer } }
  11 { $description "A generalization of " { $link dup } ", "
  12 { $link over } " and " { $link pick } " that can work "
  13 "for any stack depth. The nth item down the stack will be copied and "
  14 "placed on the top of the stack."
  15 }
  16 { $examples
  17   { $example
  18       "USING: kernel generalizations prettyprint"
  19       "sequences.generalizations ;"
  20       ""
  21       "1 2 3 4 4 npick 5 narray ."
  22       "{ 1 2 3 4 1 }"
  23   }
  24   "Some core words expressed in terms of " { $link npick } ":"
  25     { $table
  26         { { $link dup } { $snippet "1 npick" } }
  27         { { $link over } { $snippet "2 npick" } }
  28         { { $link pick } { $snippet "3 npick" } }
  29     }
  30 } ;
  31
  32 HELP: ndup
  33 { $values { "n" integer } }
  34 { $description "A generalization of " { $link dup } ", "
  35 { $link 2dup } " and " { $link 3dup } " that can work "
  36 "for any number of items. The n topmost items on the stack will be copied and "
  37 "placed on the top of the stack."
  38 }
  39 { $examples
  40   { $example
  41       "USING: prettyprint generalizations kernel"
  42       "sequences.generalizations ;"
  43       ""
  44       "1 2 3 4 4 ndup 8 narray ."
  45       "{ 1 2 3 4 1 2 3 4 }"
  46   }
  47   "Some core words expressed in terms of " { $link ndup } ":"
  48     { $table
  49         { { $link dup } { $snippet "1 ndup" } }
  50         { { $link 2dup } { $snippet "2 ndup" } }
  51         { { $link 3dup } { $snippet "3 ndup" } }
  52     }
  53 } ;
  54
  55 HELP: dupn
  56 { $values { "n" integer } }
  57 { $description "Calls " { $link dup } " enough times that " { $snippet "n" } " references to the element at the top of the stack before " { $snippet "dupn" } " is called are on the top of the stack." }
  58 { $notes { $snippet "2 dupn" } " is equivalent to " { $link dup } ". " { $snippet "1 dupn" } " is a no-op. " { $snippet "0 dupn" } " is equivalent to " { $link drop } "." } ;
  59
  60 HELP: nnip
  61 { $values { "n" integer } }
  62 { $description "A generalization of " { $link nip } " and " { $link 2nip }
  63 " that can work "
  64 "for any number of items."
  65 }
  66 { $examples
  67   { $example "USING: prettyprint generalizations kernel ;" "1 2 3 4 3 nnip ." "4" }
  68   "Some core words expressed in terms of " { $link nnip } ":"
  69     { $table
  70         { { $link nip } { $snippet "1 nnip" } }
  71         { { $link 2nip } { $snippet "2 nnip" } }
  72     }
  73 } ;
  74
  75 HELP: ndrop
  76 { $values { "n" integer } }
  77 { $description "A generalization of " { $link drop }
  78 " that can work "
  79 "for any number of items."
  80 }
  81 { $examples
  82   { $example "USING: prettyprint generalizations kernel ;" "1 2 3 4 3 ndrop ." "1" }
  83   "Some core words expressed in terms of " { $link ndrop } ":"
  84     { $table
  85         { { $link drop } { $snippet "1 ndrop" } }
  86         { { $link 2drop } { $snippet "2 ndrop" } }
  87         { { $link 3drop } { $snippet "3 ndrop" } }
  88     }
  89 } ;
  90
  91 HELP: nrot
  92 { $values { "n" integer } }
  93 { $description "A generalization of " { $link rot } " that works for any "
  94 "number of items on the stack. "
  95 }
  96 { $examples
  97   { $example "USING: arrays generalizations kernel prettyprint ;" "1 2 3 4 4 nrot 4array ." "{ 2 3 4 1 }" }
  98   "Some core words expressed in terms of " { $link nrot } ":"
  99     { $table
 100         { { $link swap } { $snippet "2 nrot" } }
 101         { { $link rot } { $snippet "3 nrot" } }
 102     }
 103 } ;
 104
 105 HELP: -nrot
 106 { $values { "n" integer } }
 107 { $description "A generalization of " { $link -rot } " that works for any "
 108 "number of items on the stack. "
 109 }
 110 { $examples
 111   { $example "USING: arrays generalizations kernel prettyprint ;" "1 2 3 4 4 -nrot 4array ." "{ 4 1 2 3 }" }
 112   "Some core words expressed in terms of " { $link -nrot } ":"
 113     { $table
 114         { { $link swap } { $snippet "2 -nrot" } }
 115         { { $link -rot } { $snippet "3 -nrot" } }
 116     }
 117 } ;
 118
 119 HELP: ndip
 120 { $values { "n" integer } }
 121 { $description "A generalization of " { $link dip } " that can work "
 122 "for any stack depth. The quotation will be called with a stack that "
 123 "has 'n' items removed first. The 'n' items are then put back on the "
 124 "stack. The quotation can consume and produce any number of items."
 125 }
 126 { $examples
 127   { $example "USING: arrays generalizations kernel prettyprint ;" "1 2 [ dup ] 1 ndip 3array ." "{ 1 1 2 }" }
 128   { $example "USING: arrays generalizations kernel prettyprint ;" "1 2 3 [ drop ] 2 ndip 2array ." "{ 2 3 }" }
 129   "Some core words expressed in terms of " { $link ndip } ":"
 130     { $table
 131         { { $link dip } { $snippet "1 ndip" } }
 132         { { $link 2dip } { $snippet "2 ndip" } }
 133         { { $link 3dip } { $snippet "3 ndip" } }
 134     }
 135 } ;
 136
 137 HELP: nkeep
 138 { $values { "n" integer } }
 139 { $description "A generalization of " { $link keep } " that can work "
 140 "for any stack depth. The first " { $snippet "n" } " items after the quotation will be "
 141 "saved, the quotation called, and the items restored."
 142 }
 143 { $examples
 144   { $example
 145       "USING: generalizations kernel prettyprint"
 146       "sequences.generalizations ;"
 147       ""
 148       "1 2 3 4 5 [ drop drop drop drop drop 99 ] 5 nkeep 6 narray ."
 149       "{ 99 1 2 3 4 5 }"
 150   }
 151   "Some core words expressed in terms of " { $link nkeep } ":"
 152     { $table
 153         { { $link keep } { $snippet "1 nkeep" } }
 154         { { $link 2keep } { $snippet "2 nkeep" } }
 155         { { $link 3keep } { $snippet "3 nkeep" } }
 156     }
 157 } ;
 158
 159 HELP: ncurry
 160 { $values { "n" integer } }
 161 { $description "A generalization of " { $link curry } " that can work for any stack depth."
 162 }
 163 { $examples
 164   "Some core words expressed in terms of " { $link ncurry } ":"
 165     { $table
 166         { { $link curry } { $snippet "1 ncurry" } }
 167         { { $link 2curry } { $snippet "2 ncurry" } }
 168         { { $link 3curry } { $snippet "3 ncurry" } }
 169     }
 170 } ;
 171
 172 HELP: nwith
 173 { $values { "n" integer } }
 174 { $description "A generalization of " { $link with } " that can work for any stack depth."
 175 }
 176 { $examples
 177   "Some core words expressed in terms of " { $link nwith } ":"
 178     { $table
 179         { { $link with } { $snippet "1 nwith" } }
 180     }
 181 } ;
 182
 183 HELP: napply
 184 { $values { "quot" quotation } { "n" integer } }
 185 { $description "A generalization of " { $link bi@ } " and " { $link tri@ } " that can work for any stack depth."
 186 }
 187 { $examples
 188   "Some core words expressed in terms of " { $link napply } ":"
 189     { $table
 190         { { $link call } { $snippet "1 napply" } }
 191         { { $link bi@ } { $snippet "2 napply" } }
 192         { { $link tri@ } { $snippet "3 napply" } }
 193     }
 194 } ;
 195
 196 HELP: ncleave
 197 { $values { "quots" "a sequence of quotations" } { "n" integer } }
 198 { $description "A generalization of " { $link cleave } " and " { $link 2cleave } " that can work for any quotation arity."
 199 }
 200 { $examples
 201   "Some core words expressed in terms of " { $link ncleave } ":"
 202     { $table
 203         { { $link cleave } { $snippet "1 ncleave" } }
 204         { { $link 2cleave } { $snippet "2 ncleave" } }
 205     }
 206 } ;
 207
 208 HELP: nspread
 209 { $values { "quots" "a sequence of quotations" } { "n" integer } }
 210 { $description "A generalization of " { $link spread } " that can work for any quotation arity."
 211 } ;
 212
 213 HELP: cleave*
 214 { $values { "n" integer } }
 215 { $description "Like " { $link cleave } ", but instead of taking a single array of quotations, cleaves using quotations taken from the top " { $snippet "n" } " elements of the datastack." }
 216 { $notes "This word can be used with " { $link apply-curry } " to generalize the " { $snippet "bi-curry@ bi" } " or " { $snippet "tri-curry@ tri" } " dataflow patterns." } ;
 217
 218 HELP: spread*
 219 { $values { "n" integer } }
 220 { $description "Like " { $link spread } ", but instead of taking a single array of quotations, spreads using quotations taken from the top " { $snippet "n" } " elements of the datastack." }
 221 { $notes "This word can be used with " { $link apply-curry } " to generalize the " { $snippet "bi-curry@ bi*" } " or " { $snippet "tri-curry@ tri*" } " dataflow patterns." } ;
 222
 223 HELP: apply-curry
 224 { $values { "a..." { $snippet "n" } " values on the datastack" } { "quot" quotation } { "n" integer } }
 225 { $description "Curries each of the top " { $snippet "n" } " items of the datastack onto " { $snippet "quot" } ", leaving " { $snippet "n" } " quotations on the datastack. A generalization of " { $link bi-curry@ } " and " { $link tri-curry@ } "." }
 226 { $notes "This word can be used with " { $link cleave* } " and " { $link spread* } " to generalize dataflow patterns such as " { $snippet "bi-curry@ bi" } ", " { $snippet "tri-curry@ tri" } ", " { $snippet "bi-curry@ bi*" } ", and " { $snippet "tri-curry@ tri*" } "." } ;
 227
 228 HELP: cleave-curry
 229 { $values { "a" object } { "quot..." { $snippet "n" } " quotations on the datastack" } { "n" integer } }
 230 { $description "Curries " { $snippet "a" } " onto the " { $snippet "n" } " quotations on the top of the datastack. A generalization of " { $link bi-curry } " and " { $link tri-curry } "." }
 231 { $notes "This word can be used with " { $link cleave* } " and " { $link spread* } " to generalize dataflow patterns such as " { $snippet "bi-curry bi" } ", " { $snippet "tri-curry tri" } ", " { $snippet "bi-curry bi*" } ", and " { $snippet "tri-curry tri*" } "." } ;
 232
 233 HELP: spread-curry
 234 { $values { "a..." { $snippet "n" } " objects on the datastack" } { "quot..." { $snippet "n" } " quotations on the datastack" } { "n" integer } }
 235 { $description "Curries the " { $snippet "n" } " quotations on the top of the datastack with the " { $snippet "n" } " values just below them. A generalization of " { $link bi-curry* } " and " { $link tri-curry* } "." }
 236 { $notes "This word can be used with " { $link cleave* } " and " { $link spread* } " to generalize dataflow patterns such as " { $snippet "bi-curry* bi" } ", " { $snippet "tri-curry* tri" } ", " { $snippet "bi-curry* bi*" } ", and " { $snippet "tri-curry* tri*" } "." } ;
 237
 238 HELP: mnswap
 239 { $values { "m" integer } { "n" integer } }
 240 { $description "Swaps the top " { $snippet "m" } " stack elements with the " { $snippet "n" } " elements directly underneath." }
 241 { $examples
 242   "Some core words expressed in terms of " { $link mnswap } ":"
 243     { $table
 244         { { $link swap } { $snippet "1 1 mnswap" } }
 245         { { $link rot } { $snippet "2 1 mnswap" } }
 246         { { $link -rot } { $snippet "1 2 mnswap" } }
 247     }
 248 } ;
 249
 250 HELP: nweave
 251 { $values { "n" integer } }
 252 { $description "Copies the top " { $snippet "n" } " stack elements underneath each one of the " { $snippet "n" } " elements below." }
 253 { $examples
 254   { $example
 255     "USING: arrays kernel generalizations prettyprint ;"
 256     "\"e1\" \"e2\" \"o1\" \"o2\" 2 nweave [ 3array ] 3dip 3array 2array ."
 257     "{ { \"e1\" \"o1\" \"o2\" } { \"e2\" \"o1\" \"o2\" } }"
 258   }
 259 } ;
 260
 261 HELP: n*quot
 262 { $values
 263      { "n" integer } { "quot" quotation }
 264      { "quotquot" quotation }
 265 }
 266 { $examples
 267     { $example "USING: generalizations prettyprint math ;"
 268                "3 [ + ] n*quot ."
 269                "[ + + + ]"
 270     }
 271 }
 272 { $description "Construct a quotation containing the contents of " { $snippet "seq" } " repeated " { $snippet "n"} " times." } ;
 273
 274 ARTICLE: "shuffle-generalizations" "Generalized shuffle words"
 275 { $subsections
 276     ndup
 277     dupn
 278     npick
 279     nrot
 280     -nrot
 281     nnip
 282     ndrop
 283     mnswap
 284     nweave
 285 } ;
 286
 287 ARTICLE: "combinator-generalizations" "Generalized combinators"
 288 { $subsections
 289     ndip
 290     nkeep
 291     napply
 292     ncleave
 293     nspread
 294     cleave*
 295     spread*
 296     apply-curry
 297     cleave-curry
 298     spread-curry
 299 } ;
 300
 301 ARTICLE: "other-generalizations" "Additional generalizations"
 302 { $subsections
 303     ncurry
 304     nwith
 305     nsum
 306 } ;
 307
 308 ARTICLE: "generalizations" "Generalized shuffle words and combinators"
 309 "The " { $vocab-link "generalizations" } " vocabulary defines a number of stack shuffling words and combinators for use in "
 310 "macros where the arity of the input quotations depends on an "
 311 "input parameter."
 312 { $subsections
 313     "shuffle-generalizations"
 314     "combinator-generalizations"
 315     "other-generalizations"
 316 }
 317 "Also see the " { $vocab-link "sequences.generalizations" } " vocabulary for generalized sequence operations." ;
 318
 319 ABOUT: "generalizations"