Class: ARGF

Inherits:
Object show all
Includes:
Enumerable
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, 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"

Instance Method Summary collapse

Methods included from Enumerable

#all?, #any?, #chunk, #collect, #collect_concat, #count, #cycle, #detect, #drop, #drop_while, #each_cons, #each_entry, #each_slice, #each_with_index, #each_with_object, #entries, #find, #find_all, #find_index, #first, #flat_map, #grep, #group_by, #include?, #inject, #lazy, #map, #max, #max_by, #member?, #min, #min_by, #minmax, #minmax_by, #none?, #one?, #partition, #reduce, #reject, #reverse_each, #select, #slice_before, #sort, #sort_by, #take, #take_while, #to_h, #zip

Constructor Details

#initializeObject

:nodoc:



7607
7608
7609
7610
7611
7612
7613
7614
# File 'io.c', line 7607

static VALUE
argf_initialize(VALUE argf, VALUE argv)
{
    memset(&ARGF, 0, sizeof(ARGF));
    argf_init(&ARGF, argv);

    return argf;
}

Instance Method Details

#argvObject

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"]


11602
11603
11604
11605
11606
# File 'io.c', line 11602

static VALUE
argf_argv(VALUE argf)
{
    return ARGF.argv;
}

#binmodeObject

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.



11398
11399
11400
11401
11402
11403
11404
11405
11406
# File 'io.c', line 11398

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

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

Returns:

  • (Boolean)

Returns:

  • (Boolean)


11421
11422
11423
11424
11425
# File 'io.c', line 11421

static VALUE
argf_binmode_p(VALUE argf)
{
    return ARGF.binmode ? Qtrue : Qfalse;
}

#bytesObject

This is a deprecated alias for each_byte.



11240
11241
11242
11243
11244
11245
11246
11247
# File 'io.c', line 11240

static VALUE
argf_bytes(VALUE argf)
{
    rb_warn("ARGF#bytes is deprecated; use #each_byte instead");
    if (!rb_block_given_p())
	return rb_enumeratorize(argf, ID2SYM(rb_intern("each_byte")), 0, 0);
    return argf_each_byte(argf);
}

#charsObject

This is a deprecated alias for each_char.



11279
11280
11281
11282
11283
11284
11285
11286
# File 'io.c', line 11279

static VALUE
argf_chars(VALUE argf)
{
    rb_warn("ARGF#chars is deprecated; use #each_char instead");
    if (!rb_block_given_p())
	return rb_enumeratorize(argf, ID2SYM(rb_intern("each_char")), 0, 0);
    return argf_each_char(argf);
}

#closeObject

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)


11469
11470
11471
11472
11473
11474
11475
11476
11477
11478
11479
# File 'io.c', line 11469

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;
}

#closed?Boolean

Returns true if the current file has been closed; false otherwise. Use ARGF.close to actually close the current file.

Returns:

  • (Boolean)

Returns:

  • (Boolean)


11488
11489
11490
11491
11492
11493
11494
# File 'io.c', line 11488

static VALUE
argf_closed(VALUE argf)
{
    next_argv();
    ARGF_FORWARD(0, 0);
    return rb_io_closed(ARGF.current_file);
}

#codepointsObject

This is a deprecated alias for each_codepoint.



11318
11319
11320
11321
11322
11323
11324
11325
# File 'io.c', line 11318

static VALUE
argf_codepoints(VALUE argf)
{
    rb_warn("ARGF#codepoints is deprecated; use #each_codepoint instead");
    if (!rb_block_given_p())
	return rb_enumeratorize(argf, ID2SYM(rb_intern("each_codepoint")), 0, 0);
    return argf_each_codepoint(argf);
}

#each(sep = $/) {|line| ... } ⇒ Object #each(sep = $/, limit) {|line| ... } ⇒ Object #each(...) ⇒ Object

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 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

Overloads:

  • #each(sep = $/) {|line| ... } ⇒ Object

    Yields:

    • (line)
  • #each(sep = $/, limit) {|line| ... } ⇒ Object

    Yields:

    • (line)


11179
11180
11181
11182
11183
11184
11185
11186
11187
# File 'io.c', line 11179

static VALUE
argf_each_line(int argc, VALUE *argv, VALUE argf)
{
    RETURN_ENUMERATOR(argf, argc, argv);
    FOREACH_ARGF() {
	argf_block_call(rb_intern("each_line"), argc, argv, argf);
    }
    return argf;
}

#bytes {|byte| ... } ⇒ Object #bytesObject

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 ARGF.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]

