Top Level Namespace

Defined Under Namespace

Modules: Comparable, Enumerable, Errno, FileTest, GC, Kernel, Marshal, Math, ObjectSpace, Process, Signal, UnicodeNormalize, Warning Classes: ArgumentError, Array, BasicObject, Binding, Class, ClosedQueueError, Complex, Continuation, Data, Dir, ENV, EOFError, Encoding, EncodingError, Enumerator, Exception, FalseClass, Fiber, FiberError, File, Float, FloatDomainError, FrozenError, Hash, IO, IOError, IndexError, Integer, Interrupt, KeyError, LoadError, LocalJumpError, MatchData, Method, Module, NameError, NilClass, NoMatchingPatternError, NoMatchingPatternKeyError, NoMemoryError, NoMethodError, NotImplementedError, Numeric, Object, Proc, Ractor, Random, Range, RangeError, Rational, Refinement, Regexp, RegexpError, RubyVM, RuntimeError, ScriptError, SecurityError, SignalException, StandardError, StopIteration, String, Struct, Symbol, SyntaxError, SystemCallError, SystemExit, SystemStackError, Thread, ThreadError, ThreadGroup, Time, TracePoint, TrueClass, TypeError, UnboundMethod, UncaughtThrowError, ZeroDivisionError, fatal

Constant Summary collapse

STDIN =

Holds the original stdin

rb_stdin
STDOUT =

Holds the original stdout

rb_stdout
STDERR =

Holds the original stderr

rb_stderr
ARGF =

  • ARGV may be thought of as the argument vector array.

    Initially, it contains the command-line arguments and options that are passed to the Ruby program; the program can modify that array as it likes.

  • ARGF may be thought of as the argument files object.

    It can access file streams and/or the $stdin stream, based on what it finds in ARGV. This provides a convenient way for the command line to specify streams for a Ruby program to read.

Reading

ARGF may read from source streams, which at any particular time are determined by the content of ARGV.

Simplest Case

When the very first ARGF read occurs with an empty ARGV ([]), the source is $stdin:

  • File t.rb:

    p ['ARGV', ARGV]
p ['ARGF.read', ARGF.read]

  • Commands and outputs (see below for the content of files foo.txt and bar.txt):

    $ echo "Open the pod bay doors, Hal." | ruby t.rb
["ARGV", []]
["ARGF.read", "Open the pod bay doors, Hal.\n"]

$ cat foo.txt bar.txt | ruby t.rb
["ARGV", []]
["ARGF.read", "Foo 0\nFoo 1\nBar 0\nBar 1\nBar 2\nBar 3\n"]

About the Examples

Many examples here assume the existence of files foo.txt and bar.txt:

$ cat foo.txt
Foo 0
Foo 1
$ cat bar.txt
Bar 0
Bar 1
Bar 2
Bar 3

Sources in ARGV

For any ARGF read except the simplest case (that is, except for the very first ARGF read with an empty ARGV), the sources are found in ARGV.

ARGF assumes that each element in array ARGV is a potential source, and is one of:

  • The string path to a file that may be opened as a stream.

  • The character '-', meaning stream $stdin.

Each element that is not one of these should be removed from ARGV before ARGF accesses that source.

In the following example:

  • Filepaths foo.txt and bar.txt may be retained as potential sources.

  • Options --xyzzy and --mojo should be removed.

Example:

  • File t.rb:

    # Print arguments (and options, if any) found on command line.
p ['ARGV', ARGV]

  • Command and output:

    $ ruby t.rb --xyzzy --mojo foo.txt bar.txt
["ARGV", ["--xyzzy", "--mojo", "foo.txt", "bar.txt"]]

ARGF’s stream access considers the elements of ARGV, left to right:

  • File t.rb:

    p "ARGV: #{ARGV}"
p "Line: #{ARGF.read}" # Read everything from all specified streams.

  • Command and output:

    $ ruby t.rb foo.txt bar.txt
"ARGV: [\"foo.txt\", \"bar.txt\"]"
"Read: Foo 0\nFoo 1\nBar 0\nBar 1\nBar 2\nBar 3\n"

Because the value at ARGV is an ordinary array, you can manipulate it to control which sources ARGF considers:

  • If you remove an element from ARGV, ARGF will not consider the corresponding source.

  • If you add an element to ARGV, ARGF will consider the corresponding source.

Each element in ARGV is removed when its corresponding source is accessed; when all sources have been accessed, the array is empty:

  • File t.rb:

    until ARGV.empty? && ARGF.eof?
  p "ARGV: #{ARGV}"
  p "Line: #{ARGF.readline}" # Read each line from each specified stream.
end

  • Command and output:

    $ ruby t.rb foo.txt bar.txt
