rbs 1.7.0.beta.5 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/core/env.rbs ADDED
@@ -0,0 +1,881 @@
1
+ # ENV is a hash-like accessor for environment variables.
2
+ #
3
+ # ### Interaction with the Operating System
4
+ #
5
+ # The ENV object interacts with the operating system's environment variables:
6
+ #
7
+ # * When you get the value for a name in ENV, the value is retrieved from
8
+ # among the current environment variables.
9
+ # * When you create or set a name-value pair in ENV, the name and value are
10
+ # immediately set in the environment variables.
11
+ # * When you delete a name-value pair in ENV, it is immediately deleted from
12
+ # the environment variables.
13
+ #
14
+ #
15
+ # ### Names and Values
16
+ #
17
+ # Generally, a name or value is a String.
18
+ #
19
+ # #### Valid Names and Values
20
+ #
21
+ # Each name or value must be one of the following:
22
+ #
23
+ # * A String.
24
+ # * An object that responds to #to_str by returning a String, in which case
25
+ # that String will be used as the name or value.
26
+ #
27
+ #
28
+ # #### Invalid Names and Values
29
+ #
30
+ # A new name:
31
+ #
32
+ # * May not be the empty string:
33
+ # ENV[''] = '0'
34
+ # # Raises Errno::EINVAL (Invalid argument - ruby_setenv())
35
+ #
36
+ # * May not contain character `"="`:
37
+ # ENV['='] = '0'
38
+ # # Raises Errno::EINVAL (Invalid argument - ruby_setenv(=))
39
+ #
40
+ #
41
+ # A new name or value:
42
+ #
43
+ # * May not be a non-String that does not respond to #to_str:
44
+ #
45
+ # ENV['foo'] = Object.new
46
+ # # Raises TypeError (no implicit conversion of Object into String)
47
+ # ENV[Object.new] = '0'
48
+ # # Raises TypeError (no implicit conversion of Object into String)
49
+ #
50
+ # * May not contain the NUL character `"\0"`:
51
+ #
52
+ # ENV['foo'] = "\0"
53
+ # # Raises ArgumentError (bad environment variable value: contains null byte)
54
+ # ENV["\0"] == '0'
55
+ # # Raises ArgumentError (bad environment variable name: contains null byte)
56
+ #
57
+ # * May not have an ASCII-incompatible encoding such as UTF-16LE or
58
+ # ISO-2022-JP:
59
+ #
60
+ # ENV['foo'] = '0'.force_encoding(Encoding::ISO_2022_JP)
61
+ # # Raises ArgumentError (bad environment variable name: ASCII incompatible encoding: ISO-2022-JP)
62
+ # ENV["foo".force_encoding(Encoding::ISO_2022_JP)] = '0'
63
+ # # Raises ArgumentError (bad environment variable name: ASCII incompatible encoding: ISO-2022-JP)
64
+ #
65
+ #
66
+ # ### About Ordering
67
+ #
68
+ # ENV enumerates its name/value pairs in the order found in the operating
69
+ # system's environment variables. Therefore the ordering of ENV content is
70
+ # OS-dependent, and may be indeterminate.
71
+ #
72
+ # This will be seen in:
73
+ # * A Hash returned by an ENV method.
74
+ # * An Enumerator returned by an ENV method.
75
+ # * An Array returned by ENV.keys, ENV.values, or ENV.to_a.
76
+ # * The String returned by ENV.inspect.
77
+ # * The Array returned by ENV.shift.
78
+ # * The name returned by ENV.key.
79
+ #
80
+ #
81
+ # ### About the Examples
82
+ # Some methods in ENV return ENV itself. Typically, there are many environment
83
+ # variables. It's not useful to display a large ENV in the examples here, so
84
+ # most example snippets begin by resetting the contents of ENV:
85
+ # * ENV.replace replaces ENV with a new collection of entries.
86
+ # * ENV.clear empties ENV.
87
+ #
88
+ class ENVClass
89
+ include Enumerable[[ String, String ]]
90
+
91
+ # Returns the value for the environment variable `name` if it exists:
92
+ # ENV['foo'] = '0'
93
+ # ENV['foo'] # => "0"
94
+ #
95
+ # Returns `nil` if the named variable does not exist.
96
+ #
97
+ # Raises an exception if `name` is invalid. See [Invalid Names and
98
+ # Values](#class-ENV-label-Invalid+Names+and+Values).
99
+ #
100
+ def []: (String name) -> String?
101
+
102
+ # If `name` is the name of an environment variable, returns its value:
103
+ # ENV['foo'] = '0'
104
+ # ENV.fetch('foo') # => '0'
105
+ #
106
+ # Otherwise if a block is given (but not a default value), yields `name` to the
107
+ # block and returns the block's return value:
108
+ # ENV.fetch('foo') { |name| :need_not_return_a_string } # => :need_not_return_a_string
109
+ #
110
+ # Otherwise if a default value is given (but not a block), returns the default
111
+ # value:
112
+ # ENV.delete('foo')
113
+ # ENV.fetch('foo', :default_need_not_be_a_string) # => :default_need_not_be_a_string
114
+ #
115
+ # If the environment variable does not exist and both default and block are
116
+ # given, issues a warning ("warning: block supersedes default value argument"),
117
+ # yields `name` to the block, and returns the block's return value:
118
+ # ENV.fetch('foo', :default) { |name| :block_return } # => :block_return
119
+ #
120
+ # Raises KeyError if `name` is valid, but not found, and neither default value
121
+ # nor block is given:
122
+ # ENV.fetch('foo') # Raises KeyError (key not found: "foo")
123
+ #
124
+ # Raises an exception if `name` is invalid. See [Invalid Names and
125
+ # Values](#class-ENV-label-Invalid+Names+and+Values).
126
+ #
127
+ def fetch: (String name) -> String
128
+ | [X] (String name, X default) -> (String | X)
129
+ | [X] (String name) { (String) -> X } -> (String | X)
130
+
131
+ # ENV.store is an alias for ENV.[]=.
132
+ #
133
+ # Creates, updates, or deletes the named environment variable, returning the
134
+ # value. Both `name` and `value` may be instances of String. See [Valid Names
135
+ # and Values](#class-ENV-label-Valid+Names+and+Values).
136
+ #
137
+ # * If the named environment variable does not exist:
138
+ # * If `value` is `nil`, does nothing.
139
+ # ENV.clear
140
+ # ENV['foo'] = nil # => nil
141
+ # ENV.include?('foo') # => false
142
+ # ENV.store('bar', nil) # => nil
143
+ # ENV.include?('bar') # => false
144
+ #
145
+ # * If `value` is not `nil`, creates the environment variable with `name`
146
+ # and `value`:
147
+ # # Create 'foo' using ENV.[]=.
148
+ # ENV['foo'] = '0' # => '0'
149
+ # ENV['foo'] # => '0'
150
+ # # Create 'bar' using ENV.store.
151
+ # ENV.store('bar', '1') # => '1'
152
+ # ENV['bar'] # => '1'
153
+ #
154
+ #
155
+ # * If the named environment variable exists:
156
+ # * If `value` is not `nil`, updates the environment variable with value
157
+ # `value`:
158
+ # # Update 'foo' using ENV.[]=.
159
+ # ENV['foo'] = '2' # => '2'
160
+ # ENV['foo'] # => '2'
161
+ # # Update 'bar' using ENV.store.
162
+ # ENV.store('bar', '3') # => '3'
163
+ # ENV['bar'] # => '3'
164
+ #
165
+ # * If `value` is `nil`, deletes the environment variable:
166
+ # # Delete 'foo' using ENV.[]=.
167
+ # ENV['foo'] = nil # => nil
168
+ # ENV.include?('foo') # => false
169
+ # # Delete 'bar' using ENV.store.
170
+ # ENV.store('bar', nil) # => nil
171
+ # ENV.include?('bar') # => false
172
+ #
173
+ #
174
+ #
175
+ # Raises an exception if `name` or `value` is invalid. See [Invalid Names and
176
+ # Values](#class-ENV-label-Invalid+Names+and+Values).
177
+ #
178
+ def []=: (String name, String? value) -> String?
179
+
180
+ # ENV.store is an alias for ENV.[]=.
181
+ #
182
+ # Creates, updates, or deletes the named environment variable, returning the
183
+ # value. Both `name` and `value` may be instances of String. See [Valid Names
184
+ # and Values](#class-ENV-label-Valid+Names+and+Values).
185
+ #
186
+ # * If the named environment variable does not exist:
187
+ # * If `value` is `nil`, does nothing.
188
+ # ENV.clear
189
+ # ENV['foo'] = nil # => nil
190
+ # ENV.include?('foo') # => false
191
+ # ENV.store('bar', nil) # => nil
192
+ # ENV.include?('bar') # => false
193
+ #
194
+ # * If `value` is not `nil`, creates the environment variable with `name`
195
+ # and `value`:
196
+ # # Create 'foo' using ENV.[]=.
197
+ # ENV['foo'] = '0' # => '0'
198
+ # ENV['foo'] # => '0'
199
+ # # Create 'bar' using ENV.store.
200
+ # ENV.store('bar', '1') # => '1'
201
+ # ENV['bar'] # => '1'
202
+ #
203
+ #
204
+ # * If the named environment variable exists:
205
+ # * If `value` is not `nil`, updates the environment variable with value
206
+ # `value`:
207
+ # # Update 'foo' using ENV.[]=.
208
+ # ENV['foo'] = '2' # => '2'
209
+ # ENV['foo'] # => '2'
210
+ # # Update 'bar' using ENV.store.
211
+ # ENV.store('bar', '3') # => '3'
212
+ # ENV['bar'] # => '3'
213
+ #
214
+ # * If `value` is `nil`, deletes the environment variable:
215
+ # # Delete 'foo' using ENV.[]=.
216
+ # ENV['foo'] = nil # => nil
217
+ # ENV.include?('foo') # => false
218
+ # # Delete 'bar' using ENV.store.
219
+ # ENV.store('bar', nil) # => nil
220
+ # ENV.include?('bar') # => false
221
+ #
222
+ #
223
+ #
224
+ # Raises an exception if `name` or `value` is invalid. See [Invalid Names and
225
+ # Values](#class-ENV-label-Invalid+Names+and+Values).
226
+ #
227
+ alias store []=
228
+
229
+ # Yields each environment variable name and its value as a 2-element Array:
230
+ # h = {}
231
+ # ENV.each_pair { |name, value| h[name] = value } # => ENV
232
+ # h # => {"bar"=>"1", "foo"=>"0"}
233
+ #
234
+ # Returns an Enumerator if no block given:
235
+ # h = {}
236
+ # e = ENV.each_pair # => #<Enumerator: {"bar"=>"1", "foo"=>"0"}:each_pair>
237
+ # e.each { |name, value| h[name] = value } # => ENV
238
+ # h # => {"bar"=>"1", "foo"=>"0"}
239
+ #
240
+ def each: () -> ::Enumerator[[ String, String ], self]
241
+ | () { ([ String, String ]) -> void } -> self
242
+
243
+ # Yields each environment variable name and its value as a 2-element Array:
244
+ # h = {}
245
+ # ENV.each_pair { |name, value| h[name] = value } # => ENV
246
+ # h # => {"bar"=>"1", "foo"=>"0"}
247
+ #
248
+ # Returns an Enumerator if no block given:
249
+ # h = {}
250
+ # e = ENV.each_pair # => #<Enumerator: {"bar"=>"1", "foo"=>"0"}:each_pair>
251
+ # e.each { |name, value| h[name] = value } # => ENV
252
+ # h # => {"bar"=>"1", "foo"=>"0"}
253
+ #
254
+ def each_pair: () -> ::Enumerator[[ String, String ], self]
255
+ | () { ([ String, String ]) -> void } -> self
256
+
257
+ # Yields each environment variable name:
258
+ # ENV.replace('foo' => '0', 'bar' => '1') # => ENV
259
+ # names = []
260
+ # ENV.each_key { |name| names.push(name) } # => ENV
261
+ # names # => ["bar", "foo"]
262
+ #
263
+ # Returns an Enumerator if no block given:
264
+ # e = ENV.each_key # => #<Enumerator: {"bar"=>"1", "foo"=>"0"}:each_key>
265
+ # names = []
266
+ # e.each { |name| names.push(name) } # => ENV
267
+ # names # => ["bar", "foo"]
268
+ #
269
+ def each_key: () -> ::Enumerator[[ String ], self]
270
+ | () { (String name) -> void } -> self
271
+
272
+ # Yields each environment variable value:
273
+ # ENV.replace('foo' => '0', 'bar' => '1') # => ENV
274
+ # values = []
275
+ # ENV.each_value { |value| values.push(value) } # => ENV
276
+ # values # => ["1", "0"]
277
+ #
278
+ # Returns an Enumerator if no block given:
279
+ # e = ENV.each_value # => #<Enumerator: {"bar"=>"1", "foo"=>"0"}:each_value>
280
+ # values = []
281
+ # e.each { |value| values.push(value) } # => ENV
282
+ # values # => ["1", "0"]
283
+ #
284
+ def each_value: () -> ::Enumerator[[ String ], self]
285
+ | () { (String value) -> void } -> self
286
+
287
+ # Deletes the environment variable with `name` if it exists and returns its
288
+ # value:
289
+ # ENV['foo'] = '0'
290
+ # ENV.delete('foo') # => '0'
291
+ #
292
+ # If a block is not given and the named environment variable does not exist,
293
+ # returns `nil`.
294
+ #
295
+ # If a block given and the environment variable does not exist, yields `name` to
296
+ # the block and returns the value of the block:
297
+ # ENV.delete('foo') { |name| name * 2 } # => "foofoo"
298
+ #
299
+ # If a block given and the environment variable exists, deletes the environment
300
+ # variable and returns its value (ignoring the block):
301
+ # ENV['foo'] = '0'
302
+ # ENV.delete('foo') { |name| raise 'ignored' } # => "0"
303
+ #
304
+ # Raises an exception if `name` is invalid. See [Invalid Names and
305
+ # Values](#class-ENV-label-Invalid+Names+and+Values).
306
+ #
307
+ def delete: (String name) -> String?
308
+ | (String name) { (String) -> String } -> String
309
+
310
+ # Yields each environment variable name and its value as a 2-element Array,
311
+ # deleting each environment variable for which the block returns a truthy value,
312
+ # and returning ENV (regardless of whether any deletions):
313
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
314
+ # ENV.delete_if { |name, value| name.start_with?('b') } # => ENV
315
+ # ENV # => {"foo"=>"0"}
316
+ # ENV.delete_if { |name, value| name.start_with?('b') } # => ENV
317
+ #
318
+ # Returns an Enumerator if no block given:
319
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
320
+ # e = ENV.delete_if # => #<Enumerator: {"bar"=>"1", "baz"=>"2", "foo"=>"0"}:delete_if!>
321
+ # e.each { |name, value| name.start_with?('b') } # => ENV
322
+ # ENV # => {"foo"=>"0"}
323
+ # e.each { |name, value| name.start_with?('b') } # => ENV
324
+ #
325
+ def delete_if: () -> ::Enumerator[[ String, String ], self]
326
+ | () { (String name, String value) -> boolish } -> self
327
+
328
+ # Yields each environment variable name and its value as a 2-element Array,
329
+ # deleting each environment variable for which the block returns `false` or
330
+ # `nil`, and returning ENV:
331
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
332
+ # ENV.keep_if { |name, value| name.start_with?('b') } # => ENV
333
+ # ENV # => {"bar"=>"1", "baz"=>"2"}
334
+ #
335
+ # Returns an Enumerator if no block given:
336
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
337
+ # e = ENV.keep_if # => #<Enumerator: {"bar"=>"1", "baz"=>"2", "foo"=>"0"}:keep_if>
338
+ # e.each { |name, value| name.start_with?('b') } # => ENV
339
+ # ENV # => {"bar"=>"1", "baz"=>"2"}
340
+ #
341
+ def keep_if: () -> ::Enumerator[[ String, String ], self]
342
+ | () { (String name, String value) -> boolish } -> self
343
+
344
+ # Returns a Hash of the given ENV names and their corresponding values:
345
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2', 'bat' => '3')
346
+ # ENV.slice('foo', 'baz') # => {"foo"=>"0", "baz"=>"2"}
347
+ # ENV.slice('baz', 'foo') # => {"baz"=>"2", "foo"=>"0"}
348
+ #
349
+ # Raises an exception if any of the `names` is invalid (see [Invalid Names and
350
+ # Values](#class-ENV-label-Invalid+Names+and+Values)):
351
+ # ENV.slice('foo', 'bar', :bat) # Raises TypeError (no implicit conversion of Symbol into String)
352
+ #
353
+ def slice: (*String names) -> ::Hash[String, String]
354
+
355
+ # Returns a hash except the given keys from ENV and their values.
356
+ #
357
+ # ENV #=> {"LANG"=>"en_US.UTF-8", "TERM"=>"xterm-256color", "HOME"=>"/Users/rhc"}
358
+ # ENV.except("TERM","HOME") #=> {"LANG"=>"en_US.UTF-8"}
359
+ #
360
+ def except: (*String names) -> ::Hash[String, String]
361
+
362
+ # Removes every environment variable; returns ENV:
363
+ # ENV.replace('foo' => '0', 'bar' => '1')
364
+ # ENV.size # => 2
365
+ # ENV.clear # => ENV
366
+ # ENV.size # => 0
367
+ #
368
+ def clear: () -> self
369
+
370
+ # Yields each environment variable name and its value as a 2-element Array.
371
+ # Returns a Hash whose items are determined by the block. When the block returns
372
+ # a truthy value, the name/value pair is added to the return Hash; otherwise the
373
+ # pair is ignored:
374
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
375
+ # ENV.reject { |name, value| name.start_with?('b') } # => {"foo"=>"0"}
376
+ #
377
+ # Returns an Enumerator if no block given:
378
+ # e = ENV.reject
379
+ # e.each { |name, value| name.start_with?('b') } # => {"foo"=>"0"}
380
+ #
381
+ def reject: () -> ::Enumerator[[ String, String ], self]
382
+ | () { (String name, String value) -> boolish } -> self
383
+
384
+ # Similar to ENV.delete_if, but returns `nil` if no changes were made.
385
+ #
386
+ # Yields each environment variable name and its value as a 2-element Array,
387
+ # deleting each environment variable for which the block returns a truthy value,
388
+ # and returning ENV (if any deletions) or `nil` (if not):
389
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
390
+ # ENV.reject! { |name, value| name.start_with?('b') } # => ENV
391
+ # ENV # => {"foo"=>"0"}
392
+ # ENV.reject! { |name, value| name.start_with?('b') } # => nil
393
+ #
394
+ # Returns an Enumerator if no block given:
395
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
396
+ # e = ENV.reject! # => #<Enumerator: {"bar"=>"1", "baz"=>"2", "foo"=>"0"}:reject!>
397
+ # e.each { |name, value| name.start_with?('b') } # => ENV
398
+ # ENV # => {"foo"=>"0"}
399
+ # e.each { |name, value| name.start_with?('b') } # => nil
400
+ #
401
+ def reject!: () -> ::Enumerator[[ String, String ], self?]
402
+ | () { (String name, String value) -> boolish } -> self?
403
+
404
+ # ENV.filter is an alias for ENV.select.
405
+ #
406
+ # Yields each environment variable name and its value as a 2-element Array,
407
+ # returning a Hash of the names and values for which the block returns a truthy
408
+ # value:
409
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
410
+ # ENV.select { |name, value| name.start_with?('b') } # => {"bar"=>"1", "baz"=>"2"}
411
+ # ENV.filter { |name, value| name.start_with?('b') } # => {"bar"=>"1", "baz"=>"2"}
412
+ #
413
+ # Returns an Enumerator if no block given:
414
+ # e = ENV.select # => #<Enumerator: {"bar"=>"1", "baz"=>"2", "foo"=>"0"}:select>
415
+ # e.each { |name, value | name.start_with?('b') } # => {"bar"=>"1", "baz"=>"2"}
416
+ # e = ENV.filter # => #<Enumerator: {"bar"=>"1", "baz"=>"2", "foo"=>"0"}:filter>
417
+ # e.each { |name, value | name.start_with?('b') } # => {"bar"=>"1", "baz"=>"2"}
418
+ #
419
+ def select: () -> ::Enumerator[[ String, String ], ::Hash[String, String]]
420
+ | () { (String name, String value) -> boolish } -> ::Hash[String, String]
421
+
422
+ # ENV.filter is an alias for ENV.select.
423
+ #
424
+ # Yields each environment variable name and its value as a 2-element Array,
425
+ # returning a Hash of the names and values for which the block returns a truthy
426
+ # value:
427
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
428
+ # ENV.select { |name, value| name.start_with?('b') } # => {"bar"=>"1", "baz"=>"2"}
429
+ # ENV.filter { |name, value| name.start_with?('b') } # => {"bar"=>"1", "baz"=>"2"}
430
+ #
431
+ # Returns an Enumerator if no block given:
432
+ # e = ENV.select # => #<Enumerator: {"bar"=>"1", "baz"=>"2", "foo"=>"0"}:select>
433
+ # e.each { |name, value | name.start_with?('b') } # => {"bar"=>"1", "baz"=>"2"}
434
+ # e = ENV.filter # => #<Enumerator: {"bar"=>"1", "baz"=>"2", "foo"=>"0"}:filter>
435
+ # e.each { |name, value | name.start_with?('b') } # => {"bar"=>"1", "baz"=>"2"}
436
+ #
437
+ alias filter select
438
+
439
+ # ENV.filter! is an alias for ENV.select!.
440
+ #
441
+ # Yields each environment variable name and its value as a 2-element Array,
442
+ # deleting each entry for which the block returns `false` or `nil`, and
443
+ # returning ENV if any deletions made, or `nil` otherwise:
444
+ #
445
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
446
+ # ENV.select! { |name, value| name.start_with?('b') } # => ENV
447
+ # ENV # => {"bar"=>"1", "baz"=>"2"}
448
+ # ENV.select! { |name, value| true } # => nil
449
+ #
450
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
451
+ # ENV.filter! { |name, value| name.start_with?('b') } # => ENV
452
+ # ENV # => {"bar"=>"1", "baz"=>"2"}
453
+ # ENV.filter! { |name, value| true } # => nil
454
+ #
455
+ # Returns an Enumerator if no block given:
456
+ #
457
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
458
+ # e = ENV.select! # => #<Enumerator: {"bar"=>"1", "baz"=>"2"}:select!>
459
+ # e.each { |name, value| name.start_with?('b') } # => ENV
460
+ # ENV # => {"bar"=>"1", "baz"=>"2"}
461
+ # e.each { |name, value| true } # => nil
462
+ #
463
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
464
+ # e = ENV.filter! # => #<Enumerator: {"bar"=>"1", "baz"=>"2"}:filter!>
465
+ # e.each { |name, value| name.start_with?('b') } # => ENV
466
+ # ENV # => {"bar"=>"1", "baz"=>"2"}
467
+ # e.each { |name, value| true } # => nil
468
+ #
469
+ def select!: () -> ::Enumerator[[ String, String ], self?]
470
+ | () { (String name, String value) -> boolish } -> self?
471
+
472
+ # ENV.filter! is an alias for ENV.select!.
473
+ #
474
+ # Yields each environment variable name and its value as a 2-element Array,
475
+ # deleting each entry for which the block returns `false` or `nil`, and
476
+ # returning ENV if any deletions made, or `nil` otherwise:
477
+ #
478
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
479
+ # ENV.select! { |name, value| name.start_with?('b') } # => ENV
480
+ # ENV # => {"bar"=>"1", "baz"=>"2"}
481
+ # ENV.select! { |name, value| true } # => nil
482
+ #
483
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
484
+ # ENV.filter! { |name, value| name.start_with?('b') } # => ENV
485
+ # ENV # => {"bar"=>"1", "baz"=>"2"}
486
+ # ENV.filter! { |name, value| true } # => nil
487
+ #
488
+ # Returns an Enumerator if no block given:
489
+ #
490
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
491
+ # e = ENV.select! # => #<Enumerator: {"bar"=>"1", "baz"=>"2"}:select!>
492
+ # e.each { |name, value| name.start_with?('b') } # => ENV
493
+ # ENV # => {"bar"=>"1", "baz"=>"2"}
494
+ # e.each { |name, value| true } # => nil
495
+ #
496
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
497
+ # e = ENV.filter! # => #<Enumerator: {"bar"=>"1", "baz"=>"2"}:filter!>
498
+ # e.each { |name, value| name.start_with?('b') } # => ENV
499
+ # ENV # => {"bar"=>"1", "baz"=>"2"}
500
+ # e.each { |name, value| true } # => nil
501
+ #
502
+ alias filter! select!
503
+
504
+ # Removes the first environment variable from ENV and returns a 2-element Array
505
+ # containing its name and value:
506
+ # ENV.replace('foo' => '0', 'bar' => '1')
507
+ # ENV.to_hash # => {'bar' => '1', 'foo' => '0'}
508
+ # ENV.shift # => ['bar', '1']
509
+ # ENV.to_hash # => {'foo' => '0'}
510
+ #
511
+ # Exactly which environment variable is "first" is OS-dependent. See [About
512
+ # Ordering](#class-ENV-label-About+Ordering).
513
+ #
514
+ # Returns `nil` if the environment is empty.
515
+ #
516
+ def shift: () -> [ String, String ]?
517
+
518
+ # Returns a Hash whose keys are the ENV values, and whose values are the
519
+ # corresponding ENV names:
520
+ # ENV.replace('foo' => '0', 'bar' => '1')
521
+ # ENV.invert # => {"1"=>"bar", "0"=>"foo"}
522
+ #
523
+ # For a duplicate ENV value, overwrites the hash entry:
524
+ # ENV.replace('foo' => '0', 'bar' => '0')
525
+ # ENV.invert # => {"0"=>"foo"}
526
+ #
527
+ # Note that the order of the ENV processing is OS-dependent, which means that
528
+ # the order of overwriting is also OS-dependent. See [About
529
+ # Ordering](#class-ENV-label-About+Ordering).
530
+ #
531
+ def invert: () -> ::Hash[String, String]
532
+
533
+ # Replaces the entire content of the environment variables with the name/value
534
+ # pairs in the given `hash`; returns ENV.
535
+ #
536
+ # Replaces the content of ENV with the given pairs:
537
+ # ENV.replace('foo' => '0', 'bar' => '1') # => ENV
538
+ # ENV.to_hash # => {"bar"=>"1", "foo"=>"0"}
539
+ #
540
+ # Raises an exception if a name or value is invalid (see [Invalid Names and
541
+ # Values](#class-ENV-label-Invalid+Names+and+Values)):
542
+ # ENV.replace('foo' => '0', :bar => '1') # Raises TypeError (no implicit conversion of Symbol into String)
543
+ # ENV.replace('foo' => '0', 'bar' => 1) # Raises TypeError (no implicit conversion of Integer into String)
544
+ # ENV.to_hash # => {"bar"=>"1", "foo"=>"0"}
545
+ #
546
+ def replace: (Hash[String, String]) -> self
547
+
548
+ # ENV.update is an alias for ENV.merge!.
549
+ #
550
+ # Adds to ENV each key/value pair in the given `hash`; returns ENV:
551
+ # ENV.replace('foo' => '0', 'bar' => '1')
552
+ # ENV.merge!('baz' => '2', 'bat' => '3') # => {"bar"=>"1", "bat"=>"3", "baz"=>"2", "foo"=>"0"}
553
+ #
554
+ # Deletes the ENV entry for a hash value that is `nil`:
555
+ # ENV.merge!('baz' => nil, 'bat' => nil) # => {"bar"=>"1", "foo"=>"0"}
556
+ #
557
+ # For an already-existing name, if no block given, overwrites the ENV value:
558
+ # ENV.merge!('foo' => '4') # => {"bar"=>"1", "foo"=>"4"}
559
+ #
560
+ # For an already-existing name, if block given, yields the name, its ENV value,
561
+ # and its hash value; the block's return value becomes the new name:
562
+ # ENV.merge!('foo' => '5') { |name, env_val, hash_val | env_val + hash_val } # => {"bar"=>"1", "foo"=>"45"}
563
+ #
564
+ # Raises an exception if a name or value is invalid (see [Invalid Names and
565
+ # Values](#class-ENV-label-Invalid+Names+and+Values));
566
+ # ENV.replace('foo' => '0', 'bar' => '1')
567
+ # ENV.merge!('foo' => '6', :bar => '7', 'baz' => '9') # Raises TypeError (no implicit conversion of Symbol into String)
568
+ # ENV # => {"bar"=>"1", "foo"=>"6"}
569
+ # ENV.merge!('foo' => '7', 'bar' => 8, 'baz' => '9') # Raises TypeError (no implicit conversion of Integer into String)
570
+ # ENV # => {"bar"=>"1", "foo"=>"7"}
571
+ #
572
+ # Raises an exception if the block returns an invalid name: (see [Invalid Names
573
+ # and Values](#class-ENV-label-Invalid+Names+and+Values)):
574
+ # ENV.merge!('bat' => '8', 'foo' => '9') { |name, env_val, hash_val | 10 } # Raises TypeError (no implicit conversion of Integer into String)
575
+ # ENV # => {"bar"=>"1", "bat"=>"8", "foo"=>"7"}
576
+ #
577
+ # Note that for the exceptions above, hash pairs preceding an invalid name or
578
+ # value are processed normally; those following are ignored.
579
+ #
580
+ def update: (Hash[String, String?]) -> self
581
+ | (Hash[String, String?]) { (String name, String env_val, String? hash_val) -> String } -> self
582
+
583
+ # ENV.update is an alias for ENV.merge!.
584
+ #
585
+ # Adds to ENV each key/value pair in the given `hash`; returns ENV:
586
+ # ENV.replace('foo' => '0', 'bar' => '1')
587
+ # ENV.merge!('baz' => '2', 'bat' => '3') # => {"bar"=>"1", "bat"=>"3", "baz"=>"2", "foo"=>"0"}
588
+ #
589
+ # Deletes the ENV entry for a hash value that is `nil`:
590
+ # ENV.merge!('baz' => nil, 'bat' => nil) # => {"bar"=>"1", "foo"=>"0"}
591
+ #
592
+ # For an already-existing name, if no block given, overwrites the ENV value:
593
+ # ENV.merge!('foo' => '4') # => {"bar"=>"1", "foo"=>"4"}
594
+ #
595
+ # For an already-existing name, if block given, yields the name, its ENV value,
596
+ # and its hash value; the block's return value becomes the new name:
597
+ # ENV.merge!('foo' => '5') { |name, env_val, hash_val | env_val + hash_val } # => {"bar"=>"1", "foo"=>"45"}
598
+ #
599
+ # Raises an exception if a name or value is invalid (see [Invalid Names and
600
+ # Values](#class-ENV-label-Invalid+Names+and+Values));
601
+ # ENV.replace('foo' => '0', 'bar' => '1')
602
+ # ENV.merge!('foo' => '6', :bar => '7', 'baz' => '9') # Raises TypeError (no implicit conversion of Symbol into String)
603
+ # ENV # => {"bar"=>"1", "foo"=>"6"}
604
+ # ENV.merge!('foo' => '7', 'bar' => 8, 'baz' => '9') # Raises TypeError (no implicit conversion of Integer into String)
605
+ # ENV # => {"bar"=>"1", "foo"=>"7"}
606
+ #
607
+ # Raises an exception if the block returns an invalid name: (see [Invalid Names
608
+ # and Values](#class-ENV-label-Invalid+Names+and+Values)):
609
+ # ENV.merge!('bat' => '8', 'foo' => '9') { |name, env_val, hash_val | 10 } # Raises TypeError (no implicit conversion of Integer into String)
610
+ # ENV # => {"bar"=>"1", "bat"=>"8", "foo"=>"7"}
611
+ #
612
+ # Note that for the exceptions above, hash pairs preceding an invalid name or
613
+ # value are processed normally; those following are ignored.
614
+ #
615
+ alias merge! update
616
+
617
+ # (Provided for compatibility with Hash.)
618
+ #
619
+ # Does not modify ENV; returns `nil`.
620
+ #
621
+ def rehash: () -> nil
622
+
623
+ # Returns the contents of ENV as an Array of 2-element Arrays, each of which is
624
+ # a name/value pair:
625
+ # ENV.replace('foo' => '0', 'bar' => '1')
626
+ # ENV.to_a # => [["bar", "1"], ["foo", "0"]]
627
+ #
628
+ def to_a: () -> ::Array[[ String, String ]]
629
+
630
+ # Returns String 'ENV':
631
+ # ENV.to_s # => "ENV"
632
+ #
633
+ def to_s: () -> "ENV"
634
+
635
+ # Returns the name of the first environment variable with `value`, if it exists:
636
+ # ENV.replace('foo' => '0', 'bar' => '0')
637
+ # ENV.key('0') # => "foo"
638
+ #
639
+ # The order in which environment variables are examined is OS-dependent. See
640
+ # [About Ordering](#class-ENV-label-About+Ordering).
641
+ #
642
+ # Returns `nil` if there is no such value.
643
+ #
644
+ # Raises an exception if `value` is invalid:
645
+ # ENV.key(Object.new) # raises TypeError (no implicit conversion of Object into String)
646
+ #
647
+ # See [Invalid Names and Values](#class-ENV-label-Invalid+Names+and+Values).
648
+ #
649
+ def key: (String value) -> String?
650
+
651
+ # Returns the count of environment variables:
652
+ # ENV.replace('foo' => '0', 'bar' => '1')
653
+ # ENV.length # => 2
654
+ # ENV.size # => 2
655
+ #
656
+ def size: () -> Integer
657
+
658
+ # Returns the count of environment variables:
659
+ # ENV.replace('foo' => '0', 'bar' => '1')
660
+ # ENV.length # => 2
661
+ # ENV.size # => 2
662
+ #
663
+ alias length size
664
+
665
+ # Returns `true` when there are no environment variables, `false` otherwise:
666
+ # ENV.clear
667
+ # ENV.empty? # => true
668
+ # ENV['foo'] = '0'
669
+ # ENV.empty? # => false
670
+ #
671
+ def empty?: () -> bool
672
+
673
+ # Returns all variable names in an Array:
674
+ # ENV.replace('foo' => '0', 'bar' => '1')
675
+ # ENV.keys # => ['bar', 'foo']
676
+ #
677
+ # The order of the names is OS-dependent. See [About
678
+ # Ordering](#class-ENV-label-About+Ordering).
679
+ #
680
+ # Returns the empty Array if ENV is empty.
681
+ #
682
+ def keys: () -> ::Array[String]
683
+
684
+ # Returns all environment variable values in an Array:
685
+ # ENV.replace('foo' => '0', 'bar' => '1')
686
+ # ENV.values # => ['1', '0']
687
+ #
688
+ # The order of the values is OS-dependent. See [About
689
+ # Ordering](#class-ENV-label-About+Ordering).
690
+ #
691
+ # Returns the empty Array if ENV is empty.
692
+ #
693
+ def values: () -> ::Array[String]
694
+
695
+ # Returns an Array containing the environment variable values associated with
696
+ # the given names:
697
+ # ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
698
+ # ENV.values_at('foo', 'baz') # => ["0", "2"]
699
+ #
700
+ # Returns `nil` in the Array for each name that is not an ENV name:
701
+ # ENV.values_at('foo', 'bat', 'bar', 'bam') # => ["0", nil, "1", nil]
702
+ #
703
+ # Returns an empty Array if no names given.
704
+ #
705
+ # Raises an exception if any name is invalid. See [Invalid Names and
706
+ # Values](#class-ENV-label-Invalid+Names+and+Values).
707
+ #
708
+ def values_at: (*String names) -> ::Array[String?]
709
+
710
+ # ENV.has_key?, ENV.member?, and ENV.key? are aliases for ENV.include?.
711
+ #
712
+ # Returns `true` if there is an environment variable with the given `name`:
713
+ # ENV.replace('foo' => '0', 'bar' => '1')
714
+ # ENV.include?('foo') # => true
715
+ #
716
+ # Returns `false` if `name` is a valid String and there is no such environment
717
+ # variable:
718
+ # ENV.include?('baz') # => false
719
+ #
720
+ # Returns `false` if `name` is the empty String or is a String containing
721
+ # character `'='`:
722
+ # ENV.include?('') # => false
723
+ # ENV.include?('=') # => false
724
+ #
725
+ # Raises an exception if `name` is a String containing the NUL character `"\0"`:
726
+ # ENV.include?("\0") # Raises ArgumentError (bad environment variable name: contains null byte)
727
+ #
728
+ # Raises an exception if `name` has an encoding that is not ASCII-compatible:
729
+ # ENV.include?("\xa1\xa1".force_encoding(Encoding::UTF_16LE))
730
+ # # Raises ArgumentError (bad environment variable name: ASCII incompatible encoding: UTF-16LE)
731
+ #
732
+ # Raises an exception if `name` is not a String:
733
+ # ENV.include?(Object.new) # TypeError (no implicit conversion of Object into String)
734
+ #
735
+ def include?: (String name) -> bool
736
+
737
+ # ENV.has_key?, ENV.member?, and ENV.key? are aliases for ENV.include?.
738
+ #
739
+ # Returns `true` if there is an environment variable with the given `name`:
740
+ # ENV.replace('foo' => '0', 'bar' => '1')
741
+ # ENV.include?('foo') # => true
742
+ #
743
+ # Returns `false` if `name` is a valid String and there is no such environment
744
+ # variable:
745
+ # ENV.include?('baz') # => false
746
+ #
747
+ # Returns `false` if `name` is the empty String or is a String containing
748
+ # character `'='`:
749
+ # ENV.include?('') # => false
750
+ # ENV.include?('=') # => false
751
+ #
752
+ # Raises an exception if `name` is a String containing the NUL character `"\0"`:
753
+ # ENV.include?("\0") # Raises ArgumentError (bad environment variable name: contains null byte)
754
+ #
755
+ # Raises an exception if `name` has an encoding that is not ASCII-compatible:
756
+ # ENV.include?("\xa1\xa1".force_encoding(Encoding::UTF_16LE))
757
+ # # Raises ArgumentError (bad environment variable name: ASCII incompatible encoding: UTF-16LE)
758
+ #
759
+ # Raises an exception if `name` is not a String:
760
+ # ENV.include?(Object.new) # TypeError (no implicit conversion of Object into String)
761
+ #
762
+ alias member? include?
763
+
764
+ # ENV.has_key?, ENV.member?, and ENV.key? are aliases for ENV.include?.
765
+ #
766
+ # Returns `true` if there is an environment variable with the given `name`:
767
+ # ENV.replace('foo' => '0', 'bar' => '1')
768
+ # ENV.include?('foo') # => true
769
+ #
770
+ # Returns `false` if `name` is a valid String and there is no such environment
771
+ # variable:
772
+ # ENV.include?('baz') # => false
773
+ #
774
+ # Returns `false` if `name` is the empty String or is a String containing
775
+ # character `'='`:
776
+ # ENV.include?('') # => false
777
+ # ENV.include?('=') # => false
778
+ #
779
+ # Raises an exception if `name` is a String containing the NUL character `"\0"`:
780
+ # ENV.include?("\0") # Raises ArgumentError (bad environment variable name: contains null byte)
781
+ #
782
+ # Raises an exception if `name` has an encoding that is not ASCII-compatible:
783
+ # ENV.include?("\xa1\xa1".force_encoding(Encoding::UTF_16LE))
784
+ # # Raises ArgumentError (bad environment variable name: ASCII incompatible encoding: UTF-16LE)
785
+ #
786
+ # Raises an exception if `name` is not a String:
787
+ # ENV.include?(Object.new) # TypeError (no implicit conversion of Object into String)
788
+ #
789
+ alias has_key? include?
790
+
791
+ # Returns `true` if `value` is the value for some environment variable name,
792
+ # `false` otherwise:
793
+ # ENV.replace('foo' => '0', 'bar' => '1')
794
+ # ENV.value?('0') # => true
795
+ # ENV.has_value?('0') # => true
796
+ # ENV.value?('2') # => false
797
+ # ENV.has_value?('2') # => false
798
+ #
799
+ def has_value?: (String value) -> bool
800
+
801
+ # Returns `true` if `value` is the value for some environment variable name,
802
+ # `false` otherwise:
803
+ # ENV.replace('foo' => '0', 'bar' => '1')
804
+ # ENV.value?('0') # => true
805
+ # ENV.has_value?('0') # => true
806
+ # ENV.value?('2') # => false
807
+ # ENV.has_value?('2') # => false
808
+ #
809
+ alias value? has_value?
810
+
811
+ # ENV.has_key?, ENV.member?, and ENV.key? are aliases for ENV.include?.
812
+ #
813
+ # Returns `true` if there is an environment variable with the given `name`:
814
+ # ENV.replace('foo' => '0', 'bar' => '1')
815
+ # ENV.include?('foo') # => true
816
+ #
817
+ # Returns `false` if `name` is a valid String and there is no such environment
818
+ # variable:
819
+ # ENV.include?('baz') # => false
820
+ #
821
+ # Returns `false` if `name` is the empty String or is a String containing
822
+ # character `'='`:
823
+ # ENV.include?('') # => false
824
+ # ENV.include?('=') # => false
825
+ #
826
+ # Raises an exception if `name` is a String containing the NUL character `"\0"`:
827
+ # ENV.include?("\0") # Raises ArgumentError (bad environment variable name: contains null byte)
828
+ #
829
+ # Raises an exception if `name` has an encoding that is not ASCII-compatible:
830
+ # ENV.include?("\xa1\xa1".force_encoding(Encoding::UTF_16LE))
831
+ # # Raises ArgumentError (bad environment variable name: ASCII incompatible encoding: UTF-16LE)
832
+ #
833
+ # Raises an exception if `name` is not a String:
834
+ # ENV.include?(Object.new) # TypeError (no implicit conversion of Object into String)
835
+ #
836
+ alias key? include?
837
+
838
+ # Returns a Hash containing all name/value pairs from ENV:
839
+ # ENV.replace('foo' => '0', 'bar' => '1')
840
+ # ENV.to_hash # => {"bar"=>"1", "foo"=>"0"}
841
+ #
842
+ def to_hash: () -> ::Hash[String, String]
843
+
844
+ # Returns a 2-element Array containing the name and value of the environment
845
+ # variable for `name` if it exists:
846
+ # ENV.replace('foo' => '0', 'bar' => '1')
847
+ # ENV.assoc('foo') # => ['foo', '0']
848
+ #
849
+ # Returns `nil` if `name` is a valid String and there is no such environment
850
+ # variable.
851
+ #
852
+ # Returns `nil` if `name` is the empty String or is a String containing
853
+ # character `'='`.
854
+ #
855
+ # Raises an exception if `name` is a String containing the NUL character `"\0"`:
856
+ # ENV.assoc("\0") # Raises ArgumentError (bad environment variable name: contains null byte)
857
+ #
858
+ # Raises an exception if `name` has an encoding that is not ASCII-compatible:
859
+ # ENV.assoc("\xa1\xa1".force_encoding(Encoding::UTF_16LE))
860
+ # # Raises ArgumentError (bad environment variable name: ASCII incompatible encoding: UTF-16LE)
861
+ #
862
+ # Raises an exception if `name` is not a String:
863
+ # ENV.assoc(Object.new) # TypeError (no implicit conversion of Object into String)
864
+ #
865
+ def assoc: (String name) -> [ String, String ]?
866
+
867
+ # Returns a 2-element Array containing the name and value of the **first**
868
+ # **found** environment variable that has value `value`, if one exists:
869
+ # ENV.replace('foo' => '0', 'bar' => '0')
870
+ # ENV.rassoc('0') # => ["bar", "0"]
871
+ #
872
+ # The order in which environment variables are examined is OS-dependent. See
873
+ # [About Ordering](#class-ENV-label-About+Ordering).
874
+ #
875
+ # Returns `nil` if there is no such environment variable.
876
+ #
877
+ def rassoc: (String value) -> [ String, String ]?
878
+ end
879
+
880
+ # EnvClass is a temporary class prepared for ENV typing.
881
+ ENV: ENVClass