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