"ARGV: [\"foo.txt\", \"bar.txt\"]"
"Line: Foo 0\n"
"ARGV: [\"bar.txt\"]"
"Line: Foo 1\n"
"ARGV: [\"bar.txt\"]"
"Line: Bar 0\n"
"ARGV: []"
"Line: Bar 1\n"
"ARGV: []"
"Line: Bar 2\n"
"ARGV: []"
"Line: Bar 3\n"

Filepaths in ARGV

The ARGV array may contain filepaths the specify sources for ARGF reading.

This program prints what it reads from files at the paths specified on the command line:

  • File t.rb:

    p ['ARGV', ARGV]
# Read and print all content from the specified sources.
p ['ARGF.read', ARGF.read]

  • Command and output:

    $ ruby t.rb foo.txt bar.txt
["ARGV", [foo.txt, bar.txt]
["ARGF.read", "Foo 0\nFoo 1\nBar 0\nBar 1\nBar 2\nBar 3\n"]

Specifying $stdin in ARGV

To specify stream $stdin in ARGV, us the character '-':

  • File t.rb:

    p ['ARGV', ARGV]
p ['ARGF.read', ARGF.read]

  • Command and output:

    $ echo "Open the pod bay doors, Hal." | ruby t.rb -
["ARGV", ["-"]]
["ARGF.read", "Open the pod bay doors, Hal.\n"]

When no character '-' is given, stream $stdin is ignored (exception: see Specifying $stdin in ARGV):

  • Command and output:

    $ echo "Open the pod bay doors, Hal." | ruby t.rb foo.txt bar.txt
"ARGV: [\"foo.txt\", \"bar.txt\"]"
"Read: Foo 0\nFoo 1\nBar 0\nBar 1\nBar 2\nBar 3\n"

Mixtures and Repetitions in ARGV

For an ARGF reader, ARGV may contain any mixture of filepaths and character '-', including repetitions.

Modifications to ARGV

The running Ruby program may make any modifications to the ARGV array; the current value of ARGV affects ARGF reading.

Empty ARGV

For an empty ARGV, an ARGF read method either returns nil or raises an exception, depending on the specific method.

More Read Methods

As seen above, method ARGF#read reads the content of all sources into a single string. Other ARGF methods provide other ways to access that content; these include:

  • Byte access: #each_byte, #getbyte, #readbyte.

  • Character access: #each_char, #getc, #readchar.

  • Codepoint access: #each_codepoint.

  • Line access: #each_line, #gets, #readline, #readlines.

  • Source access: #read, #read_nonblock, #readpartial.

About Enumerable

ARGF includes module Enumerable. Virtually all methods in Enumerable call method #each in the including class.

Note well: In ARGF, method #each returns data from the sources, not from ARGV; therefore, for example, ARGF#entries returns an array of lines from the sources, not an array of the strings from ARGV:

  • File t.rb:

    p ['ARGV', ARGV]
p ['ARGF.entries', ARGF.entries]

  • Command and output:

    $ ruby t.rb foo.txt bar.txt
["ARGV", ["foo.txt", "bar.txt"]]
["ARGF.entries", ["Foo 0\n", "Foo 1\n", "Bar 0\n", "Bar 1\n", "Bar 2\n", "Bar 3\n"]]

Writing

If inplace mode is in effect, ARGF may write to target streams, which at any particular time are determined by the content of ARGV.

Methods about inplace mode:

  • #inplace_mode

  • #inplace_mode=

  • #to_write_io

Methods for writing:

  • #print

  • #printf

  • #putc

  • #puts

  • #write

== \ARGF and +ARGV+

The \ARGF object works with the array at global variable +ARGV+
to make <tt>$stdin</tt> and file streams available in the Ruby program
TOPLEVEL_BINDING =

The Binding of the top level scope

rb_binding_new()
DATA = 
file
ARGV =

ARGV contains the command line arguments used to run ruby.

A library like OptionParser can be used to process command-line arguments.

rb_argv
RUBY_VERSION =

MKSTR(version)

/* MKSTR(version) */ version
RUBY_RELEASE_DATE =

The date this ruby was released

MKSTR(release_date)
RUBY_PLATFORM =

The platform for this ruby

MKSTR(platform)
RUBY_PATCHLEVEL =

The patchlevel for this ruby. If this is a development build of ruby the patchlevel will be -1

MKINT(patchlevel)
RUBY_REVISION =

The GIT commit hash for this ruby.

MKSTR(revision)
MKSTR(copyright)
RUBY_ENGINE =

MKSTR(engine)

/* MKSTR(engine) */ ruby_engine_name
RUBY_ENGINE_VERSION =

MKSTR(version)

/* MKSTR(version) */ version
RUBY_DESCRIPTION =

MKSTR(description)

/* MKSTR(description) */ description