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?| }