rbs 2.0.0 → 2.1.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (179) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/ruby.yml +5 -0
  3. data/CHANGELOG.md +23 -0
  4. data/README.md +6 -1
  5. data/core/array.rbs +2866 -1086
  6. data/core/basic_object.rbs +150 -30
  7. data/core/binding.rbs +33 -0
  8. data/core/builtin.rbs +4 -4
  9. data/core/class.rbs +43 -5
  10. data/core/comparable.rbs +57 -0
  11. data/core/complex.rbs +170 -4
  12. data/core/constants.rbs +51 -0
  13. data/core/deprecated.rbs +7 -0
  14. data/core/dir.rbs +305 -20
  15. data/core/encoding.rbs +472 -77
  16. data/core/enumerable.rbs +2173 -234
  17. data/core/enumerator.rbs +448 -182
  18. data/core/env.rbs +448 -1
  19. data/core/errno.rbs +1 -10
  20. data/core/errors.rbs +152 -2
  21. data/core/exception.rbs +201 -127
  22. data/core/false_class.rbs +27 -0
  23. data/core/fiber.rbs +118 -37
  24. data/core/fiber_error.rbs +8 -9
  25. data/core/file.rbs +1059 -139
  26. data/core/file_test.rbs +287 -32
  27. data/core/float.rbs +776 -300
  28. data/core/gc.rbs +185 -34
  29. data/core/global_variables.rbs +5 -1
  30. data/core/hash.rbs +1582 -649
  31. data/core/integer.rbs +974 -204
  32. data/core/io/buffer.rbs +710 -0
  33. data/core/io/wait.rbs +29 -8
  34. data/core/io.rbs +2438 -417
  35. data/core/kernel.rbs +2315 -316
  36. data/core/marshal.rbs +37 -2
  37. data/core/match_data.rbs +123 -6
  38. data/core/math.rbs +126 -6
  39. data/core/method.rbs +226 -102
  40. data/core/module.rbs +421 -45
  41. data/core/nil_class.rbs +64 -0
  42. data/core/numeric.rbs +620 -142
  43. data/core/object.rbs +453 -81
  44. data/core/object_space.rbs +92 -2
  45. data/core/proc.rbs +482 -285
  46. data/core/process.rbs +443 -34
  47. data/core/ractor.rbs +232 -9
  48. data/core/random.rbs +151 -52
  49. data/core/range.rbs +885 -160
  50. data/core/rational.rbs +122 -6
  51. data/core/rb_config.rbs +14 -4
  52. data/core/refinement.rbs +44 -0
  53. data/core/regexp.rbs +156 -14
  54. data/core/ruby_vm.rbs +42 -3
  55. data/core/signal.rbs +78 -39
  56. data/core/string.rbs +2123 -567
  57. data/core/string_io.rbs +204 -0
  58. data/core/struct.rbs +283 -28
  59. data/core/symbol.rbs +304 -30
  60. data/core/thread.rbs +1288 -688
  61. data/core/thread_group.rbs +66 -10
  62. data/core/time.rbs +643 -217
  63. data/core/trace_point.rbs +100 -12
  64. data/core/true_class.rbs +24 -0
  65. data/core/unbound_method.rbs +73 -7
  66. data/core/warning.rbs +37 -12
  67. data/docs/CONTRIBUTING.md +40 -34
  68. data/docs/stdlib.md +3 -102
  69. data/lib/rbs/annotate/annotations.rb +197 -0
  70. data/lib/rbs/annotate/formatter.rb +80 -0
  71. data/lib/rbs/annotate/rdoc_annotator.rb +398 -0
  72. data/lib/rbs/annotate/rdoc_source.rb +120 -0
  73. data/lib/rbs/annotate.rb +6 -0
  74. data/lib/rbs/cli.rb +45 -1
  75. data/lib/rbs/definition_builder.rb +5 -1
  76. data/lib/rbs/location_aux.rb +12 -0
  77. data/lib/rbs/prototype/rb.rb +12 -0
  78. data/lib/rbs/version.rb +1 -1
  79. data/sig/annotate/annotations.rbs +102 -0
  80. data/sig/annotate/formatter.rbs +24 -0
  81. data/sig/annotate/rdoc_annotater.rbs +82 -0
  82. data/sig/annotate/rdoc_source.rbs +30 -0
  83. data/sig/cli.rbs +2 -0
  84. data/sig/collection/{collections.rbs → sources.rbs} +0 -0
  85. data/sig/location.rbs +6 -0
  86. data/sig/method_types.rbs +5 -1
  87. data/sig/polyfill.rbs +78 -0
  88. data/stdlib/abbrev/0/abbrev.rbs +6 -0
  89. data/stdlib/abbrev/0/array.rbs +26 -0
  90. data/stdlib/base64/0/base64.rbs +31 -0
  91. data/stdlib/benchmark/0/benchmark.rbs +74 -3
  92. data/stdlib/bigdecimal/0/big_decimal.rbs +614 -165
  93. data/stdlib/bigdecimal-math/0/big_math.rbs +41 -64
  94. data/stdlib/cgi/0/core.rbs +59 -0
  95. data/stdlib/coverage/0/coverage.rbs +164 -2
  96. data/stdlib/csv/0/csv.rbs +2862 -398
  97. data/stdlib/date/0/date.rbs +483 -25
  98. data/stdlib/date/0/date_time.rbs +187 -12
  99. data/stdlib/dbm/0/dbm.rbs +152 -17
  100. data/stdlib/digest/0/digest.rbs +146 -0
  101. data/stdlib/erb/0/erb.rbs +65 -245
  102. data/stdlib/fiber/0/fiber.rbs +73 -91
  103. data/stdlib/fileutils/0/fileutils.rbs +301 -1
  104. data/stdlib/find/0/find.rbs +9 -0
  105. data/stdlib/forwardable/0/forwardable.rbs +65 -1
  106. data/stdlib/io-console/0/io-console.rbs +227 -15
  107. data/stdlib/ipaddr/0/ipaddr.rbs +161 -0
  108. data/stdlib/json/0/json.rbs +1146 -144
  109. data/stdlib/logger/0/formatter.rbs +24 -0
  110. data/stdlib/logger/0/log_device.rbs +64 -0
  111. data/stdlib/logger/0/logger.rbs +165 -13
  112. data/stdlib/logger/0/period.rbs +10 -0
  113. data/stdlib/logger/0/severity.rbs +26 -0
  114. data/stdlib/monitor/0/monitor.rbs +163 -0
  115. data/stdlib/mutex_m/0/mutex_m.rbs +35 -6
  116. data/stdlib/net-http/0/net-http.rbs +1492 -683
  117. data/stdlib/nkf/0/nkf.rbs +372 -0
  118. data/stdlib/objspace/0/objspace.rbs +149 -90
  119. data/stdlib/openssl/0/openssl.rbs +8108 -71
  120. data/stdlib/optparse/0/optparse.rbs +487 -19
  121. data/stdlib/pathname/0/pathname.rbs +425 -124
  122. data/stdlib/prettyprint/0/prettyprint.rbs +120 -99
  123. data/stdlib/prime/0/integer-extension.rbs +20 -2
  124. data/stdlib/prime/0/prime.rbs +88 -21
  125. data/stdlib/pstore/0/pstore.rbs +102 -0
  126. data/stdlib/pty/0/pty.rbs +64 -14
  127. data/stdlib/resolv/0/resolv.rbs +420 -31
  128. data/stdlib/rubygems/0/basic_specification.rbs +4 -1
  129. data/stdlib/rubygems/0/config_file.rbs +33 -1
  130. data/stdlib/rubygems/0/dependency_installer.rbs +4 -3
  131. data/stdlib/rubygems/0/installer.rbs +13 -1
  132. data/stdlib/rubygems/0/path_support.rbs +4 -1
  133. data/stdlib/rubygems/0/platform.rbs +5 -1
  134. data/stdlib/rubygems/0/request_set.rbs +44 -2
  135. data/stdlib/rubygems/0/requirement.rbs +65 -2
  136. data/stdlib/rubygems/0/rubygems.rbs +407 -0
  137. data/stdlib/rubygems/0/source_list.rbs +13 -0
  138. data/stdlib/rubygems/0/specification.rbs +21 -1
  139. data/stdlib/rubygems/0/stream_ui.rbs +3 -1
  140. data/stdlib/rubygems/0/uninstaller.rbs +8 -1
  141. data/stdlib/rubygems/0/version.rbs +60 -157
  142. data/stdlib/securerandom/0/securerandom.rbs +44 -0
  143. data/stdlib/set/0/set.rbs +420 -106
  144. data/stdlib/shellwords/0/shellwords.rbs +55 -77
  145. data/stdlib/singleton/0/singleton.rbs +20 -0
  146. data/stdlib/socket/0/addrinfo.rbs +210 -9
  147. data/stdlib/socket/0/basic_socket.rbs +103 -11
  148. data/stdlib/socket/0/ip_socket.rbs +31 -9
  149. data/stdlib/socket/0/socket.rbs +586 -38
  150. data/stdlib/socket/0/tcp_server.rbs +22 -2
  151. data/stdlib/socket/0/tcp_socket.rbs +12 -1
  152. data/stdlib/socket/0/udp_socket.rbs +25 -2
  153. data/stdlib/socket/0/unix_server.rbs +22 -2
  154. data/stdlib/socket/0/unix_socket.rbs +45 -5
  155. data/stdlib/strscan/0/string_scanner.rbs +210 -9
  156. data/stdlib/tempfile/0/tempfile.rbs +58 -10
  157. data/stdlib/time/0/time.rbs +208 -116
  158. data/stdlib/timeout/0/timeout.rbs +10 -0
  159. data/stdlib/tmpdir/0/tmpdir.rbs +13 -4
  160. data/stdlib/tsort/0/cyclic.rbs +1 -0
  161. data/stdlib/tsort/0/interfaces.rbs +1 -0
  162. data/stdlib/tsort/0/tsort.rbs +42 -0
  163. data/stdlib/uri/0/common.rbs +57 -8
  164. data/stdlib/uri/0/file.rbs +55 -109
  165. data/stdlib/uri/0/ftp.rbs +6 -3
  166. data/stdlib/uri/0/generic.rbs +556 -327
  167. data/stdlib/uri/0/http.rbs +26 -115
  168. data/stdlib/uri/0/https.rbs +8 -102
  169. data/stdlib/uri/0/ldap.rbs +143 -137
  170. data/stdlib/uri/0/ldaps.rbs +8 -102
  171. data/stdlib/uri/0/mailto.rbs +3 -0
  172. data/stdlib/uri/0/rfc2396_parser.rbs +66 -26
  173. data/stdlib/uri/0/ws.rbs +6 -3
  174. data/stdlib/uri/0/wss.rbs +5 -3
  175. data/stdlib/yaml/0/dbm.rbs +151 -87
  176. data/stdlib/yaml/0/store.rbs +6 -0
  177. data/stdlib/zlib/0/zlib.rbs +90 -31
  178. metadata +17 -5
  179. data/lib/rbs/location.rb +0 -221
data/core/io.rbs CHANGED
@@ -1,123 +1,699 @@
1
- # The [IO](IO) class is the basis for all input and
2
- # output in Ruby. An I/O stream may be *duplexed* (that is,
3
- # bidirectional), and so may use more than one native operating system
4
- # stream.
5
- #
6
- # Many of the examples in this section use the
7
- # [File](https://ruby-doc.org/core-2.6.3/File.html) class, the only
8
- # standard subclass of [IO](IO). The two classes are
9
- # closely associated. Like the
10
- # [File](https://ruby-doc.org/core-2.6.3/File.html) class, the Socket
11
- # library subclasses from [IO](IO) (such as TCPSocket
12
- # or UDPSocket).
13
- #
14
- # The
15
- # [Kernel\#open](https://ruby-doc.org/core-2.6.3/Kernel.html#method-i-open)
16
- # method can create an [IO](IO) (or
17
- # [File](https://ruby-doc.org/core-2.6.3/File.html) ) object for these
18
- # types of arguments:
19
- #
20
- # - A plain string represents a filename suitable for the underlying
21
- # operating system.
22
- #
23
- # - A string starting with `"|"` indicates a subprocess. The remainder
24
- # of the string following the `"|"` is invoked as a process with
25
- # appropriate input/output channels connected to it.
26
- #
27
- # - A string equal to `"|-"` will create another Ruby instance as a
1
+ # <!-- rdoc-file=io.c -->
2
+ # The IO class is the basis for all input and output in Ruby. An I/O stream may
3
+ # be *duplexed* (that is, bidirectional), and so may use more than one native
4
+ # operating system stream.
5
+ #
6
+ # Many of the examples in this section use the File class, the only standard
7
+ # subclass of IO. The two classes are closely associated. Like the File class,
8
+ # the Socket library subclasses from IO (such as TCPSocket or UDPSocket).
9
+ #
10
+ # The Kernel#open method can create an IO (or File) object for these types of
11
+ # arguments:
12
+ #
13
+ # * A plain string represents a filename suitable for the underlying operating
14
+ # system.
15
+ #
16
+ # * A string starting with `"|"` indicates a subprocess. The remainder of the
17
+ # string following the `"|"` is invoked as a process with appropriate
18
+ # input/output channels connected to it.
19
+ #
20
+ # * A string equal to `"|-"` will create another Ruby instance as a
28
21
  # subprocess.
29
22
  #
30
- # The [IO](IO) may be opened with different file modes
31
- # (read-only, write-only) and encodings for proper conversion. See
32
- # [::new](IO#method-c-new) for these options. See
33
- # [Kernel\#open](https://ruby-doc.org/core-2.6.3/Kernel.html#method-i-open)
34
- # for details of the various command formats described above.
35
23
  #
36
- # [::popen](IO#method-c-popen), the Open3 library, or
37
- # Process\#spawn may also be used to communicate with subprocesses through
38
- # an [IO](IO).
24
+ # The IO may be opened with different file modes (read-only, write-only) and
25
+ # encodings for proper conversion. See IO.new for these options. See
26
+ # Kernel#open for details of the various command formats described above.
39
27
  #
40
- # Ruby will convert pathnames between different operating system
41
- # conventions if possible. For instance, on a Windows system the filename
42
- # `"/gumby/ruby/test.rb"` will be opened as `"\gumby\ruby\test.rb"` . When
43
- # specifying a Windows-style filename in a Ruby string, remember to escape
44
- # the backslashes:
28
+ # IO.popen, the Open3 library, or Process#spawn may also be used to communicate
29
+ # with subprocesses through an IO.
45
30
  #
46
- # ```ruby
47
- # "C:\\gumby\\ruby\\test.rb"
48
- # ```
31
+ # Ruby will convert pathnames between different operating system conventions if
32
+ # possible. For instance, on a Windows system the filename
33
+ # `"/gumby/ruby/test.rb"` will be opened as `"\gumby\ruby\test.rb"`. When
34
+ # specifying a Windows-style filename in a Ruby string, remember to escape the
35
+ # backslashes:
49
36
  #
50
- # Our examples here will use the Unix-style forward slashes;
51
- # File::ALT\_SEPARATOR can be used to get the platform-specific separator
52
- # character.
37
+ # "C:\\gumby\\ruby\\test.rb"
53
38
  #
54
- # The global constant [ARGF](https://ruby-doc.org/core-2.6.3/ARGF.html)
55
- # (also accessible as `$<` ) provides an IO-like stream which allows
56
- # access to all files mentioned on the command line (or STDIN if no files
57
- # are mentioned).
58
- # [ARGF\#path](https://ruby-doc.org/core-2.6.3/ARGF.html#method-i-path)
59
- # and its alias
60
- # [ARGF\#filename](https://ruby-doc.org/core-2.6.3/ARGF.html#method-i-filename)
61
- # are provided to access the name of the file currently being read.
39
+ # Our examples here will use the Unix-style forward slashes; File::ALT_SEPARATOR
40
+ # can be used to get the platform-specific separator character.
62
41
  #
42
+ # The global constant ARGF (also accessible as `$<`) provides an IO-like stream
43
+ # which allows access to all files mentioned on the command line (or STDIN if no
44
+ # files are mentioned). ARGF#path and its alias ARGF#filename are provided to
45
+ # access the name of the file currently being read.
63
46
  #
64
- # The io/console extension provides methods for interacting with the
65
- # console. The console can be accessed from IO.console or the standard
66
- # input/output/error [IO](IO) objects.
47
+ # ## io/console
48
+ #
49
+ # The io/console extension provides methods for interacting with the console.
50
+ # The console can be accessed from IO.console or the standard input/output/error
51
+ # IO objects.
67
52
  #
68
53
  # Requiring io/console adds the following methods:
69
54
  #
70
- # - IO::console
55
+ # * IO::console
56
+ # * IO#raw
57
+ # * IO#raw!
58
+ # * IO#cooked
59
+ # * IO#cooked!
60
+ # * IO#getch
61
+ # * IO#echo=
62
+ # * IO#echo?
63
+ # * IO#noecho
64
+ # * IO#winsize
65
+ # * IO#winsize=
66
+ # * IO#iflush
67
+ # * IO#ioflush
68
+ # * IO#oflush
69
+ #
70
+ #
71
+ # Example:
72
+ #
73
+ # require 'io/console'
74
+ # rows, columns = $stdout.winsize
75
+ # puts "Your screen is #{columns} wide and #{rows} tall"
76
+ #
77
+ # ## Example Files
78
+ #
79
+ # Many examples here use these filenames and their corresponding files:
80
+ #
81
+ # * `t.txt`: A text-only file that is assumed to exist via:
82
+ #
83
+ # text = <<~EOT
84
+ # This is line one.
85
+ # This is the second line.
86
+ # This is the third line.
87
+ # EOT
88
+ # File.write('t.txt', text)
89
+ #
90
+ # * `t.dat`: A data file that is assumed to exist via:
91
+ #
92
+ # data = "\u9990\u9991\u9992\u9993\u9994"
93
+ # f = File.open('t.dat', 'wb:UTF-16')
94
+ # f.write(data)
95
+ # f.close
96
+ #
97
+ # * `t.rus`: A Russian-language text file that is assumed to exist via:
98
+ #
99
+ # File.write('t.rus', "\u{442 435 441 442}")
100
+ #
101
+ # * `t.tmp`: A file that is assumed *not* to exist.
102
+ #
71
103
  #
72
- # - IO\#raw
104
+ # ## Modes
73
105
  #
74
- # - IO\#raw\!
106
+ # A number of IO method calls must or may specify a *mode* for the stream; the
107
+ # mode determines how stream is to be accessible, including:
75
108
  #
76
- # - IO\#cooked
109
+ # * Whether the stream is to be read-only, write-only, or read-write.
110
+ # * Whether the stream is positioned at its beginning or its end.
111
+ # * Whether the stream treats data as text-only or binary.
112
+ # * The external and internal encodings.
77
113
  #
78
- # - IO\#cooked\!
79
114
  #
80
- # - IO\#getch
115
+ # ### Mode Specified as an Integer
81
116
  #
82
- # - IO\#echo=
117
+ # When `mode` is an integer it must be one or more (combined by bitwise OR (`|`)
118
+ # of the modes defined in File::Constants:
83
119
  #