Overloads:

  • #bytes {|byte| ... } ⇒ Object

    Yields:

    • (byte)


11226
11227
11228
11229
11230
11231
11232
11233
11234
# File 'io.c', line 11226

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| ... } ⇒ Object #each_charObject

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 ARGF.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.

Overloads:

  • #each_char {|char| ... } ⇒ Object

    Yields:

    • (char)


11265
11266
11267
11268
11269
11270
11271
11272
11273
# File 'io.c', line 11265

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| ... } ⇒ Object #each_codepointObject

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 ARGF.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.

Overloads:

  • #each_codepoint {|codepoint| ... } ⇒ Object

    Yields:

    • (codepoint)


11304
11305
11306
11307
11308
11309
11310
11311
11312
# File 'io.c', line 11304

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| ... } ⇒ Object #each(sep = $/, limit) {|line| ... } ⇒ Object #each(...) ⇒ Object

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 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

Overloads:

  • #each(sep = $/) {|line| ... } ⇒ Object

    Yields:

    • (line)
  • #each(sep = $/, limit) {|line| ... } ⇒ Object

    Yields:

    • (line)


11179
11180
11181
11182
11183
11184
11185
11186
11187
# File 'io.c', line 11179

static VALUE
argf_each_line(int argc, VALUE *argv, VALUE argf)
{
    RETURN_ENUMERATOR(argf, argc, argv);
    FOREACH_ARGF() {
	argf_block_call(rb_intern("each_line"), argc, argv, argf);
    }
    return argf;
}

#eof?Boolean #eofBoolean

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

Overloads:

  • #eof?Boolean

    Returns:

    • (Boolean)
  • #eofBoolean

    Returns:

    • (Boolean)


10775
10776
10777
10778
10779
10780
10781
10782
10783
10784
10785
10786
10787
10788
# File 'io.c', line 10775

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 #eofBoolean

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

Overloads:

  • #eof?Boolean

    Returns:

    • (Boolean)
  • #eofBoolean

    Returns:

    • (Boolean)

Returns:

  • (Boolean)


10775
10776
10777
10778
10779
10780
10781
10782
10783
10784
10785
10786
10787
10788
# File 'io.c', line 10775

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;
}

#external_encodingEncoding

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>

Returns:



10559
10560
10561
10562
10563
10564
10565
10566
# File 'io.c', line 10559

static VALUE
argf_external_encoding(VALUE argf)
{
    if (!RTEST(ARGF.current_file)) {
	return rb_enc_from_encoding(rb_default_external_encoding());
    }
    return rb_io_external_encoding(rb_io_check_io(ARGF.current_file));
}

#fileFile 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>

Returns:



11380
11381
11382
11383
11384
11385
# File 'io.c', line 11380

static VALUE
argf_file(VALUE argf)
{
    next_argv();
    return ARGF.current_file;
}

#filenameString #pathString

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"

Overloads:



11349
11350
11351
11352
11353
11354
# File 'io.c', line 11349

static VALUE
argf_filename(VALUE argf)
{
    next_argv();
    return ARGF.filename;
}

#filenoFixnum #to_iFixnum

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

Overloads:



10727
10728
10729
10730
10731
10732
10733
10734
10735
# File 'io.c', line 10727

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);
}

#getbyteFixnum?

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

Returns:



11034
11035
11036
11037
11038
11039
11040
11041
11042
11043
11044
11045
11046
11047
11048
11049
11050
11051
11052
11053
11054
# File 'io.c', line 11034

