src.elv.sh@v0.21.0-dev.0.20240515223629-06979efb9a2a/pkg/eval/builtin_fn_container.d.elv (about)

     1  # Constructs a namespace from `$map`, using the keys as variable names and the
     2  # values as their values. Examples:
     3  #
     4  # ```elvish-transcript
     5  # ~> var n = (ns [&name=value])
     6  # ~> put $n[name]
     7  # ▶ value
     8  # ~> var n: = (ns [&name=value])
     9  # ~> put $n:name
    10  # ▶ value
    11  # ```
    12  fn ns {|map| }
    13  
    14  # Outputs a map from the [value inputs](#value-inputs), each of which must be
    15  # an iterable value with with two elements. The first element of each value
    16  # is used as the key, and the second element is used as the value.
    17  #
    18  # If the same key appears multiple times, the last value is used.
    19  #
    20  # Examples:
    21  #
    22  # ```elvish-transcript
    23  # ~> make-map [[k v]]
    24  # ▶ [&k=v]
    25  # ~> make-map [[k v1] [k v2]]
    26  # ▶ [&k=v2]
    27  # ~> put [k1 v1] [k2 v2] | make-map
    28  # ▶ [&k1=v1 &k2=v2]
    29  # ~> put aA bB | make-map
    30  # ▶ [&a=A &b=B]
    31  # ```
    32  fn make-map {|input?| }
    33  
    34  # Outputs a list created from adding values in `$more` to the end of `$list`.
    35  #
    36  # The output is the same as `[$@list $more...]`, but the time complexity is
    37  # guaranteed to be O(m), where m is the number of values in `$more`.
    38  #
    39  # Examples:
    40  #
    41  # ```elvish-transcript
    42  # ~> conj [] a
    43  # ▶ [a]
    44  # ~> conj [a b] c d
    45  # ▶ [a b c d]
    46  # ```
    47  #
    48  # Etymology: [Clojure](https://clojuredocs.org/clojure.core/conj).
    49  fn conj {|list @more| }
    50  
    51  # Output a slightly modified version of `$container`, such that its value at `$k`
    52  # is `$v`. Applies to both lists and to maps.
    53  #
    54  # When `$container` is a list, `$k` may be a negative index. However, slice is not
    55  # yet supported.
    56  #
    57  # ```elvish-transcript
    58  # ~> assoc [foo bar quux] 0 lorem
    59  # ▶ [lorem bar quux]
    60  # ~> assoc [foo bar quux] -1 ipsum
    61  # ▶ [foo bar ipsum]
    62  # ~> assoc [&k=v] k v2
    63  # ▶ [&k=v2]
    64  # ~> assoc [&k=v] k2 v2
    65  # ▶ [&k=v &k2=v2]
    66  # ```
    67  #
    68  # Etymology: [Clojure](https://clojuredocs.org/clojure.core/assoc).
    69  #
    70  # See also [`dissoc`]().
    71  fn assoc {|container k v| }
    72  
    73  # Output a slightly modified version of `$map`, with the key `$k` removed. If
    74  # `$map` does not contain `$k` as a key, the same map is returned.
    75  #
    76  # ```elvish-transcript
    77  # ~> dissoc [&foo=bar &lorem=ipsum] foo
    78  # ▶ [&lorem=ipsum]
    79  # ~> dissoc [&foo=bar &lorem=ipsum] k
    80  # ▶ [&foo=bar &lorem=ipsum]
    81  # ```
    82  #
    83  # See also [`assoc`]().
    84  fn dissoc {|map k| }
    85  
    86  # Determine whether `$value` is a value in `$container`.
    87  #
    88  # Examples, maps:
    89  #
    90  # ```elvish-transcript
    91  # ~> has-value [&k1=v1 &k2=v2] v1
    92  # ▶ $true
    93  # ~> has-value [&k1=v1 &k2=v2] k1
    94  # ▶ $false
    95  # ```
    96  #
    97  # Examples, lists:
    98  #
    99  # ```elvish-transcript
   100  # ~> has-value [v1 v2] v1
   101  # ▶ $true
   102  # ~> has-value [v1 v2] k1
   103  # ▶ $false
   104  # ```
   105  #
   106  # Examples, strings:
   107  #
   108  # ```elvish-transcript
   109  # ~> has-value ab b
   110  # ▶ $true
   111  # ~> has-value ab c
   112  # ▶ $false
   113  # ```
   114  fn has-value {|container value| }
   115  
   116  # Determine whether `$key` is a key in `$container`. A key could be a map key or
   117  # an index on a list or string. This includes a range of indexes.
   118  #
   119  # Examples, maps:
   120  #
   121  # ```elvish-transcript
   122  # ~> has-key [&k1=v1 &k2=v2] k1
   123  # ▶ $true
   124  # ~> has-key [&k1=v1 &k2=v2] v1
   125  # ▶ $false
   126  # ```
   127  #
   128  # Examples, lists:
   129  #
   130  # ```elvish-transcript
   131  # ~> has-key [v1 v2] 0
   132  # ▶ $true
   133  # ~> has-key [v1 v2] 1
   134  # ▶ $true
   135  # ~> has-key [v1 v2] 2
   136  # ▶ $false
   137  # ~> has-key [v1 v2] 0..2
   138  # ▶ $true
   139  # ~> has-key [v1 v2] 0..3
   140  # ▶ $false
   141  # ```
   142  #
   143  # Examples, strings:
   144  #
   145  # ```elvish-transcript
   146  # ~> has-key ab 0
   147  # ▶ $true
   148  # ~> has-key ab 1
   149  # ▶ $true
   150  # ~> has-key ab 2
   151  # ▶ $false
   152  # ~> has-key ab 0..2
   153  # ▶ $true
   154  # ~> has-key ab 0..3
   155  # ▶ $false
   156  # ```
   157  fn has-key {|container key| }
   158  
   159  #//skip-test
   160  # Put all keys of `$map` on the structured stdout.
   161  #
   162  # Example:
   163  #
   164  # ```elvish-transcript
   165  # ~> keys [&a=foo &b=bar &c=baz]
   166  # ▶ a
   167  # ▶ c
   168  # ▶ b
   169  # ```
   170  #
   171  # Note that there is no guaranteed order for the keys of a map.
   172  fn keys {|map| }