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: firstn\r
  34 { $values { "n" integer } }\r
  35 { $description "A generalization of " { $link first } ", "\r
  36 { $link first2 } ", " { $link first3 } " and " { $link first4 } " "\r
  37 "that pushes the first " { $snippet "n" } " elements of a sequence on the stack."\r
  38 }\r
  39 { $examples\r
  40     "Some core words expressed in terms of " { $link firstn } ":"\r
  41     { $table\r
  42         { { $link first } { $snippet "1 firstn" } }\r
  43         { { $link first2 } { $snippet "2 firstn" } }\r
  44         { { $link first3 } { $snippet "3 firstn" } }\r
  45         { { $link first4 } { $snippet "4 firstn" } }\r
  46     }\r
  47 } ;\r
  48 \r
  49 HELP: npick\r
  50 { $values { "n" integer } }\r
  51 { $description "A generalization of " { $link dup } ", "\r
  52 { $link over } " and " { $link pick } " that can work "\r
  53 "for any stack depth. The nth item down the stack will be copied and "\r
  54 "placed on the top of the stack."\r
  55 }\r
  56 { $examples\r
  57   { $example "USING: prettyprint generalizations ;" "1 2 3 4 4 npick .s" "1\n2\n3\n4\n1" }\r
  58   "Some core words expressed in terms of " { $link npick } ":"\r
  59     { $table\r
  60         { { $link dup } { $snippet "1 npick" } }\r
  61         { { $link over } { $snippet "2 npick" } }\r
  62         { { $link pick } { $snippet "3 npick" } }\r
  63     }\r
  64 } ;\r
  65 \r
  66 HELP: ndup\r
  67 { $values { "n" integer } }\r
  68 { $description "A generalization of " { $link dup } ", "\r
  69 { $link 2dup } " and " { $link 3dup } " that can work "\r
  70 "for any number of items. The n topmost items on the stack will be copied and "\r
  71 "placed on the top of the stack."\r
  72 }\r
  73 { $examples\r
  74   { $example "USING: prettyprint generalizations ;" "1 2 3 4 4 ndup .s" "1\n2\n3\n4\n1\n2\n3\n4" }\r
  75   "Some core words expressed in terms of " { $link ndup } ":"\r
  76     { $table\r
  77         { { $link dup } { $snippet "1 ndup" } }\r
  78         { { $link 2dup } { $snippet "2 ndup" } }\r
  79         { { $link 3dup } { $snippet "3 ndup" } }\r
  80     }\r
  81 } ;\r
  82 \r
  83 HELP: nnip\r
  84 { $values { "n" integer } }\r
  85 { $description "A generalization of " { $link nip } " and " { $link 2nip }\r
  86 " that can work "\r
  87 "for any number of items."\r
  88 }\r
  89 { $examples\r
  90   { $example "USING: prettyprint generalizations ;" "1 2 3 4 3 nnip .s" "4" }\r
  91   "Some core words expressed in terms of " { $link nnip } ":"\r
  92     { $table\r
  93         { { $link nip } { $snippet "1 nnip" } }\r
  94         { { $link 2nip } { $snippet "2 nnip" } }\r
  95     }\r
  96 } ;\r
  97 \r
  98 HELP: ndrop\r
  99 { $values { "n" integer } }\r
 100 { $description "A generalization of " { $link drop }\r
 101 " that can work "\r
 102 "for any number of items."\r
 103 }\r
 104 { $examples\r
 105   { $example "USING: prettyprint generalizations ;" "1 2 3 4 3 ndrop .s" "1" }\r
 106   "Some core words expressed in terms of " { $link ndrop } ":"\r
 107     { $table\r
 108         { { $link drop } { $snippet "1 ndrop" } }\r
 109         { { $link 2drop } { $snippet "2 ndrop" } }\r
 110         { { $link 3drop } { $snippet "3 ndrop" } }\r
 111     }\r
 112 } ;\r
 113 \r
 114 HELP: nrot\r
 115 { $values { "n" integer } }\r
 116 { $description "A generalization of " { $link rot } " that works for any "\r
 117 "number of items on the stack. "\r
 118 }\r
 119 { $examples\r
 120   { $example "USING: prettyprint generalizations ;" "1 2 3 4 4 nrot .s" "2\n3\n4\n1" }\r
 121   "Some core words expressed in terms of " { $link nrot } ":"\r
 122     { $table\r
 123         { { $link swap } { $snippet "1 nrot" } }\r
 124         { { $link rot } { $snippet "2 nrot" } }\r
 125     }\r
 126 } ;\r
 127 \r
 128 HELP: -nrot\r
 129 { $values { "n" integer } }\r
 130 { $description "A generalization of " { $link -rot } " that works for any "\r
 131 "number of items on the stack. "\r
 132 }\r
 133 { $examples\r
 134   { $example "USING: prettyprint generalizations ;" "1 2 3 4 4 -nrot .s" "4\n1\n2\n3" }\r
 135   "Some core words expressed in terms of " { $link -nrot } ":"\r
 136     { $table\r
 137         { { $link swap } { $snippet "1 -nrot" } }\r
 138         { { $link -rot } { $snippet "2 -nrot" } }\r
 139     }\r
 140 } ;\r
 141 \r
 142 HELP: nrev\r
 143 { $values { "n" integer } }\r
 144 { $description "A generalization of " { $link spin } " that reverses any number of items at the top of the stack."\r
 145 }\r
 146 { $examples\r
 147   { $example "USING: prettyprint generalizations ;" "1 2 3 4 4 nrev .s" "4\n3\n2\n1" }\r
 148   "The " { $link spin } " word is equivalent to " { $snippet "3 nrev" } "."\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: generalizations kernel prettyprint ;" "1 2 [ dup ] 1 ndip .s" "1\n1\n2" }\r
 160   { $example "USING: generalizations kernel prettyprint ;" "1 2 3 [ drop ] 2 ndip .s" "2\n3" }\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: nslip\r
 170 { $values { "n" integer } }\r
 171 { $description "A generalization of " { $link slip } " that can work " \r
 172 "for any stack depth. The first " { $snippet "n" } " items after the quotation will be "\r
 173 "removed from the stack, the quotation called, and the items restored."\r
 174 } \r
 175 { $examples\r
 176   { $example "USING: generalizations prettyprint ;" "[ 99 ] 1 2 3 4 5 5 nslip .s" "99\n1\n2\n3\n4\n5" }\r
 177   "Some core words expressed in terms of " { $link nslip } ":"\r
 178     { $table\r
 179         { { $link slip } { $snippet "1 nslip" } }\r
 180         { { $link 2slip } { $snippet "2 nslip" } }\r
 181         { { $link 3slip } { $snippet "3 nslip" } }\r
 182     }\r
 183 } ;\r
 184 \r
 185 HELP: nkeep\r
 186 { $values { "quot" quotation } { "n" integer } }\r
 187 { $description "A generalization of " { $link keep } " that can work " \r
 188 "for any stack depth. The first " { $snippet "n" } " items after the quotation will be "\r
 189 "saved, the quotation called, and the items restored."\r
 190 } \r
 191 { $examples\r
 192   { $example "USING: generalizations kernel prettyprint ;" "1 2 3 4 5 [ drop drop drop drop drop 99 ] 5 nkeep .s" "99\n1\n2\n3\n4\n5" }\r
 193   "Some core words expressed in terms of " { $link nkeep } ":"\r
 194     { $table\r
 195         { { $link keep } { $snippet "1 nkeep" } }\r
 196         { { $link 2keep } { $snippet "2 nkeep" } }\r
 197         { { $link 3keep } { $snippet "3 nkeep" } }\r
 198     }\r
 199 } ;\r
 200 \r
 201 HELP: ncurry\r
 202 { $values { "quot" quotation } { "n" integer } }\r
 203 { $description "A generalization of " { $link curry } " that can work for any stack depth."\r
 204 } \r
 205 { $examples\r
 206   "Some core words expressed in terms of " { $link ncurry } ":"\r
 207     { $table\r
 208         { { $link curry } { $snippet "1 ncurry" } }\r
 209         { { $link 2curry } { $snippet "2 ncurry" } }\r
 210         { { $link 3curry } { $snippet "3 ncurry" } }\r
 211     }\r
 212 } ;\r
 213 \r
 214 HELP: nwith\r
 215 { $values { "quot" quotation } { "n" integer } }\r
 216 { $description "A generalization of " { $link with } " that can work for any stack depth."\r
 217 } \r
 218 { $examples\r
 219   "Some core words expressed in terms of " { $link nwith } ":"\r
 220     { $table\r
 221         { { $link with } { $snippet "1 nwith" } }\r
 222     }\r
 223 } ;\r
 224 \r
 225 HELP: napply\r
 226 { $values { "quot" quotation } { "n" integer } }\r
 227 { $description "A generalization of " { $link bi@ } " and " { $link tri@ } " that can work for any stack depth."\r
 228 } \r
 229 { $examples\r
 230   "Some core words expressed in terms of " { $link napply } ":"\r
 231     { $table\r
 232         { { $link call } { $snippet "1 napply" } }\r
 233         { { $link bi@ } { $snippet "2 napply" } }\r
 234         { { $link tri@ } { $snippet "3 napply" } }\r
 235     }\r
 236 } ;\r
 237 \r
 238 HELP: ncleave\r
 239 { $values { "quots" "a sequence of quotations" } { "n" integer } }\r
 240 { $description "A generalization of " { $link cleave } " and " { $link 2cleave } " that can work for any quotation arity."\r
 241 } \r
 242 { $examples\r
 243   "Some core words expressed in terms of " { $link ncleave } ":"\r
 244     { $table\r
 245         { { $link cleave } { $snippet "1 ncleave" } }\r
 246         { { $link 2cleave } { $snippet "2 ncleave" } }\r
 247     }\r
 248 } ;\r
 249 \r
 250 HELP: mnswap\r
 251 { $values { "m" integer } { "n" integer } }\r
 252 { $description "Swaps the top " { $snippet "m" } " stack elements with the " { $snippet "n" } " elements directly underneath." }\r
 253 { $examples\r
 254   "Some core words expressed in terms of " { $link mnswap } ":"\r
 255     { $table\r
 256         { { $link swap } { $snippet "1 1 mnswap" } }\r
 257         { { $link rot } { $snippet "2 1 mnswap" } }\r
 258         { { $link -rot } { $snippet "1 2 mnswap" } }\r
 259     }\r
 260 } ;\r
 261 \r
 262 HELP: n*quot\r
 263 { $values\r
 264      { "n" integer } { "seq" sequence }\r
 265      { "seq'" sequence }\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 ARTICLE: "generalizations" "Generalized shuffle words and combinators"\r
 312 "The " { $vocab-link "generalizations" } " vocabulary defines a number of stack shuffling words and combinators for use in "\r
 313 "macros where the arity of the input quotations depends on an "\r
 314 "input parameter."\r
 315 $nl\r
 316 "Generalized sequence operations:"\r
 317 { $subsection narray }\r
 318 { $subsection nsequence }\r
 319 { $subsection firstn }\r
 320 { $subsection nappend }\r
 321 { $subsection nappend-as }\r
 322 "Generated stack shuffle operations:"\r
 323 { $subsection ndup }\r
 324 { $subsection npick }\r
 325 { $subsection nrot }\r
 326 { $subsection -nrot }\r
 327 { $subsection nnip }\r
 328 { $subsection ndrop }\r
 329 { $subsection ntuck }\r
 330 { $subsection nrev }\r
 331 { $subsection mnswap }\r
 332 "Generalized combinators:"\r
 333 { $subsection ndip }\r
 334 { $subsection nslip }\r
 335 { $subsection nkeep }\r
 336 { $subsection napply }\r
 337 { $subsection ncleave }\r
 338 "Generalized quotation construction:"\r
 339 { $subsection ncurry } \r
 340 { $subsection nwith } ;\r
 341 \r
 342 ABOUT: "generalizations"\r