Class: ARGF

Inherits:
Object show all
Includes:
Enumerable
Defined in:
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_after, #slice_before, #slice_when, #sort, #sort_by, #take, #take_while, #to_h, #zip

Constructor Details

#initializeObject

:nodoc:



7786
7787
7788
7789
7790
7791
7792
7793
# File 'io.c', line 7786

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


11820
11821
11822
11823
11824
# File 'io.c', line 11820

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.



11616
11617
11618
11619
11620
11621
11622
11623
11624
# File 'io.c', line 11616

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


11639
11640
11641
11642
11643
# File 'io.c', line 11639

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

#bytesObject

This is a deprecated alias for each_byte.



11458
11459
11460
11461
11462
11463
11464
11465
# File 'io.c', line 11458

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.



11497
11498
11499
11500
11501
11502
11503
11504
# File 'io.c', line 11497

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)


11687
11688
11689
11690
11691
11692
11693
11694
11695
11696
11697
# File 'io.c', line 11687

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.



11706
11707
11708
11709
11710
11711
11712
# File 'io.c', line 11706

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.



11536
11537
11538
11539
11540
11541
11542
11543
# File 'io.c', line 11536

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.each_line 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)


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

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)


11444
11445
11446
11447
11448
11449
11450
11451
11452
# File 'io.c', line 11444

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)


11483
11484
11485
11486
11487
11488
11489
11490
11491
# File 'io.c', line 11483

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)


11522
11523
11524
11525
11526
11527
11528
11529
11530
# File 'io.c', line 11522

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.each_line 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)


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

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


10993
10994
10995
10996
10997
10998
10999
11000
11001
11002
11003
11004
11005
11006
# File 'io.c', line 10993

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


10993
10994
10995
10996
10997
10998
10999
11000
11001
11002
11003
11004
11005
11006
# File 'io.c', line 10993

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>


10777
10778
10779
10780
10781
10782
10783
10784
# File 'io.c', line 10777

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>


11598
11599
11600
11601
11602
11603
# File 'io.c', line 11598

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"


11567
11568
11569
11570
11571
11572
# File 'io.c', line 11567

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


10945
10946
10947
10948
10949
10950
10951
10952
10953
# File 'io.c', line 10945

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


11252
11253
11254
11255
11256
11257
11258
11259
11260
11261
11262
11263
11264
11265
11266
11267
11268
11269
11270
11271
11272
# File 'io.c', line 11252

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


11212
11213
11214
11215
11216
11217
11218
11219
11220
11221
11222
11223
11224
11225
11226
11227
11228
11229
11230
11231
11232
# File 'io.c', line 11212

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.



8158
8159
8160
8161
8162
8163
8164
8165
8166
8167
# File 'io.c', line 8158

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:



7796
7797
7798
7799
7800
7801
7802
7803
7804
7805
7806
7807
7808
# File 'io.c', line 7796

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.



11734
11735
11736
11737
11738
11739
# File 'io.c', line 11734

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



11767
11768
11769
11770
11771
11772
11773
11774
11775
11776
11777
11778
11779
11780
11781
11782
11783
11784
# File 'io.c', line 11767

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.



10799
10800
10801
10802
10803
10804
10805
10806
# File 'io.c', line 10799

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


7849
7850
7851
7852
7853
# File 'io.c', line 7849

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


7828
7829
7830
7831
7832
7833
7834
# File 'io.c', line 7828

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.



11411
11412
11413
11414
11415
11416
11417
11418
# File 'io.c', line 11411

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"


11567
11568
11569
11570
11571
11572
# File 'io.c', line 11567

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


10865
10866
10867
10868
10869
10870
10871
10872
10873
# File 'io.c', line 10865

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"


10903
10904
10905
10906
10907
10908
10909
10910
10911
# File 'io.c', line 10903

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.


6912
6913
6914
6915
6916
6917
6918
6919
6920
6921
6922
6923
6924
6925
6926
6927
6928
6929
6930
6931
6932
6933
6934
6935
# File 'io.c', line 6912

VALUE
rb_io_print(int argc, const 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.



6853
6854
6855
6856
6857
6858
# File 'io.c', line 6853

VALUE
rb_io_printf(int argc, const 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


6985
6986
6987
6988
6989
6990
6991
6992
6993
6994
6995
6996
6997
6998
# File 'io.c', line 6985

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


7077
7078
7079
7080
7081
7082
7083
7084
7085
7086
7087
7088
7089
7090
7091
7092
7093
7094
7095
7096
7097
7098
7099
7100
7101
7102
7103
7104
7105
7106
# File 'io.c', line 7077

VALUE
rb_io_puts(int argc, const 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.



11047
11048
11049
11050
11051
11052
11053
11054
11055
11056
11057
11058
11059
11060
11061
11062
11063
11064
11065
11066
11067
11068
11069
11070
11071
11072
11073
11074
11075
11076
11077
11078
11079
11080
11081
11082
11083
11084
11085
11086
11087
11088
11089
11090
# File 'io.c', line 11047

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.



11142
11143
11144
11145
11146
# File 'io.c', line 11142

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)


11332
11333
11334
11335
11336
11337
11338
11339
11340
11341
11342
11343
# File 'io.c', line 11332

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)


11292
11293
11294
11295
11296
11297
11298
11299
11300
11301
11302
11303
11304
11305
11306
11307
11308
11309
11310
11311
11312
# File 'io.c', line 11292

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.



8233
8234
8235
8236
8237
8238
8239
8240
8241
8242
8243
8244
8245
8246
# File 'io.c', line 8233

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"


8285
8286
8287
8288
8289
8290
8291
8292
8293
8294
8295
8296
8297
8298
8299
8300
8301
8302
8303
8304
8305
8306
8307
# File 'io.c', line 8285

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.



11128
11129
11130
11131
11132
# File 'io.c', line 11128

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"


10925
10926
10927
10928
10929
10930
10931
10932
10933
# File 'io.c', line 10925

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.



10882
10883
10884
10885
10886
10887
10888
10889
10890
# File 'io.c', line 10882

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.


10839
10840
10841
10842
10843
10844
10845
10846
10847
10848
10849
10850
10851
# File 'io.c', line 10839

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"


11659
11660
11661
11662
11663
11664
11665
11666
11667
# File 'io.c', line 11659

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


10865
10866
10867
10868
10869
10870
10871
10872
10873
# File 'io.c', line 10865

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"


8285
8286
8287
8288
8289
8290
8291
8292
8293
8294
8295
8296
8297
8298
8299
8300
8301
8302
8303
8304
8305
8306
8307
# File 'io.c', line 8285

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


10945
10946
10947
10948
10949
10950
10951
10952
10953
# File 'io.c', line 10945

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


10967
10968
10969
10970
10971
10972
10973
# File 'io.c', line 10967

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



11720
11721
11722
11723
11724
# File 'io.c', line 11720

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.



11845
11846
11847
11848
11849
11850
11851
11852
# File 'io.c', line 11845

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.



11860
11861
11862
11863
11864
# File 'io.c', line 11860

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