static VALUE
argf_getbyte(VALUE argf)
{
    VALUE ch;

  retry:
    if (!next_argv()) return Qnil;
    if (!RB_TYPE_P(ARGF.current_file, T_FILE)) {
	ch = rb_funcall3(ARGF.current_file, 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;
}

#getcString?

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:



10994
10995
10996
10997
10998
10999
11000
11001
11002
11003
11004
11005
11006
11007
11008
11009
11010
11011
11012
11013
11014
# File 'io.c', line 10994

static VALUE
argf_getc(VALUE argf)
{
    VALUE ch;

  retry:
    if (!next_argv()) return Qnil;
    if (ARGF_GENERIC_INPUT_P()) {
	ch = rb_funcall3(ARGF.current_file, 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;
}

#gets(sep = $/) ⇒ String? #gets(limit) ⇒ String? #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.

Overloads:



7977
7978
7979
7980
7981
7982
7983
7984
7985
7986
# File 'io.c', line 7977

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_copyObject

:nodoc:



7617
7618
7619
7620
7621
7622
7623
7624
7625
7626
7627
7628
7629
# File 'io.c', line 7617

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);
    if (ARGF.inplace) {
	const char *inplace = ARGF.inplace;
	ARGF.inplace = 0;
	ARGF.inplace = ruby_strdup(inplace);
    }
    return argf;
}

#inplace_modeString

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.

Returns:



11516
11517
11518
11519
11520
11521
# File 'io.c', line 11516

static VALUE
argf_inplace_mode_get(VALUE argf)
{
    if (!ARGF.inplace) return Qnil;
    return rb_str_new2(ARGF.inplace);
}

#inplace_mode=(ext) ⇒ Object

Sets the filename extension for inplace 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.lines 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.



11549
11550
11551
11552
11553
11554
11555
11556
11557
11558
11559
11560
11561
11562
11563
11564
11565
11566
# File 'io.c', line 11549

static VALUE
argf_inplace_mode_set(VALUE argf, VALUE val)
{
    if (rb_safe_level() >= 1 && OBJ_TAINTED(val))
	rb_insecure_operation();

    if (!RTEST(val)) {
	if (ARGF.inplace) free(ARGF.inplace);
	ARGF.inplace = 0;
    }
    else {
	StringValue(val);
	if (ARGF.inplace) free(ARGF.inplace);
	ARGF.inplace = 0;
	ARGF.inplace = strdup(RSTRING_PTR(val));
    }
    return argf;
}

#internal_encodingEncoding

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.

Returns:



10581
10582
10583
10584
10585
10586
10587
10588
# File 'io.c', line 10581

static VALUE
argf_internal_encoding(VALUE argf)
{
    if (!RTEST(ARGF.current_file)) {
	return rb_enc_from_encoding(rb_default_external_encoding());
    }
    return rb_io_internal_encoding(rb_io_check_io(ARGF.current_file));
}

#linenoInteger

Returns the current line number of ARGF as a whole. This value can be set manually with ARGF.lineno=.

For example:

ARGF.lineno   #=> 0
ARGF.readline #=> "This is line 1\n"
ARGF.lineno   #=> 1

Returns:



7670
7671
7672
7673
7674
# File 'io.c', line 7670

static VALUE
argf_lineno(VALUE argf)
{
    return INT2FIX(ARGF.lineno);
}

#lineno=(integer) ⇒ Integer

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 ARGF.lineno.

For example:

ARGF.lineno      #=> 0
ARGF.readline    #=> "This is line 1\n"
ARGF.lineno      #=> 1
ARGF.lineno = 0  #=> 0
ARGF.lineno      #=> 0

Returns:



7649
7650
7651
7652
7653
7654
7655
# File 'io.c', line 7649

static VALUE
argf_set_lineno(VALUE argf, VALUE val)
{
    ARGF.lineno = NUM2INT(val);
    ARGF.last_lineno = ARGF.lineno;
    return Qnil;
}

#linesObject

This is a deprecated alias for each_line.



11193
11194
11195
11196
11197
11198
11199
11200
# File 'io.c', line 11193

static VALUE
argf_lines(int argc, VALUE *argv, VALUE argf)
{
    rb_warn("ARGF#lines is deprecated; use #each_line instead");
    if (!rb_block_given_p())
	return rb_enumeratorize(argf, ID2SYM(rb_intern("each_line")), argc, argv);
    return argf_each_line(argc, argv, argf);
}

#filenameString #pathString

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"

Overloads:



11349
11350
11351
11352
11353
11354
# File 'io.c', line 11349

static VALUE
argf_filename(VALUE argf)
{
    next_argv();
    return ARGF.filename;
}

#tellInteger #posInteger

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

Overloads:



10647
10648
10649
10650
10651
10652
10653
10654
10655
# File 'io.c', line 10647

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

Seeks to the position given by position (in bytes) in ARGF.

For example:

ARGF.pos = 17
ARGF.gets   #=> "This is line two\n"

Returns:



10685
10686
10687
10688
10689
10690
10691
10692
10693
# File 'io.c', line 10685

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);
}

Writes the given object(s) to ios. The stream must be opened for writing. If the output field separator ($,) is not nil, it will be inserted between each object. If the output record separator ($\</code>) is not <code>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. With no argument, prints the contents of the variable $_. Returns nil.

$stdout.print("This is ", 100, " percent.\n")

produces:

This is 100 percent.

Overloads:

  • #printnil

    Returns:

    • (nil)
  • #print(obj, ...) ⇒ nil

    Returns:

    • (nil)


6792
6793
6794
6795
6796
6797
6798
6799
6800
6801
6802
6803
6804
6805
6806
6807
6808
6809
6810
6811
6812
6813
6814
6815
# File 'io.c', line 6792

