From ded895baa96cb9622fcd44d308fb48341565605b Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sun, 2 Oct 2022 08:24:08 -0500 Subject: [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. --- io.c | 429 +++++++++++-------------------------------------------------------- 1 file changed, 66 insertions(+), 363 deletions(-) (limited to 'io.c') diff --git a/io.c b/io.c index 494e40bcd9..aeba98c943 100644 --- a/io.c +++ b/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 IO::SEEK_CUR: @@ -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 $_. * * 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 $_. * * 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 $? 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 # => # # 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.new(fd, File::WRONLY) # => # @@ -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 $<) * 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 io/console * @@ -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: - * - * - t.txt: 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) - * - * - t.dat: 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 - * - * - t.rus: A Russian-language text file that is assumed to exist via: - * - * File.write('t.rus', "\u{442 435 441 442}") - * - * - t.tmp: A file that is assumed _not_ to exist. - * - * == Modes + * Many examples here use these variables: * - * 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 (|) - * 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: - * - * - 'r': Read-only stream, positioned at the beginning; - * the stream cannot be changed to writable. - * - 'w': Write-only stream, positioned at the beginning; - * the stream cannot be changed to readable. - * - 'a': Write-only stream, positioned at the end; - * every write appends to the end; - * the stream cannot be changed to readable. - * - 'r+': Read-write stream, positioned at the beginning. - * - 'w+': Read-write stream, positioned at the end. - * - 'a+': 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: - * - * - 't': 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. - * - 'b': 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: - * - * - 'x': 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 # => # - * f.internal_encoding # => nil - * f = File.new('t.dat', 'rb:UTF-16') - * f.external_encoding # => # - * f.internal_encoding # => nil - * f = File.new('t.dat', 'rb:UTF-16:UTF-16') - * f.external_encoding # => # - * f.internal_encoding # => # - * 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 'BOM|UTF-8', 'BOM|UTF-16LE' - * or 'BOM|UTF16-BE', 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 $/, - * whose value is often "\n". - * 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 - * - * - '' (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: -- cgit v1.2.1