basis/generalizations/generalizations-docs.factor

   1 USING: help.syntax help.markup kernel sequences quotations\r
   2 math arrays ;\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 \r
  22 { nsequence narray } related-words\r
  23 \r
  24 HELP: firstn\r
  25 { $values { "n" integer } }\r
  26 { $description "A generalization of " { $link first } ", "\r
  27 { $link first2 } ", " { $link first3 } " and " { $link first4 } " "\r
  28 "that pushes the first " { $snippet "n" } " elements of a sequence on the stack."\r
  29 } ;\r
  30 \r
  31 HELP: npick\r
  32 { $values { "n" integer } }\r
  33 { $description "A generalization of " { $link dup } ", "\r
  34 { $link over } " and " { $link pick } " that can work "\r
  35 "for any stack depth. The nth item down the stack will be copied and "\r
  36 "placed on the top of the stack."\r
  37 }\r
  38 { $examples\r
  39   { $example "USING: prettyprint generalizations ;" "1 2 3 4 4 npick .s" "1\n2\n3\n4\n1" }\r
  40 }\r
  41 { $see-also dup over pick } ;\r
  42 \r
  43 HELP: ndup\r
  44 { $values { "n" integer } }\r
  45 { $description "A generalization of " { $link dup } ", "\r
  46 { $link 2dup } " and " { $link 3dup } " that can work "\r
  47 "for any number of items. The n topmost items on the stack will be copied and "\r
  48 "placed on the top of the stack."\r
  49 }\r
  50 { $examples\r
  51   { $example "USING: prettyprint generalizations ;" "1 2 3 4 4 ndup .s" "1\n2\n3\n4\n1\n2\n3\n4" }\r
  52 }\r
  53 { $see-also dup 2dup 3dup } ;\r
  54 \r
  55 HELP: nnip\r
  56 { $values { "n" integer } }\r
  57 { $description "A generalization of " { $link nip } " and " { $link 2nip }\r
  58 " that can work "\r
  59 "for any number of items."\r
  60 }\r
  61 { $examples\r
  62   { $example "USING: prettyprint generalizations ;" "1 2 3 4 3 nnip .s" "4" }\r
  63 }\r
  64 { $see-also nip 2nip } ;\r
  65 \r
  66 HELP: ndrop\r
  67 { $values { "n" integer } }\r
  68 { $description "A generalization of " { $link drop }\r
  69 " that can work "\r
  70 "for any number of items."\r
  71 }\r
  72 { $examples\r
  73   { $example "USING: prettyprint generalizations ;" "1 2 3 4 3 ndrop .s" "1" }\r
  74 }\r
  75 { $see-also drop 2drop 3drop } ;\r
  76 \r
  77 HELP: nrot\r
  78 { $values { "n" integer } }\r
  79 { $description "A generalization of " { $link rot } " that works for any "\r
  80 "number of items on the stack. "\r
  81 }\r
  82 { $examples\r
  83   { $example "USING: prettyprint generalizations ;" "1 2 3 4 4 nrot .s" "2\n3\n4\n1" }\r
  84 }\r
  85 { $see-also rot -nrot } ;\r
  86 \r
  87 HELP: -nrot\r
  88 { $values { "n" integer } }\r
  89 { $description "A generalization of " { $link -rot } " that works for any "\r
  90 "number of items on the stack. "\r
  91 }\r
  92 { $examples\r
  93   { $example "USING: prettyprint generalizations ;" "1 2 3 4 4 -nrot .s" "4\n1\n2\n3" }\r
  94 }\r
  95 { $see-also rot nrot } ;\r
  96 \r
  97 HELP: nrev\r
  98 { $values { "n" integer } }\r
  99 { $description "A generalization of " { $link spin } " that reverses any number of items at the top of the stack."\r
 100 }\r
 101 { $examples\r
 102   { $example "USING: prettyprint generalizations ;" "1 2 3 4 4 nrev .s" "4\n3\n2\n1" }\r
 103 }\r
 104 { $see-also rot nrot } ;\r
 105 \r
 106 HELP: ndip\r
 107 { $values { "quot" quotation } { "n" number } }\r
 108 { $description "A generalization of " { $link dip } " that can work " \r
 109 "for any stack depth. The quotation will be called with a stack that "\r
 110 "has 'n' items removed first. The 'n' items are then put back on the "\r
 111 "stack. The quotation can consume and produce any number of items."\r
 112 } \r
 113 { $examples\r
 114   { $example "USING: generalizations kernel prettyprint ;" "1 2 [ dup ] 1 ndip .s" "1\n1\n2" }\r
 115   { $example "USING: generalizations kernel prettyprint ;" "1 2 3 [ drop ] 2 ndip .s" "2\n3" }\r
 116 }\r
 117 { $see-also dip 2dip } ;\r
 118 \r
 119 HELP: nslip\r
 120 { $values { "n" number } }\r
 121 { $description "A generalization of " { $link slip } " that can work " \r
 122 "for any stack depth. The first " { $snippet "n" } " items after the quotation will be "\r
 123 "removed from the stack, the quotation called, and the items restored."\r
 124 } \r
 125 { $examples\r
 126   { $example "USING: generalizations prettyprint ;" "[ 99 ] 1 2 3 4 5 5 nslip .s" "99\n1\n2\n3\n4\n5" }\r
 127 }\r
 128 { $see-also slip nkeep } ;\r
 129 \r
 130 HELP: nkeep\r
 131 { $values { "quot" quotation } { "n" number } }\r
 132 { $description "A generalization of " { $link keep } " that can work " \r
 133 "for any stack depth. The first " { $snippet "n" } " items after the quotation will be "\r
 134 "saved, the quotation called, and the items restored."\r
 135 } \r
 136 { $examples\r
 137   { $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
 138 }\r
 139 { $see-also keep nslip } ;\r
 140 \r
 141 ARTICLE: "generalizations" "Generalized shuffle words and combinators"\r
 142 "The " { $vocab-link "generalizations" } " vocabulary defines a number of stack shuffling words and combinators for use in "\r
 143 "macros where the arity of the input quotations depends on an "\r
 144 "input parameter."\r
 145 $nl\r
 146 "Generalized sequence operations:"\r
 147 { $subsection narray }\r
 148 { $subsection nsequence }\r
 149 { $subsection firstn }\r
 150 "Generated stack shuffle operations:"\r
 151 { $subsection ndup }\r
 152 { $subsection npick }\r
 153 { $subsection nrot }\r
 154 { $subsection -nrot }\r
 155 { $subsection nnip }\r
 156 { $subsection ndrop }\r
 157 { $subsection nrev }\r
 158 "Generalized combinators:"\r
 159 { $subsection ndip }\r
 160 { $subsection nslip }\r
 161 { $subsection nkeep }\r
 162 { $subsection ncurry } \r
 163 { $subsection nwith } \r
 164 { $subsection napply } ;\r
 165 \r
 166 ABOUT: "generalizations"\r