84
- # - IO\#echo?
120
+ # * `File::RDONLY`: Open for reading only.
121
+ # * `File::WRONLY`: Open for writing only.
122
+ # * `File::RDWR`: Open for reading and writing.
123
+ # * `File::APPEND`: Open for appending only.
124
+ # * `File::CREAT`: Create file if it does not exist.
125
+ # * `File::EXCL`: Raise an exception if `File::CREAT` is given and the file
126
+ # exists.
85
127
  #
86
- # - IO\#noecho
87
128
  #
88
- # - IO\#winsize
129
+ # Examples:
89
130
  #
90
- # - IO\#winsize=
131
+ # File.new('t.txt', File::RDONLY)
132
+ # File.new('t.tmp', File::RDWR | File::CREAT | File::EXCL)
91
133
  #
92
- # - IO\#iflush
134
+ # Note: Method IO#set_encoding does not allow the mode to be specified as an
135
+ # integer.
93
136
  #
94
- # - IO\#ioflush
137
+ # ### Mode Specified As a String
138
+ #
139
+ # When `mode` is a string it must begin with one of the following:
140
+ #
141
+ # * `'r'`: Read-only stream, positioned at the beginning; the stream cannot be
142
+ # changed to writable.
143
+ # * `'w'`: Write-only stream, positioned at the beginning; the stream cannot
144
+ # be changed to readable.
145
+ # * `'a'`: Write-only stream, positioned at the end; every write appends to
146
+ # the end; the stream cannot be changed to readable.
147
+ # * `'r+'`: Read-write stream, positioned at the beginning.
148
+ # * `'w+'`: Read-write stream, positioned at the end.
149
+ # * `'a+'`: Read-write stream, positioned at the end.
150
+ #
151
+ #
152
+ # For a writable file stream (that is, any except read-only), the file is
153
+ # truncated to zero if it exists, and is created if it does not exist.
154
+ #
155
+ # Examples:
156
+ #
157
+ # File.open('t.txt', 'r')
158
+ # File.open('t.tmp', 'w')
159
+ #
160
+ # Either of the following may be suffixed to any of the above:
161
+ #
162
+ # * `'t'`: Text data; sets the default external encoding to `Encoding::UTF_8`;
163
+ # on Windows, enables conversion between EOL and CRLF.
164
+ # * `'b'`: Binary data; sets the default external encoding to
165
+ # `Encoding::ASCII_8BIT`; on Windows, suppresses conversion between EOL and
166
+ # CRLF.
167
+ #
168
+ #
169
+ # If neither is given, the stream defaults to text data.
170
+ #
171
+ # Examples:
172
+ #
173
+ # File.open('t.txt', 'rt')
174
+ # File.open('t.dat', 'rb')
175
+ #
176
+ # The following may be suffixed to any writable mode above:
177
+ #
178
+ # * `'x'`: Creates the file if it does not exist; raises an exception if the
179
+ # file exists.
95
180
  #
96
- # - IO\#oflush
97
181
  #
98
182
  # Example:
99
183
  #
100
- # ```ruby
101
- # require 'io/console'
102
- # rows, columns = $stdout.winsize
103
- # puts "Your screen is #{columns} wide and #{rows} tall"
104
- # ```
184
+ # File.open('t.tmp', 'wx')
185
+ #
186
+ # Finally, the mode string may specify encodings -- either external encoding
187
+ # only or both external and internal encodings -- by appending one or both
188
+ # encoding names, separated by colons:
189
+ #
190
+ # f = File.new('t.dat', 'rb')
191
+ # f.external_encoding # => #<Encoding:ASCII-8BIT>
192
+ # f.internal_encoding # => nil
193
+ # f = File.new('t.dat', 'rb:UTF-16')
194
+ # f.external_encoding # => #<Encoding:UTF-16 (dummy)>
195
+ # f.internal_encoding # => nil
196
+ # f = File.new('t.dat', 'rb:UTF-16:UTF-16')
197
+ # f.external_encoding # => #<Encoding:UTF-16 (dummy)>
198
+ # f.internal_encoding # => #<Encoding:UTF-16>
199
+ #
200
+ # The numerous encoding names are available in array Encoding.name_list:
201
+ #
202
+ # Encoding.name_list.size # => 175
203
+ # Encoding.name_list.take(3) # => ["ASCII-8BIT", "UTF-8", "US-ASCII"]
204
+ #
205
+ # ## Encodings
206
+ #
207
+ # When the external encoding is set, strings read are tagged by that encoding
208
+ # when reading, and strings written are converted to that encoding when writing.
209
+ #
210
+ # When both external and internal encodings are set, strings read are converted
211
+ # from external to internal encoding, and strings written are converted from
212
+ # internal to external encoding. For further details about transcoding input and
213
+ # output, see Encoding.
214
+ #
215
+ # If the external encoding is `'BOM|UTF-8'`, `'BOM|UTF-16LE'` or
216
+ # `'BOM|UTF16-BE'`, Ruby checks for a Unicode BOM in the input document to help
217
+ # determine the encoding. For UTF-16 encodings the file open mode must be
218
+ # binary. If the BOM is found, it is stripped and the external encoding from the
219
+ # BOM is used.
220
+ #
221
+ # Note that the BOM-style encoding option is case insensitive, so 'bom|utf-8' is
222
+ # also valid.)
223
+ #
224
+ # ## Open Options
225
+ #
226
+ # A number of IO methods accept an optional parameter `opts`, which determines
227
+ # how a new stream is to be opened:
228
+ #
229
+ # * `:mode`: Stream mode.
230
+ # * `:flags`: Integer file open flags; If `mode` is also given, the two are
231
+ # bitwise-ORed.
232
+ # * `:external_encoding`: External encoding for the stream.
233
+ # * `:internal_encoding`: Internal encoding for the stream. `'-'` is a synonym
234
+ # for the default internal encoding. If the value is `nil` no conversion
235
+ # occurs.
236
+ # * `:encoding`: Specifies external and internal encodings as
237
+ # `'extern:intern'`.
238
+ # * `:textmode`: If a truthy value, specifies the mode as text-only, binary
239
+ # otherwise.
240
+ # * `:binmode`: If a truthy value, specifies the mode as binary, text-only
241
+ # otherwise.
242
+ # * `:autoclose`: If a truthy value, specifies that the `fd` will close when
243
+ # the stream closes; otherwise it remains open.
244
+ #
245
+ #
246
+ # Also available are the options offered in String#encode, which may control
247
+ # conversion between external internal encoding.
248
+ #
249
+ # ## Getline Options
250
+ #
251
+ # A number of IO methods accept optional keyword arguments that determine how a
252
+ # stream is to be treated:
253
+ #
254
+ # * `:chomp`: If `true`, line separators are omitted; default is `false`.
255
+ #
256
+ #
257
+ # ## Position
258
+ #
259
+ # An IO stream has a *position*, which is the non-negative integer offset (in
260
+ # bytes) in the stream where the next read or write will occur.
261
+ #
262
+ # Note that a text stream may have multi-byte characters, so a text stream whose
263
+ # position is `n` (*bytes*) may not have `n` *characters* preceding the current
264
+ # position -- there may be fewer.
265
+ #
266
+ # A new stream is initially positioned:
267
+ #
268
+ # * At the beginning (position `0`) if its mode is `'r'`, `'w'`, or `'r+'`.
269
+ # * At the end (position `self.size`) if its mode is `'a'`, `'w+'`, or `'a+'`.
270
+ #
271
+ #
272
+ # Methods to query the position:
273
+ #
274
+ # * IO#tell and its alias IO#pos return the position for an open stream.
275
+ # * IO#eof? and its alias IO#eof return whether the position is at the end of
276
+ # a readable stream.
277
+ #
278
+ #
279
+ # Reading from a stream usually changes its position:
280
+ #
281
+ # f = File.open('t.txt')
282
+ # f.tell # => 0
283
+ # f.readline # => "This is line one.\n"
284
+ # f.tell # => 19
285
+ # f.readline # => "This is the second line.\n"
286
+ # f.tell # => 45
287
+ # f.eof? # => false
288
+ # f.readline # => "Here's the third line.\n"
289
+ # f.eof? # => true
290
+ #
291
+ # Writing to a stream usually changes its position:
292
+ #
293
+ # f = File.open('t.tmp', 'w')
294
+ # f.tell # => 0
295
+ # f.write('foo') # => 3
296
+ # f.tell # => 3
297
+ # f.write('bar') # => 3
298
+ # f.tell # => 6
299
+ #
300
+ # Iterating over a stream usually changes its position:
301
+ #
302
+ # f = File.open('t.txt')
303
+ # f.each do |line|
304
+ # p "position=#{f.pos} eof?=#{f.eof?} line=#{line}"
305
+ # end
306
+ #
307
+ # Output:
308
+ #
309
+ # "position=19 eof?=false line=This is line one.\n"
310
+ # "position=45 eof?=false line=This is the second line.\n"
311
+ # "position=70 eof?=true line=This is the third line.\n"
312
+ #
313
+ # The position may also be changed by certain other methods:
314
+ #
315
+ # * IO#pos= and IO#seek change the position to a specified offset.
316
+ # * IO#rewind changes the position to the beginning.
317
+ #
318
+ #
319
+ # ## Line Number
320
+ #
321
+ # A readable IO stream has a *line* *number*, which is the non-negative integer
322
+ # line number in the stream where the next read will occur.
323
+ #
324
+ # A new stream is initially has line number `0`.
325
+ #
326
+ # Method IO#lineno returns the line number.
327
+ #
328
+ # Reading lines from a stream usually changes its line number:
329
+ #
330
+ # f = File.open('t.txt', 'r')
331
+ # f.lineno # => 0
332
+ # f.readline # => "This is line one.\n"
333
+ # f.lineno # => 1
334
+ # f.readline # => "This is the second line.\n"
335
+ # f.lineno # => 2
336
+ # f.readline # => "Here's the third line.\n"
337
+ # f.lineno # => 3
338
+ # f.eof? # => true
339
+ #
340
+ # Iterating over lines in a stream usually changes its line number:
341
+ #
342
+ # f = File.open('t.txt')
343
+ # f.each_line do |line|
344
+ # p "position=#{f.pos} eof?=#{f.eof?} line=#{line}"
345
+ # end
346
+ #
347
+ # Output:
348
+ #
349
+ # "position=19 eof?=false line=This is line one.\n"
350
+ # "position=45 eof?=false line=This is the second line.\n"
351
+ # "position=70 eof?=true line=This is the third line.\n"
352
+ #
353
+ # ## What's Here
354
+ #
355
+ # First, what's elsewhere. Class IO:
356
+ #
357
+ # * Inherits from [class
358
+ # Object](Object.html#class-Object-label-What-27s+Here).
359
+ # * Includes [module
360
+ # Enumerable](Enumerable.html#module-Enumerable-label-What-27s+Here), which
361
+ # provides dozens of additional methods.
362
+ #
363
+ #
364
+ # Here, class IO provides methods that are useful for:
365
+ #
366
+ # * [Creating](#class-IO-label-Creating)
367
+ # * [Reading](#class-IO-label-Reading)
368
+ # * [Writing](#class-IO-label-Writing)
369
+ # * [Positioning](#class-IO-label-Positioning)
370
+ # * [Iterating](#class-IO-label-Iterating)
371
+ # * [Settings](#class-IO-label-Settings)
372
+ # * [Querying](#class-IO-label-Querying)
373
+ # * [Buffering](#class-IO-label-Buffering)
374
+ # * [Low-Level Access](#class-IO-label-Low-Level+Access)
375
+ # * [Other](#class-IO-label-Other)
376
+ #
377
+ #
378
+ # ### Creating
379
+ #
380
+ # ::new (aliased as ::for_fd)
381
+ # : Creates and returns a new IO object for the given integer file
382
+ # descriptor.
383
+ #
384
+ # ::open
385
+ # : Creates a new IO object.
386
+ #
387
+ # ::pipe
388
+ # : Creates a connected pair of reader and writer IO objects.
389
+ #
390
+ # ::popen
391
+ # : Creates an IO object to interact with a subprocess.
392
+ #
393
+ # ::select
394
+ # : Selects which given IO instances are ready for reading,
395
+ #
396
+ # writing, or have pending exceptions.
397
+ #
398
+ #
399
+ # ### Reading
400
+ #
401
+ # ::binread
402
+ # : Returns a binary string with all or a subset of bytes from the given
403
+ # file.
404
+ #
405
+ # ::read
406
+ # : Returns a string with all or a subset of bytes from the given file.
407
+ #
408
+ # ::readlines
409
+ # : Returns an array of strings, which are the lines from the given file.
410
+ #
411
+ # #getbyte
412
+ # : Returns the next 8-bit byte read from `self` as an integer.
413
+ #
414
+ # #getc
415
+ # : Returns the next character read from `self` as a string.
416
+ #
417
+ # #gets
418
+ # : Returns the line read from `self`.
419
+ #
420
+ # #pread
421
+ # : Returns all or the next *n* bytes read from `self`, not updating the
422
+ # receiver's offset.
423
+ #
424
+ # #read
425
+ # : Returns all remaining or the next *n* bytes read from `self` for a
426
+ # given *n*.
427
+ #
428
+ # #read_nonblock
429
+ # : the next *n* bytes read from `self` for a given *n*, in non-block
430
+ # mode.
431
+ #
432
+ # #readbyte
433
+ # : Returns the next byte read from `self`; same as #getbyte, but raises
434
+ # an exception on end-of-file.
435
+ #
436
+ # #readchar
437
+ # : Returns the next character read from `self`; same as #getc, but raises
438
+ # an exception on end-of-file.
439
+ #
440
+ # #readline
441
+ # : Returns the next line read from `self`; same as #getline, but raises
442
+ # an exception of end-of-file.
443
+ #
444
+ # #readlines
445
+ # : Returns an array of all lines read read from `self`.
446
+ #
447
+ # #readpartial
448
+ # : Returns up to the given number of bytes from `self`.
449
+ #
450
+ #
451
+ #
452
+ # ### Writing
453
+ #
454
+ # ::binwrite
455
+ # : Writes the given string to the file at the given filepath, in binary
456
+ # mode.
457
+ #
458
+ # ::write
459
+ # : Writes the given string to `self`.
460
+ #
461
+ # [:<<](#method-i-3C-3C)
462
+ # : Appends the given string to `self`.
463
+ #
464
+ # #print
465
+ # : Prints last read line or given objects to `self`.
466
+ #
467
+ # #printf
468
+ # : Writes to `self` based on the given format string and objects.
469
+ #
470
+ # #putc
471
+ # : Writes a character to `self`.
472
+ #
473
+ # #puts
474
+ # : Writes lines to `self`, making sure line ends with a newline.
475
+ #
476
+ # #pwrite
477
+ # : Writes the given string at the given offset, not updating the
478
+ # receiver's offset.
479
+ #
480
+ # #write
481
+ # : Writes one or more given strings to `self`.
482
+ #
483
+ # #write_nonblock
484
+ # : Writes one or more given strings to `self` in non-blocking mode.
485
+ #
486
+ #
487
+ #
488
+ # ### Positioning
489
+ #
490
+ # #lineno
491
+ # : Returns the current line number in `self`.
492
+ #
493
+ # #lineno=
494
+ # : Sets the line number is `self`.
495
+ #
496
+ # #pos (aliased as #tell)
497
+ # : Returns the current byte offset in `self`.
498
+ #
499
+ # #pos=
500
+ # : Sets the byte offset in `self`.
501
+ #
502
+ # #reopen
503
+ # : Reassociates `self` with a new or existing IO stream.
504
+ #
505
+ # #rewind
506
+ # : Positions `self` to the beginning of input.
507
+ #
508
+ # #seek
509
+ # : Sets the offset for `self` relative to given position.
510
+ #
511
+ #
512
+ #
513
+ # ### Iterating
514
+ #
515
+ # ::foreach
516
+ # : Yields each line of given file to the block.
517
+ #
518
+ # #each (aliased as #each_line)
519
+ # : Calls the given block with each successive line in `self`.
520
+ #
521
+ # #each_byte
522
+ # : Calls the given block with each successive byte in `self` as an
523
+ # integer.
524
+ #
525
+ # #each_char
526
+ # : Calls the given block with each successive character in `self` as a
527
+ # string.
528
+ #
529
+ # #each_codepoint
530
+ # : Calls the given block with each successive codepoint in `self` as an
531
+ # integer.
532
+ #
533
+ #
534
+ #
535
+ # ### Settings
536
+ #
537
+ # #autoclose=
538
+ # : Sets whether `self` auto-closes.
539
+ #
540
+ # #binmode
541
+ # : Sets `self` to binary mode.
542
+ #
543
+ # #close
544
+ # : Closes `self`.
545
+ #
546
+ # #close_on_exec=
547
+ # : Sets the close-on-exec flag.
548
+ #
549
+ # #close_read
550
+ # : Closes `self` for reading.
551
+ #
552
+ # #close_write
553
+ # : Closes `self` for writing.
554
+ #
555
+ # #set_encoding
556
+ # : Sets the encoding for `self`.
557
+ #
558
+ # #set_encoding_by_bom
559
+ # : Sets the encoding for `self`, based on its Unicode byte-order-mark.
560
+ #
561
+ # #sync=
562
+ # : Sets the sync-mode to the given value.
563
+ #
564
+ #
565
+ #
566
+ # ### Querying
567
+ #
568
+ # #autoclose?
569
+ # : Returns whether `self` auto-closes.
570
+ #
571
+ # #binmode?
572
+ # : Returns whether `self` is in binary mode.
573
+ #
574
+ # #close_on_exec?
575
+ # : Returns the close-on-exec flag for `self`.
576
+ #
577
+ # #closed?
578
+ # : Returns whether `self` is closed.
579
+ #
580
+ # #eof? (aliased as #eof)
581
+ # : Returns whether `self` is at end-of-file.
582
+ #
583
+ # #external_encoding
584
+ # : Returns the external encoding object for `self`.
585
+ #
586
+ # #fileno (aliased as #to_i)
587
+ # : Returns the integer file descriptor for `self`
588
+ #
589
+ # #internal_encoding
590
+ # : Returns the internal encoding object for `self`.
591
+ #
592
+ # #pid
593
+ # : Returns the process ID of a child process associated with `self`, if
594
+ # `self` was created by ::popen.
595
+ #
596
+ # #stat
597
+ # : Returns the File::Stat object containing status information for
598
+ # `self`.
599
+ #
600
+ # #sync
601
+ # : Returns whether `self` is in sync-mode.
602
+ #
603
+ # #tty (aliased as #isatty)
604
+ # : Returns whether `self` is a terminal.
605
+ #
606
+ #
607
+ #
608
+ # ### Buffering
609
+ #
610
+ # #fdatasync
611
+ # : Immediately writes all buffered data in `self` to disk.
612
+ #
613
+ # #flush
614
+ # : Flushes any buffered data within `self` to the underlying operating
615
+ # system.
616
+ #
617
+ # #fsync
618
+ # : Immediately writes all buffered data and attributes in `self` to disk.
619
+ #
620
+ # #ungetbyte
621
+ # : Prepends buffer for `self` with given integer byte or string.
622
+ #
623
+ # #ungetc
624
+ # : Prepends buffer for `self` with given string.
625
+ #
626
+ #
627
+ #
628
+ # ### Low-Level Access
629
+ #
630
+ # ::sysopen
631
+ # : Opens the file given by its path, returning the integer file
632
+ # descriptor.
633
+ #
634
+ # #advise
635
+ # : Announces the intention to access data from `self` in a specific way.
636
+ #
637
+ # #fcntl
638
+ # : Passes a low-level command to the file specified by the given file
639
+ # descriptor.
640
+ #
641
+ # #ioctl
642
+ # : Passes a low-level command to the device specified by the given file
643
+ # descriptor.
644
+ #
645
+ # #sysread
646
+ # : Returns up to the next *n* bytes read from self using a low-level
647
+ # read.
648
+ #
649
+ # #sysseek
650
+ # : Sets the offset for `self`.
651
+ #
652
+ # #syswrite
653
+ # : Writes the given string to `self` using a low-level write.
654
+ #
655
+ #
656
+ #
657
+ # ### Other
658
+ #
659
+ # ::copy_stream
660
+ # : Copies data from a source to a destination, each of which is a
661
+ # filepath or an IO-like object.
662
+ #
663
+ # ::try_convert
664
+ # : Returns a new IO object resulting from converting the given object.
665
+ #
666
+ # #inspect
667
+ # : Returns the string representation of `self`.
668
+ #
669
+ %a{annotate:rdoc:source:from=io.c}
105
670
  class IO < Object
