What is the ruby -a command line switch?

Question

From the man page:

 -a     Turns on auto-split mode when used with -n or -p.
        In auto-split mode, Ruby executes
              $F = $_.split
        at beginning of each loop.

Some questions come to mind:

• What happens when -a is used without -n or -p?
• What is $F?
• What happens at the end of the loop?
• How do I control which character is chosen to split on?
• How is -a intended to be used?

From another reference page:

$F      The variable that receives the output from split when -a is specified.
        This variable is set if the -a command-line option is specified
        along with the -p or -n option.

I'm still not sure what the -a switch is. Would appreciate an explanation but would appreciate some examples more.

Some things I've tried:

$ echo foo_bar_bar | ruby -ae
ruby: no code specified for -e (RuntimeError)
$ echo foo_bar_bar | ruby -ap
$ echo foo_bar_bar | ruby -ap '$_'
ruby: No such file or directory -- $_ (LoadError)

Answer 1

Auto-split mode is enabled with the -a switch. It enables the kind of text processing that awk does by default.
In auto-split mode, ruby will read files given as arguments or stdin one line at a time, and for each line:

1. automatically split the line, $_, into fields according to a field separator (designated by the -F flag)
2. assign the result to a variable named $F
3. do actions provided via the command-line.

After all lines are processed, the program exits or executes the END block. See this answer for an example.

Auto-split mode is useful for working with tabular text files that have many records (records are lines unless the record separator is changed) and a number of delimited fields in each line. For example, consider a file with content:

ADG:YUF:TGH
UIY:POG:YTH
GHJUR:HJKL:GHKIO

Then ruby -F: -a -n -e 'puts $F[2]' file prints the third field for each line:

$ ruby -F: -a -n -e 'puts $F[2]' file
TGH
YTH
GHKIO

In this case, -F: sets the field separator to :. $F is the array where the fields live after record ($_) is split. The actions after -e are executed for each line after it is split.

The ruby cli switches are very similar to those of perl. The perl cli makes this feature more convenient, see perldoc perlrun. For example, since -a is not useful without -n(or -p), in perl, -F enables -a implicitly, which in turn enables -n. This is not the case with ruby, all of the switches must be passed explicitly. For examples of nice things that can be done with this kind of processing look for awk one liners.

Also, the ruby cli follows unix conventions for passing command-line options:

Traditionally, UNIX command-line options consist of a dash, followed by one or more lowercase letters.

So the -a and -n switches and -e flag can be combined to achieve the same result:

$ ruby -F: -ane 'puts $F[2]' file
TGH
YTH
GHKIO

If this is interesting, check out some other ruby one liners.