summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBurdette Lamar <BurdetteLamar@Yahoo.com>2022-01-14 18:33:06 -0600
committerGitHub <noreply@github.com>2022-01-14 18:33:06 -0600
commite40f79daa39141fed9d5a8d8a71211b6b97b1c8d (patch)
tree096cebb53841c47f4941bf499497377404fc1beb
parent8d378fd28bcce28013499454877678cbbfe7cdc9 (diff)
downloadruby-e40f79daa39141fed9d5a8d8a71211b6b97b1c8d.tar.gz
Enhanced RDoc for io.c (#5444)
Treated: IO#open IO#sysopen #open IO#putc IO#puts #p Kernel#display
-rw-r--r--io.c271
1 files changed, 150 insertions, 121 deletions
diff --git a/io.c b/io.c
index 00bc2a6c31..39c4dcac48 100644
--- a/io.c
+++ b/io.c
@@ -7651,15 +7651,16 @@ rb_open_file(int argc, const VALUE *argv, VALUE io)
* Document-method: IO::open
*
* call-seq:
- * IO.open(fd, mode="r" [, opt]) -> io
- * IO.open(fd, mode="r" [, opt]) {|io| block } -> obj
+ * IO.open(fd, mode = 'r', **opts]) -> io
+ * IO.open(fd, mode = 'r', **opts]) {|io| ... } -> object
*
- * With no associated block, IO.open is a synonym for IO.new. If
- * the optional code block is given, it will be passed +io+ as an argument,
- * and the IO object will automatically be closed when the block terminates.
- * In this instance, IO.open returns the value of the block.
+ * Creates a new \IO object, via IO.new with the given arguments.
+ *
+ * With no block given, returns the \IO object.
+ *
+ * With a block given, calls the block with the \IO object
+ * and returns the block's value.
*
- * See IO.new for a description of the +fd+, +mode+ and +opt+ parameters.
*/
static VALUE
@@ -7676,12 +7677,20 @@ rb_io_s_open(int argc, VALUE *argv, VALUE klass)
/*
* call-seq:
- * IO.sysopen(path, [mode, [perm]]) -> integer
+ * IO.sysopen(path, mode = 'r', perm = 0666) -> integer
+ *
+ * Opens the file at the given path with the given mode and permissions;
+ * returns the integer file descriptor.
+ *
+ * If the file is to be readable, it must exist;
+ * if the file is to be writable and does not exist,
+ * it is created with the given permissions:
+ *
+ * File.write('t.tmp', '') # => 0
+ * IO.sysopen('t.tmp') # => 8
+ * IO.sysopen('t.tmp', 'w') # => 9
*
- * Opens the given path, returning the underlying file descriptor as a
- * Integer.
*
- * IO.sysopen("testfile") #=> 3
*/
static VALUE
@@ -7728,101 +7737,100 @@ check_pipe_command(VALUE filename_or_command)
/*
* call-seq:
- * open(path [, mode [, perm]] [, opt]) -> io or nil
- * open(path [, mode [, perm]] [, opt]) {|io| block } -> obj
+ * open(path, mode = 'r', perm = 0666, **opts) -> io or nil
+ * open(path, mode = 'r', perm = 0666, **opts) {|io| ... } -> obj
*
* Creates an IO object connected to the given stream, file, or subprocess.
*
- * If +path+ does not start with a pipe character (<code>|</code>), treat it
- * as the name of a file to open using the specified mode (defaulting to
- * "r").
+ * Required string argument +path+ determines which of the following occurs:
*
- * The +mode+ is either a string or an integer. If it is an integer, it
- * must be bitwise-or of open(2) flags, such as File::RDWR or File::EXCL. If
- * it is a string, it is either "fmode", "fmode:ext_enc", or
- * "fmode:ext_enc:int_enc".
+ * - The file at the specified +path+ is opened.
+ * - The process forks.
+ * - A subprocess is created.
*
- * See the documentation of IO.new for full documentation of the +mode+ string
- * directives.
+ * Each of these is detailed below.
*
- * If a file is being created, its initial permissions may be set using the
- * +perm+ parameter. See File.new and the open(2) and chmod(2) man pages for
- * a description of permissions.
+ * <b>File Opened</b>
+
+ * If +path+ does _not_ start with a pipe character (<tt>'|'</tt>),
+ * a file stream is opened with <tt>File.open(path, mode, perm, opts)</tt>.
*
- * If a block is specified, it will be invoked with the IO object as a
- * parameter, and the IO will be automatically closed when the block
- * terminates. The call returns the value of the block.
+ * With no block given, file stream is returned:
*
- * If +path+ starts with a pipe character (<code>"|"</code>), a subprocess is
- * created, connected to the caller by a pair of pipes. The returned IO
- * object may be used to write to the standard input and read from the
- * standard output of this subprocess.
+ * open('t.txt') # => #<File:t.txt>
*
- * If the command following the pipe is a single minus sign
- * (<code>"|-"</code>), Ruby forks, and this subprocess is connected to the
- * parent. If the command is not <code>"-"</code>, the subprocess runs the
- * command. Note that the command may be processed by shell if it contains
- * shell metacharacters.
+ * With a block given, calls the block with the open file stream,
+ * then closes the stream:
*
- * When the subprocess is Ruby (opened via <code>"|-"</code>), the +open+
- * call returns +nil+. If a block is associated with the open call, that
- * block will run twice --- once in the parent and once in the child.
+ * open('t.txt') {|f| p f } # => #<File:t.txt (closed)>
*
- * The block parameter will be an IO object in the parent and +nil+ in the
- * child. The parent's +IO+ object will be connected to the child's $stdin
- * and $stdout. The subprocess will be terminated at the end of the block.
+ * Output:
*
- * === Examples
+ * #<File:t.txt>
*
- * Reading from "testfile":
+ * See File.open for details.
*
- * open("testfile") do |f|
- * print f.gets
- * end
+ * <b>Process Forked</b>
*
- * Produces:
+ * If +path+ is the 2-character string <tt>'|-'</tt>, the process forks
+ * and the child process is connected to the parent.
*
- * This is line one
+ * With no block given:
*
- * Open a subprocess and read its output:
+ * io = open('|-')
+ * if io
+ * $stderr.puts "In parent, child pid is #{io.pid}."
+ * else
+ * $stderr.puts "In child, pid is #{$$}."
+ * end
*
- * cmd = open("|date")
- * print cmd.gets
- * cmd.close
+ * Output:
*
- * Produces:
+ * In parent, child pid is 27903.
+ * In child, pid is 27903.
*
- * Wed Apr 9 08:56:31 CDT 2003
+ * With a block given:
*
- * Open a subprocess running the same Ruby program:
+ * open('|-') do |io|
+ * if io
+ * $stderr.puts "In parent, child pid is #{io.pid}."
+ * else
+ * $stderr.puts "In child, pid is #{$$}."
+ * end
+ * end
*
- * f = open("|-", "w+")
- * if f.nil?
- * puts "in Child"
- * exit
- * else
- * puts "Got: #{f.gets}"
- * end
+ * Output:
*
- * Produces:
+ * In parent, child pid is 28427.
+ * In child, pid is 28427.
*
- * Got: in Child
+ * <b>Subprocess Created</b>
*
- * Open a subprocess using a block to receive the IO object:
+ * If +path+ is <tt>'|command'</tt> (<tt>'command' != '-'</tt>),
+ * a new subprocess runs the command; its open stream is returned.
+ * Note that the command may be processed by shell if it contains
+ * shell metacharacters.
*
- * open "|-" do |f|
- * if f then
- * # parent process
- * puts "Got: #{f.gets}"
- * else
- * # child process
- * puts "in Child"
- * end
- * end
+ * With no block given:
*
- * Produces:
+ * io = open('|echo "Hi!"') # => #<IO:fd 12>
+ * print io.gets
+ * io.close
+ *
+ * Output:
+ *
+ * "Hi!"
+ *
+ * With a block given, calls the block with the stream, then closes the stream:
+ *
+ * open('|echo "Hi!"') do |io|
+ * print io.gets
+ * end
+ *
+ * Output:
+ *
+ * "Hi!"
*
- * Got: in Child
*/
static VALUE
@@ -8312,14 +8320,14 @@ rb_io_putc(VALUE io, VALUE ch)
/*
* call-seq:
- * putc(int) -> int
+ * putc(int) -> int
*
* Equivalent to:
*
* $stdout.putc(int)
*
- * Refer to the documentation for IO#putc for important information regarding
- * multi-byte characters.
+ * See IO#putc for important information regarding multi-byte characters.
+ *
*/
static VALUE
@@ -8370,29 +8378,47 @@ io_puts_ary(VALUE ary, VALUE out, int recur)
/*
* call-seq:
- * ios.puts(obj, ...) -> nil
+ * puts(*objects) -> nil
*
- * Writes the given object(s) to <em>ios</em>.
- * Writes a newline after any that do not already end
- * with a newline sequence. Returns +nil+.
+ * Writes the given +objects+ to the stream, which must be open for writing;
+ * returns +nil+.\
+ * Writes a newline after each that does not already end with a newline sequence.
+ * If called without arguments, writes a newline.
*
- * The stream must be opened for writing.
- * If called with an array argument, writes each element on a new line.
- * Each given object that isn't a string or array will be converted
- * by calling its +to_s+ method.
- * If called without arguments, outputs a single newline.
+ * Note that each added newline is the character <tt>"\n"<//tt>,
+ * not the output record separator (<tt>$\\</tt>).
*
- * $stdout.puts("this", "is", ["a", "test"])
+ * Treatment for each object:
*
- * <em>produces:</em>
+ * - \String: writes the string.
+ * - Neither string nor array: writes <tt>object.to_s</tt>.
+ * - \Array: writes each element of the array; arrays may be nested.
+ *
+ * To keep these examples brief, we define this helper method:
+ *
+ * def show(*objects)
+ * # Puts objects to file.
+ * f = File.new('t.tmp', 'w+')
+ * f.puts(objects)
+ * # Return file content.
+ * f.rewind
+ * p f.read
+ * end
+ *
+ * # Strings without newlines.
+ * show('foo', 'bar', 'baz') # => "foo\nbar\nbaz\n"
+ * # Strings, some with newlines.
+ * show("foo\n", 'bar', "baz\n") # => "foo\nbar\nbaz\n"
+ *
+ * # Neither strings nor arrays:
+ * show(0, 0.0, Rational(0, 1), Complex(9, 0), :zero)
+ * # => "0\n0.0\n0/1\n9+0i\nzero\n"
*
- * this
- * is
- * a
- * test
+ * # Array of strings.
+ * show(['foo', "bar\n", 'baz']) # => "foo\nbar\nbaz\n"
+ * # Nested arrays.
+ * show([[[0, 1], 2, 3], 4, 5]) # => "0\n1\n2\n3\n4\n5\n"
*
- * Note that +puts+ always uses newlines and is not affected
- * by the output record separator (<code>$\\</code>).
*/
VALUE
@@ -8430,11 +8456,11 @@ rb_io_puts(int argc, const VALUE *argv, VALUE out)
/*
* call-seq:
- * puts(obj, ...) -> nil
+ * puts(*objects) -> nil
*
* Equivalent to
*
- * $stdout.puts(obj, ...)
+ * $stdout.puts(objects)
*/
static VALUE
@@ -8490,20 +8516,30 @@ rb_p_result(int argc, const VALUE *argv)
/*
* call-seq:
- * p(obj) -> obj
- * p(obj1, obj2, ...) -> [obj, ...]
- * p() -> nil
+ * p(object) -> obj
+ * p(*objects) -> array of objects
+ * p -> nil
*
- * For each object, directly writes _obj_.+inspect+ followed by a
- * newline to the program's standard output.
+ * For each object +obj+, executes:
*
- * S = Struct.new(:name, :state)
- * s = S['dave', 'TX']
- * p s
+ * $stdout.write(obj.inspect, "\n")
*
- * <em>produces:</em>
+ * With one object given, returns the object;
+ * with multiple objects given, returns an array containing the objects;
+ * with no object given, returns +nil+.
+ *
+ * Examples:
+ *
+ * r = Range.new(0, 4)
+ * p r # => 0..4
+ * p [r, r, r] # => [0..4, 0..4, 0..4]
+ * p # => nil
+ *
+ * Output:
+ *
+ * 0..4
+ * [0..4, 0..4, 0..4]
*
- * #<S name="dave", state="TX">
*/
static VALUE
@@ -8519,26 +8555,19 @@ rb_f_p(int argc, VALUE *argv, VALUE self)
/*
* call-seq:
- * obj.display(port=$>) -> nil
+ * display(port = $>) -> nil
*
- * Prints <i>obj</i> on the given port (default <code>$></code>).
- * Equivalent to:
- *
- * def display(port=$>)
- * port.write self
- * nil
- * end
- *
- * For example:
+ * Writes +self+ on the given port:
*
* 1.display
* "cat".display
* [ 4, 5, 6 ].display
* puts
*
- * <em>produces:</em>
+ * Output:
*
* 1cat[4, 5, 6]
+ *
*/
static VALUE