106
671
  include File::Constants
107
672
 
108
673
  include Enumerable[String]
109
674
 
110
- # String Output---Writes *obj* to *ios*. *obj* will be converted to a string
111
- # using `to_s`.
675
+ # <!--
676
+ # rdoc-file=io.c
677
+ # - self << object -> self
678
+ # -->
679
+ # Writes the given `object` to `self`, which must be opened for writing (see
680
+ # [Modes](#class-IO-label-Modes)); returns `self`; if `object` is not a string,
681
+ # it is converted via method `to_s`:
112
682
  #
113
- # $stdout << "Hello " << "world!\n"
683
+ # $stdout << 'Hello' << ', ' << 'World!' << "\n"
684
+ # $stdout << 'foo' << :bar << 2 << "\n"
114
685
  #
115
- # *produces:*
686
+ # Output:
116
687
  #
117
- # Hello world!
688
+ # Hello, World!
689
+ # foobar2
118
690
  #
119
691
  def <<: (_ToS obj) -> self
120
692
 
693
+ # <!--
694
+ # rdoc-file=io.c
695
+ # - ios.advise(advice, offset=0, len=0) -> nil
696
+ # -->
121
697
  # Announce an intention to access data from the current file in a specific
122
698
  # pattern. On platforms that do not support the *posix_fadvise(2)* system call,
123
699
  # this method is a no-op.
@@ -167,8 +743,12 @@ class IO < Object
167
743
  # This list is not exhaustive; other Errno
168
744
  # : exceptions are also possible.
169
745
  #
170
- def advise: ((:normal | :sequential | :random | :willneed | :dontneed | :noreuse) advise, ?Integer offset, ?Integer len) -> nil
746
+ def advise: (:normal | :sequential | :random | :willneed | :dontneed | :noreuse advise, ?Integer offset, ?Integer len) -> nil
171
747
 
748
+ # <!--
749
+ # rdoc-file=io.c
750
+ # - io.autoclose = bool -> true or false
751
+ # -->
172
752
  # Sets auto-close flag.
173
753
  #
174
754
  # f = open("/dev/null")
@@ -183,77 +763,117 @@ class IO < Object
183
763
  #
184
764
  def autoclose=: (boolish) -> untyped
185
765
 
766
+ # <!--
767
+ # rdoc-file=io.c
768
+ # - ios.autoclose? -> true or false
769
+ # -->
186
770
  # Returns `true` if the underlying file descriptor of *ios* will be closed
187
771
  # automatically at its finalization, otherwise `false`.
188
772
  #
189
773
  def autoclose?: () -> bool
190
774
 
191
- # Puts *ios* into binary mode. Once a stream is in binary mode, it cannot
192
- # be reset to nonbinary mode.
193
- #
194
- # - newline conversion disabled
775
+ # <!--
776
+ # rdoc-file=io.c
777
+ # - ios.binmode -> ios
778
+ # -->
779
+ # Puts *ios* into binary mode. Once a stream is in binary mode, it cannot be
780
+ # reset to nonbinary mode.
195
781
  #
196
- # - encoding conversion disabled
782
+ # * newline conversion disabled
783
+ # * encoding conversion disabled
784
+ # * content is treated as ASCII-8BIT
197
785
  #
198
- # - content is treated as ASCII-8BIT
199
786
  def binmode: () -> self
200
787
 
788
+ # <!--
789
+ # rdoc-file=io.c
790
+ # - ios.binmode? -> true or false
791
+ # -->
201
792
  # Returns `true` if *ios* is binmode.
793
+ #
202
794
  def binmode?: () -> bool
203
795
 
796
+ # <!--
797
+ # rdoc-file=io.c
798
+ # - ios.close -> nil
799
+ # -->
204
800
  # Closes *ios* and flushes any pending writes to the operating system. The
205
- # stream is unavailable for any further data operations; an `IOError` is
206
- # raised if such an attempt is made. I/O streams are automatically closed
207
- # when they are claimed by the garbage collector.
801
+ # stream is unavailable for any further data operations; an IOError is raised if
802
+ # such an attempt is made. I/O streams are automatically closed when they are
803
+ # claimed by the garbage collector.
804
+ #
805
+ # If *ios* is opened by IO.popen, #close sets `$?`.
208
806
  #
209
- # If *ios* is opened by `IO.popen`, `close` sets `$?` .
807
+ # Calling this method on closed IO object is just ignored since Ruby 2.3.
210
808
  #
211
- # Calling this method on closed [IO](IO.downloaded.ruby_doc) object is
212
- # just ignored since Ruby 2.3.
213
809
  def close: () -> NilClass
214
810
 
811
+ # <!--
812
+ # rdoc-file=io.c
813
+ # - ios.close_on_exec = bool -> true or false
814
+ # -->
815
+ # Sets a close-on-exec flag.
816
+ #
817
+ # f = open("/dev/null")
818
+ # f.close_on_exec = true
819
+ # system("cat", "/proc/self/fd/#{f.fileno}") # cat: /proc/self/fd/3: No such file or directory
820
+ # f.closed? #=> false
821
+ #
822
+ # Ruby sets close-on-exec flags of all file descriptors by default since Ruby
823
+ # 2.0.0. So you don't need to set by yourself. Also, unsetting a close-on-exec
824
+ # flag can cause file descriptor leak if another thread use fork() and exec()
825
+ # (via system() method for example). If you really needs file descriptor
826
+ # inheritance to child process, use spawn()'s argument such as fd=>fd.
827
+ #
215
828
  def close_on_exec=: (boolish) -> untyped
216
829
 
830
+ # <!--
831
+ # rdoc-file=io.c
832
+ # - ios.close_on_exec? -> true or false
833
+ # -->
217
834
  # Returns `true` if *ios* will be closed on exec.
218
835
  #
219
- # ```ruby
220
- # f = open("/dev/null")
221
- # f.close_on_exec? #=> false
222
- # f.close_on_exec = true
223
- # f.close_on_exec? #=> true
224
- # f.close_on_exec = false
225
- # f.close_on_exec? #=> false
226
- # ```
836
+ # f = open("/dev/null")
837
+ # f.close_on_exec? #=> false
838
+ # f.close_on_exec = true
839
+ # f.close_on_exec? #=> true
840
+ # f.close_on_exec = false
841
+ # f.close_on_exec? #=> false
842
+ #
227
843
  def close_on_exec?: () -> bool
228
844
 
229
- # Closes the read end of a duplex I/O stream (i.e., one that contains both
230
- # a read and a write stream, such as a pipe). Will raise an `IOError` if
231
- # the stream is not duplexed.
845
+ # <!--
846
+ # rdoc-file=io.c
847
+ # - ios.close_read -> nil
848
+ # -->
849
+ # Closes the read end of a duplex I/O stream (i.e., one that contains both a
850
+ # read and a write stream, such as a pipe). Will raise an IOError if the stream
851
+ # is not duplexed.
232
852
  #
233
- # ```ruby
234
- # f = IO.popen("/bin/sh","r+")
235
- # f.close_read
236
- # f.readlines
237
- # ```
853
+ # f = IO.popen("/bin/sh","r+")
854
+ # f.close_read
855
+ # f.readlines
238
856
  #
239
857
  # *produces:*
240
858
  #
241
859
  # prog.rb:3:in `readlines': not opened for reading (IOError)
242
860
  # from prog.rb:3
243
861
  #
244
- # Calling this method on closed [IO](IO.downloaded.ruby_doc) object is
245
- # just ignored since Ruby 2.3.
862
+ # Calling this method on closed IO object is just ignored since Ruby 2.3.
863
+ #
246
864
  def close_read: () -> NilClass
247
865
 
248
- # Closes the write end of a duplex I/O stream (i.e., one that contains
249
- # both a read and a write stream, such as a pipe). Will raise an `IOError`
250
- # if the stream is not duplexed.
866
+ # <!--
867
+ # rdoc-file=io.c
868
+ # - ios.close_write -> nil
869
+ # -->
870
+ # Closes the write end of a duplex I/O stream (i.e., one that contains both a
871
+ # read and a write stream, such as a pipe). Will raise an IOError if the stream
872
+ # is not duplexed.
251
873
  #
252
- # ```ruby
253
- # f = IO.popen("/bin/sh","r+")
254
- # f.close_write
255
- # f.print "nowhere"
256
- # ```
874
+ # f = IO.popen("/bin/sh","r+")
875
+ # f.close_write
876
+ # f.print "nowhere"
257
877
  #
258
878
  # *produces:*
259
879
  #
@@ -261,469 +881,1404 @@ class IO < Object
261
881
  # from prog.rb:3:in `print'
262
882
  # from prog.rb:3
263
883
  #
264
- # Calling this method on closed [IO](IO.downloaded.ruby_doc) object is
265
- # just ignored since Ruby 2.3.
884
+ # Calling this method on closed IO object is just ignored since Ruby 2.3.
885
+ #
266
886
  def close_write: () -> NilClass
267
887
 
268
- # Returns `true` if *ios* is completely closed (for duplex streams, both
269
- # reader and writer), `false` otherwise.
270
- #
271
- # ```ruby
272
- # f = File.new("testfile")
273
- # f.close #=> nil
274
- # f.closed? #=> true
275
- # f = IO.popen("/bin/sh","r+")
276
- # f.close_write #=> nil
277
- # f.closed? #=> false
278
- # f.close_read #=> nil
279
- # f.closed? #=> true
280
- # ```
888
+ # <!--
889
+ # rdoc-file=io.c
890
+ # - ios.closed? -> true or false
891
+ # -->
892
+ # Returns `true` if *ios* is completely closed (for duplex streams, both reader
893
+ # and writer), `false` otherwise.
894
+ #
895
+ # f = File.new("testfile")
896
+ # f.close #=> nil
897
+ # f.closed? #=> true
898
+ # f = IO.popen("/bin/sh","r+")
899
+ # f.close_write #=> nil
900
+ # f.closed? #=> false
901
+ # f.close_read #=> nil
902
+ # f.closed? #=> true
903
+ #
281
904
  def closed?: () -> bool
282
905
 
906
+ # <!--
907
+ # rdoc-file=io.c
908
+ # - ios.each(sep=$/ [, getline_args]) {|line| block } -> ios
909
+ # - ios.each(limit [, getline_args]) {|line| block } -> ios
910
+ # - ios.each(sep, limit [, getline_args]) {|line| block } -> ios
911
+ # - ios.each(...) -> an_enumerator
912
+ # - ios.each_line(sep=$/ [, getline_args]) {|line| block } -> ios
913
+ # - ios.each_line(limit [, getline_args]) {|line| block } -> ios
914
+ # - ios.each_line(sep, limit [, getline_args]) {|line| block } -> ios
915
+ # - ios.each_line(...) -> an_enumerator
916
+ # -->
917
+ # Executes the block for every line in *ios*, where lines are separated by
918
+ # *sep*. *ios* must be opened for reading or an IOError will be raised.
919
+ #
920
+ # If no block is given, an enumerator is returned instead.
921
+ #
922
+ # f = File.new("testfile")
923
+ # f.each {|line| puts "#{f.lineno}: #{line}" }
924
+ #
925
+ # *produces:*
926
+ #
927
+ # 1: This is line one
928
+ # 2: This is line two
929
+ # 3: This is line three
930
+ # 4: And so on...
931
+ #
932
+ # See IO.readlines for details about getline_args.
933
+ #
283
934
  def each: (?String sep, ?Integer limit) { (String arg0) -> untyped } -> self
284
935
  | (?String sep, ?Integer limit) -> ::Enumerator[String, self]
285
936
 
937
+ # <!--
938
+ # rdoc-file=io.c
939
+ # - ios.each_byte {|byte| block } -> ios
940
+ # - ios.each_byte -> an_enumerator
941
+ # -->
942
+ # Calls the given block once for each byte (0..255) in *ios*, passing the byte
943
+ # as an argument. The stream must be opened for reading or an IOError will be
944
+ # raised.
945
+ #
946
+ # If no block is given, an enumerator is returned instead.
947
+ #
948
+ # f = File.new("testfile")
949
+ # checksum = 0
950
+ # f.each_byte {|x| checksum ^= x } #=> #<File:testfile>
951
+ # checksum #=> 12
952
+ #
286
953
  def each_byte: () { (Integer arg0) -> untyped } -> self
287
954
  | () -> ::Enumerator[Integer, self]
288
955
 
956
+ # <!--
957
+ # rdoc-file=io.c
958
+ # - ios.each_char {|c| block } -> ios
959
+ # - ios.each_char -> an_enumerator
960
+ # -->
961
+ # Calls the given block once for each character in *ios*, passing the character
962
+ # as an argument. The stream must be opened for reading or an IOError will be
963
+ # raised.
964
+ #
965
+ # If no block is given, an enumerator is returned instead.
966
+ #
967
+ # f = File.new("testfile")
968
+ # f.each_char {|c| print c, ' ' } #=> #<File:testfile>
969
+ #
289
970
  def each_char: () { (String arg0) -> untyped } -> self
290
971
  | () -> ::Enumerator[String, self]
291
972
 
973
+ # <!--
974
+ # rdoc-file=io.c
975
+ # - ios.each_codepoint {|c| block } -> ios
976
+ # - ios.each_codepoint -> an_enumerator
977
+ # -->
978
+ # Passes the Integer ordinal of each character in *ios*, passing the codepoint
979
+ # as an argument. The stream must be opened for reading or an IOError will be
980
+ # raised.
981
+ #
982
+ # If no block is given, an enumerator is returned instead.
983
+ #
292
984
  def each_codepoint: () { (Integer arg0) -> untyped } -> self
293
985
  | () -> ::Enumerator[Integer, self]
294
986
 
295
- # Returns true if *ios* is at end of file that means there are no more
296
- # data to read. The stream must be opened for reading or an `IOError` will
297
- # be raised.
987
+ # <!--
988
+ # rdoc-file=io.c
989
+ # - eof -> true or false
990
+ # -->
991
+ # Returns `true` if the stream is positioned at its end, `false` otherwise; see
992
+ # [Position](#class-IO-label-Position):
298
993
  #
299
- # ```ruby
300
- # f = File.new("testfile")
301
- # dummy = f.readlines
302
- # f.eof #=> true
303
- # ```
994
+ # f = File.open('t.txt')
995
+ # f.eof # => false
996
+ # f.seek(0, :END) # => 0
997
+ # f.eof # => true
304
998
  #
305
- # If *ios* is a stream such as pipe or socket, `IO#eof?` blocks until the
306
- # other end sends some data or closes it.
999
+ # Raises an exception unless the stream is opened for reading; see
1000
+ # [Mode](#class-IO-label-Mode).
307
1001
  #
308
- # ```ruby
309
- # r, w = IO.pipe
310
- # Thread.new { sleep 1; w.close }
311
- # r.eof? #=> true after 1 second blocking
1002
+ # If `self` is a stream such as pipe or socket, this method blocks until the
1003
+ # other end sends some data or closes it:
312
1004
  #
313
- # r, w = IO.pipe
314
- # Thread.new { sleep 1; w.puts "a" }
315
- # r.eof? #=> false after 1 second blocking
1005
+ # r, w = IO.pipe
1006
+ # Thread.new { sleep 1; w.close }
1007
+ # r.eof? # => true # After 1-second wait.
316
1008
  #
317
- # r, w = IO.pipe
318
- # r.eof? # blocks forever
319
- # ```
1009
+ # r, w = IO.pipe
1010
+ # Thread.new { sleep 1; w.puts "a" }
1011
+ # r.eof? # => false # After 1-second wait.
1012
+ #
1013
+ # r, w = IO.pipe
1014
+ # r.eof? # blocks forever
1015
+ #
1016
+ # Note that this method reads data to the input byte buffer. So IO#sysread may
1017
+ # not behave as you intend with IO#eof?, unless you call IO#rewind first (which
1018
+ # is not available for some streams).
1019
+ #
1020
+ # I#eof? is an alias for IO#eof.
320
1021
  #
321
- # Note that `IO#eof?` reads data to the input byte buffer. So `IO#sysread`
322
- # may not behave as you intend with `IO#eof?`, unless you call
323
- # `IO#rewind` first (which is not available for some streams).
324
1022
  def eof: () -> bool
325
1023
 
1024
+ # <!--
1025
+ # rdoc-file=io.c
1026
+ # - ios.fcntl(integer_cmd, arg) -> integer
1027
+ # -->
1028
+ # Provides a mechanism for issuing low-level commands to control or query
1029
+ # file-oriented I/O streams. Arguments and results are platform dependent. If
1030
+ # *arg* is a number, its value is passed directly. If it is a string, it is
1031
+ # interpreted as a binary sequence of bytes (Array#pack might be a useful way to
1032
+ # build this string). On Unix platforms, see `fcntl(2)` for details. Not
1033
+ # implemented on all platforms.
1034
+ #
326
1035
  def fcntl: (Integer integer_cmd, String | Integer arg) -> Integer
327
1036
 
328
- # Immediately writes all buffered data in *ios* to disk.
1037
+ # <!--
1038
+ # rdoc-file=io.c
1039
+ # - fdatasync -> 0
1040
+ # -->
1041
+ # Immediately writes to disk all data buffered in the stream, via the operating
1042
+ # system's: `fdatasync(2)`, if supported, otherwise via `fsync(2)`, if
1043
+ # supported; otherwise raises an exception.
329
1044
  #
330
- # If the underlying operating system does not support *fdatasync(2)* ,
331
- # `IO#fsync` is called instead (which might raise a `NotImplementedError`
332
- # ).
333
1045
  def fdatasync: () -> Integer?
334
1046
 
335
- # Returns an integer representing the numeric file descriptor for *ios* .
336
- #
337
- # ```ruby
338
- # $stdin.fileno #=> 0
339
- # $stdout.fileno #=> 1
340
- # ```
1047
+ # <!--
1048
+ # rdoc-file=io.c
1049
+ # - fileno -> integer
1050
+ # -->
1051
+ # Returns the integer file descriptor for the stream:
341
1052
  #
