Class: ARGF
Relationships & Source Files | |
Super Chains via Extension / Inclusion / Inheritance | |
Instance Chain:
self,
::Enumerable
|
|
Inherits: | Object |
Defined in: | io.c, io.c |
Overview
ARGF and ARGV
The ARGF object works with the array at global variable ARGV to make $stdin
and file streams available in the Ruby program:
-
ARGV may be thought of as the argument vector array.
Initially, it contains the command-line arguments and options that are passed to the Ruby program; the program can modify that array as it likes.
-
ARGF may be thought of as the argument files object.
It can access file streams and/or the
$stdin
stream, based on what it finds in ARGV. This provides a convenient way for the command line to specify streams for a Ruby program to read.
Reading
ARGF may read from source streams, which at any particular time are determined by the content of ARGV.
Simplest Case
When the very first ARGF read occurs with an empty ARGV ([]
), the source is $stdin
:
-
File
t.rb
:p ['ARGV', ARGV] p ['ARGF.read', ARGF.read]
-
Commands and outputs (see below for the content of files
foo.txt
andbar.txt
):$ echo "Open the pod bay doors, Hal." | ruby t.rb ["ARGV", []] ["ARGF.read", "Open the pod bay doors, Hal.\n"] $ cat foo.txt .txt | ruby t.rb ["ARGV", []] ["ARGF.read", "Foo 0\nFoo 1\nBar 0\nBar 1\nBar 2\nBar 3\n"]
About the Examples
Many examples here assume the existence of files foo.txt
and bar.txt
:
$ cat foo.txt
Foo 0
Foo 1
$ cat .txt
Bar 0
Bar 1
Bar 2
Bar 3
Sources in ARGV
For any ARGF read except the simplest case
(that is, except for the very first ARGF read with an empty ARGV), the sources are found in ARGV.
ARGF assumes that each element in array ARGV is a potential source, and is one of:
-
The string path to a file that may be opened as a stream.
-
The character
'-'
, meaning stream$stdin
.
Each element that is not one of these should be removed from ARGV before ARGF accesses that source.
In the following example:
-
Filepaths
foo.txt
andbar.txt
may be retained as potential sources. -
Options
--xyzzy
and--mojo
should be removed.
Example:
-
File
t.rb
:# Print arguments (and options, if any) found on command line. p ['ARGV', ARGV]
-
Command and output:
$ ruby t.rb --xyzzy --mojo foo.txt .txt ["ARGV", ["--xyzzy", "--mojo", "foo.txt", "bar.txt"]]
ARGF’s stream access considers the elements of ARGV, left to right:
-
File
t.rb
:p "ARGV: #{ARGV}" p "Line: #{ARGF.read}" # Read everything from all specified streams.
-
Command and output:
$ ruby t.rb foo.txt .txt "ARGV: [\"foo.txt\", \"bar.txt\"]" "Read: Foo 0\nFoo 1\nBar 0\nBar 1\nBar 2\nBar 3\n"
Because the value at ARGV is an ordinary array, you can manipulate it to control which sources ARGF considers:
-
If you remove an element from ARGV, ARGF will not consider the corresponding source.
-
If you add an element to ARGV, ARGF will consider the corresponding source.
Each element in ARGV is removed when its corresponding source is accessed; when all sources have been accessed, the array is empty:
-
File
t.rb
:until ARGV.empty? && ARGF.eof? p "ARGV: #{ARGV}" p "Line: #{ARGF.readline}" # Read each line from each specified stream. end
-
Command and output:
$ ruby t.rb foo.txt .txt "ARGV: [\"foo.txt\", \"bar.txt\"]" "Line: Foo 0\n" "ARGV: [\"bar.txt\"]" "Line: Foo 1\n" "ARGV: [\"bar.txt\"]" "Line: Bar 0\n" "ARGV: []" "Line: Bar 1\n" "ARGV: []" "Line: Bar 2\n" "ARGV: []" "Line: Bar 3\n"
Filepaths in ARGV
The ARGV array may contain filepaths the specify sources for ARGF reading.
This program prints what it reads from files at the paths specified on the command line:
-
File
t.rb
:p ['ARGV', ARGV] # Read and print all content from the specified sources. p ['ARGF.read', ARGF.read]
-
Command and output:
$ ruby t.rb foo.txt .txt ["ARGV", [foo.txt, .txt] ["ARGF.read", "Foo 0\nFoo 1\nBar 0\nBar 1\nBar 2\nBar 3\n"]
Specifying $stdin
in ARGV
To specify stream $stdin
in ARGV, us the character '-'
:
-
File
t.rb
:p ['ARGV', ARGV] p ['ARGF.read', ARGF.read]
-
Command and output:
$ echo "Open the pod bay doors, Hal." | ruby t.rb - ["ARGV", ["-"]] ["ARGF.read", "Open the pod bay doors, Hal.\n"]
When no character '-'
is given, stream $stdin
is ignored (exception: see Specifying $stdin in ARGV
):
-
Command and output:
$ echo "Open the pod bay doors, Hal." | ruby t.rb foo.txt .txt "ARGV: [\"foo.txt\", \"bar.txt\"]" "Read: Foo 0\nFoo 1\nBar 0\nBar 1\nBar 2\nBar 3\n"
Mixtures and Repetitions in ARGV
For an ARGF reader, ARGV may contain any mixture of filepaths and character '-'
, including repetitions.
Modifications to ARGV
The running Ruby program may make any modifications to the ARGV array; the current value of ARGV affects ARGF reading.
Empty ARGV
For an empty ARGV, an ARGF read method either returns nil
or raises an exception, depending on the specific method.
More Read Methods
As seen above, method #read reads the content of all sources into a single string. Other ARGF methods provide other ways to access that content; these include:
-
Byte access: #each_byte, #getbyte, #readbyte.
-
Character access: #each_char, #getc, #readchar.
-
Codepoint access: #each_codepoint.
-
Line access: #each_line, #gets, #readline, #readlines.
-
Source access: #read, #read_nonblock, #readpartial.
About Enumerable
ARGF includes module ::Enumerable
. Virtually all methods in Enumerable call method #each in the including class.
Note well: In ARGF, method #each returns data from the sources, not from ARGV; therefore, for example, ARGF#entries
returns an array of lines from the sources, not an array of the strings from ARGV:
-
File
t.rb
:p ['ARGV', ARGV] p ['ARGF.entries', ARGF.entries]
-
Command and output:
$ ruby t.rb foo.txt .txt ["ARGV", ["foo.txt", "bar.txt"]] ["ARGF.entries", ["Foo 0\n", "Foo 1\n", "Bar 0\n", "Bar 1\n", "Bar 2\n", "Bar 3\n"]]
Writing
If inplace mode is in effect, ARGF may write to target streams, which at any particular time are determined by the content of ARGV.
Methods about inplace mode:
Methods for writing:
Class Method Summary
- .new(argv) constructor Internal use only
Instance Attribute Summary
-
#binmode ⇒ ARGF
readonly
Puts ARGF into binary mode.
-
#binmode? ⇒ Boolean
readonly
Returns true if
ARGF
is being read in binary mode; false otherwise. -
#closed? ⇒ Boolean
readonly
Returns true if the current file has been closed; false otherwise.
-
#eof? ⇒ Boolean
(also: #eof?)
readonly
Returns true if the current file in
ARGF
is at end of file, i.e. it has no data to read. -
#eof? ⇒ Boolean
readonly
Alias for #eof.
-
#inplace_mode ⇒ String
rw
Returns the file extension appended to the names of backup copies of modified files under in-place edit mode.
-
#inplace_mode=(ext) ⇒ ARGF
rw
Sets the filename extension for in-place editing mode to the given
::String
. -
#lineno ⇒ Integer
rw
Returns the current line number of
ARGF
as a whole. -
#lineno=(integer) ⇒ Integer
rw
Sets the line number of
ARGF
as a whole to the given::Integer
. -
#pos ⇒ Integer
(also: #tell)
rw
Returns the current offset (in bytes) of the current file in
ARGF
. -
#pos=(position) ⇒ Integer
rw
Seeks to the position given by position (in bytes) in
ARGF
. -
#tell ⇒ Integer
readonly
Alias for #pos.
Instance Method Summary
-
#argv ⇒ ARGV
Returns the ARGV array, which contains the arguments passed to your script, one per element.
-
#close ⇒ ARGF
Closes the current file and skips to the next file in ARGV.
-
#each(sep = $/) {|line| ... } ⇒ ARGF
(also: #each_line)
ARGF
.each_line(sep=$/) {|line| block } ->ARGF
. -
#each_byte {|byte| ... } ⇒ ARGF
Iterates over each byte of each file in ARGV.
-
#each_char {|char| ... } ⇒ ARGF
Iterates over each character of each file in
ARGF
. -
#each_codepoint {|codepoint| ... } ⇒ ARGF
Iterates over each codepoint of each file in
ARGF
. -
#each(sep = $/) {|line| ... } ⇒ ARGF
Alias for #each.
-
#external_encoding ⇒ Encoding
Returns the external encoding for files read from
ARGF
as an::Encoding
object. - #file ⇒ IO, File object
-
#filename ⇒ String
Alias for #path.
-
#fileno ⇒ Integer
Alias for #to_i.
-
#getbyte ⇒ Integer?
Gets the next 8-bit byte (0..255) from
ARGF
. -
#getc ⇒ String?
Reads the next character from
ARGF
and returns it as a::String
. -
#gets(sep=$/ [, getline_args]) ⇒ String?
Returns the next line from the current file in
ARGF
. -
#inspect ⇒ String
Alias for #to_s.
-
#internal_encoding ⇒ Encoding
Returns the internal encoding for strings read from
ARGF
as an::Encoding
object. -
#path ⇒ String
(also: #filename)
Returns the current filename.
-
#print(*objects) ⇒ nil
Alias for IO#print.
-
#printf(format_string, *objects) ⇒ nil
Alias for IO#printf.
-
#putc(object) ⇒ Object
Alias for IO#putc.
-
#puts(*objects) ⇒ nil
Alias for IO#puts.
-
#read([length [, outbuf]]) ⇒ String, ...
Reads length bytes from
ARGF
. -
#read_nonblock(maxlen[, options]) ⇒ String
Reads at most maxlen bytes from the
ARGF
stream in non-blocking mode. -
#readbyte ⇒ Integer
Reads the next 8-bit byte from
ARGF
and returns it as an::Integer
. -
#readchar ⇒ String?
Reads the next character from
ARGF
and returns it as a::String
. -
#readline(sep = $/) ⇒ String
Returns the next line from the current file in
ARGF
. -
#readlines(sep = $/, chomp: false) ⇒ Array
Alias for #to_a.
-
#readpartial(maxlen) ⇒ String
Reads at most maxlen bytes from the
ARGF
stream. -
#rewind ⇒ 0
Positions the current file to the beginning of input, resetting #lineno to zero.
-
#seek(amount, whence = IO::SEEK_SET) ⇒ 0
Seeks to offset amount (an
::Integer
) in theARGF
stream according to the value of whence. -
#set_encoding(ext_enc) ⇒ ARGF
If single argument is specified, strings read from
ARGF
are tagged with the encoding specified. -
#skip ⇒ ARGF
Sets the current file to the next file in ARGV.
-
#readlines(sep = $/, chomp: false) ⇒ Array
(also: #readlines)
ARGF
.to_a(sep = $/, chomp: false) -> array. -
#to_i ⇒ Integer
(also: #fileno)
Returns an integer representing the numeric file descriptor for the current file.
-
#to_io ⇒ IO
Returns an
::IO
object representing the current file. -
#to_s ⇒ String
(also: #inspect)
Returns “ARGF”.
-
#to_write_io ⇒ IO
Returns IO instance tied to ARGF for writing if inplace mode is enabled.
-
#write(*objects) ⇒ Integer
Writes each of the given
objects
if inplace mode. - #initialize_copy(orig) Internal use only
::Enumerable
- Included
#all? | Returns whether every element meets a given criterion. |
#any? | Returns whether any element meets a given criterion. |
#chain | Returns an enumerator object generated from this enumerator and given enumerables. |
#chunk | Each element in the returned enumerator is a 2-element array consisting of: |
#chunk_while | Creates an enumerator for each chunked elements. |
#collect | Alias for Enumerable#map. |
#collect_concat | Alias for Enumerable#flat_map. |
#compact | Returns an array of all non- |
#count | Returns the count of elements, based on an argument or block criterion, if given. |
#cycle | When called with positive integer argument |
#detect | Alias for Enumerable#find. |
#drop | For positive integer |
#drop_while | Calls the block with successive elements as long as the block returns a truthy value; returns an array of all elements after that point: |
#each_cons | Calls the block with each successive overlapped |
#each_entry | Calls the given block with each element, converting multiple values from yield to an array; returns |
#each_slice | Calls the block with each successive disjoint |
#each_with_index | Invoke |
#each_with_object | Calls the block once for each element, passing both the element and the given object: |
#entries | Alias for Enumerable#to_a. |
#filter | Returns an array containing elements selected by the block. |
#filter_map | Returns an array containing truthy elements returned by the block. |
#find | Returns the first element for which the block returns a truthy value. |
#find_all | Alias for Enumerable#filter. |
#find_index | Returns the index of the first element that meets a specified criterion, or |
#first | Returns the first element or elements. |
#flat_map | Returns an array of flattened objects returned by the block. |
#grep | Returns an array of objects based elements of |
#grep_v | Returns an array of objects based on elements of |
#group_by | With a block given returns a hash: |
#include? | Alias for Enumerable#member?. |
#inject | Returns the result of applying a reducer to an initial value and the first element of the |
#lazy | Returns an |
#map | Returns an array of objects returned by the block. |
#max | Returns the element with the maximum element according to a given criterion. |
#max_by | Returns the elements for which the block returns the maximum values. |
#member? | Returns whether for any element |
#min | Returns the element with the minimum element according to a given criterion. |
#min_by | Returns the elements for which the block returns the minimum values. |
#minmax | Returns a 2-element array containing the minimum and maximum elements according to a given criterion. |
#minmax_by | Returns a 2-element array containing the elements for which the block returns minimum and maximum values: |
#none? | Returns whether no element meets a given criterion. |
#one? | Returns whether exactly one element meets a given criterion. |
#partition | With a block given, returns an array of two arrays: |
#reduce | Alias for Enumerable#inject. |
#reject | Returns an array of objects rejected by the block. |
#reverse_each | With a block given, calls the block with each element, but in reverse order; returns |
#select | Alias for Enumerable#filter. |
#slice_after | Creates an enumerator for each chunked elements. |
#slice_before | With argument |
#slice_when | Creates an enumerator for each chunked elements. |
#sort | Returns an array containing the sorted elements of |
#sort_by | With a block given, returns an array of elements of |
#sum | With no block given, returns the sum of |
#take | For non-negative integer |
#take_while | Calls the block with successive elements as long as the block returns a truthy value; returns an array of all elements up to that point: |
#tally | When argument |
#to_a | Returns an array containing the items in |
#to_h | When |
#to_set | Makes a set from the enumerable object with given arguments. |
#uniq | With no block, returns a new array containing only unique elements; the array has no two elements |
#zip | With no block given, returns a new array |
Constructor Details
.new(argv)
# File 'io.c', line 9967
static VALUE argf_initialize(VALUE argf, VALUE argv) { memset(&ARGF, 0, sizeof(ARGF)); argf_init(&ARGF, argv); return argf; }
Instance Attribute Details
#binmode ⇒ ARGF
(readonly)
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.
# File 'io.c', line 14380
static VALUE argf_binmode_m(VALUE argf) { ARGF.binmode = 1; next_argv(); ARGF_FORWARD(0, 0); rb_io_ascii8bit_binmode(ARGF.current_file); return argf; }
#binmode? ⇒ Boolean
(readonly)
# File 'io.c', line 14403
static VALUE argf_binmode_p(VALUE argf) { return RBOOL(ARGF.binmode); }
#closed? ⇒ Boolean
(readonly)
Returns true if the current file has been closed; false otherwise. Use #close to actually close the current file.
# File 'io.c', line 14469
static VALUE argf_closed(VALUE argf) { next_argv(); ARGF_FORWARD(0, 0); return rb_io_closed_p(ARGF.current_file); }
#eof? ⇒ Boolean
(readonly)
#eof ⇒ Boolean
Also known as: #eof?
Boolean
(readonly)
#eof ⇒ Boolean
# File 'io.c', line 13761
static VALUE argf_eof(VALUE argf) { next_argv(); if (RTEST(ARGF.current_file)) { if (ARGF.init_p == 0) return Qtrue; next_argv(); ARGF_FORWARD(0, 0); if (rb_io_eof(ARGF.current_file)) { return Qtrue; } } return Qfalse; }
#eof? ⇒ Boolean
(readonly)
#eof ⇒ Boolean
Boolean
(readonly)
#eof ⇒ Boolean
Alias for #eof.
#inplace_mode ⇒ String (rw)
Returns the file extension appended to the names of backup copies of modified files under in-place edit mode. This value can be set using #inplace_mode= or passing the -i
switch to the Ruby binary.
# File 'io.c', line 14497
static VALUE argf_inplace_mode_get(VALUE argf) { if (!ARGF.inplace) return Qnil; if (NIL_P(ARGF.inplace)) return rb_str_new(0, 0); return rb_str_dup(ARGF.inplace); }
#inplace_mode=(ext) ⇒ ARGF
(rw)
Sets the filename extension for in-place editing mode to the given ::String
. The backup copy of each file being edited has this value appended to its filename.
For example:
$ ruby argf.rb file.txt
ARGF.inplace_mode = '.bak'
ARGF.each_line do |line|
print line.sub("foo","bar")
end
First, file.txt.bak is created as a backup copy of file.txt. Then, each line of file.txt has the first occurrence of “foo” replaced with “bar”.
# File 'io.c', line 14532
static VALUE argf_inplace_mode_set(VALUE argf, VALUE val) { if (!RTEST(val)) { ARGF.inplace = Qfalse; } else if (StringValueCStr(val), !RSTRING_LEN(val)) { ARGF.inplace = Qnil; } else { ARGF.inplace = rb_str_new_frozen(val); } return argf; }
#lineno ⇒ Integer (rw)
# File 'io.c', line 10025
static VALUE argf_lineno(VALUE argf) { return INT2FIX(ARGF.lineno); }
#lineno=(integer) ⇒ Integer (rw)
Sets the line number of ARGF
as a whole 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 #lineno.
For example:
ARGF.lineno #=> 0
ARGF.readline #=> "This is line 1\n"
ARGF.lineno #=> 1
ARGF.lineno = 0 #=> 0
ARGF.lineno #=> 0
# File 'io.c', line 10004
static VALUE argf_set_lineno(VALUE argf, VALUE val) { ARGF.lineno = NUM2INT(val); ARGF.last_lineno = ARGF.lineno; return val; }
Also known as: #tell
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
# File 'io.c', line 13625
static VALUE argf_tell(VALUE argf) { if (!next_argv()) { rb_raise(rb_eArgError, "no stream to tell"); } ARGF_FORWARD(0, 0); return rb_io_tell(ARGF.current_file); }
#pos=(position) ⇒ Integer (rw)
# File 'io.c', line 13663
static VALUE argf_set_pos(VALUE argf, VALUE offset) { if (!next_argv()) { rb_raise(rb_eArgError, "no stream to set position"); } ARGF_FORWARD(1, &offset); return rb_io_set_pos(ARGF.current_file, offset); }
Alias for #pos.
Instance Method Details
#argv ⇒ ARGV
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"]
# File 'io.c', line 14573
static VALUE argf_argv(VALUE argf) { return ARGF.argv; }
#close ⇒ ARGF
# File 'io.c', line 14450
static VALUE argf_close_m(VALUE argf) { next_argv(); argf_close(argf); if (ARGF.next_p != -1) { ARGF.next_p = 1; } ARGF.lineno = 0; return argf; }
#each(sep = $/) {|line| ... } ⇒ ARGF
#each(sep = $/, limit) {|line| ... } ⇒ ARGF
#each(...) ⇒ Enumerator
Also known as: #each_line
ARGF
#each(sep = $/, limit) {|line| ... } ⇒ ARGF
#each(...) ⇒ Enumerator
ARGF
.each_line(sep=$/) {|line| block } -> ARGF
ARGF.each_line(sep=$/, limit) {|line| block } -> ARGF
ARGF.each_line(...) -> an_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, otherwise an enumerator is returned. The optional limit argument is an ::Integer
specifying the maximum 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 #filename and #lineno methods can be used to determine the filename of the current line and line number of the whole input, respectively.
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.each_line do |line|
puts ARGF.filename if ARGF.file.lineno == 1
puts "#{ARGF.file.lineno}: #{line}"
end
While the following code prints only the first file’s name at first, and the contents with line number counted through all named files.
ARGF.each_line do |line|
puts ARGF.filename if ARGF.lineno == 1
puts "#{ARGF.lineno}: #{line}"
end
# File 'io.c', line 14216
static VALUE argf_each_line(int argc, VALUE *argv, VALUE argf) { RETURN_ENUMERATOR(argf, argc, argv); FOREACH_ARGF() { argf_block_call_line(rb_intern("each_line"), argc, argv, argf); } return argf; }
#each_byte {|byte| ... } ⇒ ARGF
#each_byte ⇒ Enumerator
ARGF
#each_byte ⇒ Enumerator
Iterates over each byte of each file in ARGV. A byte is returned as an ::Integer
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 #filename method can be used to determine the filename of the current byte.
If no block is given, an enumerator is returned instead.
For example:
ARGF.bytes.to_a #=> [35, 32, ... 95, 10]
# File 'io.c', line 14247
static VALUE argf_each_byte(VALUE argf) { RETURN_ENUMERATOR(argf, 0, 0); FOREACH_ARGF() { argf_block_call(rb_intern("each_byte"), 0, 0, argf); } return argf; }
#each_char {|char| ... } ⇒ ARGF
#each_char ⇒ Enumerator
ARGF
#each_char ⇒ Enumerator
Iterates over each character of each file in ARGF
.
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 #filename method can be used to determine the name of the file in which the current character appears.
If no block is given, an enumerator is returned instead.
# File 'io.c', line 14273
static VALUE argf_each_char(VALUE argf) { RETURN_ENUMERATOR(argf, 0, 0); FOREACH_ARGF() { argf_block_call(rb_intern("each_char"), 0, 0, argf); } return argf; }
#each_codepoint {|codepoint| ... } ⇒ ARGF
#each_codepoint ⇒ Enumerator
ARGF
#each_codepoint ⇒ Enumerator
Iterates over each codepoint of each file in ARGF
.
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 codepoint of the first file has been returned, the first codepoint of the second file is returned. The #filename method can be used to determine the name of the file in which the current codepoint appears.
If no block is given, an enumerator is returned instead.
# File 'io.c', line 14299
static VALUE argf_each_codepoint(VALUE argf) { RETURN_ENUMERATOR(argf, 0, 0); FOREACH_ARGF() { argf_block_call(rb_intern("each_codepoint"), 0, 0, argf); } return argf; }
#each(sep = $/) {|line| ... } ⇒ ARGF
#each(sep = $/, limit) {|line| ... } ⇒ ARGF
#each(...) ⇒ Enumerator
ARGF
#each(sep = $/, limit) {|line| ... } ⇒ ARGF
#each(...) ⇒ Enumerator
Alias for #each.
#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 #internal_encoding, which is the encoding used to represent this text within Ruby.
To set the external encoding use #set_encoding.
For example:
ARGF.external_encoding #=> #<Encoding:UTF-8>
# File 'io.c', line 13543
static VALUE argf_external_encoding(VALUE argf) { return argf_encoding(argf, rb_io_external_encoding); }
#file ⇒ IO, File object
# File 'io.c', line 14362
static VALUE argf_file(VALUE argf) { next_argv(); return ARGF.current_file; }
Alias for #path.
Alias for #to_i.
#getbyte ⇒ Integer?
# File 'io.c', line 14043
static VALUE argf_getbyte(VALUE argf) { VALUE ch; retry: if (!next_argv()) return Qnil; if (!RB_TYPE_P(ARGF.current_file, T_FILE)) { ch = forward_current(rb_intern("getbyte"), 0, 0); } else { ch = rb_io_getbyte(ARGF.current_file); } if (NIL_P(ch) && ARGF.next_p != -1) { argf_close(argf); ARGF.next_p = 1; goto retry; } return ch; }
#getc ⇒ String?
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
# File 'io.c', line 14003
static VALUE argf_getc(VALUE argf) { VALUE ch; retry: if (!next_argv()) return Qnil; if (ARGF_GENERIC_INPUT_P()) { ch = forward_current(rb_intern("getc"), 0, 0); } else { ch = rb_io_getc(ARGF.current_file); } if (NIL_P(ch) && ARGF.next_p != -1) { argf_close(argf); ARGF.next_p = 1; goto retry; } return ch; }
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.
See IO.readlines for details about getline_args.
# File 'io.c', line 10354
static VALUE argf_gets(int argc, VALUE *argv, VALUE argf) { VALUE line; line = argf_getline(argc, argv, argf); rb_lastline_set(line); return line; }
#initialize_copy(orig)
# File 'io.c', line 9977
static VALUE argf_initialize_copy(VALUE argf, VALUE orig) { if (!OBJ_INIT_COPY(argf, orig)) return argf; ARGF = argf_of(orig); ARGF.argv = rb_obj_dup(ARGF.argv); return argf; }
Alias for #to_s.
#internal_encoding ⇒ Encoding
Returns the internal encoding for strings read from ARGF
as an ::Encoding
object.
If #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.
# File 'io.c', line 13562
static VALUE argf_internal_encoding(VALUE argf) { return argf_encoding(argf, rb_io_internal_encoding); }
Also known as: #filename
# File 'io.c', line 14331
static VALUE argf_filename(VALUE argf) { next_argv(); return ARGF.filename; }
#print(*objects) ⇒ nil
Alias for IO#print.
#printf(format_string, *objects) ⇒ nil
Alias for IO#printf.
#putc(object) ⇒ Object
Alias for IO#putc.
#puts(*objects) ⇒ nil
Alias for IO#puts.
#read([length [, outbuf]]) ⇒ String, ...
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 length is a positive integer, read
tries to read length bytes without any conversion (binary mode). It returns nil
if an EOF is encountered before anything can be read. Fewer than length bytes are returned if an EOF is encountered during the read. In the case of an integer length, the resulting string is always in ASCII-8BIT encoding.
If length is omitted or is nil
, it reads until EOF and the encoding conversion is applied, if applicable. A string is returned even if EOF is encountered before any data is read.
If length is zero, it returns an empty string (""
).
If the optional outbuf argument is present, it must reference a ::String
, which will receive the data. The outbuf will contain only the received data after the method call even if it is not empty at the beginning.
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 the fread() function in C. This means it retries to invoke read(2) system calls to read data with the specified length. If you need the behavior like a single read(2) system call, consider #readpartial or #read_nonblock.
# File 'io.c', line 13824
static VALUE argf_read(int argc, VALUE *argv, VALUE argf) { VALUE tmp, str, length; long len = 0; rb_scan_args(argc, argv, "02", &length, &str); if (!NIL_P(length)) { len = NUM2LONG(argv[0]); } if (!NIL_P(str)) { StringValue(str); rb_str_resize(str,0); argv[1] = Qnil; } retry: if (!next_argv()) { return str; } if (ARGF_GENERIC_INPUT_P()) { tmp = argf_forward(argc, argv, argf); } else { tmp = io_read(argc, argv, ARGF.current_file); } if (NIL_P(str)) str = tmp; else if (!NIL_P(tmp)) rb_str_append(str, tmp); if (NIL_P(tmp) || NIL_P(length)) { if (ARGF.next_p != -1) { argf_close(argf); ARGF.next_p = 1; goto retry; } } else if (argc >= 1) { long slen = RSTRING_LEN(str); if (slen < len) { argv[0] = LONG2NUM(len - slen); goto retry; } } return str; }
#read_nonblock(maxlen[, options]) ⇒ String
#read_nonblock(maxlen, outbuf[, options]) ⇒ outbuf
outbuf
Reads at most maxlen bytes from the ARGF
stream in non-blocking mode.
# File 'io.c', line 13920
static VALUE argf_read_nonblock(int argc, VALUE *argv, VALUE argf) { VALUE opts; rb_scan_args(argc, argv, "11:", NULL, NULL, &opts); if (!NIL_P(opts)) argc--; return argf_getpartial(argc, argv, argf, opts, 1); }
#readbyte ⇒ Integer
Reads the next 8-bit byte from ARGF
and returns it as an ::Integer
. 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)
# File 'io.c', line 14123
static VALUE argf_readbyte(VALUE argf) { VALUE c; NEXT_ARGF_FORWARD(0, 0); c = argf_getbyte(argf); if (NIL_P(c)) { rb_eof_error(); } return c; }
#readchar ⇒ String?
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)
# File 'io.c', line 14083
static VALUE argf_readchar(VALUE argf) { VALUE ch; retry: if (!next_argv()) rb_eof_error(); if (!RB_TYPE_P(ARGF.current_file, T_FILE)) { ch = forward_current(rb_intern("getc"), 0, 0); } else { ch = rb_io_getc(ARGF.current_file); } if (NIL_P(ch) && ARGF.next_p != -1) { argf_close(argf); ARGF.next_p = 1; goto retry; } return ch; }
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.
# File 'io.c', line 10437
static VALUE argf_readline(int argc, VALUE *argv, VALUE argf) { VALUE line; if (!next_argv()) rb_eof_error(); ARGF_FORWARD(argc, argv); line = argf_gets(argc, argv, argf); if (NIL_P(line)) { rb_eof_error(); } return line; }
Alias for #to_a.
#readpartial(maxlen) ⇒ String
#readpartial(maxlen, outbuf) ⇒ outbuf
outbuf
Reads at most maxlen bytes from the ARGF
stream.
If the optional outbuf argument is present, it must reference a ::String
, which will receive the data. The outbuf will contain only the received data after the method call even if it is not empty at the beginning.
It raises ::EOFError
on end of ARGF
stream. Since ARGF stream is a concatenation of multiple files, internally EOF is occur for each file. #readpartial
returns empty strings for EOFs except the last one and raises ::EOFError
for the last one.
# File 'io.c', line 13906
static VALUE argf_readpartial(int argc, VALUE *argv, VALUE argf) { return argf_getpartial(argc, argv, argf, Qnil, 0); }
#rewind ⇒ 0
# File 'io.c', line 13685
static VALUE argf_rewind(VALUE argf) { VALUE ret; int old_lineno; if (!next_argv()) { rb_raise(rb_eArgError, "no stream to rewind"); } ARGF_FORWARD(0, 0); old_lineno = RFILE(ARGF.current_file)->fptr->lineno; ret = rb_io_rewind(ARGF.current_file); if (!global_argf_p(argf)) { ARGF.last_lineno = ARGF.lineno -= old_lineno; } return ret; }
#seek(amount, whence = IO::SEEK_SET) ⇒ 0
# File 'io.c', line 13642
static VALUE argf_seek_m(int argc, VALUE *argv, VALUE argf) { if (!next_argv()) { rb_raise(rb_eArgError, "no stream to seek"); } ARGF_FORWARD(argc, argv); return rb_io_seek_m(argc, argv, ARGF.current_file); }
#set_encoding(ext_enc) ⇒ ARGF
#set_encoding("ext_enc:int_enc") ⇒ ARGF
#set_encoding(ext_enc, int_enc) ⇒ ARGF
#set_encoding("ext_enc:int_enc", opt) ⇒ ARGF
#set_encoding(ext_enc, int_enc, opt) ⇒ ARGF
ARGF
#set_encoding("ext_enc:int_enc") ⇒ ARGF
#set_encoding(ext_enc, int_enc) ⇒ ARGF
#set_encoding("ext_enc:int_enc", opt) ⇒ 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.
# File 'io.c', line 13599
static VALUE argf_set_encoding(int argc, VALUE *argv, VALUE argf) { rb_io_t *fptr; if (!next_argv()) { rb_raise(rb_eArgError, "no stream to set encoding"); } rb_io_set_encoding(argc, argv, ARGF.current_file); GetOpenFile(ARGF.current_file, fptr); ARGF.encs = fptr->encs; return argf; }
#skip ⇒ ARGF
# File 'io.c', line 14423
static VALUE argf_skip(VALUE argf) { if (ARGF.init_p && ARGF.next_p == 0) { argf_close(argf); ARGF.next_p = 1; } return argf; }
#readlines(sep = $/, chomp: false) ⇒ Array
#readlines(limit, chomp: false) ⇒ Array
#readlines(sep, limit, chomp: false) ⇒ Array
Also known as: #readlines
ARGF
.to_a(sep = $/, chomp: false) -> array
ARGF.to_a(limit, chomp: false) -> array
ARGF.to_a(sep, limit, chomp: false) -> array
Reads each file in ARGF
in its entirety, returning an ::Array
containing lines from the files. Lines are assumed to be separated by sep.
lines = ARGF.readlines
lines[0] #=> "This is line one\n"
See IO.readlines for a full description of all options.
# File 'io.c', line 10540
static VALUE argf_readlines(int argc, VALUE *argv, VALUE argf) { long lineno = ARGF.lineno; VALUE lines, ary; ary = rb_ary_new(); while (next_argv()) { if (ARGF_GENERIC_INPUT_P()) { lines = forward_current(rb_intern("readlines"), argc, argv); } else { lines = rb_io_readlines(argc, argv, ARGF.current_file); argf_close(argf); } ARGF.next_p = 1; rb_ary_concat(ary, lines); ARGF.lineno = lineno + RARRAY_LEN(ary); ARGF.last_lineno = ARGF.lineno; } ARGF.init_p = 0; return ary; }
Also known as: #fileno
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
# File 'io.c', line 13713
static VALUE argf_fileno(VALUE argf) { if (!next_argv()) { rb_raise(rb_eArgError, "no stream"); } ARGF_FORWARD(0, 0); return rb_io_fileno(ARGF.current_file); }
#to_io ⇒ IO
# File 'io.c', line 13735
static VALUE argf_to_io(VALUE argf) { next_argv(); ARGF_FORWARD(0, 0); return ARGF.current_file; }
#to_s ⇒ String Also known as: #inspect
Returns “ARGF”.
# File 'io.c', line 14483
static VALUE argf_to_s(VALUE argf) { return rb_str_new2("ARGF"); }
#to_write_io ⇒ IO
Returns IO instance tied to ARGF for writing if inplace mode is enabled.
# File 'io.c', line 14598
static VALUE argf_write_io(VALUE argf) { if (!RTEST(ARGF.current_file)) { rb_raise(rb_eIOError, "not opened for writing"); } return GetWriteIO(ARGF.current_file); }
#write(*objects) ⇒ Integer
Writes each of the given objects
if inplace mode.
# File 'io.c', line 14613
static VALUE argf_write(int argc, VALUE *argv, VALUE argf) { return rb_io_writev(argf_write_io(argf), argc, argv); }