From 349f4e7db766e618d606768d5ead8cbc9f4ef74f Mon Sep 17 00:00:00 2001 From: dave Date: Tue, 30 Dec 2003 16:38:32 +0000 Subject: Add RDoc for kernel functions, and tidy up git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@5352 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- io.c | 278 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 278 insertions(+) (limited to 'io.c') diff --git a/io.c b/io.c index 31d4bce67e..3ccb375876 100644 --- a/io.c +++ b/io.c @@ -2879,6 +2879,88 @@ rb_io_s_sysopen(argc, argv) return INT2NUM(fd); } +/* + * call-seq: + * open(path [, mode [, perm]] ) => io or nil + * open(path [, mode [. perm]] ) {|io| block } => nil + * + * Creates an IO object connected to the given stream, + * file, or subprocess. + * + * If path does not start with a pipe character + * (``|''), treat it as the name of a file to open using + * the specified mode (defaulting to ``r''). (See the table + * of valid modes on page 331.) If a file is being created, its initial + * permissions may be set using the integer third parameter. + * + * If a block is specified, it will be invoked with the + * File object as a parameter, and the file will be + * automatically closed when the block terminates. The call always + * returns nil in this case. + * + * If path starts with a pipe character, 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. If the command + * following the ``|'' is a single minus sign, Ruby forks, + * and this subprocess is connected to the parent. In the subprocess, + * the open call returns nil. If the command + * is not ``-'', the subprocess runs the command. If a + * block is associated with an open("|-") call, that block + * will be run twice---once in the parent and once in the child. 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. + * + * open("testfile") do |f| + * print f.gets + * end + * + * produces: + * + * This is line one + * + * Open a subprocess and read its output: + * + * cmd = open("|date") + * print cmd.gets + * cmd.close + * + * produces: + * + * Wed Apr 9 08:56:31 CDT 2003 + * + * Open a subprocess running the same Ruby program: + * + * f = open("|-", "w+") + * if f == nil + * puts "in Child" + * exit + * else + * puts "Got: #{f.gets}" + * end + * + * produces: + * + * Got: in Child + * + * Open a subprocess using a block to receive the I/O object: + * + * open("|-") do |f| + * if f == nil + * puts "in Child" + * else + * puts "Got: #{f.gets}" + * end + * end + * + * produces: + * + * Got: in Child + */ + static VALUE rb_f_open(argc, argv) int argc; @@ -3173,6 +3255,17 @@ rb_io_printf(argc, argv, out) return Qnil; } +/* + * call-seq: + * printf(io, string [, obj ... ] ) => nil + * printf(string [, obj ... ] ) => nil + * + * Equivalent to: + * io.write(sprintf(string, obj, ...) + * or + * $defout.write(sprintf(string, obj, ...) + */ + static VALUE rb_f_printf(argc, argv) int argc; @@ -3249,6 +3342,29 @@ rb_io_print(argc, argv, out) return Qnil; } +/* + * call-seq: + * print(obj, ...) => nil + * + * Prints each object in turn to $defout. 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. + * + * print "cat", [1,2,3], 99, "\n" + * $, = ", " + * $\ = "\n" + * print "cat", [1,2,3], 99 + * + * produces: + * + * cat12399 + * cat, 1, 2, 3, 99 + */ + static VALUE rb_f_print(argc, argv) int argc; @@ -3284,6 +3400,15 @@ rb_io_putc(io, ch) return ch; } +/* + * call-seq: + * putc(int) => int + * + * Equivalent to: + * + * $defout.putc(int) + */ + static VALUE rb_f_putc(recv, ch) VALUE recv, ch; @@ -3364,6 +3489,15 @@ rb_io_puts(argc, argv, out) return Qnil; } +/* + * call-seq: + * puts(obj, ...) => nil + * + * Equivalent to + * + * $defout.puts(obj, ...) + */ + static VALUE rb_f_puts(argc, argv) int argc; @@ -3381,6 +3515,24 @@ rb_p(obj) /* for debug print within C code */ rb_io_write(rb_stdout, rb_default_rs); } +/* + * call-seq: + * p(obj, ...) => nil + * + * For each object, directly writes + * _obj_.+inspect+ followed by the current output + * record separator to the program's standard output. +p+ + * bypasses the Ruby I/O libraries. + * + * S = Struct.new(:name, :state) + * s = S['dave', 'TX'] + * p s + * + * produces: + * + * # + */ + static VALUE rb_f_p(argc, argv) int argc; @@ -3397,6 +3549,29 @@ rb_f_p(argc, argv) return Qnil; } +/* + * call-seq: + * obj.display(port=$>) => nil + * + * Prints obj on the given port (default $>). + * Equivalent to: + * + * def display(port=$>) + * port.write self + * end + * + * For example: + * + * 1.display + * "cat".display + * [ 4, 5, 6 ].display + * puts + * + * produces: + * + * 1cat456 + */ + static VALUE rb_obj_display(argc, argv, self) int argc; @@ -3561,6 +3736,28 @@ rb_io_initialize(argc, argv, io) return io; } + +/* + * call-seq: + * File.new(filename, mode="r") => file + * File.new(filename [, mode [, perm]]) => file + * + + * Opens the file named by _filename_ according to + * _mode_ (default is ``r'') and returns a new + * File object. See the description of class +IO+ for + * a description of _mode_. The file mode may optionally be + * specified as a +Fixnum+ by _or_-ing together the + * flags (O_RDONLY etc, again described under +IO+). Optional + * permission bits may be given in _perm_. These mode and permission + * bits are platform dependent; on Unix systems, see + * open(2) for details. + * + * f = File.new("testfile", "r") + * f = File.new("newfile", "w+") + * f = File.new("newfile", File::CREAT|File::TRUNC|File::RDWR, 0644) + */ + static VALUE rb_file_initialize(argc, argv, io) int argc; @@ -3820,6 +4017,35 @@ argf_getline(argc, argv) return line; } +/* + * call-seq: + * gets(separator=$/) => string or nil + * + * Returns (and assigns to $_) the next line from the list + * of files in +ARGV+ (or $*), or from standard + * input if no files are present on the command line. Returns + * +nil+ at end of file. The optional argument specifies the + * record separator. The separator is included with the contents of + * each record. A separator of +nil+ reads the entire + * contents, and a zero-length separator reads the input one paragraph + * at a time, where paragraphs are divided by two consecutive newlines. + * If multiple filenames are present in +ARGV+, + * +gets(nil)+ will read the contents one file at a time. + * + * ARGV << "testfile" + * print while gets + * + * produces: + * + * This is line one + * This is line two + * This is line three + * And so on... + * + * The style of programming using $_ as an implicit + * parameter is gradually losing favor in the Ruby community. + */ + static VALUE rb_f_gets(argc, argv) int argc; @@ -3864,6 +4090,14 @@ rb_gets() return line; } +/* + * call-seq: + * readline(separator=$/ => string + * + * Equivalent to Kernel::gets, except + * +readline+ raises +EOFError+ at end of file. + */ + static VALUE rb_f_readline(argc, argv) int argc; @@ -3880,6 +4114,9 @@ rb_f_readline(argc, argv) return line; } +/* + * obsolete + */ static VALUE rb_f_getc() { @@ -3890,6 +4127,14 @@ rb_f_getc() return rb_io_getc(rb_stdin); } +/* + * call-seq: + * readlines(separator=$/) => array + * + * Returns an array containing the lines returned by calling + * Kernel.gets(aString) until the end of file. + */ + static VALUE rb_f_readlines(argc, argv) int argc; @@ -3906,6 +4151,20 @@ rb_f_readlines(argc, argv) return ary; } +/* + * call-seq: + * `cmd` => string + * + * Returns the standard output of running _cmd_ in a subshell. + * The built-in syntax %x{...} uses + * this method. Sets $? to the process status. + * + * `date` #=> "Wed Apr 9 08:56:30 CDT 2003\n" + * `ls testdir`.split[1] #=> "main.rb" + * `echo oops && exit 99` #=> "oops\n" + * $?.exitstatus #=> 99 + */ + static VALUE rb_f_backquote(obj, str) VALUE obj, str; @@ -4230,6 +4489,25 @@ rb_io_fcntl(argc, argv, io) #endif } +/* + * call-seq: + * syscall(fixnum [, args...]) => integer + * + * Calls the operating system function identified by _fixnum_, + * passing in the arguments, which must be either +String+ + * objects, or +Integer+ objects that ultimately fit within + * a native +long+. Up to nine parameters may be passed (14 + * on the Atari-ST). The function identified by _fixnum_ is system + * dependent. On some Unix systems, the numbers may be obtained from a + * header file called syscall.h. + * + * syscall 4, 1, "hello\n", 6 # '4' is write(2) on our box + * + * produces: + * + * hello + */ + static VALUE rb_f_syscall(argc, argv) int argc; -- cgit v1.2.3