1053
+ # $stdin.fileno # => 0
1054
+ # $stdout.fileno # => 1
1055
+ # $stderr.fileno # => 2
1056
+ # File.open('t.txt').fileno # => 10
342
1057
  #
1058
+ # IO#to_i is an alias for IO#fileno.
343
1059
  #
344
- # Also aliased as: [to\_i](IO.downloaded.ruby_doc#method-i-to_i)
345
1060
  def fileno: () -> Integer
346
1061
 
347
- # Flushes any buffered data within *ios* to the underlying operating
348
- # system (note that this is Ruby internal buffering only; the OS may
349
- # buffer the data as well).
1062
+ # <!--
1063
+ # rdoc-file=io.c
1064
+ # - flush -> self
1065
+ # -->
1066
+ # Flushes data buffered in `self` to the operating system (but does not
1067
+ # necessarily flush data buffered in the operating system):
350
1068
  #
351
- # ```ruby
352
- # $stdout.print "no newline"
353
- # $stdout.flush
354
- # ```
1069
+ # $stdout.print 'no newline' # Not necessarily flushed.
1070
+ # $stdout.flush # Flushed.
355
1071
  #
356
- # *produces:*
357
- #
358
- # ```ruby
359
- # no newline
360
- # ```
361
1072
  def flush: () -> self
362
1073
 
363
- # Immediately writes all buffered data in *ios* to disk. Note that `fsync`
364
- # differs from using `IO#sync=` . The latter ensures that data is flushed
365
- # from Ruby’s buffers, but does not guarantee that the underlying
366
- # operating system actually writes it to disk.
1074
+ # <!--
1075
+ # rdoc-file=io.c
1076
+ # - fsync -> 0
1077
+ # -->
1078
+ # Immediately writes to disk all data buffered in the stream, via the operating
1079
+ # system's `fsync(2)`.
1080
+ #
1081
+ # Note this difference:
1082
+ #
1083
+ # * IO#sync=: Ensures that data is flushed from the stream's internal buffers,
1084
+ # but does not guarantee that the operating system actually writes the data
1085
+ # to disk.
1086
+ # * IO#fsync: Ensures both that data is flushed from internal buffers, and
1087
+ # that data is written to disk.
1088
+ #
1089
+ #
1090
+ # Raises an exception if the operating system does not support `fsync(2)`.
367
1091
  #
368
- # `NotImplementedError` is raised if the underlying operating system does
369
- # not support *fsync(2)* .
370
1092
  def fsync: () -> Integer?
371
1093
 
372
- # Gets the next 8-bit byte (0..255) from *ios* . Returns `nil` if called
373
- # at end of file.
1094
+ # <!--
1095
+ # rdoc-file=io.c
1096
+ # - ios.getbyte -> integer or nil
1097
+ # -->
1098
+ # Gets the next 8-bit byte (0..255) from *ios*. Returns `nil` if called at end
1099
+ # of file.
1100
+ #
1101
+ # f = File.new("testfile")
1102
+ # f.getbyte #=> 84
1103
+ # f.getbyte #=> 104
374
1104
  #
375
- # ```ruby
376
- # f = File.new("testfile")
377
- # f.getbyte #=> 84
378
- # f.getbyte #=> 104
379
- # ```
380
1105
  def getbyte: () -> Integer?
381
1106
 
382
- # Reads a one-character string from *ios* . Returns `nil` if called at end
383
- # of file.
1107
+ # <!--
1108
+ # rdoc-file=io.c
1109
+ # - ios.getc -> string or nil
1110
+ # -->
1111
+ # Reads a one-character string from *ios*. Returns `nil` if called at end of
1112
+ # file.
1113
+ #
1114
+ # f = File.new("testfile")
1115
+ # f.getc #=> "h"
1116
+ # f.getc #=> "e"
384
1117
  #
385
- # ```ruby
386
- # f = File.new("testfile")
387
- # f.getc #=> "h"
388
- # f.getc #=> "e"
389
- # ```
390
1118
  def getc: () -> String?
391
1119
 
1120
+ # <!--
1121
+ # rdoc-file=io.c
1122
+ # - gets(sep = $/, **getline_opts) -> string or nil
1123
+ # - gets(limit, **getline_opts) -> string or nil
1124
+ # - gets(sep, limit, **getline_opts) -> string or nil
1125
+ # -->
1126
+ # Reads and returns data from the stream; assigns the return value to `$_`.
1127
+ #
1128
+ # With no arguments given, returns the next line as determined by line separator
1129
+ # `$/`, or `nil` if none:
1130
+ #
1131
+ # f = File.open('t.txt')
1132
+ # f.gets # => "This is line one.\n"
1133
+ # $_ # => "This is line one.\n"
1134
+ # f.gets # => "This is the second line.\n"
1135
+ # f.gets # => "This is the third line.\n"
1136
+ # f.gets # => nil
1137
+ #
1138
+ # With string argument `sep` given, but not argument `limit`, returns the next
1139
+ # line as determined by line separator `sep`, or `nil` if none:
1140
+ #
1141
+ # f = File.open('t.txt')
1142
+ # f.gets(' is') # => "This is"
1143
+ # f.gets(' is') # => " line one.\nThis is"
1144
+ # f.gets(' is') # => " the second line.\nThis is"
1145
+ # f.gets(' is') # => " the third line.\n"
1146
+ # f.gets(' is') # => nil
1147
+ #
1148
+ # Note two special values for `sep`:
1149
+ #
1150
+ # * `nil`: The entire stream is read and returned.
1151
+ # * `''` (empty string): The next "paragraph" is read and returned, the
1152
+ # paragraph separator being two successive line separators.
1153
+ #
1154
+ #
1155
+ # With integer argument `limit` given, returns up to `limit+1` bytes:
1156
+ #
1157
+ # # Text with 1-byte characters.
1158
+ # File.open('t.txt') {|f| f.gets(1) } # => "T"
1159
+ # File.open('t.txt') {|f| f.gets(2) } # => "Th"
1160
+ # File.open('t.txt') {|f| f.gets(3) } # => "Thi"
1161
+ # File.open('t.txt') {|f| f.gets(4) } # => "This"
1162
+ # # No more than one line.
1163
+ # File.open('t.txt') {|f| f.gets(17) } # => "This is line one."
1164
+ # File.open('t.txt') {|f| f.gets(18) } # => "This is line one.\n"
1165
+ # File.open('t.txt') {|f| f.gets(19) } # => "This is line one.\n"
1166
+ #
1167
+ # # Text with 2-byte characters, which will not be split.
1168
+ # File.open('t.rus') {|f| f.gets(1).size } # => 1
1169
+ # File.open('t.rus') {|f| f.gets(2).size } # => 1
1170
+ # File.open('t.rus') {|f| f.gets(3).size } # => 2
1171
+ # File.open('t.rus') {|f| f.gets(4).size } # => 2
1172
+ #
1173
+ # With arguments `sep` and `limit`, combines the two behaviors above:
1174
+ #
1175
+ # * Returns the next line as determined by line separator `sep`, or `nil` if
1176
+ # none.
1177
+ # * But returns no more than `limit+1` bytes.
1178
+ #
1179
+ #
1180
+ # For all forms above, trailing optional keyword arguments may be given; see
1181
+ # [Getline Options](#class-IO-label-Getline+Options):
1182
+ #
1183
+ # f = File.open('t.txt')
1184
+ # # Chomp the lines.
1185
+ # f.gets(chomp: true) # => "This is line one."
1186
+ # f.gets(chomp: true) # => "This is the second line."
1187
+ # f.gets(chomp: true) # => "This is the third line."
1188
+ # f.gets(chomp: true) # => nil
1189
+ #
392
1190
  def gets: (?String sep, ?Integer limit) -> String?
393
1191
 
1192
+ # <!--
1193
+ # rdoc-file=io.c
1194
+ # - IO.new(fd [, mode] [, opt]) -> io
1195
+ # -->
1196
+ # Returns a new IO object (a stream) for the given integer file descriptor `fd`
1197
+ # and `mode` string. `opt` may be used to specify parts of `mode` in a more
1198
+ # readable fashion. See also IO.sysopen and IO.for_fd.
1199
+ #
1200
+ # IO.new is called by various File and IO opening methods such as IO::open,
1201
+ # Kernel#open, and File::open.
1202
+ #
1203
+ # ### Open Mode
1204
+ #
1205
+ # When `mode` is an integer it must be combination of the modes defined in
1206
+ # File::Constants (`File::RDONLY`, `File::WRONLY|File::CREAT`). See the open(2)
1207
+ # man page for more information.
1208
+ #
1209
+ # When `mode` is a string it must be in one of the following forms:
1210
+ #
1211
+ # fmode
1212
+ # fmode ":" ext_enc
1213
+ # fmode ":" ext_enc ":" int_enc
1214
+ # fmode ":" "BOM|UTF-*"
1215
+ #
1216
+ # `fmode` is an IO open mode string, `ext_enc` is the external encoding for the
1217
+ # IO and `int_enc` is the internal encoding.
1218
+ #
1219
+ # #### IO Open Mode
1220
+ #
1221
+ # Ruby allows the following open modes:
1222
+ #
1223
+ # "r" Read-only, starts at beginning of file (default mode).
1224
+ #
1225
+ # "r+" Read-write, starts at beginning of file.
1226
+ #
1227
+ # "w" Write-only, truncates existing file
1228
+ # to zero length or creates a new file for writing.
1229
+ #
1230
+ # "w+" Read-write, truncates existing file to zero length
1231
+ # or creates a new file for reading and writing.
1232
+ #
1233
+ # "a" Write-only, each write call appends data at end of file.
1234
+ # Creates a new file for writing if file does not exist.
1235
+ #
1236
+ # "a+" Read-write, each write call appends data at end of file.
1237
+ # Creates a new file for reading and writing if file does
1238
+ # not exist.
1239
+ #
1240
+ # The following modes must be used separately, and along with one or more of the
1241
+ # modes seen above.
1242
+ #
1243
+ # "b" Binary file mode
1244
+ # Suppresses EOL <-> CRLF conversion on Windows. And
1245
+ # sets external encoding to ASCII-8BIT unless explicitly
1246
+ # specified.
1247
+ #
1248
+ # "t" Text file mode
1249
+ #
1250
+ # The exclusive access mode ("x") can be used together with "w" to ensure the
1251
+ # file is created. Errno::EEXIST is raised when it already exists. It may not be
1252
+ # supported with all kinds of streams (e.g. pipes).
1253
+ #
1254
+ # When the open mode of original IO is read only, the mode cannot be changed to
1255
+ # be writable. Similarly, the open mode cannot be changed from write only to
1256
+ # readable.
1257
+ #
1258
+ # When such a change is attempted the error is raised in different locations
1259
+ # according to the platform.
1260
+ #
1261
+ # ### IO Encoding
1262
+ #
1263
+ # When `ext_enc` is specified, strings read will be tagged by the encoding when
1264
+ # reading, and strings output will be converted to the specified encoding when
1265
+ # writing.
1266
+ #
1267
+ # When `ext_enc` and `int_enc` are specified read strings will be converted from
1268
+ # `ext_enc` to `int_enc` upon input, and written strings will be converted from
1269
+ # `int_enc` to `ext_enc` upon output. See Encoding for further details of
1270
+ # transcoding on input and output.
1271
+ #
1272
+ # If "BOM|UTF-8", "BOM|UTF-16LE" or "BOM|UTF16-BE" are used, Ruby checks for a
1273
+ # Unicode BOM in the input document to help determine the encoding. For UTF-16
1274
+ # encodings the file open mode must be binary. When present, the BOM is
1275
+ # stripped and the external encoding from the BOM is used. When the BOM is
1276
+ # missing the given Unicode encoding is used as `ext_enc`. (The BOM-set
1277
+ # encoding option is case insensitive, so "bom|utf-8" is also valid.)
1278
+ #
1279
+ # ### Options
1280
+ #
1281
+ # `opt` can be used instead of `mode` for improved readability. The following
1282
+ # keys are supported:
1283
+ #
1284
+ # :mode
1285
+ # : Same as `mode` parameter
1286
+ #
1287
+ # :flags
1288
+ # : Specifies file open flags as integer. If `mode` parameter is given, this
1289
+ # parameter will be bitwise-ORed.
1290
+ #
1291
+ # :external_encoding
1292
+ # : External encoding for the IO.
1293
+ #
1294
+ # :internal_encoding
1295
+ # : Internal encoding for the IO. "-" is a synonym for the default internal
1296
+ # encoding.
1297
+ #
1298
+ # If the value is `nil` no conversion occurs.
1299
+ #
1300
+ # :encoding
1301
+ # : Specifies external and internal encodings as "extern:intern".
1302
+ #
1303
+ # :textmode
1304
+ # : If the value is truth value, same as "t" in argument `mode`.
1305
+ #
1306
+ # :binmode
1307
+ # : If the value is truth value, same as "b" in argument `mode`.
1308
+ #
1309
+ # :autoclose
1310
+ # : If the value is `false`, the `fd` will be kept open after this IO instance
1311
+ # gets finalized.
1312
+ #
1313
+ #
1314
+ # Also, `opt` can have same keys in String#encode for controlling conversion
1315
+ # between the external encoding and the internal encoding.
1316
+ #
1317
+ # ### Example 1
1318
+ #
1319
+ # fd = IO.sysopen("/dev/tty", "w")
1320
+ # a = IO.new(fd,"w")
1321
+ # $stderr.puts "Hello"
1322
+ # a.puts "World"
1323
+ #
1324
+ # Produces:
1325
+ #
1326
+ # Hello
1327
+ # World
1328
+ #
1329
+ # ### Example 2
1330
+ #
1331
+ # require 'fcntl'
1332
+ #
1333
+ # fd = STDERR.fcntl(Fcntl::F_DUPFD)
1334
+ # io = IO.new(fd, mode: 'w:UTF-16LE', cr_newline: true)
1335
+ # io.puts "Hello, World!"
1336
+ #
1337
+ # fd = STDERR.fcntl(Fcntl::F_DUPFD)
1338
+ # io = IO.new(fd, mode: 'w', cr_newline: true,
1339
+ # external_encoding: Encoding::UTF_16LE)
1340
+ # io.puts "Hello, World!"
1341
+ #
1342
+ # Both of above print "Hello, World!" in UTF-16LE to standard error output with
1343
+ # converting EOL generated by #puts to CR.
1344
+ #
394
1345
  def initialize: (Integer fd, ?Integer mode, ?Integer opt) -> void
395
1346
 
396
- # Return a string describing this [IO](IO.downloaded.ruby_doc) object.
1347
+ # <!--
1348
+ # rdoc-file=io.c
1349
+ # - inspect -> string
1350
+ # -->
1351
+ # Returns a string representation of `self`:
1352
+ #
1353
+ # f = File.open('t.txt')
1354
+ # f.inspect # => "#<File:t.txt>"
1355
+ #
397
1356
  def inspect: () -> String
398
1357
 
399
- # Returns the [Encoding](https://ruby-doc.org/core-2.6.3/Encoding.html) of
400
- # the internal string if conversion is specified. Otherwise returns `nil`
401
- # .
1358
+ # <!--
1359
+ # rdoc-file=io.c
1360
+ # - io.internal_encoding -> encoding
1361
+ # -->
1362
+ # Returns the Encoding of the internal string if conversion is specified.
1363
+ # Otherwise returns `nil`.
1364
+ #
402
1365
  def internal_encoding: () -> Encoding
403
1366
 
1367
+ # <!--
1368
+ # rdoc-file=io.c
1369
+ # - ios.ioctl(integer_cmd, arg) -> integer
1370
+ # -->
1371
+ # Provides a mechanism for issuing low-level commands to control or query I/O
1372
+ # devices. Arguments and results are platform dependent. If *arg* is a number,
1373
+ # its value is passed directly. If it is a string, it is interpreted as a binary
1374
+ # sequence of bytes. On Unix platforms, see `ioctl(2)` for details. Not
1375
+ # implemented on all platforms.
1376
+ #
404
1377
  def ioctl: (Integer integer_cmd, String | Integer arg) -> Integer
405
1378
 
406
- # Returns `true` if *ios* is associated with a terminal device (tty),
407
- # `false` otherwise.
1379
+ # <!--
1380
+ # rdoc-file=io.c
1381
+ # - ios.isatty -> true or false
1382
+ # - ios.tty? -> true or false
1383
+ # -->
1384
+ # Returns `true` if *ios* is associated with a terminal device (tty), `false`
1385
+ # otherwise.
1386
+ #
1387
+ # File.new("testfile").isatty #=> false
1388
+ # File.new("/dev/tty").isatty #=> true
408
1389
  #
409
- # ```ruby
410
- # File.new("testfile").isatty #=> false
411
- # File.new("/dev/tty").isatty #=> true
412
- # ```
413
1390
  def isatty: () -> bool
414
1391
 
415
- # Returns the current line number in *ios* . The stream must be opened for
416
- # reading. `lineno` counts the number of times
417
- # [gets](IO.downloaded.ruby_doc#method-i-gets) is called rather than the
418
- # number of newlines encountered. The two values will differ if
419
- # [gets](IO.downloaded.ruby_doc#method-i-gets) is called with a separator
420
- # other than newline.
1392
+ # <!--
1393
+ # rdoc-file=io.c
1394
+ # - ios.lineno -> integer
1395
+ # -->
1396
+ # Returns the current line number in *ios*. The stream must be opened for
1397
+ # reading. #lineno counts the number of times #gets is called rather than the
1398
+ # number of newlines encountered. The two values will differ if #gets is called
1399
+ # with a separator other than newline.
421
1400
  #
422
- # Methods that use `$/` like [each](IO.downloaded.ruby_doc#method-i-each)
423
- # , [lines](IO.downloaded.ruby_doc#method-i-lines) and
424
- # [readline](IO.downloaded.ruby_doc#method-i-readline) will also increment
425
- # `lineno` .
1401
+ # Methods that use `$/` like #each, #lines and #readline will also increment
1402
+ # #lineno.
426
1403
  #
427
1404
  # See also the `$.` variable.
428
1405
  #
429
- # ```ruby
430
- # f = File.new("testfile")
431
- # f.lineno #=> 0
432
- # f.gets #=> "This is line one\n"
433
- # f.lineno #=> 1
434
- # f.gets #=> "This is line two\n"
435
- # f.lineno #=> 2
436
- # ```
1406
+ # f = File.new("testfile")
1407
+ # f.lineno #=> 0
1408
+ # f.gets #=> "This is line one\n"
1409
+ # f.lineno #=> 1
1410
+ # f.gets #=> "This is line two\n"
1411
+ # f.lineno #=> 2
1412
+ #
437
1413
  def lineno: () -> Integer
438
1414
 
1415
+ # <!--
1416
+ # rdoc-file=io.c
1417
+ # - ios.lineno = integer -> integer
1418
+ # -->
1419
+ # Manually sets the current line number to the given value. `$.` is updated only
1420
+ # on the next read.
1421
+ #
1422
+ # f = File.new("testfile")
1423
+ # f.gets #=> "This is line one\n"
1424
+ # $. #=> 1
1425
+ # f.lineno = 1000
1426
+ # f.lineno #=> 1000
1427
+ # $. #=> 1 # lineno of last read
1428
+ # f.gets #=> "This is line two\n"
1429
+ # $. #=> 1001 # lineno of last read
1430
+ #
439
1431
  def lineno=: (Integer arg0) -> Integer
