rbs 2.0.0 → 2.1.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.github/workflows/ruby.yml +5 -0
- data/CHANGELOG.md +23 -0
- data/README.md +6 -1
- data/core/array.rbs +2866 -1086
- data/core/basic_object.rbs +150 -30
- data/core/binding.rbs +33 -0
- data/core/builtin.rbs +4 -4
- data/core/class.rbs +43 -5
- data/core/comparable.rbs +57 -0
- data/core/complex.rbs +170 -4
- data/core/constants.rbs +51 -0
- data/core/deprecated.rbs +7 -0
- data/core/dir.rbs +305 -20
- data/core/encoding.rbs +472 -77
- data/core/enumerable.rbs +2173 -234
- data/core/enumerator.rbs +448 -182
- data/core/env.rbs +448 -1
- data/core/errno.rbs +1 -10
- data/core/errors.rbs +152 -2
- data/core/exception.rbs +201 -127
- data/core/false_class.rbs +27 -0
- data/core/fiber.rbs +118 -37
- data/core/fiber_error.rbs +8 -9
- data/core/file.rbs +1059 -139
- data/core/file_test.rbs +287 -32
- data/core/float.rbs +776 -300
- data/core/gc.rbs +185 -34
- data/core/global_variables.rbs +5 -1
- data/core/hash.rbs +1582 -649
- data/core/integer.rbs +974 -204
- data/core/io/buffer.rbs +710 -0
- data/core/io/wait.rbs +29 -8
- data/core/io.rbs +2438 -417
- data/core/kernel.rbs +2315 -316
- data/core/marshal.rbs +37 -2
- data/core/match_data.rbs +123 -6
- data/core/math.rbs +126 -6
- data/core/method.rbs +226 -102
- data/core/module.rbs +421 -45
- data/core/nil_class.rbs +64 -0
- data/core/numeric.rbs +620 -142
- data/core/object.rbs +453 -81
- data/core/object_space.rbs +92 -2
- data/core/proc.rbs +482 -285
- data/core/process.rbs +443 -34
- data/core/ractor.rbs +232 -9
- data/core/random.rbs +151 -52
- data/core/range.rbs +885 -160
- data/core/rational.rbs +122 -6
- data/core/rb_config.rbs +14 -4
- data/core/refinement.rbs +44 -0
- data/core/regexp.rbs +156 -14
- data/core/ruby_vm.rbs +42 -3
- data/core/signal.rbs +78 -39
- data/core/string.rbs +2123 -567
- data/core/string_io.rbs +204 -0
- data/core/struct.rbs +283 -28
- data/core/symbol.rbs +304 -30
- data/core/thread.rbs +1288 -688
- data/core/thread_group.rbs +66 -10
- data/core/time.rbs +643 -217
- data/core/trace_point.rbs +100 -12
- data/core/true_class.rbs +24 -0
- data/core/unbound_method.rbs +73 -7
- data/core/warning.rbs +37 -12
- data/docs/CONTRIBUTING.md +40 -34
- data/docs/stdlib.md +3 -102
- data/lib/rbs/annotate/annotations.rb +197 -0
- data/lib/rbs/annotate/formatter.rb +80 -0
- data/lib/rbs/annotate/rdoc_annotator.rb +398 -0
- data/lib/rbs/annotate/rdoc_source.rb +120 -0
- data/lib/rbs/annotate.rb +6 -0
- data/lib/rbs/cli.rb +45 -1
- data/lib/rbs/definition_builder.rb +5 -1
- data/lib/rbs/location_aux.rb +12 -0
- data/lib/rbs/prototype/rb.rb +12 -0
- data/lib/rbs/version.rb +1 -1
- data/sig/annotate/annotations.rbs +102 -0
- data/sig/annotate/formatter.rbs +24 -0
- data/sig/annotate/rdoc_annotater.rbs +82 -0
- data/sig/annotate/rdoc_source.rbs +30 -0
- data/sig/cli.rbs +2 -0
- data/sig/collection/{collections.rbs → sources.rbs} +0 -0
- data/sig/location.rbs +6 -0
- data/sig/method_types.rbs +5 -1
- data/sig/polyfill.rbs +78 -0
- data/stdlib/abbrev/0/abbrev.rbs +6 -0
- data/stdlib/abbrev/0/array.rbs +26 -0
- data/stdlib/base64/0/base64.rbs +31 -0
- data/stdlib/benchmark/0/benchmark.rbs +74 -3
- data/stdlib/bigdecimal/0/big_decimal.rbs +614 -165
- data/stdlib/bigdecimal-math/0/big_math.rbs +41 -64
- data/stdlib/cgi/0/core.rbs +59 -0
- data/stdlib/coverage/0/coverage.rbs +164 -2
- data/stdlib/csv/0/csv.rbs +2862 -398
- data/stdlib/date/0/date.rbs +483 -25
- data/stdlib/date/0/date_time.rbs +187 -12
- data/stdlib/dbm/0/dbm.rbs +152 -17
- data/stdlib/digest/0/digest.rbs +146 -0
- data/stdlib/erb/0/erb.rbs +65 -245
- data/stdlib/fiber/0/fiber.rbs +73 -91
- data/stdlib/fileutils/0/fileutils.rbs +301 -1
- data/stdlib/find/0/find.rbs +9 -0
- data/stdlib/forwardable/0/forwardable.rbs +65 -1
- data/stdlib/io-console/0/io-console.rbs +227 -15
- data/stdlib/ipaddr/0/ipaddr.rbs +161 -0
- data/stdlib/json/0/json.rbs +1146 -144
- data/stdlib/logger/0/formatter.rbs +24 -0
- data/stdlib/logger/0/log_device.rbs +64 -0
- data/stdlib/logger/0/logger.rbs +165 -13
- data/stdlib/logger/0/period.rbs +10 -0
- data/stdlib/logger/0/severity.rbs +26 -0
- data/stdlib/monitor/0/monitor.rbs +163 -0
- data/stdlib/mutex_m/0/mutex_m.rbs +35 -6
- data/stdlib/net-http/0/net-http.rbs +1492 -683
- data/stdlib/nkf/0/nkf.rbs +372 -0
- data/stdlib/objspace/0/objspace.rbs +149 -90
- data/stdlib/openssl/0/openssl.rbs +8108 -71
- data/stdlib/optparse/0/optparse.rbs +487 -19
- data/stdlib/pathname/0/pathname.rbs +425 -124
- data/stdlib/prettyprint/0/prettyprint.rbs +120 -99
- data/stdlib/prime/0/integer-extension.rbs +20 -2
- data/stdlib/prime/0/prime.rbs +88 -21
- data/stdlib/pstore/0/pstore.rbs +102 -0
- data/stdlib/pty/0/pty.rbs +64 -14
- data/stdlib/resolv/0/resolv.rbs +420 -31
- data/stdlib/rubygems/0/basic_specification.rbs +4 -1
- data/stdlib/rubygems/0/config_file.rbs +33 -1
- data/stdlib/rubygems/0/dependency_installer.rbs +4 -3
- data/stdlib/rubygems/0/installer.rbs +13 -1
- data/stdlib/rubygems/0/path_support.rbs +4 -1
- data/stdlib/rubygems/0/platform.rbs +5 -1
- data/stdlib/rubygems/0/request_set.rbs +44 -2
- data/stdlib/rubygems/0/requirement.rbs +65 -2
- data/stdlib/rubygems/0/rubygems.rbs +407 -0
- data/stdlib/rubygems/0/source_list.rbs +13 -0
- data/stdlib/rubygems/0/specification.rbs +21 -1
- data/stdlib/rubygems/0/stream_ui.rbs +3 -1
- data/stdlib/rubygems/0/uninstaller.rbs +8 -1
- data/stdlib/rubygems/0/version.rbs +60 -157
- data/stdlib/securerandom/0/securerandom.rbs +44 -0
- data/stdlib/set/0/set.rbs +420 -106
- data/stdlib/shellwords/0/shellwords.rbs +55 -77
- data/stdlib/singleton/0/singleton.rbs +20 -0
- data/stdlib/socket/0/addrinfo.rbs +210 -9
- data/stdlib/socket/0/basic_socket.rbs +103 -11
- data/stdlib/socket/0/ip_socket.rbs +31 -9
- data/stdlib/socket/0/socket.rbs +586 -38
- data/stdlib/socket/0/tcp_server.rbs +22 -2
- data/stdlib/socket/0/tcp_socket.rbs +12 -1
- data/stdlib/socket/0/udp_socket.rbs +25 -2
- data/stdlib/socket/0/unix_server.rbs +22 -2
- data/stdlib/socket/0/unix_socket.rbs +45 -5
- data/stdlib/strscan/0/string_scanner.rbs +210 -9
- data/stdlib/tempfile/0/tempfile.rbs +58 -10
- data/stdlib/time/0/time.rbs +208 -116
- data/stdlib/timeout/0/timeout.rbs +10 -0
- data/stdlib/tmpdir/0/tmpdir.rbs +13 -4
- data/stdlib/tsort/0/cyclic.rbs +1 -0
- data/stdlib/tsort/0/interfaces.rbs +1 -0
- data/stdlib/tsort/0/tsort.rbs +42 -0
- data/stdlib/uri/0/common.rbs +57 -8
- data/stdlib/uri/0/file.rbs +55 -109
- data/stdlib/uri/0/ftp.rbs +6 -3
- data/stdlib/uri/0/generic.rbs +556 -327
- data/stdlib/uri/0/http.rbs +26 -115
- data/stdlib/uri/0/https.rbs +8 -102
- data/stdlib/uri/0/ldap.rbs +143 -137
- data/stdlib/uri/0/ldaps.rbs +8 -102
- data/stdlib/uri/0/mailto.rbs +3 -0
- data/stdlib/uri/0/rfc2396_parser.rbs +66 -26
- data/stdlib/uri/0/ws.rbs +6 -3
- data/stdlib/uri/0/wss.rbs +5 -3
- data/stdlib/yaml/0/dbm.rbs +151 -87
- data/stdlib/yaml/0/store.rbs +6 -0
- data/stdlib/zlib/0/zlib.rbs +90 -31
- metadata +17 -5
- data/lib/rbs/location.rb +0 -221
data/core/io.rbs
CHANGED
@@ -1,123 +1,699 @@
|
|
1
|
-
#
|
2
|
-
# output in Ruby. An I/O stream may
|
3
|
-
# bidirectional), and so may use more than one native
|
4
|
-
# stream.
|
5
|
-
#
|
6
|
-
# Many of the examples in this section use the
|
7
|
-
#
|
8
|
-
#
|
9
|
-
#
|
10
|
-
#
|
11
|
-
#
|
12
|
-
#
|
13
|
-
#
|
14
|
-
#
|
15
|
-
#
|
16
|
-
#
|
17
|
-
#
|
18
|
-
#
|
19
|
-
#
|
20
|
-
#
|
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
|
-
#
|
37
|
-
#
|
38
|
-
#
|
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
|
-
#
|
41
|
-
#
|
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
|
-
#
|
47
|
-
#
|
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
|
-
#
|
51
|
-
# File::ALT\_SEPARATOR can be used to get the platform-specific separator
|
52
|
-
# character.
|
37
|
+
# "C:\\gumby\\ruby\\test.rb"
|
53
38
|
#
|
54
|
-
#
|
55
|
-
#
|
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
|
-
#
|
65
|
-
#
|
66
|
-
#
|
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
|
-
#
|
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
|
-
#
|
104
|
+
# ## Modes
|
73
105
|
#
|
74
|
-
#
|
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
|
-
# -
|
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
|
-
#
|
115
|
+
# ### Mode Specified as an Integer
|
81
116
|
#
|
82
|
-
#
|
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
|
-
#
|
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
|
-
#
|
129
|
+
# Examples:
|
89
130
|
#
|
90
|
-
#
|
131
|
+
# File.new('t.txt', File::RDONLY)
|
132
|
+
# File.new('t.tmp', File::RDWR | File::CREAT | File::EXCL)
|
91
133
|
#
|
92
|
-
#
|
134
|
+
# Note: Method IO#set_encoding does not allow the mode to be specified as an
|
135
|
+
# integer.
|
93
136
|
#
|
94
|
-
#
|
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
|
-
#
|
101
|
-
#
|
102
|
-
#
|
103
|
-
#
|
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
|
-
#
|
111
|
-
#
|
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 <<
|
683
|
+
# $stdout << 'Hello' << ', ' << 'World!' << "\n"
|
684
|
+
# $stdout << 'foo' << :bar << 2 << "\n"
|
114
685
|
#
|
115
|
-
#
|
686
|
+
# Output:
|
116
687
|
#
|
117
|
-
# Hello
|
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: (
|
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
|
-
#
|
192
|
-
#
|
193
|
-
#
|
194
|
-
#
|
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
|
-
#
|
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
|
206
|
-
#
|
207
|
-
#
|
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
|
-
#
|
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
|
-
#
|
220
|
-
#
|
221
|
-
#
|
222
|
-
#
|
223
|
-
#
|
224
|
-
#
|
225
|
-
#
|
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
|
-
#
|
230
|
-
#
|
231
|
-
#
|
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
|
-
#
|
234
|
-
#
|
235
|
-
#
|
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
|
245
|
-
#
|
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
|
-
#
|
249
|
-
#
|
250
|
-
#
|
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
|
-
#
|
253
|
-
#
|
254
|
-
#
|
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
|
265
|
-
#
|
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
|
-
#
|
269
|
-
#
|
270
|
-
#
|
271
|
-
#
|
272
|
-
#
|
273
|
-
#
|
274
|
-
#
|
275
|
-
#
|
276
|
-
#
|
277
|
-
#
|
278
|
-
#
|
279
|
-
#
|
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
|
-
#
|
296
|
-
#
|
297
|
-
#
|
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
|
-
#
|
300
|
-
#
|
301
|
-
#
|
302
|
-
#
|
303
|
-
# ```
|
994
|
+
# f = File.open('t.txt')
|
995
|
+
# f.eof # => false
|
996
|
+
# f.seek(0, :END) # => 0
|
997
|
+
# f.eof # => true
|
304
998
|
#
|
305
|
-
#
|
306
|
-
#
|
999
|
+
# Raises an exception unless the stream is opened for reading; see
|
1000
|
+
# [Mode](#class-IO-label-Mode).
|
307
1001
|
#
|
308
|
-
#
|
309
|
-
#
|
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
|
-
#
|
314
|
-
#
|
315
|
-
#
|
1005
|
+
# r, w = IO.pipe
|
1006
|
+
# Thread.new { sleep 1; w.close }
|
1007
|
+
# r.eof? # => true # After 1-second wait.
|
316
1008
|
#
|
317
|
-
#
|
318
|
-
#
|
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
|
-
#
|
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
|
-
#
|
336
|
-
#
|
337
|
-
#
|
338
|
-
#
|
339
|
-
#
|
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
|
-
#
|
348
|
-
#
|
349
|
-
#
|
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
|
-
#
|
352
|
-
#
|
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
|
-
#
|
364
|
-
#
|
365
|
-
#
|
366
|
-
#
|
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
|
-
#
|
373
|
-
#
|
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
|
-
#
|
383
|
-
#
|
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
|
-
#
|
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
|
-
#
|
400
|
-
#
|
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
|
-
#
|
407
|
-
#
|
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
|
-
#
|
416
|
-
#
|
417
|
-
#
|
418
|
-
#
|
419
|
-
#
|
420
|
-
#
|
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
|
423
|
-
#
|
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
|
-
#
|
430
|
-
#
|
431
|
-
#
|
432
|
-
#
|
433
|
-
#
|
434
|
-
#
|
435
|
-
#
|
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
|
-
#
|
442
|
-
#
|
443
|
-
#
|
444
|
-
#
|
445
|
-
#
|
446
|
-
# if
|
447
|
-
#
|
448
|
-
#
|
449
|
-
#
|
450
|
-
#
|
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
|
-
#
|
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
|
-
#
|
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
|
-
#
|
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
|
-
#
|
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
|
-
#
|
484
|
-
#
|
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
|
490
|
-
#
|
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
|
-
|
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
|
-
#
|
500
|
-
#
|
501
|
-
#
|
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
|
-
#
|
504
|
-
#
|
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
|
-
#
|
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
|
-
#
|
513
|
-
#
|
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
|
-
#
|
520
|
-
#
|
521
|
-
#
|
522
|
-
#
|
523
|
-
#
|
524
|
-
#
|
525
|
-
#
|
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
|
-
#
|
529
|
-
#
|
530
|
-
#
|
531
|
-
#
|
532
|
-
#
|
533
|
-
#
|
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
|
-
#
|
541
|
-
#
|
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
|
-
#
|
545
|
-
#
|
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
|
-
#
|
559
|
-
#
|
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
|
-
#
|
562
|
-
#
|
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
|
-
#
|
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
|
-
#
|
576
|
-
#
|
577
|
-
#
|
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
|
-
#
|
580
|
-
#
|
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
|
-
#
|
585
|
-
#
|
586
|
-
#
|
587
|
-
#
|
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
|
-
#
|
596
|
-
#
|
597
|
-
#
|
598
|
-
#
|
599
|
-
#
|
600
|
-
#
|
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
|
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
|
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
|
-
#
|
620
|
-
#
|
621
|
-
#
|
622
|
-
#
|
623
|
-
#
|
624
|
-
#
|
625
|
-
#
|
626
|
-
#
|
627
|
-
#
|
628
|
-
#
|
629
|
-
#
|
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
|
-
#
|
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
|
-
#
|
652
|
-
#
|
653
|
-
#
|
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
|
-
#
|
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
|
-
#
|
2075
|
+
# <!--
|
2076
|
+
# rdoc-file=io.c
|
2077
|
+
# - to_io -> self
|
2078
|
+
# -->
|
2079
|
+
# Returns `self`.
|
2080
|
+
#
|
680
2081
|
def to_io: () -> self
|
681
2082
|
|
682
|
-
#
|
683
|
-
# `false`
|
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
|
-
#
|
696
|
-
#
|
697
|
-
#
|
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
|
-
#
|
700
|
-
#
|
2167
|
+
# $stdout.write('Hello', ', ', 'World!', "\n") # => 14
|
2168
|
+
# $stdout.write('foo', :bar, 2, "\n") # => 8
|
701
2169
|
#
|
702
|
-
#
|
2170
|
+
# Output:
|
703
2171
|
#
|
704
|
-
#
|
705
|
-
#
|
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
|
-
#
|
717
|
-
#
|
718
|
-
#
|
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: (
|
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
|
-
|
755
|
-
|
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
|
-
|
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
|
-
|
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
|
-
#
|
783
|
-
#
|
784
|
-
#
|
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
|
-
#
|
787
|
-
#
|
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
|
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
|
-
#
|
796
|
-
#
|
797
|
-
#
|
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
|
-
#
|
801
|
-
#
|
802
|
-
#
|
2777
|
+
# r, w = IO.pipe
|
2778
|
+
# Thread.new { sleep 1; w.puts "a" }
|
2779
|
+
# r.eof? # => false # After 1-second wait.
|
803
2780
|
#
|
804
|
-
#
|
805
|
-
#
|
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
|
-
#
|
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
|