1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[DOC] Enhanced RDoc for io.c (#5511)

Browse Source 
Treats:

    IO.foreach
    IO.readlines
    IO.read
    IO.binread
This commit is contained in:
Burdette Lamar 2022-02-04 06:55:10 -06:00 committed by GitHub
parent 203b1fc7e2
commit 46f6575157
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
Notes: git 2022-02-04 21:55:40 +09:00 
Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
1 changed files with 205 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

301
io.c
View File

@ -11191,38 +11191,98 @@ io_s_foreach(VALUE v)
/* /*
* call-seq: * call-seq:
* IO.foreach(name, sep=$/ [, getline_args, open_args]) {|line| block } -> nil * IO.foreach(command, sep = $/, **opts) {|line| block } -> nil
* IO.foreach(name, limit [, getline_args, open_args]) {|line| block } -> nil * IO.foreach(command, limit, **opts) {|line| block } -> nil
* IO.foreach(name, sep, limit [, getline_args, open_args]) {|line| block } -> nil * IO.foreach(command, sep, limit, **opts) {|line| block } -> nil
* IO.foreach(...) -> an_enumerator * IO.foreach(path, sep = $/, **opts) {|line| block } -> nil
* File.foreach(name, sep=$/ [, getline_args, open_args]) {|line| block } -> nil * IO.foreach(path, limit, **opts) {|line| block } -> nil
* File.foreach(name, limit [, getline_args, open_args]) {|line| block } -> nil * IO.foreach(path, sep, limit, **opts) {|line| block } -> nil
* File.foreach(name, sep, limit [, getline_args, open_args]) {|line| block } -> nil * IO.foreach(...) -> an_enumerator
* File.foreach(...) -> an_enumerator
* *
* Executes the block for every line in the named I/O port, where lines * Calls the block with each successive line read from the stream.
* are separated by <em>sep</em>.
* *
* If no block is given, an enumerator is returned instead. * The first argument must be a string;
* its meaning depends on whether it starts with the pipe character (<tt>'|'</tt>):
* *
* If +name+ starts with a pipe character (<code>"|"</code>) and the receiver * - If so (and if +self+ is \IO),
* is the IO class, a subprocess is created in the same way as Kernel#open, * the rest of the string is a command to be executed as a subprocess.
* and each line in its output is yielded. * - Otherwise, the string is the path to a file.
* Consider to use File.foreach to disable the behavior of subprocess invocation.
* *
* File.foreach("testfile") {|x| print "GOT ", x } * With only argument +command+ given, executes the command in a shell,
* IO.foreach("| cat testfile") {|x| print "GOT ", x } * parses its $stdout into lines, as determined by the default line separator,
* and calls the block with each successive line:
* *
* <em>produces:</em> * IO.foreach('| cat t.txt') {|line| p line }
* *
* GOT This is line one * Output:
* GOT This is line two
* GOT This is line three
* GOT And so on...
* *
* If the last argument is a hash, it's the keyword argument to open. * "First line\n"
* See IO.readlines for details about getline_args. * "Second line\n"
* And see also IO.read for details about open_args. * "\n"
* "Third line\n"
* "Fourth line\n"
*
* With only argument +path+ given, parses lines from the file at the given +path+,
* as determined by the default line separator,
* and calls the block with each successive line:
*
* File.foreach('t.txt') {|line| p line }
*
* Output: the same as above.
*
* 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 {IO Line Separator}[#class-IO-label-Line+Separator]):
*
* File.foreach('t.txt', 'li') {|line| p line }
*
* Output:
*
* "First li"
* "ne\nSecond li"
* "ne\n\nThird li"
* "ne\nFourth li"
* "ne\n"
*
* Each paragraph:
*
* File.foreach('t.txt', '') {|paragraph| p paragraph }
*
* Output:
*
* "First line\nSecond line\n\n"
* "Third line\nFourth line\n"
*
* With argument +limit+ given, parses lines as determined by the default
* line separator and the given line-length limit
* (see {IO Line Limit}[#class-IO-label-Line+Limit]):
*
* File.foreach('t.txt', 7) {|line| p line }
*
* Output:
*
* "First l"
* "ine\n"
* "Second "
* "line\n"
* "\n"
* "Third l"
* "ine\n"
* "Fourth l"
* "line\n"
*
* With arguments +sep+ and +limit+ given,
* parses lines as determined by the given
* line separator and the given line-length limit
* (see {IO Line Separator and Line Limit}[#class-IO-label-Line+Separator+and+Line+Limit]):
*
* Optional argument +opts+ specifies open options
* (see {IO Open Options}[#class-IO-label-Open+Options])
* and/or valid line options
* (see {IO Line Options}[#class-IO-label-Line+Options])
*
* Returns an Enumerator if no block is given.
* *
*/ */
@ -11253,42 +11313,68 @@ io_s_readlines(VALUE v)
/* /*
* call-seq: * call-seq:
* IO.readlines(name, sep=$/ [, getline_args, open_args]) -> array * IO.readlines(command, sep = $/, **opts) -> array
* IO.readlines(name, limit [, getline_args, open_args]) -> array * IO.readlines(command, limit, **opts) -> array
* IO.readlines(name, sep, limit [, getline_args, open_args]) -> array * IO.readlines(command, sep, limit, **opts) -> array
* File.readlines(name, sep=$/ [, getline_args, open_args]) -> array * IO.readlines(path, sep = $/, **opts) -> array
* File.readlines(name, limit [, getline_args, open_args]) -> array * IO.readlines(path, limit, **opts) -> array
* File.readlines(name, sep, limit [, getline_args, open_args]) -> array * IO.readlines(path, sep, limit, **opts) -> array
* *
* Reads the entire file specified by <i>name</i> as individual * Returns an array of all lines read from the stream.
* lines, and returns those lines in an array. Lines are separated by
* <i>sep</i>.
* *
* If +name+ starts with a pipe character (<code>"|"</code>) and the receiver * The first argument must be a string;
* is the IO class, a subprocess is created in the same way as Kernel#open, * its meaning depends on whether it starts with the pipe character (<tt>'|'</tt>):
* and each line in its output is yielded.
* Consider to use File.readlines to disable the behavior of subprocess invocation.
* *
* a = File.readlines("testfile") * - If so (and if +self+ is \IO),
* a[0] #=> "This is line one\n" * the rest of the string is a command to be executed as a subprocess.
* - Otherwise, the string is the path to a file.
* *
* b = File.readlines("testfile", chomp: true) * With only argument +command+ given, executes the command in a shell,
* b[0] #=> "This is line one" * parses its $stdout into lines, as determined by the default line separator,
* and returns those lines in an array:
* *
* IO.readlines("|ls -a") #=> [".\n", "..\n", ...] * IO.readlines('| cat t.txt')
* # => ["First line\n", "Second line\n", "\n", "Third line\n", "Fourth line\n"]
* *
* If the last argument is a hash, it's the keyword argument to open. * With only argument +path+ given, parses lines from the file at the given +path+,
* as determined by the default line separator,
* and returns those lines in an array:
* *
* === Options for getline * IO.readlines('t.txt')
* # => ["First line\n", "Second line\n", "\n", "Third line\n", "Fourth line\n"]
* *
* The options hash accepts the following keys: * For both forms, command and path, the remaining arguments are the same.
* *
* :chomp:: * With argument +sep+ given, parses lines as determined by that line separator
* When the optional +chomp+ keyword argument has a true value, * (see {IO Line Separator}[#class-IO-label-Line+Separator]):
* <code>\n</code>, <code>\r</code>, and <code>\r\n</code> *
* will be removed from the end of each line. * # Ordinary separator.
* IO.readlines('t.txt', 'li')
* # =>["First li", "ne\nSecond li", "ne\n\nThird li", "ne\nFourth li", "ne\n"]
* # Get-paragraphs separator.
* IO.readlines('t.txt', '')
* # => ["First line\nSecond line\n\n", "Third line\nFourth line\n"]
* # Get-all separator.
* IO.readlines('t.txt', nil)
* # => ["First line\nSecond line\n\nThird line\nFourth line\n"]
*
* With argument +limit+ given, parses lines as determined by the default
* line separator and the given line-length limit
* (see {IO Line Limit}[#class-IO-label-Line+Limit]):
*
* IO.readlines('t.txt', 7)
* # => ["First l", "ine\n", "Second ", "line\n", "\n", "Third l", "ine\n", "Fourth ", "line\n"]
*
* With arguments +sep+ and +limit+ given,
* parses lines as determined by the given
* line separator and the given line-length limit
* (see {IO Line Separator and Line Limit}[#class-IO-label-Line+Separator+and+Line+Limit]):
*
* Optional argument +opts+ specifies open options
* (see {IO Open Options}[#class-IO-label-Open+Options])
* and/or valid line options
* (see {IO Line Options}[#class-IO-label-Line+Options])
* *
* See also IO.read for details about +name+ and open_args.
*/ */
static VALUE static VALUE
@ -11330,48 +11416,48 @@ seek_before_access(VALUE argp)
/* /*
* call-seq: * call-seq:
* IO.read(name, [length [, offset]] [, opt]) -> string * IO.read(command, length = nil, offset = 0, **opts) -> string or nil
* File.read(name, [length [, offset]] [, opt]) -> string * IO.read(path, length = nil, offset = 0, **opts) -> string or nil
* *
* Opens the file, optionally seeks to the given +offset+, then returns * Opens the stream, reads and returns some or all of its content,
* +length+ bytes (defaulting to the rest of the file). #read ensures * and closes the stream; returns +nil+ if no bytes were read.
* the file is closed before returning.
* *
* If +name+ starts with a pipe character (<code>"|"</code>) and the receiver * The first argument must be a string;
* is the IO class, a subprocess is created in the same way as Kernel#open, * its meaning depends on whether it starts with the pipe character (<tt>'|'</tt>):
* and its output is returned.
* Consider to use File.read to disable the behavior of subprocess invocation.
* *
* === Options * - If so (and if +self+ is \IO),
* the rest of the string is a command to be executed as a subprocess.
* - Otherwise, the string is the path to a file.
* *
* The options hash accepts the following keys: * With only argument +command+ given, executes the command in a shell,
* returns its entire $stdout:
* *
* :encoding:: * IO.read('| cat t.txt')
* string or encoding * # => "First line\nSecond line\n\nThird line\nFourth line\n"
* *
* Specifies the encoding of the read string. +:encoding+ will be ignored * With only argument +path+ given, reads and returns the entire content
* if +length+ is specified. See Encoding.aliases for possible encodings. * of the file at the given path:
* *
* :mode:: * IO.read('t.txt')
* string or integer * # => "First line\nSecond line\n\nThird line\nFourth line\n"
* *
* Specifies the <i>mode</i> argument for open(). It must start * For both forms, command and path, the remaining arguments are the same.
* with an "r", otherwise it will cause an error.
* See IO.new for the list of possible modes.
* *
* :open_args:: * With argument +length+, returns +length+ bytes if available:
* array
* *
* Specifies arguments for open() as an array. This key can not be used * IO.read('t.txt', 7) # => "First l"
* in combination with either +:encoding+ or +:mode+. * IO.read('t.txt', 700)
* # => "First line\r\nSecond line\r\n\r\nFourth line\r\nFifth line\r\n"
* *
* Examples: * With arguments +length+ and +offset+, returns +length+ bytes
* if available, beginning at the given +offset+:
*
* IO.read('t.txt', 10, 2) # => "rst line\nS"
* IO.read('t.txt', 10, 200) # => nil
*
* The optional keyword arguments +opts+ may be open options;
* see {\IO Open Options}[#class-IO-label-Open+Options]
* *
* File.read("testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
* File.read("testfile", 20) #=> "This is line one\nThi"
* File.read("testfile", 20, 10) #=> "ne one\nThis is line "
* File.read("binfile", mode: "rb") #=> "\xF7\x00\x00\x0E\x12"
* IO.read("|ls -a") #=> ".\n..\n"...
*/ */
static VALUE static VALUE
@ -11401,25 +11487,48 @@ rb_io_s_read(int argc, VALUE *argv, VALUE io)
/* /*
* call-seq: * call-seq:
* IO.binread(name, [length [, offset]]) -> string * IO.binread(command, length = nil, offset = 0) -> string or nil
* File.binread(name, [length [, offset]]) -> string * IO.binread(path, length = nil, offset = 0) -> string or nil
* *
* Opens the file, optionally seeks to the given <i>offset</i>, then * Opens the stream in binary mode (mode <tt>'rb:ASCII-8BIT'</tt>),
* returns <i>length</i> bytes (defaulting to the rest of the file). * reads and returns some or all of its content,
* #binread ensures the file is closed before returning. The open mode * and closes the stream; returns +nil+ if no bytes were read.
* would be <code>"rb:ASCII-8BIT"</code>.
* *
* If +name+ starts with a pipe character (<code>"|"</code>) and the receiver * The first argument must be a string;
* is the IO class, a subprocess is created in the same way as Kernel#open, * its meaning depends on whether it starts with the pipe character (<tt>'|'</tt>):
* and its output is returned.
* Consider to use File.binread to disable the behavior of subprocess invocation.
* *
* File.binread("testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n" * - If so (and if +self+ is \IO),
* File.binread("testfile", 20) #=> "This is line one\nThi" * the rest of the string is a command to be executed as a subprocess.
* File.binread("testfile", 20, 10) #=> "ne one\nThis is line " * - Otherwise, the string is the path to a file.
* IO.binread("| cat testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n" *
* With only argument +command+ given, executes the command in a shell,
* returns its entire $stdout:
*
* IO.binread('| cat t.rus')
* # => "\xD1\x82\xD0\xB5\xD1\x81\xD1\x82"
*
* With only argument +path+ given, returns the entire content
* of the file at the given +path+:
*
* IO.binread("t.rus")
* # => "\xD1\x82\xD0\xB5\xD1\x81\xD1\x82"
*
* For both forms, command and path, the remaining arguments are the same.
*
* With argument +length+, returns +length+ bytes if available:
*
* IO.binread('t.rus', 5)
* # => "\xD1\x82\xD0\xB5\xD1"
*
* With arguments +length+ and +offset+, returns +length+ bytes
* if available, beginning at the given +offset+:
*
* IO.binread('t.rus', 5, 2) # => "\xD0\xB5\xD1\x81\xD1"
* IO.binread('t.rus', 5, 200) # => nil
*
* The optional keyword arguments +opts+ may be open options;
* see {\IO Open Options}[#class-IO-label-Open+Options]
* *
* See also IO.read for details about +name+ and open_args.
*/ */
static VALUE static VALUE