440
1432
 
441
- # Returns the process ID of a child process associated with *ios* . This
442
- # will be set by `IO.popen` .
443
- #
444
- # ```ruby
445
- # pipe = IO.popen("-")
446
- # if pipe
447
- # $stderr.puts "In parent, child pid is #{pipe.pid}"
448
- # else
449
- # $stderr.puts "In child, pid is #{$$}"
450
- # end
451
- # ```
1433
+ # <!--
1434
+ # rdoc-file=io.c
1435
+ # - pid -> integer or nil
1436
+ # -->
1437
+ # Returns the process ID of a child process associated with the stream, which
1438
+ # will have been set by IO#popen, or `nil` if the stream was not created by
1439
+ # IO#popen:
1440
+ #
1441
+ # pipe = IO.popen("-")
1442
+ # if pipe
1443
+ # $stderr.puts "In parent, child pid is #{pipe.pid}"
1444
+ # else
1445
+ # $stderr.puts "In child, pid is #{$$}"
1446
+ # end
452
1447
  #
453
- # *produces:*
1448
+ # Output:
454
1449
  #
455
1450
  # In child, pid is 26209
456
1451
  # In parent, child pid is 26209
1452
+ #
457
1453
  def pid: () -> Integer
458
1454
 
459
- # Returns the current offset (in bytes) of *ios* .
1455
+ # <!-- rdoc-file=io.c -->
1456
+ # Returns the current position (in bytes) in `self` (see
1457
+ # [Position](#class-IO-label-Position)):
1458
+ #
1459
+ # f = File.new('t.txt')
1460
+ # f.tell # => 0
1461
+ # f.readline # => "This is line one.\n"
1462
+ # f.tell # => 19
1463
+ #
1464
+ # Related: IO#pos=, IO#seek.
1465
+ #
1466
+ # IO#pos is an alias for IO#tell.
460
1467
  #
461
- # ```ruby
462
- # f = File.new("testfile")
463
- # f.pos #=> 0
464
- # f.gets #=> "This is line one\n"
465
- # f.pos #=> 17
466
- # ```
467
1468
  def pos: () -> Integer
468
1469
 
1470
+ # <!--
1471
+ # rdoc-file=io.c
1472
+ # - pos = new_position -> new_position
1473
+ # -->
1474
+ # Seeks to the given `new_position` (in bytes); see
1475
+ # [Position](#class-IO-label-Position):
1476
+ #
1477
+ # f = File.open('t.txt')
1478
+ # f.tell # => 0
1479
+ # f.pos = 20 # => 20
1480
+ # f.tell # => 20
1481
+ #
1482
+ # Related: IO#seek, IO#tell.
1483
+ #
469
1484
  def pos=: (Integer arg0) -> Integer
470
1485
 
1486
+ # <!--
1487
+ # rdoc-file=io.c
1488
+ # - ios.print -> nil
1489
+ # - ios.print(obj, ...) -> nil
1490
+ # -->
1491
+ # Writes the given object(s) to *ios*. Returns `nil`.
1492
+ #
1493
+ # The stream must be opened for writing. Each given object that isn't a string
1494
+ # will be converted by calling its `to_s` method. When called without arguments,
1495
+ # prints the contents of `$_`.
1496
+ #
1497
+ # If the output field separator (`$,`) is not `nil`, it is inserted between
1498
+ # objects. If the output record separator (`$\`) is not `nil`, it is appended to
1499
+ # the output.
1500
+ #
1501
+ # $stdout.print("This is ", 100, " percent.\n")
1502
+ #
1503
+ # *produces:*
1504
+ #
1505
+ # This is 100 percent.
1506
+ #
471
1507
  def print: (*untyped arg0) -> NilClass
472
1508
 
1509
+ # <!--
1510
+ # rdoc-file=io.c
1511
+ # - ios.printf(format_string [, obj, ...]) -> nil
1512
+ # -->
1513
+ # Formats and writes to *ios*, converting parameters under control of the format
1514
+ # string. See Kernel#sprintf for details.
1515
+ #
473
1516
  def printf: (String format_string, *untyped arg0) -> NilClass
474
1517
 
1518
+ # <!--
1519
+ # rdoc-file=io.c
1520
+ # - ios.putc(obj) -> obj
1521
+ # -->
1522
+ # If *obj* is Numeric, write the character whose code is the least-significant
1523
+ # byte of *obj*. If *obj* is String, write the first character of *obj* to
1524
+ # *ios*. Otherwise, raise TypeError.
1525
+ #
1526
+ # $stdout.putc "A"
1527
+ # $stdout.putc 65
1528
+ #
1529
+ # *produces:*
1530
+ #
1531
+ # AA
1532
+ #
475
1533
  def putc: (Numeric | String arg0) -> untyped
476
1534
 
1535
+ # <!--
1536
+ # rdoc-file=io.c
1537
+ # - ios.puts(obj, ...) -> nil
1538
+ # -->
1539
+ # Writes the given object(s) to *ios*. Writes a newline after any that do not
1540
+ # already end with a newline sequence. Returns `nil`.
1541
+ #
1542
+ # The stream must be opened for writing. If called with an array argument,
1543
+ # writes each element on a new line. Each given object that isn't a string or
1544
+ # array will be converted by calling its `to_s` method. If called without
1545
+ # arguments, outputs a single newline.
1546
+ #
1547
+ # $stdout.puts("this", "is", ["a", "test"])
1548
+ #
1549
+ # *produces:*
1550
+ #
1551
+ # this
1552
+ # is
1553
+ # a
1554
+ # test
1555
+ #
1556
+ # Note that `puts` always uses newlines and is not affected by the output record
1557
+ # separator (`$\`).
1558
+ #
477
1559
  def puts: (*untyped arg0) -> NilClass
478
1560
 
479
- # Reads *length* bytes from the I/O stream.
1561
+ # <!--
1562
+ # rdoc-file=io.c
1563
+ # - read(maxlen = nil) -> string or nil
1564
+ # - read(maxlen = nil, out_string) -> out_string or nil
1565
+ # -->
1566
+ # Reads bytes from the stream (in binary mode):
1567
+ #
1568
+ # * If `maxlen` is `nil`, reads all bytes.
1569
+ # * Otherwise reads `maxlen` bytes, if available.
1570
+ # * Otherwise reads all bytes.
1571
+ #
1572
+ #
1573
+ # Returns a string (either a new string or the given `out_string`) containing
1574
+ # the bytes read. The encoding of the string depends on both `maxLen` and
1575
+ # `out_string`:
1576
+ #
1577
+ # * `maxlen` is `nil`: uses internal encoding of `self` (regardless of whether
1578
+ # `out_string` was given).
1579
+ # * `maxlen` not `nil`:
1580
+ #
1581
+ # * `out_string` given: encoding of `out_string` not modified.
1582
+ # * `out_string` not given: ASCII-8BIT is used.
1583
+ #
1584
+ #
1585
+ #
1586
+ # **Without Argument `out_string`**
1587
+ #
1588
+ # When argument `out_string` is omitted, the returned value is a new string:
1589
+ #
1590
+ # f = File.new('t.txt')
1591
+ # f.read
1592
+ # # => "This is line one.\nThis is the second line.\nThis is the third line.\n"
1593
+ # f.rewind
1594
+ # f.read(40) # => "This is line one.\r\nThis is the second li"
1595
+ # f.read(40) # => "ne.\r\nThis is the third line.\r\n"
1596
+ # f.read(40) # => nil
1597
+ #
1598
+ # If `maxlen` is zero, returns an empty string.
1599
+ #
1600
+ # ** With Argument `out_string`**
1601
+ #
1602
+ # When argument `out_string` is given, the returned value is `out_string`, whose
1603
+ # content is replaced:
1604
+ #
1605
+ # f = File.new('t.txt')
1606
+ # s = 'foo' # => "foo"
1607
+ # f.read(nil, s) # => "This is line one.\nThis is the second line.\nThis is the third line.\n"
1608
+ # s # => "This is line one.\nThis is the second line.\nThis is the third line.\n"
1609
+ # f.rewind
1610
+ # s = 'bar'
1611
+ # f.read(40, s) # => "This is line one.\r\nThis is the second li"
1612
+ # s # => "This is line one.\r\nThis is the second li"
1613
+ # s = 'baz'
1614
+ # f.read(40, s) # => "ne.\r\nThis is the third line.\r\n"
1615
+ # s # => "ne.\r\nThis is the third line.\r\n"
1616
+ # s = 'bat'
1617
+ # f.read(40, s) # => nil
1618
+ # s # => ""
480
1619
  #
481
- # *length* must be a non-negative integer or `nil`.
1620
+ # Note that this method behaves like the fread() function in C. This means it
1621
+ # retries to invoke read(2) system calls to read data with the specified maxlen
1622
+ # (or until EOF).
482
1623
  #
483
- # If *length* is a positive integer, `read` tries to read *length* bytes without
484
- # any conversion (binary mode). It returns `nil` if an EOF is encountered before
485
- # anything can be read. Fewer than *length* bytes are returned if an EOF is
486
- # encountered during the read. In the case of an integer *length*, the resulting
487
- # string is always in ASCII-8BIT encoding.
1624
+ # This behavior is preserved even if the stream is in non-blocking mode. (This
1625
+ # method is non-blocking-flag insensitive as other methods.)
488
1626
  #
489
- # If *length* is omitted or is `nil`, it reads until EOF and the encoding
490
- # conversion is applied, if applicable. A string is returned even if EOF is
491
- # encountered before any data is read.
1627
+ # If you need the behavior like a single read(2) system call, consider
1628
+ # #readpartial, #read_nonblock, and #sysread.
492
1629
  #
493
- # If *length* is zero, it returns an empty string (`""`).
1630
+ def read: (?int? length, ?string outbuf) -> String?
1631
+
1632
+ # <!--
1633
+ # rdoc-file=io.rb
1634
+ # - ios.read_nonblock(maxlen [, options]) -> string
1635
+ # - ios.read_nonblock(maxlen, outbuf [, options]) -> outbuf
1636
+ # -->
1637
+ # Reads at most *maxlen* bytes from *ios* using the read(2) system call after
1638
+ # O_NONBLOCK is set for the underlying file descriptor.
494
1639
  #
495
1640
  # If the optional *outbuf* argument is present, it must reference a String,
496
1641
  # which will receive the data. The *outbuf* will contain only the received data
497
1642
  # after the method call even if it is not empty at the beginning.
498
1643
  #
499
- # When this method is called at end of file, it returns `nil` or `""`, depending
500
- # on *length*: `read`, `read(nil)`, and `read(0)` return `""`,
501
- # `read(*positive_integer*)` returns `nil`.
1644
+ # read_nonblock just calls the read(2) system call. It causes all errors the
1645
+ # read(2) system call causes: Errno::EWOULDBLOCK, Errno::EINTR, etc. The caller
1646
+ # should care such errors.
502
1647
  #
503
- # f = File.new("testfile")
504
- # f.read(16) #=> "This is line one"
1648
+ # If the exception is Errno::EWOULDBLOCK or Errno::EAGAIN, it is extended by
1649
+ # IO::WaitReadable. So IO::WaitReadable can be used to rescue the exceptions for
1650
+ # retrying read_nonblock.
505
1651
  #
506
- # # read whole file
507
- # open("file") do |f|
508
- # data = f.read # This returns a string even if the file is empty.
509
- # # ...
510
- # end
1652
+ # read_nonblock causes EOFError on EOF.
511
1653
  #
512
- # # iterate over fixed length records
513
- # open("fixed-record-file") do |f|
514
- # while record = f.read(256)
515
- # # ...
516
- # end
517
- # end
1654
+ # On some platforms, such as Windows, non-blocking mode is not supported on IO
1655
+ # objects other than sockets. In such cases, Errno::EBADF will be raised.
518
1656
  #
519
- # # iterate over variable length records,
520
- # # each record is prefixed by its 32-bit length
521
- # open("variable-record-file") do |f|
522
- # while len = f.read(4)
523
- # len = len.unpack("N")[0] # 32-bit length
524
- # record = f.read(len) # This returns a string even if len is 0.
525
- # end
1657
+ # If the read byte buffer is not empty, read_nonblock reads from the buffer like
1658
+ # readpartial. In this case, the read(2) system call is not called.
1659
+ #
1660
+ # When read_nonblock raises an exception kind of IO::WaitReadable, read_nonblock
1661
+ # should not be called until io is readable for avoiding busy loop. This can be
1662
+ # done as follows.
1663
+ #
1664
+ # # emulates blocking read (readpartial).
1665
+ # begin
1666
+ # result = io.read_nonblock(maxlen)
1667
+ # rescue IO::WaitReadable
1668
+ # IO.select([io])
1669
+ # retry
526
1670
  # end
527
1671
  #
528
- # Note that this method behaves like the fread() function in C. This means it
529
- # retries to invoke read(2) system calls to read data with the specified length
530
- # (or until EOF). This behavior is preserved even if *ios* is in non-blocking
531
- # mode. (This method is non-blocking flag insensitive as other methods.) If you
532
- # need the behavior like a single read(2) system call, consider #readpartial,
533
- # #read_nonblock, and #sysread.
1672
+ # Although IO#read_nonblock doesn't raise IO::WaitWritable.
1673
+ # OpenSSL::Buffering#read_nonblock can raise IO::WaitWritable. If IO and SSL
1674
+ # should be used polymorphically, IO::WaitWritable should be rescued too. See
1675
+ # the document of OpenSSL::Buffering#read_nonblock for sample code.
1676
+ #
1677
+ # Note that this method is identical to readpartial except the non-blocking flag
1678
+ # is set.
1679
+ #
1680
+ # By specifying a keyword argument *exception* to `false`, you can indicate that
1681
+ # read_nonblock should not raise an IO::WaitReadable exception, but return the
1682
+ # symbol `:wait_readable` instead. At EOF, it will return nil instead of raising
1683
+ # EOFError.
534
1684
  #
535
- def read: (?int? length, ?string outbuf) -> String?
536
-
537
1685
  def read_nonblock: (int len, ?string buf, ?exception: true) -> String
538
1686
  | (int len, ?string buf, exception: false) -> (String | :wait_readable | nil)
539
1687
 
540
- # Reads a byte as with `IO#getbyte`, but raises an `EOFError` on end of
541
- # file.
1688
+ # <!--
1689
+ # rdoc-file=io.c
1690
+ # - ios.readbyte -> integer
1691
+ # -->
1692
+ # Reads a byte as with IO#getbyte, but raises an EOFError on end of file.
1693
+ #
542
1694
  def readbyte: () -> Integer
543
1695
 
544
- # Reads a one-character string from *ios* . Raises an `EOFError` on end of
545
- # file.
1696
+ # <!--
1697
+ # rdoc-file=io.c
1698
+ # - ios.readchar -> string
1699
+ # -->
1700
+ # Reads a one-character string from *ios*. Raises an EOFError on end of file.
1701
+ #
1702
+ # f = File.new("testfile")
1703
+ # f.readchar #=> "h"
1704
+ # f.readchar #=> "e"
546
1705
  #
547
- # ```ruby
548
- # f = File.new("testfile")
549
- # f.readchar #=> "h"
550
- # f.readchar #=> "e"
551
- # ```
552
1706
  def readchar: () -> String
553
1707
 
1708
+ # <!--
1709
+ # rdoc-file=io.c
1710
+ # - ios.readline(sep=$/ [, getline_args]) -> string
1711
+ # - ios.readline(limit [, getline_args]) -> string
1712
+ # - ios.readline(sep, limit [, getline_args]) -> string
1713
+ # -->
1714
+ # Reads a line as with IO#gets, but raises an EOFError on end of file.
1715
+ #
554
1716
  def readline: (?String sep, ?Integer limit) -> String
555
1717
 
1718
+ # <!--
1719
+ # rdoc-file=io.c
1720
+ # - ios.readlines(sep=$/ [, getline_args]) -> array
1721
+ # - ios.readlines(limit [, getline_args]) -> array
1722
+ # - ios.readlines(sep, limit [, getline_args]) -> array
1723
+ # -->
1724
+ # Reads all of the lines in *ios*, and returns them in an array. Lines are
1725
+ # separated by the optional *sep*. If *sep* is `nil`, the rest of the stream is
1726
+ # returned as a single record. If the first argument is an integer, or an
1727
+ # optional second argument is given, the returning string would not be longer
1728
+ # than the given value in bytes. The stream must be opened for reading or an
1729
+ # IOError will be raised.
1730
+ #
1731
+ # f = File.new("testfile")
1732
+ # f.readlines[0] #=> "This is line one\n"
1733
+ #
1734
+ # f = File.new("testfile", chomp: true)
1735
+ # f.readlines[0] #=> "This is line one"
1736
+ #
1737
+ # See IO.readlines for details about getline_args.
1738
+ #
556
1739
  def readlines: (?String sep, ?Integer limit) -> ::Array[String]
557
1740
 
558
- # Reads at most *maxlen* bytes from the I/O stream. It blocks only if *ios* has
559
- # no data immediately available. It doesn't block if some data available.
1741
+ # <!--
1742
+ # rdoc-file=io.c
1743
+ # - readpartial(maxlen) -> string
1744
+ # - readpartial(maxlen, out_string) -> out_string
1745
+ # -->
1746
+ # Reads up to `maxlen` bytes from the stream; returns a string (either a new
1747
+ # string or the given `out_string`). Its encoding is:
560
1748
  #
561
- # If the optional *outbuf* argument is present, it must reference a String,
562
- # which will receive the data. The *outbuf* will contain only the received data
563
- # after the method call even if it is not empty at the beginning.
1749
+ # * The unchanged encoding of `out_string`, if `out_string` is given.
1750
+ # * ASCII-8BIT, otherwise.
564
1751
  #
565
- # It raises EOFError on end of file.
1752
+ # * Contains `maxlen` bytes from the stream, if available.
1753
+ # * Otherwise contains all available bytes, if any available.
1754
+ # * Otherwise is an empty string.
566
1755
  #
567
- # readpartial is designed for streams such as pipe, socket, tty, etc. It blocks
568
- # only when no data immediately available. This means that it blocks only when
569
- # following all conditions hold.
570
- # * the byte buffer in the IO object is empty.
571
- # * the content of the stream is empty.
572
- # * the stream is not reached to EOF.
573
1756
  #
1757
+ # With the single non-negative integer argument `maxlen` given, returns a new
1758
+ # string:
574
1759
  #
575
- # When readpartial blocks, it waits data or EOF on the stream. If some data is
576
- # reached, readpartial returns with the data. If EOF is reached, readpartial
577
- # raises EOFError.
1760
+ # f = File.new('t.txt')
1761
+ # f.readpartial(30) # => "This is line one.\nThis is the"
1762
+ # f.readpartial(30) # => " second line.\nThis is the thi"
1763
+ # f.readpartial(30) # => "rd line.\n"
1764
+ # f.eof # => true
1765
+ # f.readpartial(30) # Raises EOFError.
578
1766
  #
579
- # When readpartial doesn't blocks, it returns or raises immediately. If the byte
580
- # buffer is not empty, it returns the data in the buffer. Otherwise if the
581
- # stream has some content, it returns the data in the stream. Otherwise if the
582
- # stream is reached to EOF, it raises EOFError.
1767
+ # With both argument `maxlen` and string argument `out_string` given, returns
1768
+ # modified `out_string`:
583
1769
  #
