diff options
author | naruse <naruse@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2009-09-05 20:23:56 +0000 |
---|---|---|
committer | naruse <naruse@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2009-09-05 20:23:56 +0000 |
commit | a535975bcb43eb5c9afb2bff8f8211fb974246de (patch) | |
tree | e7901632a1efac445a94de3a89e2ec1459b2d6b0 | |
parent | ef2c92ddf0c008c9bd785491d505afd3c7a73af9 (diff) | |
download | ruby-a535975bcb43eb5c9afb2bff8f8211fb974246de.tar.gz |
* io.c: Add rdoc for ARGF.
contributed by Run Paint Run Run. [ruby-core:23854]
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@24764 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
-rw-r--r-- | ChangeLog | 5 | ||||
-rw-r--r-- | io.c | 649 |
2 files changed, 648 insertions, 6 deletions
@@ -1,3 +1,8 @@ +Sun Sep 6 05:19:09 2009 NARUSE, Yui <naruse@ruby-lang.org> + + * io.c: Add rdoc for ARGF. + contributed by Run Paint Run Run. [ruby-core:23854] + Sat Sep 5 15:21:13 2009 Nobuyoshi Nakada <nobu@ruby-lang.org> * compile.c (iseq_compile_each): op_asgn to aref should return rhs. @@ -1300,7 +1300,7 @@ rb_io_set_sync(VALUE io, VALUE sync) * operating system actually writes it to disk. * * <code>NotImplementedError</code> is raised - * if the underlying operating system does not support <em>fsync(2)</em>. + * if the underlying operating system does not support <em>fsync(2)</em>. */ static VALUE @@ -1329,7 +1329,7 @@ rb_io_fsync(VALUE io) * Immediately writes all buffered data in <em>ios</em> to disk. * * <code>NotImplementedError</code> is raised - * if the underlying operating system does not support <em>fdatasync(2)</em>. + * if the underlying operating system does not support <em>fdatasync(2)</em>. */ static VALUE @@ -2275,7 +2275,7 @@ rb_io_getline_fast(rb_io_t *fptr, rb_encoding *enc) ENC_CODERANGE_SET(str, cr); fptr->lineno++; ARGF.last_lineno = fptr->lineno; - + return str; } @@ -4441,7 +4441,7 @@ static VALUE sysopen_func(void *ptr) { const struct sysopen_struct *data = ptr; - const char *fname = RSTRING_PTR(data->fname); + const char *fname = RSTRING_PTR(data->fname); #ifdef _WIN32 if (data->wchar) return (VALUE)rb_w32_wopen((WCHAR *)fname, data->oflags, data->perm); @@ -6541,6 +6541,24 @@ argf_initialize_copy(VALUE argf, VALUE orig) return argf; } +/* + * call-seq: + * ARGF.lineno = number => nil + * + * Sets the line number of the current file in +ARGF+ to the given +Integer+. + * + * +ARGF+ sets the line number automatically as you read data, so normally + * you will not need to set it explicitly. To access the current line number + * use +ARGF.lineno+. + * + * For example: + * + * ARGF.lineno #=> 0 + * ARGF.readline #=> "This is line 1\n" + * ARGF.lineno #=> 1 + * ARGF.lineno = 0 #=> nil + * ARGF.lineno #=> 0 + */ static VALUE argf_set_lineno(VALUE argf, VALUE val) { @@ -6549,6 +6567,19 @@ argf_set_lineno(VALUE argf, VALUE val) return Qnil; } +/* + * call-seq: + * ARGF.lineno => Integer + * + * Returns the current line number of the current file in +ARGF+. This value + * can be set manually with +ARGF.lineno=+. + * + * For example: + * + * ARGF.lineno #=> 0 + * ARGF.readline #=> "This is line 1\n" + * ARGF.lineno #=> 1 + */ static VALUE argf_lineno(VALUE argf) { @@ -6684,7 +6715,7 @@ argf_next_argv(VALUE argf) } ARGF.current_file = prep_io(fr, FMODE_READABLE, rb_cFile, fn); } - if (ARGF.binmode) rb_io_ascii8bit_binmode(ARGF.current_file); + if (ARGF.binmode) rb_io_ascii8bit_binmode(ARGF.current_file); if (ARGF.encs.enc) { rb_io_t *fptr; @@ -6798,6 +6829,21 @@ rb_f_gets(int argc, VALUE *argv, VALUE recv) return rb_funcall2(argf, rb_intern("gets"), argc, argv); } +/* + * call-seq: + * ARGF.gets(sep=$/) => String + * ARGF.gets(limit) => String + * ARGF.gets(sep, limit) => String + * + * Returns the next line from the current file in +ARGF+. + * + * By default lines are assumed to be separated by +$/+; to use a different + * character as a separator, supply it as a +String+ for the _sep_ argument. + * + * The optional _limit_ argument specifies how many characters of each line + * to return. By default all characters are returned. + * + */ static VALUE argf_gets(int argc, VALUE *argv, VALUE argf) { @@ -6856,6 +6902,23 @@ rb_f_readline(int argc, VALUE *argv, VALUE recv) return rb_funcall2(argf, rb_intern("readline"), argc, argv); } + +/* + * call-seq: + * ARGF.readline(sep=$/) => String + * ARGF.readline(limit) => String + * ARGF.readline(sep, limit) => String + * + * Returns the next line from the current file in +ARGF+. + * + * By default lines are assumed to be separated by +$/+; to use a different + * character as a separator, supply it as a +String+ for the _sep_ argument. + * + * The optional _limit_ argument specifies how many characters of each line + * to return. By default all characters are returned. + * + * An +EOFError+ is raised at the end of the file. + */ static VALUE argf_readline(int argc, VALUE *argv, VALUE argf) { @@ -6892,6 +6955,22 @@ rb_f_readlines(int argc, VALUE *argv, VALUE recv) return rb_funcall2(argf, rb_intern("readlines"), argc, argv); } +/* + * call-seq: + * ARGF.readlines(sep=$/) => Array + * ARGF.readlines(limit) => Array + * ARGF.readlines(sep, limit) => Array + * + * ARGF.to_a(sep=$/) => Array + * ARGF.to_a(limit) => Array + * ARGF.to_a(sep, limit) => Array + * + * Reads +ARGF+'s current file in its entirety, returning an +Array+ of its + * lines, one line per element. Lines are assumed to be separated by _sep_. + * + * lines = ARGF.readlines + * lines[0] #=> "This is line one\n" + */ static VALUE argf_readlines(int argc, VALUE *argv, VALUE argf) { @@ -8426,6 +8505,22 @@ rb_stdio_set_default_encoding(void) rb_io_set_encoding(1, &val, rb_stderr); } +/* + * call-seq: + * ARGF.external_encoding => encoding + * + * Returns the external encoding for files read from +ARGF+ as an +Encoding+ + * object. The external encoding is the encoding of the text as stored in a + * file. Contrast with +ARGF.internal_encoding+, which is the encoding used + * to represent this text within Ruby. + * + * To set the external encoding use +ARGF.set_encoding+. + * + * For example: + * + * ARGF.external_encoding #=> #<Encoding:UTF-8> + * + */ static VALUE argf_external_encoding(VALUE argf) { @@ -8435,6 +8530,19 @@ argf_external_encoding(VALUE argf) return rb_io_external_encoding(rb_io_check_io(ARGF.current_file)); } +/* + * call-seq: + * ARGF.internal_encoding => encoding + * + * Returns the internal encoding for strings read from +ARGF+ as an + * +Encoding+ object. + * + * If +ARGF.set_encoding+ has been called with two encoding names, the second + * is returned. Otherwise, if +Encoding.default_external+ has been set, that + * value is returned. Failing that, if a default external encoding was + * specified on the command-line, that value is used. If the encoding is + * unknown, nil is returned. + */ static VALUE argf_internal_encoding(VALUE argf) { @@ -8444,6 +8552,37 @@ argf_internal_encoding(VALUE argf) return rb_io_internal_encoding(rb_io_check_io(ARGF.current_file)); } +/* + * call-seq: + * ARGF.set_encoding(ext_enc) => ARGF + * ARGF.set_encoding("ext_enc:int_enc") => ARGF + * ARGF.set_encoding(ext_enc, int_enc) => ARGF + * ARGF.set_encoding("ext_enc:int_enc", opt) => ARGF + * ARGF.set_encoding(ext_enc, int_enc, opt) => ARGF + * + * If single argument is specified, strings read from ARGF are tagged with + * the encoding specified. + * + * If two encoding names separated by a colon are given, e.g. "ascii:utf-8", + * the read string is converted from the first encoding (external encoding) + * to the second encoding (internal encoding), then tagged with the second + * encoding. + * + * If two arguments are specified, they must be encoding objects or encoding + * names. Again, the first specifies the external encoding; the second + * specifies the internal encoding. + * + * If the external encoding and the internal encoding are specified, the + * optional +Hash+ argument can be used to adjust the conversion process. The + * structure of this hash is explained in the +String#encode+ documentation. + * + * For example: + * + * ARGF.set_encoding('ascii') # Tag the input as US-ASCII text + * ARGF.set_encoding(Encoding::UTF_8) # Tag the input as UTF-8 text + * ARGF.set_encoding('utf-8','ascii') # Transcode the input from US-ASCII + * # to UTF-8. + */ static VALUE argf_set_encoding(int argc, VALUE *argv, VALUE argf) { @@ -8458,6 +8597,18 @@ argf_set_encoding(int argc, VALUE *argv, VALUE argf) return argf; } +/* + * call-seq: + * ARGF.tell => Integer + * ARGF.pos => Integer + * + * Returns the current offset (in bytes) of the current file in +ARGF+. + * + * ARGF.pos #=> 0 + * ARGF.gets #=> "This is line one\n" + * ARGF.pos #=> 17 + * + */ static VALUE argf_tell(VALUE argf) { @@ -8468,6 +8619,13 @@ argf_tell(VALUE argf) return rb_io_tell(ARGF.current_file); } +/* + * call-seq: + * ARGF.seek(amount, whence=SEEK_SET) -> 0 + * + * Seeks to offset _amount_ (an +Integer+) in the +ARGF+ stream according to + * the value of _whence_. See +IO#seek+ for further details. + */ static VALUE argf_seek_m(int argc, VALUE *argv, VALUE argf) { @@ -8478,6 +8636,17 @@ argf_seek_m(int argc, VALUE *argv, VALUE argf) return rb_io_seek_m(argc, argv, ARGF.current_file); } +/* + * call-seq: + * ARGF.pos = position => Integer + * + * Seeks to the position given by _position_ (in bytes) in +ARGF+. + * + * For example: + * + * ARGF.pos = 17 + * ARGF.gets #=> "This is line two\n" + */ static VALUE argf_set_pos(VALUE argf, VALUE offset) { @@ -8488,6 +8657,18 @@ argf_set_pos(VALUE argf, VALUE offset) return rb_io_set_pos(ARGF.current_file, offset); } +/* + * call-seq: + * ARGF.rewind => 0 + * + * Positions the current file to the beginning of input, resetting + * +ARGF.lineno+ to zero. + * + * ARGF.readline #=> "This is line one\n" + * ARGF.rewind #=> 0 + * ARGF.lineno #=> 0 + * ARGF.readline #=> "This is line one\n" + */ static VALUE argf_rewind(VALUE argf) { @@ -8498,6 +8679,16 @@ argf_rewind(VALUE argf) return rb_io_rewind(ARGF.current_file); } +/* + * call-seq: + * ARGF.fileno => fixnum + * ARGF.to_i => fixnum + * + * Returns an integer representing the numeric file descriptor for + * the current file. Raises an +ArgumentError+ if there isn't a current file. + * + * ARGF.fileno #=> 3 + */ static VALUE argf_fileno(VALUE argf) { @@ -8508,6 +8699,18 @@ argf_fileno(VALUE argf) return rb_io_fileno(ARGF.current_file); } +/* + * call-seq: + * ARGF.to_io => IO + * + * Returns an +IO+ object representing the current file. This will be a + * +File+ object unless the current file is a stream such as STDIN. + * + * For example: + * + * ARGF.to_io #=> #<File:glark.txt> + * ARGF.to_io #=> #<IO:<STDIN>> + */ static VALUE argf_to_io(VALUE argf) { @@ -8516,6 +8719,24 @@ argf_to_io(VALUE argf) return ARGF.current_file; } +/* + * call-seq: + * ARGF.eof? => true or false + * ARGF.eof => true or false + * + * Returns true if the current file in +ARGF+ is at end of file, i.e. it has + * no data to read. The stream must be opened for reading or an +IOError+ + * will be raised. + * + * $ echo "eof" | ruby argf.rb + * + * ARGF.eof? #=> false + * 3.times { ARGF.readchar } + * ARGF.eof? #=> false + * ARGF.readchar #=> "\n" + * ARGF.eof? #=> true + */ + static VALUE argf_eof(VALUE argf) { @@ -8531,6 +8752,43 @@ argf_eof(VALUE argf) return Qfalse; } +/* + * call-seq: + * ARGF.read([length [, buffer]]) => string, buffer, or nil + * + * Reads _length_ bytes from ARGF. The files named on the command line + * are concatenated and treated as a single file by this method, so when + * called without arguments the contents of this pseudo file are returned in + * their entirety. + * + * _length_ must be a non-negative integer or nil. If it is a positive + * integer, +read+ tries to read at most _length_ bytes. It returns nil + * if an EOF was encountered before anything could be read. Fewer than + * _length_ bytes may be returned if an EOF is encountered during the read. + * + * If _length_ is omitted or is _nil_, it reads until EOF. A String is + * returned even if EOF is encountered before any data is read. + * + * If _length_ is zero, it returns _""_. + * + * If the optional _buffer_ argument is present, it must reference a String, + * which will receive the data. + * + * For example: + * + * $ echo "small" > small.txt + * $ echo "large" > large.txt + * $ ./glark.rb small.txt large.txt + * + * ARGF.read #=> "small\nlarge" + * ARGF.read(200) #=> "small\nlarge" + * ARGF.read(2) #=> "sm" + * ARGF.read(0) #=> "" + * + * Note that this method behaves like fread() function in C. If you need the + * behavior like read(2) system call, consider +ARGF.readpartial+. + */ + static VALUE argf_read(int argc, VALUE *argv, VALUE argf) { @@ -8590,6 +8848,34 @@ argf_forward_call(VALUE arg) return Qnil; } +/* + * call-seq: + * ARGF.readpartial(maxlen) => string + * ARGF.readpartial(maxlen, outbuf) => outbuf + * + * Reads at most _maxlen_ bytes from the ARGF stream. It blocks only if + * +ARGF+ has no data immediately available. If the optional _outbuf_ + * argument is present, it must reference a String, which will receive the + * data. It raises <code>EOFError</code> on end of file. + * + * +readpartial+ is designed for streams such as pipes, sockets, and ttys. It + * blocks only when no data is immediately available. This means that it + * blocks only when following all conditions hold: + * + * * The buffer in the +IO+ object is empty. + * * The content of the stream is empty. + * * The stream has not reached EOF. + * + * When +readpartial+ blocks, it waits for data or EOF. If some data is read, + * +readpartial+ returns with the data. If EOF is reached, readpartial raises + * an +EOFError+. + * + * When +readpartial+ doesn't block, it returns or raises immediately. If + * the buffer is not empty, it returns the data in the buffer. Otherwise, if + * the stream has some content, it returns the data in the stream. If the + * stream reaches EOF an +EOFError+ is raised. + */ + static VALUE argf_readpartial(int argc, VALUE *argv, VALUE argf) { @@ -8631,6 +8917,29 @@ argf_readpartial(int argc, VALUE *argv, VALUE argf) return tmp; } +/* + * call-seq: + * ARGF.getc => String or nil + * + * Reads the next character from +ARGF+ and returns it as a +String+. Returns + * +nil+ at the end of the stream. + * + * +ARGF+ treats the files named on the command line as a single file created + * by concatenating their contents. After returning the last character of the + * first file, it returns the first character of the second file, and so on. + * + * For example: + * + * $ echo "foo" > file + * $ ruby argf.rb file + * + * ARGF.getc #=> "f" + * ARGF.getc #=> "o" + * ARGF.getc #=> "o" + * ARGF.getc #=> "\n" + * ARGF.getc #=> nil + * ARGF.getc #=> nil + */ static VALUE argf_getc(VALUE argf) { @@ -8653,6 +8962,24 @@ argf_getc(VALUE argf) return ch; } +/* + * call-seq: + * ARGF.getbyte => Fixnum or nil + * + * Gets the next 8-bit byte (0..255) from +ARGF+. Returns +nil+ if called at + * the end of the stream. + * + * For example: + * + * $ echo "foo" > file + * $ ruby argf.rb file + * + * ARGF.getbyte #=> 102 + * ARGF.getbyte #=> 111 + * ARGF.getbyte #=> 10 + * ARGF.getbyte #=> nil + * ARGF.getbyte #=> nil + */ static VALUE argf_getbyte(VALUE argf) { @@ -8675,6 +9002,24 @@ argf_getbyte(VALUE argf) return ch; } +/* + * call-seq: + * ARGF.readchar => String or nil + * + * Reads the next character from +ARGF+ and returns it as a +String+. Raises + * an +EOFError+ after the last character of the last file has been read. + * + * For example: + * + * $ echo "foo" > file + * $ ruby argf.rb file + * + * ARGF.readchar #=> "f" + * ARGF.readchar #=> "o" + * ARGF.readchar #=> "o" + * ARGF.readchar #=> "\n" + * ARGF.readchar #=> end of file reached (EOFError) + */ static VALUE argf_readchar(VALUE argf) { @@ -8697,6 +9042,24 @@ argf_readchar(VALUE argf) return ch; } +/* + * call-seq: + * ARGF.readbyte => Fixnum + * + * Reads the next 8-bit byte from ARGF and returns it as a +Fixnum+. Raises + * an +EOFError+ after the last byte of the last file has been read. + * + * For example: + * + * $ echo "foo" > file + * $ ruby argf.rb file + * + * ARGF.readbyte #=> 102 + * ARGF.readbyte #=> 111 + * ARGF.readbyte #=> 111 + * ARGF.readbyte #=> 10 + * ARGF.readbyte #=> end of file reached (EOFError) + */ static VALUE argf_readbyte(VALUE argf) { @@ -8710,6 +9073,43 @@ argf_readbyte(VALUE argf) return c; } +/* + * call-seq: + * ARGF.lines(sep=$/) => Enumerator + * ARGF.lines(sep=$/) {|line| } => Enumerator + * ARGF.lines(sep=$/,limit) => Enumerator + * ARGF.lines(sep=$/,limit) {|line| } => Enumerator + * + * ARGF.each_line(sep=$/) => Enumerator + * ARGF.each_line(sep=$/) {|line| } => Enumerator + * ARGF.each_line(sep=$/,limit) => Enumerator + * ARGF.each_line(sep=$/,limit) {|line| } => Enumerator + * ARGF.each(sep=$/) => Enumerator + * ARGF.each(sep=$/) {|line| } => Enumerator + * ARGF.each(sep=$/,limit) => Enumerator + * ARGF.each(sep=$/,limit) {|line| } => Enumerator + * + * Returns an enumerator which iterates over each line (separated by _sep_, + * which defaults to your platform's newline character) of each file in + * +ARGV+. If a block is supplied, each line in turn will be yielded to the + * block. The optional _limit_ argument is a +Fixnum+ specifying the maximumn + * length of each line; longer lines will be split according to this limit. + * + * This method allows you to treat the files supplied on the command line as + * a single file consisting of the concatenation of each named file. After + * the last line of the first file has been returned, the first line of the + * second file is returned. The +ARGF.filename+ and +ARGF.lineno+ methods can + * be used to determine the filename and line number, respectively, of the + * current line. + * + * For example, the following code prints out each line of each named file + * prefixed with its line number, displaying the filename once per file: + * + * ARGF.lines do |line| + * puts ARGF.filename if ARGF.lineno == 1 + * puts "#{ARGF.lineno}: #{line}" + * end + */ static VALUE argf_each_line(int argc, VALUE *argv, VALUE argf) { @@ -8721,6 +9121,29 @@ argf_each_line(int argc, VALUE *argv, VALUE argf) } } +/* + * call-seq: + * ARGF.bytes => Enumerator + * ARGF.bytes {|byte| } => Enumerator + * + * ARGF.each_byte => Enumerator + * ARGF.each_byte {|byte| } => Enumerator + * + * Returns an enumerator which iterates over each byte of each file in + * +ARGV+. If a block is supplied, each byte in turn will be yielded to the + * block. A byte is returned as a +Fixnum+ in the range 0..255. + * + * This method allows you to treat the files supplied on the command line as + * a single file consisting of the concatenation of each named file. After + * the last byte of the first file has been returned, the first byte of the + * second file is returned. The +ARGF.filename+ method can be used to + * determine the filename of the current byte. + * + * For example: + * + * ARGF.bytes.to_a #=> [35, 32, ... 95, 10] + * + */ static VALUE argf_each_byte(VALUE argf) { @@ -8732,6 +9155,25 @@ argf_each_byte(VALUE argf) } } +/* + * call-seq: + * ARGF.chars => Enumerator + * ARGF.chars {|char| } => Enumerator + * + * ARGF.each_char => Enumerator + * ARGF.each_char {|char| } => Enumerator + * + * Returns an enumerator which iterates over each character of each file in + * +ARGV+. If a block is supplied, each character in turn will be yielded to + * the block. + * + * This method allows you to treat the files supplied on the command line as + * a single file consisting of the concatenation of each named file. After + * the last character of the first file has been returned, the first + * character of the second file is returned. The +ARGF.filename+ method can + * be used to determine the name of the file in which the current character + * appears. + */ static VALUE argf_each_char(VALUE argf) { @@ -8743,6 +9185,28 @@ argf_each_char(VALUE argf) } } +/* + * call-seq: + * ARGF.filename => String + * ARGF.path => String + * + * Returns the current filename. "-" is returned when the current file is + * STDIN. + * + * For example: + * + * $ echo "foo" > foo + * $ echo "bar" > bar + * $ echo "glark" > glark + * + * $ ruby argf.rb foo bar glark + * + * ARGF.filename #=> "foo" + * ARGF.read(5) #=> "foo\nb" + * ARGF.filename #=> "bar" + * ARGF.skip + * ARGF.filename #=> "glark" + */ static VALUE argf_filename(VALUE argf) { @@ -8756,6 +9220,24 @@ argf_filename_getter(ID id, VALUE *var) return argf_filename(*var); } +/* + * call-seq: + * ARGF.file => IO or File object + * + * Returns the current file as an +IO+ or +File+ object. #<IO:<STDIN>> is + * returned when the current file is STDIN. + * + * For example: + * + * $ echo "foo" > foo + * $ echo "bar" > bar + * + * $ ruby argf.rb foo bar + * + * ARGF.file #=> #<File:foo> + * ARGF.read(5) #=> "foo\nb" + * ARGF.file #=> #<File:bar> + */ static VALUE argf_file(VALUE argf) { @@ -8763,6 +9245,17 @@ argf_file(VALUE argf) return ARGF.current_file; } +/* + * call-seq: + * ARGF.binmode => ARGF + * + * Puts +ARGF+ into binary mode. Once a stream is in binary mode, it cannot + * be reset to non-binary mode. This option has the following effects: + * + * * Newline conversion is disabled. + * * Encoding conversion is disabled. + * * Content is treated as ASCII-8BIT. + */ static VALUE argf_binmode_m(VALUE argf) { @@ -8770,16 +9263,42 @@ argf_binmode_m(VALUE argf) next_argv(); ARGF_FORWARD(0, 0); rb_io_ascii8bit_binmode(ARGF.current_file); - return argf; } +/* + * call-seq: + * ARGF.binmode? => true or false + * + * Returns true if +ARGF+ is being read in binary mode; false otherwise. (To + * enable binary mode use +ARGF.binmode+. + * + * For example: + * + * ARGF.binmode? #=> false + * ARGF.binmode + * ARGF.binmode? #=> true + */ static VALUE argf_binmode_p(VALUE argf) { return ARGF.binmode ? Qtrue : Qfalse; } +/* + * call-seq: + * ARGF.skip => ARGF + * + * Sets the current file to the next file in ARGV. If there aren't any more + * files it has no effect. + * + * For example: + * + * $ ruby argf.rb foo bar + * ARGF.filename #=> "foo" + * ARGF.skip + * ARGF.filename #=> "bar" + */ static VALUE argf_skip(VALUE argf) { @@ -8790,6 +9309,24 @@ argf_skip(VALUE argf) return argf; } +/* + * call-seq: + * ARGF.close => ARGF + * + * Closes the current file and skips to the next in the stream. Trying to + * close a file that has already been closed causes an +IOError+ to be + * raised. + * + * For example: + * + * $ ruby argf.rb foo bar + * + * ARGF.filename #=> "foo" + * ARGF.close + * ARGF.filename #=> "bar" + * ARGF.close + * ARGF.close #=> closed stream (IOError) + */ static VALUE argf_close_m(VALUE argf) { @@ -8802,6 +9339,13 @@ argf_close_m(VALUE argf) return argf; } +/* + * call-seq: + * ARGF.closed? => true or false + * + * Returns _true_ if the current file has been closed; _false_ otherwise. Use + * +ARGF.close+ to actually close the current file. + */ static VALUE argf_closed(VALUE argf) { @@ -8810,12 +9354,26 @@ argf_closed(VALUE argf) return rb_io_closed(ARGF.current_file); } +/* + * call-seq: + * ARGF.to_s => String + * + * Returns "ARGF". + */ static VALUE argf_to_s(VALUE argf) { return rb_str_new2("ARGF"); } +/* + * call-seq: + * ARGF.inplace_mode => String + * + * Returns the file extension appended to the names of modified files under + * inplace-edit mode. This value can be set using +ARGF.inplace_mode=+ or + * passing the +-i+ switch to the Ruby binary. + */ static VALUE argf_inplace_mode_get(VALUE argf) { @@ -8829,6 +9387,26 @@ opt_i_get(ID id, VALUE *var) return argf_inplace_mode_get(*var); } +/* + * call-seq: + * ARGF.inplace_mode = ext => ARGF + * + * Sets the filename extension for inplace editing mode to the given String. + * Each file being edited has this value appended to its filename. The + * modifed file is saved under this new name. + * + * For example: + * + * $ ruby argf.rb file.txt + * + * ARGF.inplace_mode = '.bak' + * ARGF.lines do |line| + * print line.sub("foo","bar") + * end + * + * Each line of _file.txt_ has the first occurence of "foo" replaced with + * "bar", then the new line is written out to _file.txt.bak_. + */ static VALUE argf_inplace_mode_set(VALUE argf, VALUE val) { @@ -8865,6 +9443,20 @@ ruby_set_inplace_mode(const char *suffix) if (suffix) ARGF.inplace = strdup(suffix); } +/* + * call-seq: + * ARGF.argv => Array + * + * Returns the +ARGV+ Array, which contains the arguments passed to your + * script, one per element. + * + * For example: + * + * $ ruby argf.rb -v glark.txt + * + * ARGF.argv #=> ["-v", "glark.txt"] + * + */ static VALUE argf_argv(VALUE argf) { @@ -8884,6 +9476,47 @@ rb_get_argv(void) } /* + * Document-class: ARGF + * + * +ARGF+ is a stream designed for use in scripts that process files given as + * command-line arguments, or passed in via STDIN. + * + * The arguments passed to your script are stored in the +ARGV+ Array, one + * argument per element. +ARGF+ assumes that any arguments that aren't + * filenames have been removed from +ARGV+. For example: + * + * $ ruby argf.rb --verbose file1 file2 + * + * ARGV #=> ["--verbose", "file1", "file2"] + * option = ARGV.shift #=> "--verbose" + * ARGV #=> ["file1", "file2"] + * + * You can now use +ARGF+ to work with a concatenation of each of these named + * files. For instance, +ARGF.read+ will return the contents of _file1_ + * followed by the contents of _file2_. + * + * After a file in +ARGV+ has been read, +ARGF+ removes it from the Array. + * Thus, after all files have been read +ARGV+ will be empty. + * + * You can manipulate +ARGV+ yourself to control what +ARGF+ operates on. If + * you remove a file from +ARGV+, it is ignored by +ARGF+; if you add files to + * +ARGV+, they are treated as if they were named on the command line. For + * example: + * + * ARGV.replace ["file1"] + * ARGF.readlines # Returns the contents of file1 as an Array + * ARGV #=> [] + * ARGV.replace ["file2", "file3"] + * ARGF.read # Returns the contents of file2 and file3 + * + * If +ARGV+ is empty, +ARGF+ acts as if it contained STDIN, i.e. the data + * piped to your script. For example: + * + * $ echo "glark" | ruby -e 'p ARGF.read' + * "glark\n" + */ + +/* * Class <code>IO</code> is the basis for all input and output in Ruby. * An I/O stream may be <em>duplexed</em> (that is, bidirectional), and * so may use more than one native operating system stream. @@ -9152,6 +9785,10 @@ Init_IO(void) rb_define_global_const("STDOUT", rb_stdout); rb_define_global_const("STDERR", rb_stderr); + /* + * Hack to get rdoc to regard ARGF as a class: + * rb_cARGF = rb_define_class("ARGF", rb_cObject); + * */ rb_cARGF = rb_class_new(rb_cObject); rb_set_class_path(rb_cARGF, rb_cObject, "ARGF.class"); rb_define_alloc_func(rb_cARGF, argf_alloc); |