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
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, #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"
Instance Attribute Summary
-
#inplace_mode ⇒ String
rw
Returns the file extension appended to the names 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
. -
#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.
-
#tell ⇒ Integer
readonly
Alias for #pos.
::Enumerable - Included
Instance Method Summary
-
#argv ⇒ ARGV
Returns the ARGV array, which contains the arguments passed to your script, one per element.
-
#bytes
This is a deprecated alias for #each_byte.
-
#chars
This is a deprecated alias for #each_char.
-
#close ⇒ ARGF
Closes the current file and skips to the next in the stream.
-
#codepoints
This is a deprecated alias for #each_codepoint.
-
#each(sep = $/) {|line| ... } ⇒ ARGF
(also: #each_line)
ARGF
.each_line(sep=$/) {|line| block } ->ARGF
. -
#bytes {|byte| ... } ⇒ ARGF
ARGF
.each_byte {|byte| block } ->ARGF
. -
#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 ⇒ Fixnum
Alias for #to_i.
-
#getbyte ⇒ Fixnum?
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 = $/) ⇒ 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. -
#lines(*args)
This is a deprecated alias for #each_line.
-
#path ⇒ String
(also: #filename)
Returns the current filename.
-
#print ⇒ nil
Alias for IO#print.
-
#printf(format_string [, obj, ...]) ⇒ nil
Alias for IO#printf.
-
#putc(obj) ⇒ Object
Alias for IO#putc.
-
#puts(obj, ...) ⇒ nil
Alias for IO#puts.
-
#read([length [, outbuf]]) ⇒ String, ...
Reads length bytes from
ARGF
. -
#read_nonblock(maxlen) ⇒ String
Reads at most maxlen bytes from the
ARGF
stream in non-blocking mode. -
#readbyte ⇒ Fixnum
Reads the next 8-bit byte from
ARGF
and returns it as a ::Fixnum. -
#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 = $/) ⇒ 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 the
ARGF
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 = $/) ⇒ Array
(also: #readlines)
ARGF
.to_a(sep=$/) -> array. -
#to_i ⇒ Fixnum
(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(string) ⇒ Integer
Writes string if inplace mode.
::Enumerable - Included
#chunk | Enumerates over the items, chunking them together based on the return value of the block. |
#chunk_while | Creates an enumerator for each chunked elements. |
#collect | Alias for Enumerable#map. |
#collect_concat | Alias for Enumerable#flat_map. |
#count | Returns the number of items in |
#cycle | Calls block for each element of enum repeatedly n times or forever if none or |
#detect | Alias for Enumerable#find. |
#drop | Drops first n elements from enum, and returns rest elements in an array. |
#drop_while | Drops elements up to, but not including, the first element for which the block returns |
#each_cons | Iterates the given block for each array of consecutive <n> elements. |
#each_entry | Calls block once for each element in |
#each_slice | Iterates the given block for each slice of <n> elements. |
#each_with_index | Calls block with two arguments, the item and its index, for each item in enum. |
#each_with_object | Iterates the given block for each element with an arbitrary object given, and returns the initially given object. |
#entries | Alias for Enumerable#to_a. |
#find | Passes each entry in enum to block. |
#find_all | Alias for Enumerable#select. |
#find_index | Compares each entry in enum with value or passes to block. |
#first | Returns the first element, or the first |
#flat_map | Returns a new array with the concatenated results of running block once for every element in enum. |
#grep | Returns an array of every element in enum for which |
#grep_v | Inverted version of Enumerable#grep. |
#group_by | Groups the collection by result of the block. |
#include? | Alias for Enumerable#member?. |
#inject | Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator. |
#lazy | Returns a lazy enumerator, whose methods map/collect, flat_map/collect_concat, select/find_all, reject, grep, grep_v, zip, take, take_while, drop, and drop_while enumerate values only on an as-needed basis. |
#map | Returns a new array with the results of running block once for every element in enum. |
#max | Returns the object in enum with the maximum value. |
#max_by | Returns the object in enum that gives the maximum value from the given block. |
#member? | Returns |
#min | Returns the object in enum with the minimum value. |
#min_by | Returns the object in enum that gives the minimum value from the given block. |
#minmax | Returns a two element array which contains the minimum and the maximum value in the enumerable. |
#minmax_by | Returns a two element array containing the objects in enum that correspond to the minimum and maximum values respectively from the given block. |
#partition | Returns two arrays, the first containing the elements of enum for which the block evaluates to true, the second containing the rest. |
#reduce | Alias for Enumerable#inject. |
#reject | Returns an array for all elements of |
#reverse_each | Builds a temporary array and traverses that array in reverse order. |
#select | Returns an array containing all elements of |
#slice_after | Creates an enumerator for each chunked elements. |
#slice_before | Creates an enumerator for each chunked elements. |
#slice_when | Creates an enumerator for each chunked elements. |
#sort | Returns an array containing the items in enum sorted, either according to their own |
#sort_by | Sorts enum using a set of keys generated by mapping the values in enum through the given block. |
#take | Returns first n elements from enum. |
#take_while | Passes elements to the block until the block returns |
#to_a | Returns an array containing the items in enum. |
#to_h | Returns the result of interpreting enum as a list of |
#zip | Takes one element from enum and merges corresponding elements from each args. |
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.
#binmode? ⇒ Boolean
(readonly)
#closed? ⇒ Boolean
(readonly)
Returns true if the current file has been closed; false otherwise. Use #close to actually close the current file.
#eof? ⇒ Boolean
(readonly)
#eof ⇒ Boolean
Also known as: #eof?
Boolean
(readonly)
#eof ⇒ Boolean
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
#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 modified files under in-place edit mode. This value can be set using #inplace_mode= or passing the -i
switch to the Ruby binary.
#inplace_mode=(ext) ⇒ ARGF
(rw)
Sets the filename extension for in-place editing mode to the given ::String. Each file being edited has this value appended to its filename. The modified file is saved under this new name.
For example:
$ ruby argf.rb file.txt
ARGF.inplace_mode = '.bak'
ARGF.each_line do |line|
print line.sub("foo","bar")
end
Each line of file.txt has the first occurrence of “foo” replaced with “bar”, then the new line is written out to file.txt.bak.
#lineno ⇒ Integer (rw)
#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
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
#pos=(position) ⇒ Integer (rw)
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"]
#bytes
This is a deprecated alias for #each_byte.
#chars
This is a deprecated alias for #each_char.
#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)
#codepoints
This is a deprecated alias for #each_codepoint.
#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 a ::Fixnum 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 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.each_line do |line|
puts ARGF.filename if ARGF.lineno == 1
puts "#{ARGF.lineno}: #{line}"
end
#bytes {|byte| ... } ⇒ ARGF
#bytes ⇒ Enumerator
ARGF
#bytes ⇒ Enumerator
ARGF
.each_byte {|byte| block } -> ARGF
ARGF.each_byte -> an_enumerator
Iterates over each byte of each file in ARGV. 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 #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]
#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.
#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.
#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, File object
Alias for #path.
Alias for #to_i.
#getbyte ⇒ Fixnum?
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 #=> 111
ARGF.getbyte #=> 10
ARGF.getbyte #=> nil
#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
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.
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.
#lines(*args)
This is a deprecated alias for #each_line.
Also known as: #filename
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"
#print ⇒ nil
#print(obj, ...) ⇒ nil
nil
#print(obj, ...) ⇒ nil
Alias for IO#print.
#printf(format_string [, obj, ...]) ⇒ nil
Alias for IO#printf.
#putc(obj) ⇒ Object
Alias for IO#putc.
#puts(obj, ...) ⇒ 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.
#read_nonblock(maxlen) ⇒ String
#read_nonblock(maxlen, outbuf) ⇒ outbuf
outbuf
Reads at most maxlen bytes from the ARGF
stream in non-blocking mode.
#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)
#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)
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.
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.
#rewind ⇒ 0
#seek(amount, whence = IO::SEEK_SET) ⇒ 0
#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.
#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"
Also known as: #readlines
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
#to_io ⇒ IO
#to_s ⇒ String Also known as: #inspect
Returns “ARGF”.
#to_write_io ⇒ IO
Returns IO instance tied to ARGF for writing if inplace mode is enabled.
#write(string) ⇒ Integer
Writes string if inplace mode.