584
- # r, w = IO.pipe # buffer pipe content
585
- # w << "abc" # "" "abc".
586
- # r.readpartial(4096) #=> "abc" "" ""
587
- # r.readpartial(4096) # blocks because buffer and pipe is empty.
1770
+ # f = File.new('t.txt')
1771
+ # s = 'foo'
1772
+ # f.readpartial(30, s) # => "This is line one.\nThis is the"
1773
+ # s = 'bar'
1774
+ # f.readpartial(0, s) # => ""
1775
+ #
1776
+ # This method is useful for a stream such as a pipe, a socket, or a tty. It
1777
+ # blocks only when no data is immediately available. This means that it blocks
1778
+ # only when *all* of the following are true:
1779
+ #
1780
+ # * The byte buffer in the stream is empty.
1781
+ # * The content of the stream is empty.
1782
+ # * The stream is not at EOF.
588
1783
  #
589
- # r, w = IO.pipe # buffer pipe content
590
- # w << "abc" # "" "abc"
591
- # w.close # "" "abc" EOF
592
- # r.readpartial(4096) #=> "abc" "" EOF
593
- # r.readpartial(4096) # raises EOFError
594
1784
  #
595
- # r, w = IO.pipe # buffer pipe content
596
- # w << "abc\ndef\n" # "" "abc\ndef\n"
597
- # r.gets #=> "abc\n" "def\n" ""
598
- # w << "ghi\n" # "def\n" "ghi\n"
599
- # r.readpartial(4096) #=> "def\n" "" "ghi\n"
600
- # r.readpartial(4096) #=> "ghi\n" "" ""
1785
+ # When blocked, the method waits for either more data or EOF on the stream:
1786
+ #
1787
+ # * If more data is read, the method returns the data.
1788
+ # * If EOF is reached, the method raises EOFError.
1789
+ #
1790
+ #
1791
+ # When not blocked, the method responds immediately:
1792
+ #
1793
+ # * Returns data from the buffer if there is any.
1794
+ # * Otherwise returns data from the stream if there is any.
1795
+ # * Otherwise raises EOFError if the stream has reached EOF.
1796
+ #
1797
+ #
1798
+ # Note that this method is similar to sysread. The differences are:
601
1799
  #
602
- # Note that readpartial behaves similar to sysread. The differences are:
603
1800
  # * If the byte buffer is not empty, read from the byte buffer instead of
604
1801
  # "sysread for buffered IO (IOError)".
605
1802
  # * It doesn't cause Errno::EWOULDBLOCK and Errno::EINTR. When readpartial
606
- # meets EWOULDBLOCK and EINTR by read system call, readpartial retry the
1803
+ # meets EWOULDBLOCK and EINTR by read system call, readpartial retries the
607
1804
  # system call.
608
1805
  #
609
1806
  #
610
- # The latter means that readpartial is nonblocking-flag insensitive. It blocks
1807
+ # The latter means that readpartial is non-blocking-flag insensitive. It blocks
611
1808
  # on the situation IO#sysread causes Errno::EWOULDBLOCK as if the fd is blocking
612
1809
  # mode.
613
1810
  #
1811
+ # Examples:
1812
+ #
1813
+ # # # Returned Buffer Content Pipe Content
1814
+ # r, w = IO.pipe #
1815
+ # w << 'abc' # "" "abc".
1816
+ # r.readpartial(4096) # => "abc" "" ""
1817
+ # r.readpartial(4096) # (Blocks because buffer and pipe are empty.)
1818
+ #
1819
+ # # # Returned Buffer Content Pipe Content
1820
+ # r, w = IO.pipe #
1821
+ # w << 'abc' # "" "abc"
1822
+ # w.close # "" "abc" EOF
1823
+ # r.readpartial(4096) # => "abc" "" EOF
1824
+ # r.readpartial(4096) # raises EOFError
1825
+ #
1826
+ # # # Returned Buffer Content Pipe Content
1827
+ # r, w = IO.pipe #
1828
+ # w << "abc\ndef\n" # "" "abc\ndef\n"
1829
+ # r.gets # => "abc\n" "def\n" ""
1830
+ # w << "ghi\n" # "def\n" "ghi\n"
1831
+ # r.readpartial(4096) # => "def\n" "" "ghi\n"
1832
+ # r.readpartial(4096) # => "ghi\n" "" ""
1833
+ #
614
1834
  def readpartial: (int maxlen, ?string outbuf) -> String
615
1835
 
1836
+ # <!--
1837
+ # rdoc-file=io.c
1838
+ # - ios.reopen(other_IO) -> ios
1839
+ # - ios.reopen(path, mode [, opt]) -> ios
1840
+ # -->
1841
+ # Reassociates *ios* with the I/O stream given in *other_IO* or to a new stream
1842
+ # opened on *path*. This may dynamically change the actual class of this stream.
1843
+ # The `mode` and `opt` parameters accept the same values as IO.open.
1844
+ #
1845
+ # f1 = File.new("testfile")
1846
+ # f2 = File.new("testfile")
1847
+ # f2.readlines[0] #=> "This is line one\n"
1848
+ # f2.reopen(f1) #=> #<File:testfile>
1849
+ # f2.readlines[0] #=> "This is line one\n"
1850
+ #
616
1851
  def reopen: (IO other_IO_or_path) -> IO
617
1852
  | (String other_IO_or_path, ?String mode_str) -> IO
618
1853
 
619
- # Positions *ios* to the beginning of input, resetting `lineno` to zero.
620
- #
621
- # ```ruby
622
- # f = File.new("testfile")
623
- # f.readline #=> "This is line one\n"
624
- # f.rewind #=> 0
625
- # f.lineno #=> 0
626
- # f.readline #=> "This is line one\n"
627
- # ```
628
- #
629
- # Note that it cannot be used with streams such as pipes, ttys, and
1854
+ # <!--
1855
+ # rdoc-file=io.c
1856
+ # - rewind -> 0
1857
+ # -->
1858
+ # Repositions the stream to its beginning, setting both the position and the
1859
+ # line number to zero; see [Position](#class-IO-label-Position) and [Line
1860
+ # Number](#class-IO-label-Line+Number):
1861
+ #
1862
+ # f = File.open('t.txt')
1863
+ # f.tell # => 0
1864
+ # f.lineno # => 0
1865
+ # f.readline # => "This is line one.\n"
1866
+ # f.tell # => 19
1867
+ # f.lineno # => 1
1868
+ # f.rewind # => 0
1869
+ # f.tell # => 0
1870
+ # f.lineno # => 0
1871
+ #
1872
+ # Note that this method cannot be used with streams such as pipes, ttys, and
630
1873
  # sockets.
1874
+ #
631
1875
  def rewind: () -> Integer
632
1876
 
1877
+ # <!--
1878
+ # rdoc-file=io.c
1879
+ # - seek(offset, whence = IO::SEEK_SET) -> 0
1880
+ # -->
1881
+ # Seeks to the position given by integer `offset` (see
1882
+ # [Position](#class-IO-label-Position)) and constant `whence`, which is one of:
1883
+ #
1884
+ # * `:CUR` or `IO::SEEK_CUR`: Repositions the stream to its current position
1885
+ # plus the given `offset`:
1886
+ #
1887
+ # f = File.open('t.txt')
1888
+ # f.tell # => 0
1889
+ # f.seek(20, :CUR) # => 0
1890
+ # f.tell # => 20
1891
+ # f.seek(-10, :CUR) # => 0
1892
+ # f.tell # => 10
1893
+ #
1894
+ # * `:END` or `IO::SEEK_END`: Repositions the stream to its end plus the given
1895
+ # `offset`:
1896
+ #
1897
+ # f = File.open('t.txt')
1898
+ # f.tell # => 0
1899
+ # f.seek(0, :END) # => 0 # Repositions to stream end.
1900
+ # f.tell # => 70
1901
+ # f.seek(-20, :END) # => 0
1902
+ # f.tell # => 50
1903
+ # f.seek(-40, :END) # => 0
1904
+ # f.tell # => 30
1905
+ #
1906
+ # * `:SET` or `IO:SEEK_SET`: Repositions the stream to the given `offset`:
1907
+ #
1908
+ # f = File.open('t.txt')
1909
+ # f.tell # => 0
1910
+ # f.seek(20, :SET) # => 0
1911
+ # f.tell # => 20
1912
+ # f.seek(40, :SET) # => 0
1913
+ # f.tell # => 40
1914
+ #
1915
+ #
1916
+ # Related: IO#pos=, IO#tell.
1917
+ #
633
1918
  def seek: (Integer amount, ?Integer whence) -> Integer
634
1919
 
1920
+ # <!--
1921
+ # rdoc-file=io.c
1922
+ # - io.set_encoding(ext_enc) -> io
1923
+ # - io.set_encoding("ext_enc:int_enc") -> io
1924
+ # - io.set_encoding(ext_enc, int_enc) -> io
1925
+ # - io.set_encoding("ext_enc:int_enc", opt) -> io
1926
+ # - io.set_encoding(ext_enc, int_enc, opt) -> io
1927
+ # -->
1928
+ # If single argument is specified, read string from io is tagged with the
1929
+ # encoding specified. If encoding is a colon separated two encoding names
1930
+ # "A:B", the read string is converted from encoding A (external encoding) to
1931
+ # encoding B (internal encoding), then tagged with B. If two arguments are
1932
+ # specified, those must be encoding objects or encoding names, and the first one
1933
+ # is the external encoding, and the second one is the internal encoding. If the
1934
+ # external encoding and the internal encoding is specified, optional hash
1935
+ # argument specify the conversion option.
1936
+ #
635
1937
  def set_encoding: (?String | Encoding ext_or_ext_int_enc) -> self
636
1938
  | (?String | Encoding ext_or_ext_int_enc, ?String | Encoding int_enc) -> self
637
1939
 
1940
+ # <!--
1941
+ # rdoc-file=io.c
1942
+ # - ios.set_encoding_by_bom -> encoding or nil
1943
+ # -->
1944
+ # Checks if `ios` starts with a BOM, and then consumes it and sets the external
1945
+ # encoding. Returns the result encoding if found, or nil. If `ios` is not
1946
+ # binmode or its encoding has been set already, an exception will be raised.
1947
+ #
1948
+ # File.write("bom.txt", "\u{FEFF}abc")
1949
+ # ios = File.open("bom.txt", "rb")
1950
+ # ios.set_encoding_by_bom #=> #<Encoding:UTF-8>
1951
+ #
1952
+ # File.write("nobom.txt", "abc")
1953
+ # ios = File.open("nobom.txt", "rb")
1954
+ # ios.set_encoding_by_bom #=> nil
1955
+ #
638
1956
  def set_encoding_by_bom: () -> Encoding?
639
1957
 
640
- # Returns status information for *ios* as an object of type `File::Stat` .
1958
+ # <!--
1959
+ # rdoc-file=file.c
1960
+ # - ios.stat -> stat
1961
+ # -->
1962
+ # Returns status information for *ios* as an object of type File::Stat.
1963
+ #
1964
+ # f = File.new("testfile")
1965
+ # s = f.stat
1966
+ # "%o" % s.mode #=> "100644"
1967
+ # s.blksize #=> 4096
1968
+ # s.atime #=> Wed Apr 09 08:53:54 CDT 2003
641
1969
  #
642
- # ```ruby
643
- # f = File.new("testfile")
644
- # s = f.stat
645
- # "%o" % s.mode #=> "100644"
646
- # s.blksize #=> 4096
647
- # s.atime #=> Wed Apr 09 08:53:54 CDT 2003
648
- # ```
649
1970
  def stat: () -> File::Stat
650
1971
 
651
- # Returns the current “sync mode” of *ios* . When sync mode is true, all
652
- # output is immediately flushed to the underlying operating system and is
653
- # not buffered by Ruby internally. See also `IO#fsync` .
1972
+ # <!--
1973
+ # rdoc-file=io.c
1974
+ # - sync -> true or false
1975
+ # -->
1976
+ # Returns the current sync mode of the stream. When sync mode is true, all
1977
+ # output is immediately flushed to the underlying operating system and is not
1978
+ # buffered by Ruby internally. See also #fsync.
1979
+ #
1980
+ # f = File.open('t.tmp', 'w')
1981
+ # f.sync # => false
1982
+ # f.sync = true
1983
+ # f.sync # => true
654
1984
  #
655
- # ```ruby
656
- # f = File.new("testfile")
657
- # f.sync #=> false
658
- # ```
659
1985
  def sync: () -> bool
660
1986
 
1987
+ # <!--
1988
+ # rdoc-file=io.c
1989
+ # - sync = boolean -> boolean
1990
+ # -->
1991
+ # Sets the *sync* *mode* for the stream to the given value; returns the given
1992
+ # value.
1993
+ #
1994
+ # Values for the sync mode:
1995
+ #
1996
+ # * `true`: All output is immediately flushed to the underlying operating
1997
+ # system and is not buffered internally.
1998
+ # * `false`: Output may be buffered internally.
1999
+ #
2000
+ #
2001
+ # Example;
2002
+ #
2003
+ # f = File.open('t.tmp', 'w')
2004
+ # f.sync # => false
2005
+ # f.sync = true
2006
+ # f.sync # => true
2007
+ #
2008
+ # Related: IO#fsync.
2009
+ #
661
2010
  def sync=: (boolish) -> untyped
662
2011
 
2012
+ # <!--
2013
+ # rdoc-file=io.c
2014
+ # - ios.sysread(maxlen[, outbuf]) -> string
2015
+ # -->
2016
+ # Reads *maxlen* bytes from *ios* using a low-level read and returns them as a
2017
+ # string. Do not mix with other methods that read from *ios* or you may get
2018
+ # unpredictable results.
2019
+ #
2020
+ # If the optional *outbuf* argument is present, it must reference a String,
2021
+ # which will receive the data. The *outbuf* will contain only the received data
2022
+ # after the method call even if it is not empty at the beginning.
2023
+ #
2024
+ # Raises SystemCallError on error and EOFError at end of file.
2025
+ #
2026
+ # f = File.new("testfile")
2027
+ # f.sysread(16) #=> "This is line one"
2028
+ #
663
2029
  def sysread: (Integer maxlen, String outbuf) -> String
664
2030
 
2031
+ # <!--
2032
+ # rdoc-file=io.c
2033
+ # - ios.sysseek(offset, whence=IO::SEEK_SET) -> integer
2034
+ # -->
2035
+ # Seeks to a given *offset* in the stream according to the value of *whence*
2036
+ # (see IO#seek for values of *whence*). Returns the new offset into the file.
2037
+ #
2038
+ # f = File.new("testfile")
2039
+ # f.sysseek(-13, IO::SEEK_END) #=> 53
2040
+ # f.sysread(10) #=> "And so on."
2041
+ #
665
2042
  def sysseek: (Integer amount, ?Integer whence) -> Integer
666
2043
 
2044
+ # <!--
2045
+ # rdoc-file=io.c
2046
+ # - ios.syswrite(string) -> integer
2047
+ # -->
2048
+ # Writes the given string to *ios* using a low-level write. Returns the number
2049
+ # of bytes written. Do not mix with other methods that write to *ios* or you may
2050
+ # get unpredictable results. Raises SystemCallError on error.
2051
+ #
2052
+ # f = File.new("out", "w")
2053
+ # f.syswrite("ABCDEF") #=> 6
2054
+ #
667
2055
  def syswrite: (_ToS arg0) -> Integer
668
2056
 
669
- # Returns the current offset (in bytes) of *ios* .
2057
+ # <!--
2058
+ # rdoc-file=io.c
2059
+ # - tell -> integer
2060
+ # -->
2061
+ # Returns the current position (in bytes) in `self` (see
2062
+ # [Position](#class-IO-label-Position)):
2063
+ #
2064
+ # f = File.new('t.txt')
2065
+ # f.tell # => 0
2066
+ # f.readline # => "This is line one.\n"
2067
+ # f.tell # => 19
2068
+ #
2069
+ # Related: IO#pos=, IO#seek.
2070
+ #
2071
+ # IO#pos is an alias for IO#tell.
670
2072
  #
671
- # ```ruby
672
- # f = File.new("testfile")
673
- # f.pos #=> 0
674
- # f.gets #=> "This is line one\n"
675
- # f.pos #=> 17
676
- # ```
677
2073
  def tell: () -> Integer
678
2074
 
679
- # Returns *ios* .
2075
+ # <!--
2076
+ # rdoc-file=io.c
2077
+ # - to_io -> self
2078
+ # -->
2079
+ # Returns `self`.
2080
+ #
680
2081
  def to_io: () -> self
681
2082
 
682
- # Returns `true` if *ios* is associated with a terminal device (tty),
683
- # `false` otherwise.
2083
+ # <!-- rdoc-file=io.c -->
2084
+ # Returns `true` if *ios* is associated with a terminal device (tty), `false`
2085
+ # otherwise.
2086
+ #
2087
+ # File.new("testfile").isatty #=> false
2088
+ # File.new("/dev/tty").isatty #=> true
684
2089
  #
685
- # ```ruby
686
- # File.new("testfile").isatty #=> false
687
- # File.new("/dev/tty").isatty #=> true
688
- # ```
689
2090
  def tty?: () -> bool
690
2091
 
2092
+ # <!--
2093
+ # rdoc-file=io.c
2094
+ # - ios.ungetbyte(string) -> nil
2095
+ # - ios.ungetbyte(integer) -> nil
2096
+ # -->
2097
+ # Pushes back bytes (passed as a parameter) onto *ios*, such that a subsequent
2098
+ # buffered read will return it. It is only guaranteed to support a single byte,
2099
+ # and only if ungetbyte or ungetc has not already been called on *ios* since the
2100
+ # previous read of at least a single byte from *ios*. However, it can support
2101
+ # additional bytes if there is space in the internal buffer to allow for it.
2102
+ #
2103
+ # f = File.new("testfile") #=> #<File:testfile>
2104
+ # b = f.getbyte #=> 0x38
2105
+ # f.ungetbyte(b) #=> nil
2106
+ # f.getbyte #=> 0x38
2107
+ #
2108
+ # If given an integer, only uses the lower 8 bits of the integer as the byte to
2109
+ # push.
2110
+ #
2111
+ # f = File.new("testfile") #=> #<File:testfile>
2112
+ # f.ungetbyte(0x102) #=> nil
2113
+ # f.getbyte #=> 0x2
2114
+ #
2115
+ # Calling this method prepends to the existing buffer, even if the method has
2116
+ # already been called previously:
2117
+ #
2118
+ # f = File.new("testfile") #=> #<File:testfile>
2119
+ # f.ungetbyte("ab") #=> nil
2120
+ # f.ungetbyte("cd") #=> nil
2121
+ # f.read(5) #=> "cdab8"
2122
+ #
2123
+ # Has no effect with unbuffered reads (such as IO#sysread).
2124
+ #
691
2125
  def ungetbyte: (String | Integer arg0) -> NilClass
692
2126
 
