basis/generalizations/generalizations-docs.factor

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