VALUE
rb_io_print(int argc, VALUE *argv, VALUE out)
{
    int i;
    VALUE line;

    /* if no argument given, print `$_' */
    if (argc == 0) {
	argc = 1;
	line = rb_lastline_get();
	argv = &line;
    }
    for (i=0; i<argc; i++) {
	if (!NIL_P(rb_output_fs) && i>0) {
	    rb_io_write(out, rb_output_fs);
	}
	rb_io_write(out, argv[i]);
    }
    if (argc > 0 && !NIL_P(rb_output_rs)) {
	rb_io_write(out, rb_output_rs);
    }

    return Qnil;
}

#printf(format_string[, obj, ...]) ⇒ nil

Formats and writes to ios, converting parameters under control of the format string. See Kernel#sprintf for details.

Returns:

  • (nil)


6733
6734
6735
6736
6737
6738
# File 'io.c', line 6733

VALUE
rb_io_printf(int argc, VALUE *argv, VALUE out)
{
    rb_io_write(out, rb_f_sprintf(argc, argv));
    return Qnil;
}

#putc(obj) ⇒ Object

If obj is Numeric, write the character whose code is the least-significant byte of obj, otherwise write the first byte of the string representation of obj to ios. Note: This method is not safe for use with multi-byte characters as it will truncate them.

$stdout.putc "A"
$stdout.putc 65

produces:

AA

Returns:



6865
6866
6867
6868
6869
6870
6871
6872
6873
6874
6875
6876
6877
6878
# File 'io.c', line 6865

static VALUE
rb_io_putc(VALUE io, VALUE ch)
{
    VALUE str;
    if (RB_TYPE_P(ch, T_STRING)) {
	str = rb_str_substr(ch, 0, 1);
    }
    else {
	char c = NUM2CHR(ch);
	str = rb_str_new(&c, 1);
    }
    rb_io_write(io, str);
    return ch;
}

#puts(obj, ...) ⇒ nil

Writes the given objects to ios as with IO#print. Writes a record separator (typically a newline) after any that do not already end with a newline sequence. If called with an array argument, writes each element on a new line. If called without arguments, outputs a single record separator.

$stdout.puts("this", "is", "a", "test")

produces:

this
is
a
test

Returns:

  • (nil)


6957
6958
6959
6960
6961
6962
6963
6964
6965
6966
6967
6968
6969
6970
6971
6972
6973
6974
6975
6976
6977
6978
6979
6980
6981
6982
6983
6984
6985
6986
# File 'io.c', line 6957

VALUE
rb_io_puts(int argc, VALUE *argv, VALUE out)
{
    int i;
    VALUE line;

    /* if no argument given, print newline. */
    if (argc == 0) {
	rb_io_write(out, rb_default_rs);
	return Qnil;
    }
    for (i=0; i<argc; i++) {
	if (RB_TYPE_P(argv[i], T_STRING)) {
	    line = argv[i];
	    goto string;
	}
	if (rb_exec_recursive(io_puts_ary, argv[i], out)) {
	    continue;
	}
	line = rb_obj_as_string(argv[i]);
      string:
	rb_io_write(out, line);
	if (RSTRING_LEN(line) == 0 ||
            !str_end_with_asciichar(line, '\n')) {
	    rb_io_write(out, rb_default_rs);
	}
    }

    return Qnil;
}

#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 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 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 fread() function in C. If you need the behavior like read(2) system call, consider ARGF.readpartial.

Returns:



10829
10830
10831
10832
10833
10834
10835
10836
10837
10838
10839
10840
10841
10842
10843
10844
10845
10846
10847
10848
10849
10850
10851
10852
10853
10854
10855
10856
10857
10858
10859
10860
10861
10862
10863
10864
10865
10866
10867
10868
10869
10870
10871
10872
# File 'io.c', line 10829

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) {
	if (RSTRING_LEN(str) < len) {
	    len -= RSTRING_LEN(str);
	    argv[0] = INT2NUM(len);
	    goto retry;
	}
    }
    return str;
}

#read_nonblock(maxlen) ⇒ String #read_nonblock(maxlen, outbuf) ⇒ Object

Reads at most maxlen bytes from the ARGF stream in non-blocking mode.

Overloads:



10924
10925
10926
10927
10928
# File 'io.c', line 10924

static VALUE
argf_read_nonblock(int argc, VALUE *argv, VALUE argf)
{
    return argf_getpartial(argc, argv, argf, 1);
}

#readbyteFixnum

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)