2127
+ # <!--
2128
+ # rdoc-file=io.c
2129
+ # - ios.ungetc(integer) -> nil
2130
+ # - ios.ungetc(string) -> nil
2131
+ # -->
2132
+ # Pushes back characters (passed as a parameter) onto *ios*, such that a
2133
+ # subsequent buffered read will return it. It is only guaranteed to support a
2134
+ # single byte, and only if ungetbyte or ungetc has not already been called on
2135
+ # *ios* since the previous read of at least a single byte from *ios*. However,
2136
+ # it can support additional bytes if there is space in the internal buffer to
2137
+ # allow for it.
2138
+ #
2139
+ # f = File.new("testfile") #=> #<File:testfile>
2140
+ # c = f.getc #=> "8"
2141
+ # f.ungetc(c) #=> nil
2142
+ # f.getc #=> "8"
2143
+ #
2144
+ # If given an integer, the integer must represent a valid codepoint in the
2145
+ # external encoding of *ios*.
2146
+ #
2147
+ # Calling this method prepends to the existing buffer, even if the method has
2148
+ # already been called previously:
2149
+ #
2150
+ # f = File.new("testfile") #=> #<File:testfile>
2151
+ # f.ungetc("ab") #=> nil
2152
+ # f.ungetc("cd") #=> nil
2153
+ # f.read(5) #=> "cdab8"
2154
+ #
2155
+ # Has no effect with unbuffered reads (such as IO#sysread).
2156
+ #
693
2157
  def ungetc: (String arg0) -> NilClass
694
2158
 
695
- # Writes the given strings to *ios*. The stream must be opened for writing.
696
- # Arguments that are not a string will be converted to a string using `to_s`.
697
- # Returns the number of bytes written in total.
2159
+ # <!--
2160
+ # rdoc-file=io.c
2161
+ # - write(*objects) -> integer
2162
+ # -->
2163
+ # Writes each of the given `objects` to `self`, which must be opened for writing
2164
+ # (see [Modes](#class-IO-label-Modes)); returns the total number bytes written;
2165
+ # each of `objects` that is not a string is converted via method `to_s`:
698
2166
  #
699
- # count = $stdout.write("This is", " a test\n")
700
- # puts "That was #{count} bytes of data"
2167
+ # $stdout.write('Hello', ', ', 'World!', "\n") # => 14
2168
+ # $stdout.write('foo', :bar, 2, "\n") # => 8
701
2169
  #
702
- # *produces:*
2170
+ # Output:
703
2171
  #
704
- # This is a test
705
- # That was 15 bytes of data
2172
+ # Hello, World!
2173
+ # foobar2
706
2174
  #
707
2175
  def write: (*_ToS string) -> Integer
708
2176
 
2177
+ # <!--
2178
+ # rdoc-file=io.rb
2179
+ # - ios.write_nonblock(string) -> integer
2180
+ # - ios.write_nonblock(string [, options]) -> integer
2181
+ # -->
2182
+ # Writes the given string to *ios* using the write(2) system call after
2183
+ # O_NONBLOCK is set for the underlying file descriptor.
2184
+ #
2185
+ # It returns the number of bytes written.
2186
+ #
2187
+ # write_nonblock just calls the write(2) system call. It causes all errors the
2188
+ # write(2) system call causes: Errno::EWOULDBLOCK, Errno::EINTR, etc. The result
2189
+ # may also be smaller than string.length (partial write). The caller should care
2190
+ # such errors and partial write.
2191
+ #
2192
+ # If the exception is Errno::EWOULDBLOCK or Errno::EAGAIN, it is extended by
2193
+ # IO::WaitWritable. So IO::WaitWritable can be used to rescue the exceptions for
2194
+ # retrying write_nonblock.
2195
+ #
2196
+ # # Creates a pipe.
2197
+ # r, w = IO.pipe
2198
+ #
2199
+ # # write_nonblock writes only 65536 bytes and return 65536.
2200
+ # # (The pipe size is 65536 bytes on this environment.)
2201
+ # s = "a" * 100000
2202
+ # p w.write_nonblock(s) #=> 65536
2203
+ #
2204
+ # # write_nonblock cannot write a byte and raise EWOULDBLOCK (EAGAIN).
2205
+ # p w.write_nonblock("b") # Resource temporarily unavailable (Errno::EAGAIN)
2206
+ #
2207
+ # If the write buffer is not empty, it is flushed at first.
2208
+ #
2209
+ # When write_nonblock raises an exception kind of IO::WaitWritable,
2210
+ # write_nonblock should not be called until io is writable for avoiding busy
2211
+ # loop. This can be done as follows.
2212
+ #
2213
+ # begin
2214
+ # result = io.write_nonblock(string)
2215
+ # rescue IO::WaitWritable, Errno::EINTR
2216
+ # IO.select(nil, [io])
2217
+ # retry
2218
+ # end
2219
+ #
2220
+ # Note that this doesn't guarantee to write all data in string. The length
2221
+ # written is reported as result and it should be checked later.
2222
+ #
2223
+ # On some platforms such as Windows, write_nonblock is not supported according
2224
+ # to the kind of the IO object. In such cases, write_nonblock raises
2225
+ # `Errno::EBADF`.
2226
+ #
2227
+ # By specifying a keyword argument *exception* to `false`, you can indicate that
2228
+ # write_nonblock should not raise an IO::WaitWritable exception, but return the
2229
+ # symbol `:wait_writable` instead.
2230
+ #
709
2231
  def write_nonblock: (_ToS s, ?exception: true) -> Integer
710
2232
  | (_ToS s, exception: false) -> (Integer | :wait_writable | nil)
711
2233
 
2234
+ # <!--
2235
+ # rdoc-file=io.c
2236
+ # - IO.binread(name, [length [, offset]]) -> string
2237
+ # - File.binread(name, [length [, offset]]) -> string
2238
+ # -->
712
2239
  # Opens the file, optionally seeks to the given *offset*, then returns *length*
713
2240
  # bytes (defaulting to the rest of the file). #binread ensures the file is
714
2241
  # closed before returning. The open mode would be `"rb:ASCII-8BIT"`.
715
2242
  #
716
- # IO.binread("testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
717
- # IO.binread("testfile", 20) #=> "This is line one\nThi"
718
- # IO.binread("testfile", 20, 10) #=> "ne one\nThis is line "
2243
+ # If `name` starts with a pipe character (`"|"`) and the receiver is the IO
2244
+ # class, a subprocess is created in the same way as Kernel#open, and its output
2245
+ # is returned. Consider to use File.binread to disable the behavior of
2246
+ # subprocess invocation.
2247
+ #
2248
+ # File.binread("testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
2249
+ # File.binread("testfile", 20) #=> "This is line one\nThi"
2250
+ # File.binread("testfile", 20, 10) #=> "ne one\nThis is line "
2251
+ # IO.binread("| cat testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
2252
+ #
2253
+ # See also IO.read for details about `name` and open_args.
719
2254
  #
720
2255
  def self.binread: (String name, ?Integer length, ?Integer offset) -> String
721
2256
 
2257
+ # <!--
2258
+ # rdoc-file=io.c
2259
+ # - IO.binwrite(name, string, [offset]) -> integer
2260
+ # - IO.binwrite(name, string, [offset], open_args) -> integer
2261
+ # - File.binwrite(name, string, [offset]) -> integer
2262
+ # - File.binwrite(name, string, [offset], open_args) -> integer
2263
+ # -->
722
2264
  # Same as IO.write except opening the file in binary mode and ASCII-8BIT
723
2265
  # encoding (`"wb:ASCII-8BIT"`).
724
2266
  #
2267
+ # If `name` starts with a pipe character (`"|"`) and the receiver is the IO
2268
+ # class, a subprocess is created in the same way as Kernel#open, and its output
2269
+ # is returned. Consider to use File.binwrite to disable the behavior of
2270
+ # subprocess invocation.
2271
+ #
2272
+ # See also IO.read for details about `name` and open_args.
2273
+ #
725
2274
  def self.binwrite: (String name, _ToS string, ?Integer offset, ?mode: String mode) -> Integer
726
2275
 
2276
+ # <!--
2277
+ # rdoc-file=io.c
2278
+ # - IO.copy_stream(src, dst)
2279
+ # - IO.copy_stream(src, dst, copy_length)
2280
+ # - IO.copy_stream(src, dst, copy_length, src_offset)
2281
+ # -->
727
2282
  # IO.copy_stream copies *src* to *dst*. *src* and *dst* is either a filename or
728
2283
  # an IO-like object. IO-like object for *src* should have #readpartial or #read
729
2284
  # method. IO-like object for *dst* should have #write method. (Specialized
@@ -743,28 +2298,431 @@ class IO < Object
743
2298
  # When *src_offset* is specified and *src* is an IO, IO.copy_stream doesn't move
744
2299
  # the current file offset.
745
2300
  #
746
- def self.copy_stream: ((String | _Reader | _ReaderPartial) src, (String | _Writer) dst, ?Integer copy_length, ?Integer src_offset) -> Integer
747
-
2301
+ def self.copy_stream: (String | _Reader | _ReaderPartial src, String | _Writer dst, ?Integer copy_length, ?Integer src_offset) -> Integer
2302
+
2303
+ # <!--
2304
+ # rdoc-file=io.c
2305
+ # - IO.popen([env,] cmd, mode="r" [, opt]) -> io
2306
+ # - IO.popen([env,] cmd, mode="r" [, opt]) {|io| block } -> obj
2307
+ # -->
2308
+ # Runs the specified command as a subprocess; the subprocess's standard input
2309
+ # and output will be connected to the returned IO object.
2310
+ #
2311
+ # The PID of the started process can be obtained by IO#pid method.
2312
+ #
2313
+ # *cmd* is a string or an array as follows.
2314
+ #
2315
+ # cmd:
2316
+ # "-" : fork
2317
+ # commandline : command line string which is passed to a shell
2318
+ # [env, cmdname, arg1, ..., opts] : command name and zero or more arguments (no shell)
2319
+ # [env, [cmdname, argv0], arg1, ..., opts] : command name, argv[0] and zero or more arguments (no shell)
2320
+ # (env and opts are optional.)
2321
+ #
2322
+ # If *cmd* is a `String` ```-`'', then a new instance of Ruby is started as the
2323
+ # subprocess.
2324
+ #
2325
+ # If *cmd* is an `Array` of `String`, then it will be used as the subprocess's
2326
+ # `argv` bypassing a shell. The array can contain a hash at first for
2327
+ # environments and a hash at last for options similar to #spawn.
2328
+ #
2329
+ # The default mode for the new file object is ``r'', but *mode* may be set to
2330
+ # any of the modes listed in the description for class IO. The last argument
2331
+ # *opt* qualifies *mode*.
2332
+ #
2333
+ # # set IO encoding
2334
+ # IO.popen("nkf -e filename", :external_encoding=>"EUC-JP") {|nkf_io|
2335
+ # euc_jp_string = nkf_io.read
2336
+ # }
2337
+ #
2338
+ # # merge standard output and standard error using
2339
+ # # spawn option. See the document of Kernel.spawn.
2340
+ # IO.popen(["ls", "/", :err=>[:child, :out]]) {|ls_io|
2341
+ # ls_result_with_error = ls_io.read
2342
+ # }
2343
+ #
2344
+ # # spawn options can be mixed with IO options
2345
+ # IO.popen(["ls", "/"], :err=>[:child, :out]) {|ls_io|
2346
+ # ls_result_with_error = ls_io.read
2347
+ # }
2348
+ #
2349
+ # Raises exceptions which IO.pipe and Kernel.spawn raise.
2350
+ #
2351
+ # If a block is given, Ruby will run the command as a child connected to Ruby
2352
+ # with a pipe. Ruby's end of the pipe will be passed as a parameter to the
2353
+ # block. At the end of block, Ruby closes the pipe and sets `$?`. In this case
2354
+ # IO.popen returns the value of the block.
2355
+ #
2356
+ # If a block is given with a *cmd* of ```-`'', the block will be run in two
2357
+ # separate processes: once in the parent, and once in a child. The parent
2358
+ # process will be passed the pipe object as a parameter to the block, the child
2359
+ # version of the block will be passed `nil`, and the child's standard in and
2360
+ # standard out will be connected to the parent through the pipe. Not available
2361
+ # on all platforms.
2362
+ #
2363
+ # f = IO.popen("uname")
2364
+ # p f.readlines
2365
+ # f.close
2366
+ # puts "Parent is #{Process.pid}"
2367
+ # IO.popen("date") {|f| puts f.gets }
2368
+ # IO.popen("-") {|f| $stderr.puts "#{Process.pid} is here, f is #{f.inspect}"}
2369
+ # p $?
2370
+ # IO.popen(%w"sed -e s|^|<foo>| -e s&$&;zot;&", "r+") {|f|
2371
+ # f.puts "bar"; f.close_write; puts f.gets
2372
+ # }
2373
+ #
2374
+ # *produces:*
2375
+ #
2376
+ # ["Linux\n"]
2377
+ # Parent is 21346
2378
+ # Thu Jan 15 22:41:19 JST 2009
2379
+ # 21346 is here, f is #<IO:fd 3>
2380
+ # 21352 is here, f is nil
2381
+ # #<Process::Status: pid 21352 exit 0>
2382
+ # <foo>bar;zot;
2383
+ #
748
2384
  def self.popen: (*untyped args) -> untyped
749
2385
 
2386
+ # <!--
2387
+ # rdoc-file=io.c
2388
+ # - IO.read(name, [length [, offset]] [, opt]) -> string
2389
+ # - File.read(name, [length [, offset]] [, opt]) -> string
2390
+ # -->
2391
+ # Opens the file, optionally seeks to the given `offset`, then returns `length`
2392
+ # bytes (defaulting to the rest of the file). #read ensures the file is closed
2393
+ # before returning.
2394
+ #
2395
+ # If `name` starts with a pipe character (`"|"`) and the receiver is the IO
2396
+ # class, a subprocess is created in the same way as Kernel#open, and its output
2397
+ # is returned. Consider to use File.read to disable the behavior of subprocess
2398
+ # invocation.
2399
+ #
2400
+ # ### Options
2401
+ #
2402
+ # The options hash accepts the following keys:
2403
+ #
2404
+ # :encoding
2405
+ # : string or encoding
2406
+ #
2407
+ # Specifies the encoding of the read string. `:encoding` will be ignored if
2408
+ # `length` is specified. See Encoding.aliases for possible encodings.
2409
+ #
2410
+ # :mode
2411
+ # : string or integer
2412
+ #
2413
+ # Specifies the *mode* argument for open(). It must start with an "r",
2414
+ # otherwise it will cause an error. See IO.new for the list of possible
2415
+ # modes.
2416
+ #
2417
+ # :open_args
2418
+ # : array
2419
+ #
2420
+ # Specifies arguments for open() as an array. This key can not be used in
2421
+ # combination with either `:encoding` or `:mode`.
2422
+ #
2423
+ #
2424
+ # Examples:
2425
+ #
2426
+ # File.read("testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
2427
+ # File.read("testfile", 20) #=> "This is line one\nThi"
2428
+ # File.read("testfile", 20, 10) #=> "ne one\nThis is line "
2429
+ # File.read("binfile", mode: "rb") #=> "\xF7\x00\x00\x0E\x12"
2430
+ # IO.read("|ls -a") #=> ".\n..\n"...
2431
+ #
750
2432
  def self.read: (String name, ?Integer length, ?Integer offset, ?external_encoding: String external_encoding, ?internal_encoding: String internal_encoding, ?encoding: String encoding, ?textmode: untyped textmode, ?binmode: untyped binmode, ?autoclose: untyped autoclose, ?mode: String mode) -> String
751
2433
 
2434
+ # <!--
2435
+ # rdoc-file=io.c
2436
+ # - IO.readlines(name, sep=$/ [, getline_args, open_args]) -> array
2437
+ # - IO.readlines(name, limit [, getline_args, open_args]) -> array
2438
+ # - IO.readlines(name, sep, limit [, getline_args, open_args]) -> array
2439
+ # - File.readlines(name, sep=$/ [, getline_args, open_args]) -> array
2440
+ # - File.readlines(name, limit [, getline_args, open_args]) -> array
2441
+ # - File.readlines(name, sep, limit [, getline_args, open_args]) -> array
2442
+ # -->
2443
+ # Reads the entire file specified by *name* as individual lines, and returns
2444
+ # those lines in an array. Lines are separated by *sep*.
2445
+ #
2446
+ # If `name` starts with a pipe character (`"|"`) and the receiver is the IO
2447
+ # class, a subprocess is created in the same way as Kernel#open, and its output
2448
+ # is returned. Consider to use File.readlines to disable the behavior of
2449
+ # subprocess invocation.
2450
+ #
2451
+ # a = File.readlines("testfile")
2452
+ # a[0] #=> "This is line one\n"
2453
+ #
2454
+ # b = File.readlines("testfile", chomp: true)
2455
+ # b[0] #=> "This is line one"
2456
+ #
2457
+ # IO.readlines("|ls -a") #=> [".\n", "..\n", ...]
2458
+ #
2459
+ # If the last argument is a hash, it's the keyword argument to open.
2460
+ #
2461
+ # ### Options for getline
2462
+ #
2463
+ # The options hash accepts the following keys:
2464
+ #
2465
+ # :chomp
2466
+ # : When the optional `chomp` keyword argument has a true value, `\n`, `\r`,
2467
+ # and `\r\n` will be removed from the end of each line.
2468
+ #
2469
+ #
2470
+ # See also IO.read for details about `name` and open_args.
2471
+ #
752
2472
  def self.readlines: (String name, ?String sep, ?Integer limit, ?external_encoding: String external_encoding, ?internal_encoding: String internal_encoding, ?encoding: String encoding, ?textmode: untyped textmode, ?binmode: untyped binmode, ?autoclose: untyped autoclose, ?mode: String mode, ?chomp: boolish) -> ::Array[String]
753
2473
 
