From ab85c5e979d53e2e07c714122645b1c4b782f571 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Tue, 18 Jan 2022 06:25:26 -0600 Subject: [DOC] Enhanced RDoc for io.c (#5451) Treats: IO#reopen IO#printf Kernel#printf IO#print Kernel#print IO#putc IO.new IO#set_encoding_by_bom IO.for_fd --- io.c | 393 +++++++++++++++++++++++++++++++------------------------------------ 1 file changed, 181 insertions(+), 212 deletions(-) (limited to 'io.c') diff --git a/io.c b/io.c index 0973bd604f..237bb9becc 100644 --- a/io.c +++ b/io.c @@ -7635,8 +7635,8 @@ rb_open_file(int argc, const VALUE *argv, VALUE io) * Document-method: File::open * * call-seq: - * File.open(path, mode = 'r', perm = 0666, **opts]) -> file - * File.open(path, mode = 'r', perm = 0666, **opts]) {|f| ... } -> object + * File.open(path, mode = 'r', perm = 0666, **opts) -> file + * File.open(path, mode = 'r', perm = 0666, **opts) {|f| ... } -> object * * Creates a new \File object, via File.new with the given arguments. * @@ -7651,8 +7651,8 @@ rb_open_file(int argc, const VALUE *argv, VALUE io) * Document-method: IO::open * * call-seq: - * IO.open(fd, mode = 'r', **opts]) -> io - * IO.open(fd, mode = 'r', **opts]) {|io| ... } -> object + * IO.open(fd, mode = 'r', **opts) -> io + * IO.open(fd, mode = 'r', **opts) {|io| ... } -> object * * Creates a new \IO object, via IO.new with the given arguments. * @@ -7996,19 +7996,29 @@ rb_freopen(VALUE fname, const char *mode, FILE *fp) /* * call-seq: - * ios.reopen(other_IO) -> ios - * ios.reopen(path, mode [, opt]) -> ios + * reopen(other_io) -> self + * reopen(path, mode = 'r', **opts) -> self * - * Reassociates ios with the I/O stream given in - * other_IO or to a new stream opened on path. This may - * dynamically change the actual class of this stream. - * The +mode+ and +opt+ parameters accept the same values as IO.open. + * Reassociates the stream with another stream, + * which may be of a different class. + * This method may be used to redirect an existing stream + * to a new destination. + * + * With argument +other_io+ given, reassociates with that stream: + * + * # Redirect $stdin from a file. + * f = File.open('t.txt') + * $stdin.reopen(f) + * + * # Redirect $stdout to a file. + * f = File.open('t.tmp', 'w') + * $stdout.reopen(f) + * + * With argument +path+ given, reassociates with a new stream to that file path: + * + * $stdin.reopen('t.txt') + * $stdout.reopen('t.tmp', 'w') * - * f1 = File.new("testfile") - * f2 = File.new("testfile") - * f2.readlines[0] #=> "This is line one\n" - * f2.reopen(f1) #=> # - * f2.readlines[0] #=> "This is line one\n" */ static VALUE @@ -8144,10 +8154,10 @@ rb_io_init_copy(VALUE dest, VALUE io) /* * call-seq: - * ios.printf(format_string [, obj, ...]) -> nil + * printf(format_string, *objects) -> nil * - * Formats and writes to ios, converting parameters under - * control of the format string. See Kernel#sprintf for details. + * Formats and writes +objects+ to the stream. + * See Kernel#sprintf for formatting details. */ VALUE @@ -8159,13 +8169,33 @@ rb_io_printf(int argc, const VALUE *argv, VALUE out) /* * call-seq: - * printf(io, string [, obj ... ]) -> nil - * printf(string [, obj ... ]) -> nil + * printf(string, *objects) -> nil + * printf(io, string, *objects) -> nil * * Equivalent to: - * io.write(sprintf(string, obj, ...)) - * or - * $stdout.write(sprintf(string, obj, ...)) + * + * io.write(sprintf(string, *objects)) + * + * With the single argument +string+, formats +objects+ into the string, + * then writes the formatted string to $stdout: + * + * printf('%4.4d %10s %2.2f', 24, 24, 24.0) + * + * Output (on $stdout): + * + * 0024 24 24.00# + * + * With arguments +io+ and +string, formats +objects+ into the string, + * then writes the formatted string to +io+: + * + * printf($stderr, '%4.4d %10s %2.2f', 24, 24, 24.0) + * + * Output (on $stderr): + * + * 0024 24 24.00# => nil + * + * With no arguments, does nothing. + * */ static VALUE @@ -8199,26 +8229,55 @@ deprecated_str_setter(VALUE val, ID id, VALUE *var) /* * call-seq: - * ios.print -> nil - * ios.print(obj, ...) -> nil + * print(*objects) -> nil * - * Writes the given object(s) to ios. Returns +nil+. + * Writes the given objects to the stream; returns +nil+. + * Appends the output record separator $OUTPUT_RECORD_SEPARATOR + * ($\\), if it is not +nil+. * - * The stream must be opened for writing. - * Each given object that isn't a string will be converted by calling - * its to_s method. - * When called without arguments, prints the contents of $_. + * With argument +objects+ given, for each object: * - * If the output field separator ($,) is not +nil+, - * it is inserted between objects. - * If the output record separator ($\\) is not +nil+, - * it is appended to the output. + * - Converts via its method +to_s+ if not a string. + * - Writes to the stream. + * - If not the last object, writes the output field separator + * $OUTPUT_FIELD_SEPARATOR ($,) if it is not +nil+. * - * $stdout.print("This is ", 100, " percent.\n") + * With default separators: * - * produces: + * f = File.open('t.tmp', 'w+') + * objects = [0, 0.0, Rational(0, 1), Complex(0, 0), :zero, 'zero'] + * p $OUTPUT_RECORD_SEPARATOR + * p $OUTPUT_FIELD_SEPARATOR + * f.print(*objects) + * f.rewind + * p f.read + * + * Output: + * + * nil + * nil + * "00.00/10+0izerozero" + * + * With specified separators: + * + * $\ = "\n" + * $, = ',' + * f.rewind + * f.print(*objects) + * f.rewind + * p f.read + * + * Output: + * + * "0,0.0,0/1,0+0i,zero,zero\n" + * + * With no argument given, writes the content of $_ + * (which is usually the most recent user input): + * + * f = File.open('t.tmp', 'w+') + * gets # Sets $_ to the most recent user input. + * f.print * - * This is 100 percent. */ VALUE @@ -8251,25 +8310,51 @@ rb_io_print(int argc, const VALUE *argv, VALUE out) /* * call-seq: - * print(obj, ...) -> nil + * print(*objects) -> nil * - * Prints each object in turn to $stdout. If the output - * field separator ($,) is not +nil+, its - * contents will appear between each field. If the output record - * separator ($\\) is not +nil+, it will be - * appended to the output. If no arguments are given, prints - * $_. Objects that aren't strings will be converted by - * calling their to_s method. + * Equivalent to $stdout.print(*objects), + * this method is the straightforward way to write to $stdout. * - * print "cat", [1,2,3], 99, "\n" - * $, = ", " - * $\ = "\n" - * print "cat", [1,2,3], 99 + * Writes the given objects to $stdout; returns +nil+. + * Appends the output record separator $OUTPUT_RECORD_SEPARATOR + * $\\), if it is not +nil+. * - * produces: + * With argument +objects+ given, for each object: + * + * - Converts via its method +to_s+ if not a string. + * - Writes to stdout. + * - If not the last object, writes the output field separator + * $OUTPUT_FIELD_SEPARATOR ($, if it is not +nil+. + * + * With default separators: + * + * objects = [0, 0.0, Rational(0, 1), Complex(0, 0), :zero, 'zero'] + * $OUTPUT_RECORD_SEPARATOR + * $OUTPUT_FIELD_SEPARATOR + * print(*objects) + * + * Output: + * + * nil + * nil + * 00.00/10+0izerozero + * + * With specified separators: + * + * $OUTPUT_RECORD_SEPARATOR = "\n" + * $OUTPUT_FIELD_SEPARATOR = ',' + * print(*objects) + * + * Output: + * + * 0,0.0,0/1,0+0i,zero,zero + * + * With no argument given, writes the content of $_ + * (which is usually the most recent user input): + * + * gets # Sets $_ to the most recent user input. + * print # Prints $_. * - * cat12399 - * cat, 1, 2, 3, 99 */ static VALUE @@ -8281,19 +8366,22 @@ rb_f_print(int argc, const VALUE *argv, VALUE _) /* * call-seq: - * ios.putc(obj) -> obj + * putc(object) -> object * - * If obj is Numeric, write the character whose code is the - * least-significant byte of obj. If obj is String, - * write the first character of obj to ios. Otherwise, - * raise TypeError. + * Writes a character to the stream. * - * $stdout.putc "A" - * $stdout.putc 65 + * If +object+ is numeric, converts to integer if necessary, + * then writes the character whose code is the + * least significant byte; + * if +object+ is a string, writes the first character: * - * produces: + * $stdout.putc "A" + * $stdout.putc 65 + * + * Output: * * AA + * */ static VALUE @@ -8828,155 +8916,32 @@ rb_io_make_open_file(VALUE obj) /* * call-seq: - * IO.new(fd [, mode] [, opt]) -> io - * - * Returns a new IO object (a stream) for the given integer file descriptor - * +fd+ and +mode+ string. +opt+ may be used to specify parts of +mode+ in a - * more readable fashion. See also IO.sysopen and IO.for_fd. - * - * IO.new is called by various File and IO opening methods such as IO::open, - * Kernel#open, and File::open. - * - * === Open Mode - * - * When +mode+ is an integer it must be combination of the modes defined in - * File::Constants (+File::RDONLY+, File::WRONLY|File::CREAT). - * See the open(2) man page for more information. - * - * When +mode+ is a string it must be in one of the following forms: - * - * fmode - * fmode ":" ext_enc - * fmode ":" ext_enc ":" int_enc - * fmode ":" "BOM|UTF-*" - * - * +fmode+ is an IO open mode string, +ext_enc+ is the external encoding for - * the IO and +int_enc+ is the internal encoding. - * - * ==== IO Open Mode - * - * Ruby allows the following open modes: - * - * "r" Read-only, starts at beginning of file (default mode). - * - * "r+" Read-write, starts at beginning of file. + * IO.new(fd, mode = 'r', **opts) -> io * - * "w" Write-only, truncates existing file - * to zero length or creates a new file for writing. + * Creates and returns a new \IO object (file stream) from a file descriptor. * - * "w+" Read-write, truncates existing file to zero length - * or creates a new file for reading and writing. + * \IO.new may be useful for interaction with low-level libraries. + * For higher-level interactions, it may be simpler to create + * the file stream using File.open. * - * "a" Write-only, each write call appends data at end of file. - * Creates a new file for writing if file does not exist. + * Argument +fd+ must be a valid file descriptor (integer): * - * "a+" Read-write, each write call appends data at end of file. - * Creates a new file for reading and writing if file does - * not exist. - * - * The following modes must be used separately, and along with one or more of - * the modes seen above. - * - * "b" Binary file mode - * Suppresses EOL <-> CRLF conversion on Windows. And - * sets external encoding to ASCII-8BIT unless explicitly - * specified. - * - * "t" Text file mode - * - * The exclusive access mode ("x") can be used together with "w" to ensure - * the file is created. Errno::EEXIST is raised when it already exists. - * It may not be supported with all kinds of streams (e.g. pipes). - * - * When the open mode of original IO is read only, the mode cannot be - * changed to be writable. Similarly, the open mode cannot be changed from - * write only to readable. - * - * When such a change is attempted the error is raised in different locations - * according to the platform. - * - * === IO Encoding - * - * When +ext_enc+ is specified, strings read will be tagged by the encoding - * when reading, and strings output will be converted to the specified - * encoding when writing. - * - * When +ext_enc+ and +int_enc+ are specified read strings will be converted - * from +ext_enc+ to +int_enc+ upon input, and written strings will be - * converted from +int_enc+ to +ext_enc+ upon output. See Encoding for - * further details of transcoding on input and output. - * - * If "BOM|UTF-8", "BOM|UTF-16LE" or "BOM|UTF16-BE" are used, 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. When present, the BOM - * is stripped and the external encoding from the BOM is used. When the BOM - * is missing the given Unicode encoding is used as +ext_enc+. (The BOM-set - * encoding option is case insensitive, so "bom|utf-8" is also valid.) + * path = 't.tmp' + * fd = IO.sysopen(path) # => 3 + * IO.new(fd) # => # * - * === Options - * - * +opt+ can be used instead of +mode+ for improved readability. The - * following keys are supported: - * - * :mode :: - * Same as +mode+ parameter - * - * :flags :: - * Specifies file open flags as integer. - * If +mode+ parameter is given, this parameter will be bitwise-ORed. - * - * :\external_encoding :: - * External encoding for the IO. - * - * :\internal_encoding :: - * Internal encoding for the IO. "-" is a synonym for the default internal - * encoding. - * - * If the value is +nil+ no conversion occurs. - * - * :encoding :: - * Specifies external and internal encodings as "extern:intern". - * - * :textmode :: - * If the value is truth value, same as "t" in argument +mode+. - * - * :binmode :: - * If the value is truth value, same as "b" in argument +mode+. - * - * :autoclose :: - * If the value is +false+, the +fd+ will be kept open after this IO - * instance gets finalized. - * - * Also, +opt+ can have same keys in String#encode for controlling conversion - * between the external encoding and the internal encoding. - * - * === Example 1 - * - * fd = IO.sysopen("/dev/tty", "w") - * a = IO.new(fd,"w") - * $stderr.puts "Hello" - * a.puts "World" - * - * Produces: - * - * Hello - * World - * - * === Example 2 + * Optional argument +mode+ (defaults to 'r') must specify a valid mode + * see {\IO Modes}[#class-IO-label-Modes]: * - * require 'fcntl' + * IO.new(fd, 'w') # => # + * IO.new(fd, File::WRONLY) # => # * - * fd = STDERR.fcntl(Fcntl::F_DUPFD) - * io = IO.new(fd, mode: 'w:UTF-16LE', cr_newline: true) - * io.puts "Hello, World!" + * Optional argument +opts+ must specify valid open options + * see {IO Open Options}[#class-IO-label-Open+Options]: * - * fd = STDERR.fcntl(Fcntl::F_DUPFD) - * io = IO.new(fd, mode: 'w', cr_newline: true, - * external_encoding: Encoding::UTF_16LE) - * io.puts "Hello, World!" + * IO.new(fd, internal_encoding: nil) # => # + * IO.new(fd, autoclose: true) # => # * - * Both of above print "Hello, World!" in UTF-16LE to standard error output - * with converting EOL generated by #puts to CR. */ static VALUE @@ -9041,20 +9006,24 @@ rb_io_initialize(int argc, VALUE *argv, VALUE io) /* * call-seq: - * ios.set_encoding_by_bom -> encoding or nil + * set_encoding_by_bom -> encoding or nil + * + * If the stream begins with a BOM + * ({byte order marker}[https://en.wikipedia.org/wiki/Byte_order_mark]), + * consumes the BOM and sets the external encoding accordingly; + * returns the result encoding if found, or +nil+ otherwise: + * + * File.write('t.tmp', "\u{FEFF}abc") + * io = File.open('t.tmp', 'rb') + * io.set_encoding_by_bom # => # * - * Checks if +ios+ starts with a BOM, and then consumes it and sets - * the external encoding. Returns the result encoding if found, or - * nil. If +ios+ is not binmode or its encoding has been set - * already, an exception will be raised. + * File.write('t.tmp', 'abc') + * io = File.open('t.tmp', 'rb') + * io.set_encoding_by_bom # => nil * - * File.write("bom.txt", "\u{FEFF}abc") - * ios = File.open("bom.txt", "rb") - * ios.set_encoding_by_bom #=> # + * Raises an exception if the stream is not binmode + * or its encoding has already been set. * - * File.write("nobom.txt", "abc") - * ios = File.open("nobom.txt", "rb") - * ios.set_encoding_by_bom #=> nil */ static VALUE @@ -9148,7 +9117,7 @@ rb_io_s_new(int argc, VALUE *argv, VALUE klass) /* * call-seq: - * IO.for_fd(fd, mode [, opt]) -> io + * IO.for_fd(fd, mode = 'r', **opts) -> io * * Synonym for IO.new. * -- cgit v1.2.1