Returns:



11114
11115
11116
11117
11118
11119
11120
11121
11122
11123
11124
11125
# File 'io.c', line 11114

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;
}

#readcharString?

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:



11074
11075
11076
11077
11078
11079
11080
11081
11082
11083
11084
11085
11086
11087
11088
11089
11090
11091
11092
11093
11094
# File 'io.c', line 11074

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 = rb_funcall3(ARGF.current_file, 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;
}

#readline(sep = $/) ⇒ String #readline(limit) ⇒ String #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.

Overloads:



8052
8053
8054
8055
8056
8057
8058
8059
8060
8061
8062
8063
8064
8065
# File 'io.c', line 8052

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;
}

#readlines(sep = $/) ⇒ Array #readlines(limit) ⇒ Array #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"

Overloads:



8104
8105
8106
8107
8108
8109
8110
8111
8112
8113
8114
8115
8116
8117
8118
8119
8120
8121
8122
8123
8124
8125
8126
# File 'io.c', line 8104

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 = rb_funcall3(ARGF.current_file, 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;
}

#readpartial(maxlen) ⇒ String #readpartial(maxlen, outbuf) ⇒ Object

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. ARGF.readpartial returns empty strings for EOFs except the last one and raises EOFError for the last one.

Overloads:



10910
10911
10912
10913
10914
# File 'io.c', line 10910

static VALUE
argf_readpartial(int argc, VALUE *argv, VALUE argf)
{
    return argf_getpartial(argc, argv, argf, 0);
}

#rewind0

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"

Returns:

  • (0)


10707
10708
10709
10710
10711
10712
10713
10714
10715
# File 'io.c', line 10707

static VALUE
argf_rewind(VALUE argf)
{
    if (!next_argv()) {
	rb_raise(rb_eArgError, "no stream to rewind");
    }
    ARGF_FORWARD(0, 0);
    return rb_io_rewind(ARGF.current_file);
}

#seek(amount, whence = IO::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.

Returns:

  • (0)


10664
10665
10666
10667
10668
10669
10670
10671
10672
# File 'io.c', line 10664

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) ⇒ Object #set_encoding("ext_enc:int_enc") ⇒ Object #set_encoding(ext_enc, int_enc) ⇒ Object #set_encoding("ext_enc:int_enc", opt) ⇒ Object #set_encoding(ext_enc, int_enc, opt) ⇒ Object

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.


10621
10622
10623
10624
10625
10626
10627
10628
10629
10630
10631
10632
10633
# File 'io.c', line 10621

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;
}

#skipObject

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"


11441
11442
11443
11444
11445
11446
11447
11448
11449
# File 'io.c', line 11441

static VALUE
argf_skip(VALUE argf)
{
    if (ARGF.init_p && ARGF.next_p == 0) {
	argf_close(argf);
	ARGF.next_p = 1;
    }
    return argf;
}

#tellInteger #posInteger

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

Overloads:



10647
10648
10649
10650
10651
10652
10653
10654
10655
# File 'io.c', line 10647

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);
}

#readlines(sep = $/) ⇒ Array #readlines(limit) ⇒ Array #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"

Overloads:



8104
8105
8106
8107
8108
8109
8110
8111
8112
8113
8114
8115
8116
8117
8118
8119
8120
8121
8122
8123
8124
8125
8126
# File 'io.c', line 8104

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 = rb_funcall3(ARGF.current_file, 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;
}

#filenoFixnum #to_iFixnum

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

Overloads:



10727
10728
10729
10730
10731
10732
10733
10734
10735
# File 'io.c', line 10727

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_ioObject

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>>


10749
10750
10751
10752
10753
10754
10755
# File 'io.c', line 10749

static VALUE
argf_to_io(VALUE argf)
{
    next_argv();
    ARGF_FORWARD(0, 0);
    return ARGF.current_file;
}

#to_sString Also known as: inspect

Returns “ARGF”.

Returns:



11502
11503
11504
11505
11506
# File 'io.c', line 11502

static VALUE
argf_to_s(VALUE argf)
{
    return rb_str_new2("ARGF");
}

#to_write_ioIO

Returns IO instance tied to ARGF for writing if inplace mode is enabled.

Returns:



11627
11628
11629
11630
11631
11632
11633
11634
# File 'io.c', line 11627

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(string) ⇒ Integer

Writes string if inplace mode.

Returns:



11642
11643
11644
11645
11646
# File 'io.c', line 11642

static VALUE
argf_write(VALUE argf, VALUE str)
{
    return rb_io_write(argf_write_io(argf), str);
}