754
- def self.select: [X, Y, Z] (::Array[X & io]? read_array, ?::Array[Y & io]? write_array, ?::Array[Z & io]? error_array) -> [Array[X], Array[Y], Array[Z]]
755
- | [X, Y, Z] (::Array[X & io]? read_array, ?::Array[Y & io]? write_array, ?::Array[Z & io]? error_array, Numeric? timeout) -> [Array[X], Array[Y], Array[Z]]?
2474
+ # <!--
2475
+ # rdoc-file=io.c
2476
+ # - IO.select(read_array [, write_array [, error_array [, timeout]]]) -> array or nil
2477
+ # -->
2478
+ # Calls select(2) system call. It monitors given arrays of IO objects, waits
2479
+ # until one or more of IO objects are ready for reading, are ready for writing,
2480
+ # and have pending exceptions respectively, and returns an array that contains
2481
+ # arrays of those IO objects. It will return `nil` if optional *timeout* value
2482
+ # is given and no IO object is ready in *timeout* seconds.
2483
+ #
2484
+ # IO.select peeks the buffer of IO objects for testing readability. If the IO
2485
+ # buffer is not empty, IO.select immediately notifies readability. This "peek"
2486
+ # only happens for IO objects. It does not happen for IO-like objects such as
2487
+ # OpenSSL::SSL::SSLSocket.
2488
+ #
2489
+ # The best way to use IO.select is invoking it after nonblocking methods such as
2490
+ # #read_nonblock, #write_nonblock, etc. The methods raise an exception which is
2491
+ # extended by IO::WaitReadable or IO::WaitWritable. The modules notify how the
2492
+ # caller should wait with IO.select. If IO::WaitReadable is raised, the caller
2493
+ # should wait for reading. If IO::WaitWritable is raised, the caller should
2494
+ # wait for writing.
2495
+ #
2496
+ # So, blocking read (#readpartial) can be emulated using #read_nonblock and
2497
+ # IO.select as follows:
2498
+ #
2499
+ # begin
2500
+ # result = io_like.read_nonblock(maxlen)
2501
+ # rescue IO::WaitReadable
2502
+ # IO.select([io_like])
2503
+ # retry
2504
+ # rescue IO::WaitWritable
2505
+ # IO.select(nil, [io_like])
2506
+ # retry
2507
+ # end
2508
+ #
2509
+ # Especially, the combination of nonblocking methods and IO.select is preferred
2510
+ # for IO like objects such as OpenSSL::SSL::SSLSocket. It has #to_io method to
2511
+ # return underlying IO object. IO.select calls #to_io to obtain the file
2512
+ # descriptor to wait.
2513
+ #
2514
+ # This means that readability notified by IO.select doesn't mean readability
2515
+ # from OpenSSL::SSL::SSLSocket object.
2516
+ #
2517
+ # The most likely situation is that OpenSSL::SSL::SSLSocket buffers some data.
2518
+ # IO.select doesn't see the buffer. So IO.select can block when
2519
+ # OpenSSL::SSL::SSLSocket#readpartial doesn't block.
2520
+ #
2521
+ # However, several more complicated situations exist.
2522
+ #
2523
+ # SSL is a protocol which is sequence of records. The record consists of
2524
+ # multiple bytes. So, the remote side of SSL sends a partial record, IO.select
2525
+ # notifies readability but OpenSSL::SSL::SSLSocket cannot decrypt a byte and
2526
+ # OpenSSL::SSL::SSLSocket#readpartial will block.
2527
+ #
2528
+ # Also, the remote side can request SSL renegotiation which forces the local SSL
2529
+ # engine to write some data. This means OpenSSL::SSL::SSLSocket#readpartial may
2530
+ # invoke #write system call and it can block. In such a situation,
2531
+ # OpenSSL::SSL::SSLSocket#read_nonblock raises IO::WaitWritable instead of
2532
+ # blocking. So, the caller should wait for ready for writability as above
2533
+ # example.
2534
+ #
2535
+ # The combination of nonblocking methods and IO.select is also useful for
2536
+ # streams such as tty, pipe socket socket when multiple processes read from a
2537
+ # stream.
2538
+ #
2539
+ # Finally, Linux kernel developers don't guarantee that readability of select(2)
2540
+ # means readability of following read(2) even for a single process. See
2541
+ # select(2) manual on GNU/Linux system.
2542
+ #
2543
+ # Invoking IO.select before IO#readpartial works well as usual. However it is
2544
+ # not the best way to use IO.select.
2545
+ #
2546
+ # The writability notified by select(2) doesn't show how many bytes are
2547
+ # writable. IO#write method blocks until given whole string is written. So,
2548
+ # `IO#write(two or more bytes)` can block after writability is notified by
2549
+ # IO.select. IO#write_nonblock is required to avoid the blocking.
2550
+ #
2551
+ # Blocking write (#write) can be emulated using #write_nonblock and IO.select as
2552
+ # follows: IO::WaitReadable should also be rescued for SSL renegotiation in
2553
+ # OpenSSL::SSL::SSLSocket.
2554
+ #
2555
+ # while 0 < string.bytesize
2556
+ # begin
2557
+ # written = io_like.write_nonblock(string)
2558
+ # rescue IO::WaitReadable
2559
+ # IO.select([io_like])
2560
+ # retry
2561
+ # rescue IO::WaitWritable
2562
+ # IO.select(nil, [io_like])
2563
+ # retry
2564
+ # end
2565
+ # string = string.byteslice(written..-1)
2566
+ # end
2567
+ #
2568
+ # ### Parameters
2569
+ # read_array
2570
+ # : an array of IO objects that wait until ready for read
2571
+ # write_array
2572
+ # : an array of IO objects that wait until ready for write
2573
+ # error_array
2574
+ # : an array of IO objects that wait for exceptions
2575
+ # timeout
2576
+ # : a numeric value in second
2577
+ #
2578
+ #
2579
+ # ### Example
2580
+ #
2581
+ # rp, wp = IO.pipe
2582
+ # mesg = "ping "
2583
+ # 100.times {
2584
+ # # IO.select follows IO#read. Not the best way to use IO.select.
2585
+ # rs, ws, = IO.select([rp], [wp])
2586
+ # if r = rs[0]
2587
+ # ret = r.read(5)
2588
+ # print ret
2589
+ # case ret
2590
+ # when /ping/
2591
+ # mesg = "pong\n"
2592
+ # when /pong/
2593
+ # mesg = "ping "
2594
+ # end
2595
+ # end
2596
+ # if w = ws[0]
2597
+ # w.write(mesg)
2598
+ # end
2599
+ # }
2600
+ #
2601
+ # *produces:*
2602
+ #
2603
+ # ping pong
2604
+ # ping pong
2605
+ # ping pong
2606
+ # (snipped)
2607
+ # ping
2608
+ #
2609
+ def self.select: [X, Y, Z] (::Array[X & io]? read_array, ?::Array[Y & io]? write_array, ?::Array[Z & io]? error_array) -> [ Array[X], Array[Y], Array[Z] ]
2610
+ | [X, Y, Z] (::Array[X & io]? read_array, ?::Array[Y & io]? write_array, ?::Array[Z & io]? error_array, Numeric? timeout) -> [ Array[X], Array[Y], Array[Z] ]?
756
2611
 
2612
+ # <!--
2613
+ # rdoc-file=io.c
2614
+ # - IO.sysopen(path, [mode, [perm]]) -> integer
2615
+ # -->
2616
+ # Opens the given path, returning the underlying file descriptor as a Integer.
2617
+ #
2618
+ # IO.sysopen("testfile") #=> 3
2619
+ #
757
2620
  def self.sysopen: (String path, ?String mode, ?String perm) -> Integer
758
2621
 
2622
+ # <!--
2623
+ # rdoc-file=io.c
2624
+ # - IO.try_convert(object) -> new_io or nil
2625
+ # -->
2626
+ # Attempts to convert `object` into an IO object via method `to_io`; returns the
2627
+ # new IO object if successful, or `nil` otherwise:
2628
+ #
2629
+ # IO.try_convert(STDOUT) # => #<IO:<STDOUT>>
2630
+ # IO.try_convert(ARGF) # => #<IO:<STDIN>>
2631
+ # IO.try_convert('STDOUT') # => nil
2632
+ #
759
2633
  def self.try_convert: (untyped arg0) -> IO?
760
2634
 
2635
+ # <!--
2636
+ # rdoc-file=io.c
2637
+ # - IO.write(name, string [, offset]) -> integer
2638
+ # - IO.write(name, string [, offset] [, opt]) -> integer
2639
+ # - File.write(name, string [, offset]) -> integer
2640
+ # - File.write(name, string [, offset] [, opt]) -> integer
2641
+ # -->
2642
+ # Opens the file, optionally seeks to the given *offset*, writes *string*, then
2643
+ # returns the length written. #write ensures the file is closed before
2644
+ # returning. If *offset* is not given in write mode, the file is truncated.
2645
+ # Otherwise, it is not truncated.
2646
+ #
2647
+ # If `name` starts with a pipe character (`"|"`) and the receiver is the IO
2648
+ # class, a subprocess is created in the same way as Kernel#open, and its output
2649
+ # is returned. Consider to use File.write to disable the behavior of subprocess
2650
+ # invocation.
2651
+ #
2652
+ # File.write("testfile", "0123456789", 20) #=> 10
2653
+ # # File could contain: "This is line one\nThi0123456789two\nThis is line three\nAnd so on...\n"
2654
+ # File.write("testfile", "0123456789") #=> 10
2655
+ # # File would now read: "0123456789"
2656
+ # IO.write("|tr a-z A-Z", "abc") #=> 3
2657
+ # # Prints "ABC" to the standard output
2658
+ #
2659
+ # If the last argument is a hash, it specifies options for the internal open().
2660
+ # It accepts the following keys:
2661
+ #
2662
+ # :encoding
2663
+ # : string or encoding
2664
+ #
2665
+ # Specifies the encoding of the read string. See Encoding.aliases for
2666
+ # possible encodings.
2667
+ #
2668
+ # :mode
2669
+ # : string or integer
2670
+ #
2671
+ # Specifies the *mode* argument for open(). It must start with "w", "a", or
2672
+ # "r+", otherwise it will cause an error. See IO.new for the list of
2673
+ # possible modes.
2674
+ #
2675
+ # :perm
2676
+ # : integer
2677
+ #
2678
+ # Specifies the *perm* argument for open().
2679
+ #
2680
+ # :open_args
2681
+ # : array
2682
+ #
2683
+ # Specifies arguments for open() as an array. This key can not be used in
2684
+ # combination with other keys.
2685
+ #
2686
+ #
2687
+ # See also IO.read for details about `name` and open_args.
2688
+ #
761
2689
  def self.write: (String name, _ToS arg0, ?Integer offset, ?external_encoding: String external_encoding, ?internal_encoding: String internal_encoding, ?encoding: String encoding, ?textmode: untyped textmode, ?binmode: untyped binmode, ?autoclose: untyped autoclose, ?mode: String mode) -> Integer
762
2690
 
763
- def self.for_fd: (int fd, ?(string | int) mode, **untyped opt) -> instance
2691
+ # <!--
2692
+ # rdoc-file=io.c
2693
+ # - IO.for_fd(fd, mode [, opt]) -> io
2694
+ # -->
2695
+ # Synonym for IO.new.
2696
+ #
2697
+ def self.for_fd: (int fd, ?string | int mode, **untyped opt) -> instance
764
2698
 
2699
+ # <!--
2700
+ # rdoc-file=io.c
2701
+ # - IO.open(fd, mode="r" [, opt]) -> io
2702
+ # - IO.open(fd, mode="r" [, opt]) {|io| block } -> obj
2703
+ # -->
2704
+ # With no associated block, IO.open is a synonym for IO.new. If the optional
2705
+ # code block is given, it will be passed `io` as an argument, and the IO object
2706
+ # will automatically be closed when the block terminates. In this instance,
2707
+ # IO.open returns the value of the block.
2708
+ #
2709
+ # See IO.new for a description of the `fd`, `mode` and `opt` parameters.
2710
+ #
765
2711
  alias self.open self.for_fd
766
2712
 
767
- def self.open: [A] (int fd, ?(string | int) mode, **untyped opt) { (instance) -> A } -> A
2713
+ # <!--
2714
+ # rdoc-file=io.c
2715
+ # - IO.open(fd, mode="r" [, opt]) -> io
2716
+ # - IO.open(fd, mode="r" [, opt]) {|io| block } -> obj
2717
+ # -->
2718
+ # With no associated block, IO.open is a synonym for IO.new. If the optional
2719
+ # code block is given, it will be passed `io` as an argument, and the IO object
2720
+ # will automatically be closed when the block terminates. In this instance,
2721
+ # IO.open returns the value of the block.
2722
+ #
2723
+ # See IO.new for a description of the `fd`, `mode` and `opt` parameters.
2724
+ #
2725
+ def self.open: [A] (int fd, ?string | int mode, **untyped opt) { (instance) -> A } -> A
768
2726
  | ...
769
2727
 
770
2728
  def bytes: () { (Integer arg0) -> untyped } -> self
@@ -776,44 +2734,74 @@ class IO < Object
776
2734
  def codepoints: () { (Integer arg0) -> untyped } -> self
777
2735
  | () -> ::Enumerator[Integer, self]
778
2736
 
2737
+ # <!-- rdoc-file=io.c -->
2738
+ # Executes the block for every line in *ios*, where lines are separated by
2739
+ # *sep*. *ios* must be opened for reading or an IOError will be raised.
2740
+ #
2741
+ # If no block is given, an enumerator is returned instead.
2742
+ #
2743
+ # f = File.new("testfile")
2744
+ # f.each {|line| puts "#{f.lineno}: #{line}" }
2745
+ #
2746
+ # *produces:*
2747
+ #
2748
+ # 1: This is line one
2749
+ # 2: This is line two
2750
+ # 3: This is line three
2751
+ # 4: And so on...
2752
+ #
2753
+ # See IO.readlines for details about getline_args.
2754
+ #
779
2755
  def each_line: (?String sep, ?Integer limit) { (String arg0) -> untyped } -> self
780
2756
  | (?String sep, ?Integer limit) -> ::Enumerator[String, self]
781
2757
 
782
- # Returns true if *ios* is at end of file that means there are no more
783
- # data to read. The stream must be opened for reading or an `IOError` will
784
- # be raised.
2758
+ # <!-- rdoc-file=io.c -->
2759
+ # Returns `true` if the stream is positioned at its end, `false` otherwise; see
2760
+ # [Position](#class-IO-label-Position):
2761
+ #
2762
+ # f = File.open('t.txt')
2763
+ # f.eof # => false
2764
+ # f.seek(0, :END) # => 0
2765
+ # f.eof # => true
785
2766
  #
786
- # ```ruby
787
- # f = File.new("testfile")
788
- # dummy = f.readlines
789
- # f.eof #=> true
790
- # ```
2767
+ # Raises an exception unless the stream is opened for reading; see
2768
+ # [Mode](#class-IO-label-Mode).
791
2769
  #
792
- # If *ios* is a stream such as pipe or socket, `IO#eof?` blocks until the
793
- # other end sends some data or closes it.
2770
+ # If `self` is a stream such as pipe or socket, this method blocks until the
2771
+ # other end sends some data or closes it:
794
2772
  #
795
- # ```ruby
796
- # r, w = IO.pipe
797
- # Thread.new { sleep 1; w.close }
798
- # r.eof? #=> true after 1 second blocking
2773
+ # r, w = IO.pipe
2774
+ # Thread.new { sleep 1; w.close }
2775
+ # r.eof? # => true # After 1-second wait.
799
2776
  #
800
- # r, w = IO.pipe
801
- # Thread.new { sleep 1; w.puts "a" }
802
- # r.eof? #=> false after 1 second blocking
2777
+ # r, w = IO.pipe
2778
+ # Thread.new { sleep 1; w.puts "a" }
2779
+ # r.eof? # => false # After 1-second wait.
803
2780
  #
804
- # r, w = IO.pipe
805
- # r.eof? # blocks forever
806
- # ```
2781
+ # r, w = IO.pipe
2782
+ # r.eof? # blocks forever
2783
+ #
2784
+ # Note that this method reads data to the input byte buffer. So IO#sysread may
2785
+ # not behave as you intend with IO#eof?, unless you call IO#rewind first (which
2786
+ # is not available for some streams).
2787
+ #
2788
+ # I#eof? is an alias for IO#eof.
807
2789
  #
808
- # Note that `IO#eof?` reads data to the input byte buffer. So `IO#sysread`
809
- # may not behave as you intend with `IO#eof?`, unless you call
810
- # `IO#rewind` first (which is not available for some streams).
811
2790
  def eof?: () -> bool
812
2791
 
813
2792
  def lines: (?String sep, ?Integer limit) { (String arg0) -> untyped } -> self
814
2793
  | (?String sep, ?Integer limit) -> ::Enumerator[String, self]
815
2794
 
816
- # Alias for: [fileno](IO.downloaded.ruby_doc#method-i-fileno)
2795
+ # <!-- rdoc-file=io.c -->
2796
+ # Returns the integer file descriptor for the stream:
2797
+ #
2798
+ # $stdin.fileno # => 0
2799
+ # $stdout.fileno # => 1
2800
+ # $stderr.fileno # => 2
2801
+ # File.open('t.txt').fileno # => 10
2802
+ #
2803
+ # IO#to_i is an alias for IO#fileno.
2804
+ #
817
2805
  def to_i: () -> Integer
818
2806
  end
819
2807
 
@@ -867,14 +2855,29 @@ IO::RDWR: Integer
867
2855
 
868
2856
  IO::RSYNC: Integer
869
2857
 
2858
+ # <!-- rdoc-file=io.c -->
2859
+ # Set I/O position from the current position
2860
+ #
870
2861
  IO::SEEK_CUR: Integer
871
2862
 
2863
+ # <!-- rdoc-file=io.c -->
2864
+ # Set I/O position to the next location containing data
2865
+ #
872
2866
  IO::SEEK_DATA: Integer
873
2867
 
2868
+ # <!-- rdoc-file=io.c -->
2869
+ # Set I/O position from the end
2870
+ #
874
2871
  IO::SEEK_END: Integer
875
2872
 
2873
+ # <!-- rdoc-file=io.c -->
2874
+ # Set I/O position to the next hole
2875
+ #
876
2876
  IO::SEEK_HOLE: Integer
877
2877
 
2878
+ # <!-- rdoc-file=io.c -->
2879
+ # Set I/O position from the beginning
2880
+ #
878
2881
  IO::SEEK_SET: Integer
879
2882
 
880
2883
  IO::SHARE_DELETE: Integer
@@ -887,32 +2890,50 @@ IO::TRUNC: Integer
887
2890
 
888
2891
  IO::WRONLY: Integer
889
2892
 
2893
+ # <!-- rdoc-file=io.c -->
2894
+ # exception to wait for reading by EAGAIN. see IO.select.
2895
+ #
890
2896
  class IO::EAGAINWaitReadable < Errno::EAGAIN
891
2897
  include IO::WaitReadable
892
2898
  end
893
2899
 
894
2900
  IO::EAGAINWaitReadable::Errno: Integer
895
2901
 
2902
+ # <!-- rdoc-file=io.c -->
2903
+ # exception to wait for writing by EAGAIN. see IO.select.
2904
+ #
896
2905
  class IO::EAGAINWaitWritable < Errno::EAGAIN
897
2906
  include IO::WaitWritable
898
2907
  end
899
2908
 
900
2909
  IO::EAGAINWaitWritable::Errno: Integer
901
2910
 
2911
+ # <!-- rdoc-file=io.c -->
2912
+ # exception to wait for reading by EINPROGRESS. see IO.select.
2913
+ #
902
2914
  class IO::EINPROGRESSWaitReadable < Errno::EINPROGRESS
903
2915
  include IO::WaitReadable
904
2916
  end
905
2917
 
906
2918
  IO::EINPROGRESSWaitReadable::Errno: Integer
907
2919
 
2920
+ # <!-- rdoc-file=io.c -->
2921
+ # exception to wait for writing by EINPROGRESS. see IO.select.
2922
+ #
908
2923
  class IO::EINPROGRESSWaitWritable < Errno::EINPROGRESS
909
2924
  include IO::WaitWritable
910
2925
  end
911
2926
 
912
2927
  IO::EINPROGRESSWaitWritable::Errno: Integer
913
2928
 
2929
+ # <!-- rdoc-file=io.c -->
2930
+ # exception to wait for reading. see IO.select.
2931
+ #
914
2932
  module IO::WaitReadable
915
2933
  end
916
2934
 
2935
+ # <!-- rdoc-file=io.c -->
2936
+ # exception to wait for writing. see IO.select.
2937
+ #
917
2938
  module IO::WaitWritable
918
2939
  end