src.elv.sh@v0.21.0-dev.0.20240515223629-06979efb9a2a/pkg/eval/builtin_fn_stream.d.elv (about) 1 # Takes [value inputs](#value-inputs), and outputs those values unchanged. 2 # 3 # This is an [identity 4 # function](https://en.wikipedia.org/wiki/Identity_function) for the value 5 # channel; in other words, `a | all` is equivalent to just `a` if `a` only has 6 # value output. 7 # 8 # This command can be used inside output capture (i.e. `(all)`) to turn value 9 # inputs into arguments. For example: 10 # 11 # ```elvish-transcript 12 # ~> echo '["foo","bar"] ["lorem","ipsum"]' | from-json 13 # ▶ [foo bar] 14 # ▶ [lorem ipsum] 15 # ~> echo '["foo","bar"] ["lorem","ipsum"]' | from-json | put (all)[0] 16 # ▶ foo 17 # ▶ lorem 18 # ``` 19 # 20 # The latter pipeline is equivalent to the following: 21 # 22 # ```elvish-transcript 23 # ~> put (echo '["foo","bar"] ["lorem","ipsum"]' | from-json)[0] 24 # ▶ foo 25 # ▶ lorem 26 # ``` 27 # 28 # In general, when `(all)` appears in the last command of a pipeline, it is 29 # equivalent to just moving the previous commands of the pipeline into `()`. 30 # The choice is a stylistic one; the `(all)` variant is longer overall, but can 31 # be more readable since it allows you to avoid putting an excessively long 32 # pipeline inside an output capture, and keeps the data flow within the 33 # pipeline. 34 # 35 # Putting the value capture inside `[]` (i.e. `[(all)]`) is useful for storing 36 # all value inputs in a list for further processing: 37 # 38 # ```elvish-transcript 39 # ~> fn f { var inputs = [(all)]; put $inputs[1] } 40 # ~> put foo bar baz | f 41 # ▶ bar 42 # ``` 43 # 44 # The `all` command can also take "inputs" from an iterable argument. This can 45 # be used to flatten lists or strings (although not recursively): 46 # 47 # ```elvish-transcript 48 # ~> all [foo [lorem ipsum]] 49 # ▶ foo 50 # ▶ [lorem ipsum] 51 # ~> all foo 52 # ▶ f 53 # ▶ o 54 # ▶ o 55 # ``` 56 # 57 # This can be used together with `(one)` to turn a single iterable value in the 58 # pipeline into its elements: 59 # 60 # ```elvish-transcript 61 # ~> echo '["foo","bar","lorem"]' | from-json 62 # ▶ [foo bar lorem] 63 # ~> echo '["foo","bar","lorem"]' | from-json | all (one) 64 # ▶ foo 65 # ▶ bar 66 # ▶ lorem 67 # ``` 68 # 69 # When given byte inputs, the `all` command currently functions like 70 # [`from-lines`](), although this behavior is subject to change: 71 # 72 # ```elvish-transcript 73 # ~> print "foo\nbar\n" | all 74 # ▶ foo 75 # ▶ bar 76 # ``` 77 # 78 # See also [`one`](). 79 fn all {|inputs?| } 80 81 # Takes exactly one [value input](#value-inputs) and outputs it. If there are 82 # more than one value inputs, raises an exception. 83 # 84 # This function can be used in a similar way to [`all`](), but is a better 85 # choice when you expect that there is exactly one output. 86 # 87 # See also [`all`](). 88 fn one {|inputs?| } 89 90 # Outputs the first `$n` [value inputs](#value-inputs). If `$n` is larger than 91 # the number of value inputs, outputs everything. 92 # 93 # Examples: 94 # 95 # ```elvish-transcript 96 # ~> range 2 | take 10 97 # ▶ (num 0) 98 # ▶ (num 1) 99 # ~> take 3 [a b c d e] 100 # ▶ a 101 # ▶ b 102 # ▶ c 103 # ~> use str 104 # ~> str:split ' ' 'how are you?' | take 1 105 # ▶ how 106 # ``` 107 # 108 # Etymology: Haskell. 109 # 110 # See also [`drop`](). 111 fn take {|n inputs?| } 112 113 # Ignores the first `$n` [value inputs](#value-inputs) and outputs the rest. 114 # If `$n` is larger than the number of value inputs, outputs nothing. 115 # 116 # Example: 117 # 118 # ```elvish-transcript 119 # ~> range 10 | drop 8 120 # ▶ (num 8) 121 # ▶ (num 9) 122 # ~> range 2 | drop 10 123 # ~> drop 2 [a b c d e] 124 # ▶ c 125 # ▶ d 126 # ▶ e 127 # ~> use str 128 # ~> str:split ' ' 'how are you?' | drop 1 129 # ▶ are 130 # ▶ 'you?' 131 # ``` 132 # 133 # Etymology: Haskell. 134 # 135 # See also [`take`](). 136 fn drop {|n inputs?| } 137 138 # Replaces consecutive runs of equal values with a single copy. Similar to the 139 # `uniq` command on Unix. 140 # 141 # Examples: 142 # 143 # ```elvish-transcript 144 # ~> put a a b b c | compact 145 # ▶ a 146 # ▶ b 147 # ▶ c 148 # ~> compact [a a b b c] 149 # ▶ a 150 # ▶ b 151 # ▶ c 152 # ~> put a b a | compact 153 # ▶ a 154 # ▶ b 155 # ▶ a 156 # ``` 157 fn compact {|inputs?| } 158 159 # Count the number of inputs. 160 # 161 # Examples: 162 # 163 # ```elvish-transcript 164 # ~> count lorem # count bytes in a string 165 # ▶ (num 5) 166 # ~> count [lorem ipsum] 167 # ▶ (num 2) 168 # ~> range 100 | count 169 # ▶ (num 100) 170 # ~> seq 100 | count 171 # ▶ (num 100) 172 # ``` 173 fn count {|input-list?| } 174 175 # Outputs the [value inputs](#value-inputs) after sorting. The sorting process 176 # is 177 # [stable](https://en.wikipedia.org/wiki/Sorting_algorithm#Stability). 178 # 179 # By default, `order` sorts the values in ascending order, using the same 180 # comparator as [`compare`](), which only supports values of the same ordered 181 # type. Its options modify this behavior: 182 # 183 # - The `&less-than` option, if given, overrides the comparator. Its 184 # value should be a function that takes two arguments `$a` and `$b` and 185 # outputs a boolean indicating whether `$a` is less than `$b`. If the 186 # function throws an exception, `order` rethrows the exception without 187 # outputting any value. 188 # 189 # The default behavior of `order` is equivalent to `order &less-than={|a b| 190 # == -1 (compare $a $b)}`. 191 # 192 # - The `&total` option, if true, overrides the comparator to be same as 193 # `compare &total=$true`, which allows sorting values of mixed types and 194 # unordered types. The result groups values by their types. Groups of 195 # ordered types are sorted internally, and groups of unordered types retain 196 # their original relative order. 197 # 198 # Specifying `&total=$true` is equivalent to specifying `&less-than={|a b| 199 # == -1 (compare &total=$true $a $b)}`. It is an error to both specify 200 # `&total=$true` and a non-nil `&less-than` callback. 201 # 202 # - The `&key` option, if given, is a function that gets called with each 203 # input value. It must output a single value, which is used for comparison 204 # in place of the original value. The comparator used can be affected by 205 # `$less-than` or `&total`. 206 # 207 # If the function throws an exception, `order` rethrows the exception. 208 # 209 # Use of `&key` can usually be rewritten to use `&less-than` instead, but 210 # using `&key` can be faster. The `&key` callback is only called once for 211 # each element, whereas the `&less-than` callback is called O(n*lg(n)) times 212 # on average. 213 # 214 # - The `&reverse` option, if true, reverses the order of output. 215 # 216 # Examples: 217 # 218 # ```elvish-transcript 219 # ~> put foo bar ipsum | order 220 # ▶ bar 221 # ▶ foo 222 # ▶ ipsum 223 # ~> order [(num 10) (num 1) (num 5)] 224 # ▶ (num 1) 225 # ▶ (num 5) 226 # ▶ (num 10) 227 # ~> order [[a b] [a] [b b] [a c]] 228 # ▶ [a] 229 # ▶ [a b] 230 # ▶ [a c] 231 # ▶ [b b] 232 # ~> order &reverse [a c b] 233 # ▶ c 234 # ▶ b 235 # ▶ a 236 # ~> put [0 x] [1 a] [2 b] | order &key={|l| put $l[1]} 237 # ▶ [1 a] 238 # ▶ [2 b] 239 # ▶ [0 x] 240 # ~> order &less-than={|a b| eq $a x } [l x o r x e x m] 241 # ▶ x 242 # ▶ x 243 # ▶ x 244 # ▶ l 245 # ▶ o 246 # ▶ r 247 # ▶ e 248 # ▶ m 249 # ``` 250 # 251 # Ordering heterogeneous values: 252 # 253 # ```elvish-transcript 254 # //skip-test 255 # ~> order [a (num 2) c (num 0) b (num 1)] 256 # Exception: bad value: inputs to "compare" or "order" must be comparable values, but is uncomparable values 257 # [tty]:1:1-37: order [a (num 2) c (num 0) b (num 1)] 258 # ~> order &total [a (num 2) c (num 0) b (num 1)] 259 # ▶ (num 0) 260 # ▶ (num 1) 261 # ▶ (num 2) 262 # ▶ a 263 # ▶ b 264 # ▶ c 265 # ``` 266 # 267 # Beware that strings that look like numbers are treated as strings, not 268 # numbers. To sort strings as numbers, use an explicit `&key` or `&less-than`: 269 # 270 # ```elvish-transcript 271 # ~> order [5 1 10] 272 # ▶ 1 273 # ▶ 10 274 # ▶ 5 275 # ~> order &key=$num~ [5 1 10] 276 # ▶ 1 277 # ▶ 5 278 # ▶ 10 279 # ~> order &less-than=$"<~" [5 1 10] 280 # ▶ 1 281 # ▶ 5 282 # ▶ 10 283 # ``` 284 # 285 # (The `$"<~"` syntax is a reference to [the `<` function](#num-lt).) 286 # 287 # See also [`compare`](). 288 fn order {|&less-than=$nil &total=$false &key=$nil &reverse=$false inputs?| }