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