зеркало из https://github.com/github/ruby.git
[DOC] RDoc changes for IO (#6458)
Moves Expect library doc into io.c. Changes certain links to local sections, now pointing to sections in doc/io_streams.rdoc. Removes local sections now superseded by sections in doc/io_streams.rdoc.
This commit is contained in:
Родитель
85fc822307
Коммит
ded895baa9
|
@ -1,19 +1,19 @@
|
|||
# frozen_string_literal: true
|
||||
$expect_verbose = false
|
||||
|
||||
# Expect library adds the IO instance method #expect, which does similar act to
|
||||
# tcl's expect extension.
|
||||
#
|
||||
# In order to use this method, you must require expect:
|
||||
#
|
||||
# require 'expect'
|
||||
#
|
||||
# Please see #expect for usage.
|
||||
class IO
|
||||
# call-seq:
|
||||
# IO#expect(pattern,timeout=9999999) -> Array
|
||||
# IO#expect(pattern,timeout=9999999) { |result| ... } -> nil
|
||||
#
|
||||
# The +expect+ library adds instance method IO#expect,
|
||||
# which is similar to the
|
||||
# {TCL expect extension}[https://www.tcl.tk/man/expect5.31/expect.1.html].
|
||||
#
|
||||
# To use this method, you must require +expect+:
|
||||
#
|
||||
# require 'expect'
|
||||
#
|
||||
# Reads from the IO until the given +pattern+ matches or the +timeout+ is over.
|
||||
#
|
||||
# It returns an array with the read buffer, followed by the matches.
|
||||
|
|
2
file.c
2
file.c
|
@ -6573,7 +6573,7 @@ const char ruby_null_device[] =
|
|||
*
|
||||
* :include: doc/examples/files.rdoc
|
||||
*
|
||||
* == \File Access Modes
|
||||
* == Access Modes
|
||||
*
|
||||
* \Methods File.new and File.open each create a \File object for a given file path.
|
||||
*
|
||||
|
|
429
io.c
429
io.c
|
@ -2057,7 +2057,8 @@ io_writev(int argc, const VALUE *argv, VALUE io)
|
|||
* write(*objects) -> integer
|
||||
*
|
||||
* Writes each of the given +objects+ to +self+,
|
||||
* which must be opened for writing (see IO@Modes);
|
||||
* which must be opened for writing
|
||||
* (see {Access Modes}[rdoc-ref:File@Access+Modes]);
|
||||
* returns the total number bytes written;
|
||||
* each of +objects+ that is not a string is converted via method +to_s+:
|
||||
*
|
||||
|
@ -2116,7 +2117,7 @@ rb_io_writev(VALUE io, int argc, const VALUE *argv)
|
|||
* self << object -> self
|
||||
*
|
||||
* Writes the given +object+ to +self+,
|
||||
* which must be opened for writing (see IO@Modes);
|
||||
* which must be opened for writing (see {Access Modes}[rdoc-ref:File@Access+Modes]);
|
||||
* returns +self+;
|
||||
* if +object+ is not a string, it is converted via method +to_s+:
|
||||
*
|
||||
|
@ -2198,7 +2199,7 @@ rb_io_flush(VALUE io)
|
|||
* tell -> integer
|
||||
*
|
||||
* Returns the current position (in bytes) in +self+
|
||||
* (see {Position}[rdoc-ref:IO@Position]):
|
||||
* (see {Position}[rdoc-ref:io_streams.rdoc@Position]):
|
||||
*
|
||||
* f = File.open('t.txt')
|
||||
* f.tell # => 0
|
||||
|
@ -2264,7 +2265,7 @@ interpret_seek_whence(VALUE vwhence)
|
|||
* seek(offset, whence = IO::SEEK_SET) -> 0
|
||||
*
|
||||
* Seeks to the position given by integer +offset+
|
||||
* (see {Position}[rdoc-ref:IO@Position])
|
||||
* (see {Position}[rdoc-ref:io_streams.rdoc@Position])
|
||||
* and constant +whence+, which is one of:
|
||||
*
|
||||
* - +:CUR+ or <tt>IO::SEEK_CUR</tt>:
|
||||
|
@ -2324,7 +2325,7 @@ rb_io_seek_m(int argc, VALUE *argv, VALUE io)
|
|||
* pos = new_position -> new_position
|
||||
*
|
||||
* Seeks to the given +new_position+ (in bytes);
|
||||
* see {Position}[rdoc-ref:IO@Position]:
|
||||
* see {Position}[rdoc-ref:io_streams.rdoc@Position]:
|
||||
*
|
||||
* f = File.open('t.txt')
|
||||
* f.tell # => 0
|
||||
|
@ -2358,8 +2359,8 @@ static void clear_readconv(rb_io_t *fptr);
|
|||
*
|
||||
* Repositions the stream to its beginning,
|
||||
* setting both the position and the line number to zero;
|
||||
* see {Position}[rdoc-ref:IO@Position]
|
||||
* and {Line Number}[rdoc-ref:IO@Line+Number]:
|
||||
* see {Position}[rdoc-ref:io_streams.rdoc@Position]
|
||||
* and {Line Number}[rdoc-ref:io_streams.rdoc@Line+Number]:
|
||||
*
|
||||
* f = File.open('t.txt')
|
||||
* f.tell # => 0
|
||||
|
@ -2449,7 +2450,7 @@ io_fillbuf(rb_io_t *fptr)
|
|||
* eof -> true or false
|
||||
*
|
||||
* Returns +true+ if the stream is positioned at its end, +false+ otherwise;
|
||||
* see {Position}[rdoc-ref:IO@Position]:
|
||||
* see {Position}[rdoc-ref:io_streams.rdoc@Position]:
|
||||
*
|
||||
* f = File.open('t.txt')
|
||||
* f.eof # => false
|
||||
|
@ -2458,7 +2459,7 @@ io_fillbuf(rb_io_t *fptr)
|
|||
* f.close
|
||||
*
|
||||
* Raises an exception unless the stream is opened for reading;
|
||||
* see {Mode}[rdoc-ref:IO@Mode].
|
||||
* see {Mode}[rdoc-ref:File@Access+Modes].
|
||||
*
|
||||
* If +self+ is a stream such as pipe or socket, this method
|
||||
* blocks until the other end sends some data or closes it:
|
||||
|
@ -4017,7 +4018,7 @@ rb_io_gets_internal(VALUE io)
|
|||
* gets(sep, limit, **line_opts) -> string or nil
|
||||
*
|
||||
* Reads and returns a line from the stream
|
||||
* (see {Lines}[rdoc-ref:IO@Lines]);
|
||||
* (see {Line IO}[rdoc-ref:io_streams.rdoc@Line+IO]);
|
||||
* assigns the return value to <tt>$_</tt>.
|
||||
*
|
||||
* With no arguments given, returns the next line
|
||||
|
@ -4035,7 +4036,7 @@ rb_io_gets_internal(VALUE io)
|
|||
* With only string argument +sep+ given,
|
||||
* returns the next line as determined by line separator +sep+,
|
||||
* or +nil+ if none;
|
||||
* see {Line Separator}[rdoc-ref:IO@Line+Separator]:
|
||||
* see {Line Separator}[rdoc-ref:io_streams.rdoc@Line+Separator]:
|
||||
*
|
||||
* f = File.new('t.txt')
|
||||
* f.gets('l') # => "First l"
|
||||
|
@ -4056,7 +4057,7 @@ rb_io_gets_internal(VALUE io)
|
|||
*
|
||||
* With only integer argument +limit+ given,
|
||||
* limits the number of bytes in the line;
|
||||
* see {Line Limit}[rdoc-ref:IO@Line+Limit]:
|
||||
* see {Line Limit}[rdoc-ref:io_streams.rdoc@Line+Limit]:
|
||||
*
|
||||
* # No more than one line.
|
||||
* File.open('t.txt') {|f| f.gets(10) } # => "First line"
|
||||
|
@ -4071,7 +4072,7 @@ rb_io_gets_internal(VALUE io)
|
|||
* - But returns no more bytes than are allowed by the limit.
|
||||
*
|
||||
* For all forms above, optional keyword arguments +line_opts+ specify
|
||||
* {Line Options}[rdoc-ref:IO@Line+Options]:
|
||||
* {Line Options}[rdoc-ref:io_streams.rdoc@Line+Options]:
|
||||
*
|
||||
* f = File.open('t.txt')
|
||||
* # Chomp the lines.
|
||||
|
@ -4101,7 +4102,7 @@ rb_io_gets_m(int argc, VALUE *argv, VALUE io)
|
|||
* lineno -> integer
|
||||
*
|
||||
* Returns the current line number for the stream.
|
||||
* See {Line Number}[rdoc-ref:IO@Line+Number].
|
||||
* See {Line Number}[rdoc-ref:io_streams.rdoc@Line+Number].
|
||||
*
|
||||
*/
|
||||
|
||||
|
@ -4120,7 +4121,7 @@ rb_io_lineno(VALUE io)
|
|||
* lineno = integer -> integer
|
||||
*
|
||||
* Sets and returns the line number for the stream.
|
||||
* See {Line Number}[rdoc-ref:IO@Line+Number].
|
||||
* See {Line Number}[rdoc-ref:io_streams.rdoc@Line+Number].
|
||||
*
|
||||
*/
|
||||
|
||||
|
@ -4165,7 +4166,7 @@ static VALUE io_readlines(const struct getline_arg *arg, VALUE io);
|
|||
* readlines(sep, limit, **line_opts) -> array
|
||||
*
|
||||
* Reads and returns all remaining line from the stream
|
||||
* (see {Lines}[rdoc-ref:IO@Lines]);
|
||||
* (see {Line IO}[rdoc-ref:io_streams.rdoc@Line+IO]);
|
||||
* does not modify <tt>$_</tt>.
|
||||
*
|
||||
* With no arguments given, returns lines
|
||||
|
@ -4180,7 +4181,7 @@ static VALUE io_readlines(const struct getline_arg *arg, VALUE io);
|
|||
* With only string argument +sep+ given,
|
||||
* returns lines as determined by line separator +sep+,
|
||||
* or +nil+ if none;
|
||||
* see {Line Separator}[rdoc-ref:IO@Line+Separator]:
|
||||
* see {Line Separator}[rdoc-ref:io_streams.rdoc@Line+Separator]:
|
||||
*
|
||||
* f = File.new('t.txt')
|
||||
* f.readlines('li')
|
||||
|
@ -4201,7 +4202,7 @@ static VALUE io_readlines(const struct getline_arg *arg, VALUE io);
|
|||
*
|
||||
* With only integer argument +limit+ given,
|
||||
* limits the number of bytes in each line;
|
||||
* see {Line Limit}[rdoc-ref:IO@Line+Limit]:
|
||||
* see {Line Limit}[rdoc-ref:io_streams.rdoc@Line+Limit]:
|
||||
*
|
||||
* f = File.new('t.txt')
|
||||
* f.readlines(8)
|
||||
|
@ -4215,7 +4216,7 @@ static VALUE io_readlines(const struct getline_arg *arg, VALUE io);
|
|||
* - But returns no more bytes in a line than are allowed by the limit.
|
||||
*
|
||||
* For all forms above, optional keyword arguments +line_opts+ specify
|
||||
* {Line Options}[rdoc-ref:IO@Line+Options]:
|
||||
* {Line Options}[rdoc-ref:io_streams.rdoc@Line+Options]:
|
||||
*
|
||||
* f = File.new('t.txt')
|
||||
* f.readlines(chomp: true)
|
||||
|
@ -4255,7 +4256,7 @@ io_readlines(const struct getline_arg *arg, VALUE io)
|
|||
* each_line -> enumerator
|
||||
*
|
||||
* Calls the block with each remaining line read from the stream
|
||||
* (see {Lines}[rdoc-ref:IO@Lines]);
|
||||
* (see {Line IO}[rdoc-ref:io_streams.rdoc@Line+IO]);
|
||||
* does nothing if already at end-of-file;
|
||||
* returns +self+.
|
||||
*
|
||||
|
@ -4277,7 +4278,7 @@ io_readlines(const struct getline_arg *arg, VALUE io)
|
|||
*
|
||||
* With only string argument +sep+ given,
|
||||
* reads lines as determined by line separator +sep+;
|
||||
* see {Line Separator}[rdoc-ref:IO@Line+Separator]:
|
||||
* see {Line Separator}[rdoc-ref:io_streams.rdoc@Line+Separator]:
|
||||
*
|
||||
* f = File.new('t.txt')
|
||||
* f.each_line('li') {|line| p line }
|
||||
|
@ -4313,7 +4314,7 @@ io_readlines(const struct getline_arg *arg, VALUE io)
|
|||
*
|
||||
* With only integer argument +limit+ given,
|
||||
* limits the number of bytes in each line;
|
||||
* see {Line Limit}[rdoc-ref:IO@Line+Limit]:
|
||||
* see {Line Limit}[rdoc-ref:io_streams.rdoc@Line+Limit]:
|
||||
*
|
||||
* f = File.new('t.txt')
|
||||
* f.each_line(8) {|line| p line }
|
||||
|
@ -4338,7 +4339,7 @@ io_readlines(const struct getline_arg *arg, VALUE io)
|
|||
* - But returns no more bytes than are allowed by the limit.
|
||||
*
|
||||
* For all forms above, optional keyword arguments +line_opts+ specify
|
||||
* {Line Options}[rdoc-ref:IO@Line+Options]:
|
||||
* {Line Options}[rdoc-ref:io_streams.rdoc@Line+Options]:
|
||||
*
|
||||
* f = File.new('t.txt')
|
||||
* f.each_line(chomp: true) {|line| p line }
|
||||
|
@ -5811,7 +5812,7 @@ pread_internal_call(VALUE arg)
|
|||
*
|
||||
* - Reads at the given +offset+ (in bytes).
|
||||
* - Disregards, and does not modify, the stream's position
|
||||
* (see {Position}[rdoc-ref:IO@Position]).
|
||||
* (see {Position}[rdoc-ref:io_streams.rdoc@Position]).
|
||||
* - Bypasses any user space buffering in the stream.
|
||||
*
|
||||
* Because this method does not disturb the stream's state
|
||||
|
@ -5887,7 +5888,7 @@ internal_pwrite_func(void *ptr)
|
|||
*
|
||||
* - Writes at the given +offset+ (in bytes).
|
||||
* - Disregards, and does not modify, the stream's position
|
||||
* (see {Position}[rdoc-ref:IO@Position]).
|
||||
* (see {Position}[rdoc-ref:io_streams.rdoc@Position]).
|
||||
* - Bypasses any user space buffering in the stream.
|
||||
*
|
||||
* Because this method does not disturb the stream's state
|
||||
|
@ -5998,7 +5999,7 @@ rb_io_ascii8bit_binmode(VALUE io)
|
|||
* binmode -> self
|
||||
*
|
||||
* Sets the stream's data mode as binary
|
||||
* (see {Data Mode}[rdoc-ref:IO@Data+Mode]).
|
||||
* (see {Data Mode}[rdoc-ref:File@Data+Mode]).
|
||||
*
|
||||
* A stream's data mode may not be changed from binary to text.
|
||||
*
|
||||
|
@ -6022,7 +6023,7 @@ rb_io_binmode_m(VALUE io)
|
|||
* binmode? -> true or false
|
||||
*
|
||||
* Returns +true+ if the stream is on binary mode, +false+ otherwise.
|
||||
* See {Data Mode}[rdoc-ref:IO@Data+Mode].
|
||||
* See {Data Mode}[rdoc-ref:File@Data+Mode].
|
||||
*
|
||||
*/
|
||||
static VALUE
|
||||
|
@ -7453,7 +7454,7 @@ static VALUE popen_finish(VALUE port, VALUE klass);
|
|||
* and the block's value is assigned to global variable <tt>$?</tt> and returned.
|
||||
*
|
||||
* Optional argument +mode+ may be any valid \IO mode.
|
||||
* See IO@Modes.
|
||||
* See {Access Modes}[rdoc-ref:File@Access+Modes].
|
||||
*
|
||||
* Required argument +cmd+ determines which of the following occurs:
|
||||
*
|
||||
|
@ -9027,8 +9028,8 @@ rb_io_make_open_file(VALUE obj)
|
|||
* io = IO.new(fd)
|
||||
* io.external_encoding # => #<Encoding:UTF-8> # Not ASCII-8BIT.
|
||||
*
|
||||
* Optional argument +mode+ (defaults to 'r') must specify a valid mode
|
||||
* see IO@Modes:
|
||||
* Optional argument +mode+ (defaults to 'r') must specify a valid mode;
|
||||
* see {Access Modes}[rdoc-ref:File@Access+Modes]:
|
||||
*
|
||||
* IO.new(fd, 'w') # => #<IO:fd 3>
|
||||
* IO.new(fd, File::WRONLY) # => #<IO:fd 3>
|
||||
|
@ -9165,14 +9166,14 @@ rb_io_set_encoding_by_bom(VALUE io)
|
|||
* File.new('/etc/fstab')
|
||||
* File.new('t.txt')
|
||||
*
|
||||
* Optional argument +mode+ (defaults to 'r') must specify a valid mode
|
||||
* see IO@Modes:
|
||||
* Optional argument +mode+ (defaults to 'r') must specify a valid mode;
|
||||
* see {Access Modes}[rdoc-ref:File@Access+Modes]:
|
||||
*
|
||||
* File.new('t.tmp', 'w')
|
||||
* File.new('t.tmp', File::RDONLY)
|
||||
*
|
||||
* Optional argument +perm+ (defaults to 0666) must specify valid permissions
|
||||
* see {File Permissions}[rdoc-ref:IO@File+Permissions]:
|
||||
* see {File Permissions}[rdoc-ref:File@File+Permissions]:
|
||||
*
|
||||
* File.new('t.tmp', File::CREAT, 0644)
|
||||
* File.new('t.tmp', File::CREAT, 0444)
|
||||
|
@ -10034,12 +10035,12 @@ static VALUE argf_readlines(int, VALUE *, VALUE);
|
|||
*
|
||||
* Returns an array containing the lines returned by calling
|
||||
* Kernel#gets until the end-of-file is reached;
|
||||
* (see {Lines}[rdoc-ref:IO@Lines]).
|
||||
* (see {Line IO}[rdoc-ref:io_streams.rdoc@Line+IO]).
|
||||
*
|
||||
* With only string argument +sep+ given,
|
||||
* returns the remaining lines as determined by line separator +sep+,
|
||||
* or +nil+ if none;
|
||||
* see {Line Separator}[rdoc-ref:IO@Line+Separator]:
|
||||
* see {Line Separator}[rdoc-ref:io_streams.rdoc@Line+Separator]:
|
||||
*
|
||||
* # Default separator.
|
||||
* $ cat t.txt | ruby -e "p readlines"
|
||||
|
@ -10059,7 +10060,7 @@ static VALUE argf_readlines(int, VALUE *, VALUE);
|
|||
*
|
||||
* With only integer argument +limit+ given,
|
||||
* limits the number of bytes in the line;
|
||||
* see {Line Limit}[rdoc-ref:IO@Line+Limit]:
|
||||
* see {Line Limit}[rdoc-ref:io_streams.rdoc@Line+Limit]:
|
||||
*
|
||||
* $cat t.txt | ruby -e "p readlines 10"
|
||||
* ["First line", "\n", "Second lin", "e\n", "\n", "Fourth lin", "e\n", "Fifth line", "\n"]
|
||||
|
@ -10071,11 +10072,11 @@ static VALUE argf_readlines(int, VALUE *, VALUE);
|
|||
* ["First line\n", "Second line\n", "\n", "Fourth line\n", "Fifth line\n"]
|
||||
*
|
||||
* With arguments +sep+ and +limit+ given, combines the two behaviors;
|
||||
* see {Line Separator and Line Limit}[rdoc-ref:IO@Line+Separator+and+Line+Limit].
|
||||
* see {Line Separator and Line Limit}[rdoc-ref:io_streams.rdoc@Line+Separator+and+Line+Limit].
|
||||
*
|
||||
* For all forms above, optional keyword arguments specify:
|
||||
*
|
||||
* - {Line Options}[rdoc-ref:IO@Line+Options].
|
||||
* - {Line Options}[rdoc-ref:io_streams.rdoc@Line+Options].
|
||||
* - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
|
||||
*
|
||||
* Examples:
|
||||
|
@ -11559,7 +11560,7 @@ io_s_foreach(VALUE v)
|
|||
* For both forms, command and path, the remaining arguments are the same.
|
||||
*
|
||||
* With argument +sep+ given, parses lines as determined by that line separator
|
||||
* (see {Line Separator}[rdoc-ref:IO@Line+Separator]):
|
||||
* (see {Line Separator}[rdoc-ref:io_streams.rdoc@Line+Separator]):
|
||||
*
|
||||
* File.foreach('t.txt', 'li') {|line| p line }
|
||||
*
|
||||
|
@ -11582,7 +11583,7 @@ io_s_foreach(VALUE v)
|
|||
*
|
||||
* With argument +limit+ given, parses lines as determined by the default
|
||||
* line separator and the given line-length limit
|
||||
* (see {Line Limit}[rdoc-ref:IO@Line+Limit]):
|
||||
* (see {Line Limit}[rdoc-ref:io_streams.rdoc@Line+Limit]):
|
||||
*
|
||||
* File.foreach('t.txt', 7) {|line| p line }
|
||||
*
|
||||
|
@ -11601,13 +11602,13 @@ io_s_foreach(VALUE v)
|
|||
* With arguments +sep+ and +limit+ given,
|
||||
* parses lines as determined by the given
|
||||
* line separator and the given line-length limit
|
||||
* (see {Line Separator and Line Limit}[rdoc-ref:IO@Line+Separator+and+Line+Limit]):
|
||||
* (see {Line Separator and Line Limit}[rdoc-ref:io_streams.rdoc@Line+Separator+and+Line+Limit]):
|
||||
*
|
||||
* Optional keyword arguments +opts+ specify:
|
||||
*
|
||||
* - {Open Options}[rdoc-ref:IO@Open+Options].
|
||||
* - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
|
||||
* - {Line Options}[rdoc-ref:IO@Line+Options].
|
||||
* - {Line Options}[rdoc-ref:io_streams.rdoc@Line+Options].
|
||||
*
|
||||
* Returns an Enumerator if no block is given.
|
||||
*
|
||||
|
@ -11677,7 +11678,7 @@ io_s_readlines(VALUE v)
|
|||
* For both forms, command and path, the remaining arguments are the same.
|
||||
*
|
||||
* With argument +sep+ given, parses lines as determined by that line separator
|
||||
* (see {Line Separator}[rdoc-ref:IO@Line+Separator]):
|
||||
* (see {Line Separator}[rdoc-ref:io_streams.rdoc@Line+Separator]):
|
||||
*
|
||||
* # Ordinary separator.
|
||||
* IO.readlines('t.txt', 'li')
|
||||
|
@ -11691,7 +11692,7 @@ io_s_readlines(VALUE v)
|
|||
*
|
||||
* With argument +limit+ given, parses lines as determined by the default
|
||||
* line separator and the given line-length limit
|
||||
* (see {Line Limit}[rdoc-ref:IO@Line+Limit]):
|
||||
* (see {Line Limit}[rdoc-ref:io_streams.rdoc@Line+Limit]):
|
||||
*
|
||||
* IO.readlines('t.txt', 7)
|
||||
* # => ["First l", "ine\n", "Second ", "line\n", "\n", "Third l", "ine\n", "Fourth ", "line\n"]
|
||||
|
@ -11699,13 +11700,13 @@ io_s_readlines(VALUE v)
|
|||
* With arguments +sep+ and +limit+ given,
|
||||
* parses lines as determined by the given
|
||||
* line separator and the given line-length limit
|
||||
* (see {Line Separator and Line Limit}[rdoc-ref:IO@Line+Separator+and+Line+Limit]):
|
||||
* (see {Line Separator and Line Limit}[rdoc-ref:io_streams.rdoc@Line+Separator+and+Line+Limit]):
|
||||
*
|
||||
* Optional keyword arguments +opts+ specify:
|
||||
*
|
||||
* - {Open Options}[rdoc-ref:IO@Open+Options].
|
||||
* - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
|
||||
* - {Line Options}[rdoc-ref:IO@Line+Options].
|
||||
* - {Line Options}[rdoc-ref:io_streams.rdoc@Line+Options].
|
||||
*
|
||||
*/
|
||||
|
||||
|
@ -13012,7 +13013,7 @@ rb_io_s_copy_stream(int argc, VALUE *argv, VALUE io)
|
|||
* Returns the Encoding object that represents the encoding of the stream,
|
||||
* or +nil+ if the stream is in write mode and no encoding is specified.
|
||||
*
|
||||
* See {Encodings}[rdoc-ref:IO@Encodings].
|
||||
* See {Encodings}[rdoc-ref:File@Encodings].
|
||||
*
|
||||
*/
|
||||
|
||||
|
@ -13040,7 +13041,7 @@ rb_io_external_encoding(VALUE io)
|
|||
* if conversion is specified,
|
||||
* or +nil+ otherwise.
|
||||
*
|
||||
* See {Encodings}[rdoc-ref:IO@Encodings].
|
||||
* See {Encodings}[rdoc-ref:File@Encodings].
|
||||
*
|
||||
*/
|
||||
|
||||
|
@ -13059,7 +13060,7 @@ rb_io_internal_encoding(VALUE io)
|
|||
* set_encoding(ext_enc, int_enc, **enc_opts) -> self
|
||||
* set_encoding('ext_enc:int_enc', **enc_opts) -> self
|
||||
*
|
||||
* See {Encodings}[rdoc-ref:IO@Encodings].
|
||||
* See {Encodings}[rdoc-ref:File@Encodings].
|
||||
*
|
||||
* Argument +ext_enc+, if given, must be an Encoding object;
|
||||
* it is assigned as the encoding for the stream.
|
||||
|
@ -14372,7 +14373,10 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
|
|||
* The global constant ARGF (also accessible as <tt>$<</tt>)
|
||||
* provides an IO-like stream that allows access to all file paths
|
||||
* found in ARGV (or found in STDIN if ARGV is empty).
|
||||
* Note that ARGF is not itself a subclass of \IO.
|
||||
* ARGF is not itself a subclass of \IO.
|
||||
*
|
||||
* \Class StringIO provides an IO-like stream that handles a String.
|
||||
* \StringIO is not itself a subclass of \IO.
|
||||
*
|
||||
* Important objects based on \IO include:
|
||||
*
|
||||
|
@ -14390,20 +14394,23 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
|
|||
* - Kernel#open: Returns a new \IO object connected to a given source:
|
||||
* stream, file, or subprocess.
|
||||
*
|
||||
* An \IO stream has:
|
||||
* Like a \File stream, an \IO stream has:
|
||||
*
|
||||
* - A read/write mode, which may be read-only, write-only, or read/write;
|
||||
* see {Read/Write Mode}[rdoc-ref:IO@Read-2FWrite+Mode].
|
||||
* see {Read/Write Mode}[rdoc-ref:File@Read-2FWrite+Mode].
|
||||
* - A data mode, which may be text-only or binary;
|
||||
* see {Data Mode}[rdoc-ref:IO@Data+Mode].
|
||||
* see {Data Mode}[rdoc-ref:File@Data+Mode].
|
||||
* - Internal and external encodings;
|
||||
* see {Encodings}[rdoc-ref:File@Encodings].
|
||||
*
|
||||
* And like other \IO streams, it has:
|
||||
*
|
||||
* - A position, which determines where in the stream the next
|
||||
* read or write is to occur;
|
||||
* see {Position}[rdoc-ref:IO@Position].
|
||||
* see {Position}[rdoc-ref:io_streams.rdoc@Position].
|
||||
* - A line number, which is a special, line-oriented, "position"
|
||||
* (different from the position mentioned above);
|
||||
* see {Line Number}[rdoc-ref:IO@Line+Number].
|
||||
* - Internal and external encodings;
|
||||
* see {Encodings}[rdoc-ref:IO@Encodings].
|
||||
* see {Line Number}[rdoc-ref:io_streams.rdoc@Line+Number].
|
||||
*
|
||||
* == Extension <tt>io/console</tt>
|
||||
*
|
||||
|
@ -14413,160 +14420,9 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
|
|||
*
|
||||
* == Example Files
|
||||
*
|
||||
* Many examples here use these filenames and their corresponding files:
|
||||
* Many examples here use these variables:
|
||||
*
|
||||
* - <tt>t.txt</tt>: A text-only file that is assumed to exist via:
|
||||
*
|
||||
* text = <<~EOT
|
||||
* First line
|
||||
* Second line
|
||||
*
|
||||
* Fourth line
|
||||
* Fifth line
|
||||
* EOT
|
||||
* File.write('t.txt', text)
|
||||
*
|
||||
* - <tt>t.dat</tt>: A data file that is assumed to exist via:
|
||||
*
|
||||
* data = "\u9990\u9991\u9992\u9993\u9994"
|
||||
* f = File.open('t.dat', 'wb:UTF-16')
|
||||
* f.write(data)
|
||||
* f.close
|
||||
*
|
||||
* - <tt>t.rus</tt>: A Russian-language text file that is assumed to exist via:
|
||||
*
|
||||
* File.write('t.rus', "\u{442 435 441 442}")
|
||||
*
|
||||
* - <tt>t.tmp</tt>: A file that is assumed _not_ to exist.
|
||||
*
|
||||
* == Modes
|
||||
*
|
||||
* A number of \IO method calls must or may specify a _mode_ for the stream;
|
||||
* the mode determines how stream is to be accessible, including:
|
||||
*
|
||||
* - Whether the stream is to be read-only, write-only, or read-write.
|
||||
* - Whether the stream is positioned at its beginning or its end.
|
||||
* - Whether the stream treats data as text-only or binary.
|
||||
* - The external and internal encodings.
|
||||
*
|
||||
* === Read/Write Mode
|
||||
*
|
||||
* ==== Read/Write Mode Specified as an \Integer
|
||||
*
|
||||
* When +mode+ is an integer it must be one or more (combined by bitwise OR (<tt>|</tt>)
|
||||
* of the following modes:
|
||||
*
|
||||
* - +File::RDONLY+: Open for reading only.
|
||||
* - +File::WRONLY+: Open for writing only.
|
||||
* - +File::RDWR+: Open for reading and writing.
|
||||
* - +File::APPEND+: Open for appending only.
|
||||
* - +File::CREAT+: Create file if it does not exist.
|
||||
* - +File::EXCL+: Raise an exception if +File::CREAT+ is given and the file exists.
|
||||
*
|
||||
* Examples:
|
||||
*
|
||||
* File.new('t.txt', File::RDONLY)
|
||||
* File.new('t.tmp', File::RDWR | File::CREAT | File::EXCL)
|
||||
*
|
||||
* Note: Method IO#set_encoding does not allow the mode to be specified as an integer.
|
||||
*
|
||||
* ==== Read/Write Mode Specified As a \String
|
||||
*
|
||||
* When +mode+ is a string it must begin with one of the following:
|
||||
*
|
||||
* - <tt>'r'</tt>: Read-only stream, positioned at the beginning;
|
||||
* the stream cannot be changed to writable.
|
||||
* - <tt>'w'</tt>: Write-only stream, positioned at the beginning;
|
||||
* the stream cannot be changed to readable.
|
||||
* - <tt>'a'</tt>: Write-only stream, positioned at the end;
|
||||
* every write appends to the end;
|
||||
* the stream cannot be changed to readable.
|
||||
* - <tt>'r+'</tt>: Read-write stream, positioned at the beginning.
|
||||
* - <tt>'w+'</tt>: Read-write stream, positioned at the end.
|
||||
* - <tt>'a+'</tt>: Read-write stream, positioned at the end.
|
||||
*
|
||||
* For a writable file stream (that is, any except read-only),
|
||||
* the file is truncated to zero if it exists,
|
||||
* and is created if it does not exist.
|
||||
*
|
||||
* Examples:
|
||||
*
|
||||
* File.open('t.txt', 'r')
|
||||
* File.open('t.tmp', 'w')
|
||||
*
|
||||
* === Data Mode
|
||||
*
|
||||
* Either of the following may be suffixed to any of the string read/write modes above:
|
||||
*
|
||||
* - <tt>'t'</tt>: Text data; sets the default external encoding to +Encoding::UTF_8+;
|
||||
* on Windows, enables conversion between EOL and CRLF and enables interpreting +0x1A+
|
||||
* as an end-of-file marker.
|
||||
* - <tt>'b'</tt>: Binary data; sets the default external encoding to +Encoding::ASCII_8BIT+;
|
||||
* on Windows, suppresses conversion between EOL and CRLF and disables interpreting +0x1A+
|
||||
* as an end-of-file marker.
|
||||
*
|
||||
* If neither is given, the stream defaults to text data.
|
||||
*
|
||||
* Examples:
|
||||
*
|
||||
* File.open('t.txt', 'rt')
|
||||
* File.open('t.dat', 'rb')
|
||||
*
|
||||
* The following may be suffixed to any writable string mode above:
|
||||
*
|
||||
* - <tt>'x'</tt>: Creates the file if it does not exist;
|
||||
* raises an exception if the file exists.
|
||||
*
|
||||
* Example:
|
||||
*
|
||||
* File.open('t.tmp', 'wx')
|
||||
*
|
||||
* Note that when using integer flags to set the read/write mode, it's not
|
||||
* possible to also set the binary data mode by adding the File::BINARY flag
|
||||
* to the bitwise OR combination of integer flags. This is because, as
|
||||
* documented in File::Constants, the File::BINARY flag only disables line code
|
||||
* conversion, but does not change the external encoding at all.
|
||||
*
|
||||
* == Encodings
|
||||
*
|
||||
* Any of the string modes above may specify encodings --
|
||||
* either external encoding only or both external and internal encodings --
|
||||
* by appending one or both encoding names, separated by colons:
|
||||
*
|
||||
* f = File.new('t.dat', 'rb')
|
||||
* f.external_encoding # => #<Encoding:ASCII-8BIT>
|
||||
* f.internal_encoding # => nil
|
||||
* f = File.new('t.dat', 'rb:UTF-16')
|
||||
* f.external_encoding # => #<Encoding:UTF-16 (dummy)>
|
||||
* f.internal_encoding # => nil
|
||||
* f = File.new('t.dat', 'rb:UTF-16:UTF-16')
|
||||
* f.external_encoding # => #<Encoding:UTF-16 (dummy)>
|
||||
* f.internal_encoding # => #<Encoding:UTF-16>
|
||||
* f.close
|
||||
*
|
||||
* The numerous encoding names are available in array Encoding.name_list:
|
||||
*
|
||||
* Encoding.name_list.size # => 175
|
||||
* Encoding.name_list.take(3) # => ["ASCII-8BIT", "UTF-8", "US-ASCII"]
|
||||
*
|
||||
* When the external encoding is set,
|
||||
* strings read are tagged by that encoding
|
||||
* when reading, and strings written are converted to that
|
||||
* encoding when writing.
|
||||
*
|
||||
* When both external and internal encodings are set,
|
||||
* strings read are converted from external to internal encoding,
|
||||
* and strings written are converted from internal to external encoding.
|
||||
* For further details about transcoding input and output, see Encoding.
|
||||
*
|
||||
* If the external encoding is <tt>'BOM|UTF-8'</tt>, <tt>'BOM|UTF-16LE'</tt>
|
||||
* or <tt>'BOM|UTF16-BE'</tt>, Ruby checks for
|
||||
* a Unicode BOM in the input document to help determine the encoding. For
|
||||
* UTF-16 encodings the file open mode must be binary.
|
||||
* If the BOM is found, it is stripped and the external encoding from the BOM is used.
|
||||
*
|
||||
* Note that the BOM-style encoding option is case insensitive,
|
||||
* so 'bom|utf-8' is also valid.)
|
||||
* :include: doc/examples/files.rdoc
|
||||
*
|
||||
* == Open Options
|
||||
*
|
||||
|
@ -14589,159 +14445,6 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
|
|||
* Also available are the options offered in String#encode,
|
||||
* which may control conversion between external internal encoding.
|
||||
*
|
||||
* == Lines
|
||||
*
|
||||
* Some reader methods in \IO are line-oriented;
|
||||
* such a method reads one or more lines,
|
||||
* which are separated by an implicit or explicit line separator.
|
||||
*
|
||||
* These methods include:
|
||||
*
|
||||
* - Kernel#gets
|
||||
* - Kernel#readline
|
||||
* - Kernel#readlines
|
||||
* - IO.foreach
|
||||
* - IO.readlines
|
||||
* - IO#each_line
|
||||
* - IO#gets
|
||||
* - IO#readline
|
||||
* - IO#readlines
|
||||
* - ARGF.each
|
||||
* - ARGF.gets
|
||||
* - ARGF.readline
|
||||
* - ARGF.readlines
|
||||
*
|
||||
* Each of these methods returns +nil+ if called when already at end-of-stream,
|
||||
* except for IO#readline, which raises an exception.
|
||||
*
|
||||
* Each of these methods may be called with:
|
||||
*
|
||||
* - An optional line separator, +sep+.
|
||||
* - An optional line-size limit, +limit+.
|
||||
* - Both +sep+ and +limit+.
|
||||
*
|
||||
* === Line Separator
|
||||
*
|
||||
* The default line separator is the given by the global variable <tt>$/</tt>,
|
||||
* whose value is often <tt>"\n"</tt>.
|
||||
* The line to be read next is all data from the current position
|
||||
* to the next line separator:
|
||||
*
|
||||
* f = File.open('t.txt')
|
||||
* f.gets # => "First line\n"
|
||||
* f.gets # => "Second line\n"
|
||||
* f.gets # => "\n"
|
||||
* f.gets # => "Fourth line\n"
|
||||
* f.gets # => "Fifth line\n"
|
||||
* f.close
|
||||
*
|
||||
* You can specify a different line separator:
|
||||
*
|
||||
* f = File.new('t.txt')
|
||||
* f.gets('l') # => "First l"
|
||||
* f.gets('li') # => "ine\nSecond li"
|
||||
* f.gets('lin') # => "ne\n\nFourth lin"
|
||||
* f.gets # => "e\n"
|
||||
* f.close
|
||||
*
|
||||
* There are two special line separators:
|
||||
*
|
||||
* - +nil+: The entire stream is read into a single string:
|
||||
*
|
||||
* f = File.new('t.txt')
|
||||
* f.gets(nil) # => "First line\nSecond line\n\nFourth line\nFifth line\n"
|
||||
* f.close
|
||||
*
|
||||
* - <tt>''</tt> (the empty string): The next "paragraph" is read
|
||||
* (paragraphs being separated by two consecutive line separators):
|
||||
*
|
||||
* f = File.new('t.txt')
|
||||
* f.gets('') # => "First line\nSecond line\n\n"
|
||||
* f.gets('') # => "Fourth line\nFifth line\n"
|
||||
* f.close
|
||||
*
|
||||
* === Line Limit
|
||||
*
|
||||
* The line to be read may be further defined by an optional argument +limit+,
|
||||
* which specifies that the line may not be (much) longer than the given limit;
|
||||
* a multi-byte character will not be split, and so a line may be slightly longer
|
||||
* than the given limit.
|
||||
*
|
||||
* If +limit+ is not given, the line is determined only by +sep+.
|
||||
*
|
||||
* # Text with 1-byte characters.
|
||||
* File.open('t.txt') {|f| f.gets(1) } # => "F"
|
||||
* File.open('t.txt') {|f| f.gets(2) } # => "Fi"
|
||||
* File.open('t.txt') {|f| f.gets(3) } # => "Fir"
|
||||
* File.open('t.txt') {|f| f.gets(4) } # => "Firs"
|
||||
* # No more than one line.
|
||||
* File.open('t.txt') {|f| f.gets(10) } # => "First line"
|
||||
* File.open('t.txt') {|f| f.gets(11) } # => "First line\n"
|
||||
* File.open('t.txt') {|f| f.gets(12) } # => "First line\n"
|
||||
*
|
||||
* # Text with 2-byte characters, which will not be split.
|
||||
* File.open('r.rus') {|f| f.gets(1).size } # => 1
|
||||
* File.open('r.rus') {|f| f.gets(2).size } # => 1
|
||||
* File.open('r.rus') {|f| f.gets(3).size } # => 2
|
||||
* File.open('r.rus') {|f| f.gets(4).size } # => 2
|
||||
*
|
||||
* === Line Separator and Line Limit
|
||||
*
|
||||
* With arguments +sep+ and +limit+ given,
|
||||
* combines the two behaviors:
|
||||
*
|
||||
* - Returns the next line as determined by line separator +sep+.
|
||||
* - But returns no more bytes than are allowed by the limit.
|
||||
*
|
||||
* Example:
|
||||
*
|
||||
* File.open('t.txt') {|f| f.gets('li', 20) } # => "First li"
|
||||
* File.open('t.txt') {|f| f.gets('li', 2) } # => "Fi"
|
||||
*
|
||||
* === Line Number
|
||||
*
|
||||
* A readable \IO stream has a _line_ _number_,
|
||||
* which is the non-negative integer line number
|
||||
* in the stream where the next read will occur.
|
||||
*
|
||||
* A new stream is initially has line number +0+.
|
||||
*
|
||||
* \Method IO#lineno returns the line number.
|
||||
*
|
||||
* Reading lines from a stream usually changes its line number:
|
||||
*
|
||||
* f = File.open('t.txt', 'r')
|
||||
* f.lineno # => 0
|
||||
* f.readline # => "This is line one.\n"
|
||||
* f.lineno # => 1
|
||||
* f.readline # => "This is the second line.\n"
|
||||
* f.lineno # => 2
|
||||
* f.readline # => "Here's the third line.\n"
|
||||
* f.lineno # => 3
|
||||
* f.eof? # => true
|
||||
* f.close
|
||||
*
|
||||
* Iterating over lines in a stream usually changes its line number:
|
||||
*
|
||||
* f = File.open('t.txt')
|
||||
* f.each_line do |line|
|
||||
* p "position=#{f.pos} eof?=#{f.eof?} line=#{line}"
|
||||
* end
|
||||
* f.close
|
||||
*
|
||||
* Output:
|
||||
*
|
||||
* "position=19 eof?=false line=This is line one.\n"
|
||||
* "position=45 eof?=false line=This is the second line.\n"
|
||||
* "position=70 eof?=true line=This is the third line.\n"
|
||||
*
|
||||
* === Line Options
|
||||
*
|
||||
* A number of \IO methods accept optional keyword arguments
|
||||
* that determine how lines in a stream are to be treated:
|
||||
*
|
||||
* - +:chomp+: If +true+, line separators are omitted; default is +false+.
|
||||
*
|
||||
* == What's Here
|
||||
*
|
||||
* First, what's elsewhere. \Class \IO:
|
||||
|
|
Загрузка…
Ссылка в новой задаче