<ppdoc>
<copyright>
    Copyright (c) 2001 by Addison Wesley Longman.  This
    material may be distributed only subject to the terms and
    conditions set forth in the Open Publication License, v1.0 or
    later (the latest version is presently available at
    http://www.opencontent.org/openpub/).
</copyright>
<chapter name="Ruby and Its World">
<p/>
It's an unfortunate fact of life that our applications have to deal
with the big, bad world.  In this chapter, we'll look at how Ruby
interacts with its environment.  Microsoft Windows users will probably
also want to look at platform-specific information beginning
on page 165.
<section>Command-Line Arguments</section>
<p/>
``In the Beginning was the Command Line.''<footnote>Title of a
  marvelous essay by Neal Stephenson  
  (available online at 
  <url>http://www.spack.org/essays/commandline.html</url>).</footnote>
Regardless of the system in which Ruby is deployed, whether it be a
super high-end scientific graphics workstation or an embedded PDA
device, you've got to start the Ruby interpreter somehow, and that
gives us the opportunity to pass in command-line arguments.
<p/>
A Ruby command line consists of three parts: options to the Ruby
interpreter, optionally the name of a program to run, and optionally a 
set of arguments for that program.
<p/>
<syntax>
ruby <opt><nt>options</nt></opt> <opt>--</opt> <opt><nt>programfile</nt></opt> <opt><nt>arguments</nt></opt>
</syntax>
<p/>
The Ruby options are terminated by the first word on the command line
that doesn't start with a hyphen, or by the special flag ``<tt>--</tt>''
(two hyphens).
<p/>
If no filename is present on the command line, or if the filename is
a single hyphen (<tt>-</tt>), Ruby reads the program source from standard
input.
<p/>
Arguments for the program itself follow the program name. For example:
<p/>
<alltt>
<tt>%<nbsp/>ruby -w - "Hello World"</tt>
</alltt>
<p/>
will enable warnings, read a program from standard input, and pass it
the quoted string <tt>"Hello World"</tt> as an argument.
<subsection>Command-Line Options</subsection>
<p/>
<dl>
    <dt>-0[<em>octal</em>}</dt><dd/>' 
  The number ``0'' flag specifies the record  
  separator character (\0, if no digit follows).  <tt>-00</tt> indicates
  paragraph mode: records are separated by two successive default
  record separator characters. <tt>-0777</tt> reads the entire file at once (as it
  is an illegal character). Sets <var>$/</var>.
<p/>
  <dt>-a</dt><dd/>'
  Auto split mode when used with <tt>-n</tt> or <tt>-p</tt>;  
  equivalent to executing
  <tt></tt>{$F at the top of each loop iteration.    
<p/>
  <dt>-C <em>directory</em></dt><dd/>'
  Changes working directory to <em>directory</em> before executing.
<p/>
  <dt>-c</dt><dd/>'
  Checks syntax only; does not execute the program.
<p/>
  <dt><cmdopt>--copyright</cmdopt></dt><dd/>      
  Prints the copyright notice and exits.
<p/>
  <dt>-d, --debug</dt><dd/>'
  Sets  <var>$DEBUG</var> to true.  
  This can be used by your programs to
  enable additional tracing.
<p/>
  <dt>-e '<em>command</em>'</dt><dd/>'
  Executes <em>command</em> as one line of Ruby source. Several <tt>-e</tt>'s
  are allowed, and the commands are treated as multiple lines in the
  same program. If <em>programfile</em> is omitted when <tt>-e</tt> is
  present, execution stops after the <tt>-e</tt> commands have been run.
<p/>
  <dt>-F <em>pattern</em></dt><dd/>'
  Specifies the input field separator (<var>$;</var>) used as the default for
  <tt>split()</tt> (affects <tt>-a</tt>).
<p/>
  <dt>-h, --help</dt><dd/>'
  Displays a short help screen.
<p/>
  <dt>-I <em>directories</em></dt><dd/>'
  Specifies directories to be prepended to <var>$LOAD_PATH</var>  
  (<var>$:</var>). Multiple <tt>-I</tt> options may be present, and
  multiple directories may appear following each <tt>-I</tt>. Directories
  are separated by a ``:'' on Unix-like systems and by a ``;'' on
  DOS/Windows systems.
<p/>
  <dt>-i [<em>extension</em>}</dt><dd/>'
  Edits <tt>ARGV</tt> files in place.    
  For each
  file named in <var>ARGV</var>, anything you write to standard output will
  be saved back as the contents of that file.
  A backup copy of the file will be made if
  <em>extension</em> is supplied.
<alltt>
<tt>%<nbsp/>ruby -pi.bak -e "gsub(/Perl/, 'Ruby')" *.txt</tt>
</alltt>
<p/>
  <dt>-K <em>kcode</em></dt><dd/>'
  Specifies the code set to be used. This  
  option is useful mainly when Ruby is used for Japanese-language
  processing. <em>kcode</em> may be one of: e, E for EUC; s, S for SJIS;
  u, U for UTF-8; or a, A, n, N for ASCII.
<p/>
  <dt>-l</dt><dd/>'
  Enables automatic line-ending processing;
  sets <var>$\</var> to the value of <var>$/</var> and chops every input line
  automatically.
<p/>
  <dt>-n</dt><dd/>'
  Assumes ``<tt>while gets; ...; end</tt>'' loop around your program.
  For example, a simple <tt>grep</tt> command might be implemented as:
<alltt>
<tt>%<nbsp/>ruby -n -e "print if /wombat/"  *.txt</tt>
</alltt>
<p/>
  <dt>-p</dt><dd/>'
  Places your program code within the loop
  ``<tt>while gets; ...; print; end</tt>.''
<alltt>
<tt>%<nbsp/>ruby -p -e "$_.downcase!" *.txt</tt>
</alltt>
  <dt>-r <em>library</em></dt><dd/>'
  <tt>require</tt>s the named library before executing.
<p/>
  <dt>-S</dt><dd/>'
  Looks for the program file using <tt>RUBYPATH</tt>
  or <tt>PATH</tt> environment
  variable.
<p/>
  <dt>-s</dt><dd/>' Any command line switches found after the program filename, but
  before any filename arguments or before a <tt>--</tt>, are removed
  from <var>ARGV</var> and set to a global variable named for the switch. In
  the following example, the effect of this would be to set the variable
  <var>$opt</var> to ``<tt>electric</tt>''.
<p/>
<alltt>
<tt>%<nbsp/>ruby -s prog -opt=electric ./mydata</tt>
</alltt>
<p/>
  <dt>-T[<em>level</em>}</dt><dd/>'
  Sets the safe level, which among other things enables tainting
  checks
  (see page 257). Sets <var>$SAFE</var>.  
<p/>
  <dt>-v, --verbose</dt><dd/>'
  Enables verbose mode and print the version number.
  In verbose mode, compilation warnings are
  printed. If no program filename appears on the command line, Ruby exits.
<p/>
  <dt><cmdopt>--version</cmdopt></dt><dd/>      
  Displays the Ruby version number and exits.
<p/>
  <dt>-w</dt><dd/>'
  Enables verbose mode. Unlike <cmdopt>-v</cmdopt>, reads program from
  standard input if no program files are present on the command line.
  We recommend running your Ruby programs with <tt>-w</tt>.
<p/>
  <dt>-X <em>directory</em></dt><dd/>'
  Changes working directory to <em>directory</em> before executing.
  Same as <tt>-C</tt><nbsp/><em>directory</em>.
<p/>
  <dt>-x [<em>directory</em>}</dt><dd/>'
  Strips off text before <tt>#!ruby</tt> line and changes working
  directory to <em>directory</em> if given.
<p/>
  <dt>-y, --yydebug</dt><dd/>'
  Enables yacc debugging in the parser <em>(waaay too much
    information)</em>.  
</dl>
<subsection>ARGV</subsection>
<p/>
Any command-line arguments after the program filename
are available to your Ruby program in the global array
<var>ARGV</var>.
For instance, invoking Ruby as
<p/>
<alltt>
<tt>%<nbsp/>ruby -w ptest "Hello World" a1 1.6180</tt>
</alltt>
<p/>
yields an <var>ARGV</var> array containing <tt>["Hello World", a1,
  1.6180]</tt>.  There's a gotcha here for all you C
programmers---<tt>ARGV[0]</tt> is the first argument to the program, not
the program name.
The name of the current program is
available in the global variable <var>$0</var>.
<section>Program Termination</section>
<p/>
The method <mim><file>kernel</file><front>Kernel</front><back>exit</back><mref>exit</mref></mim> terminates your program, returning a
status value to the operating system. However, unlike some languages,
<meth>exit</meth> doesn't just terminate the program immediately.
<mim><file>kernel</file><front>Kernel</front><back>exit</back><mref>exit</mref></mim> first raises a
<exception>SystemExit</exception> exception, which you may catch, and then performs a
number of cleanup actions, including running any registered
<tt>at_exit</tt> methods and object finalizers.  See the reference for
<mim><file>kernel</file><front>Kernel</front><back>exit</back><mref>exit</mref></mim> beginning on page 419 for details.
<section>Environment Variables</section>
<p/>
You can access operating system environment variables using
the predefined variable <var>ENV</var>.  It responds to the same
methods as <classname>Hash</classname>.<footnote><const>ENV</const> is not actually a hash, but
  if you need to, you can convert it into a <classname>Hash</classname> using
  <tt>ENV#to_hash</tt>.</footnote>
<p/>
The values of some environment variables are read by Ruby
when it first starts. These variables modify the behavior of the interpreter, 
as shown in Table 13.1 on page 141.
<figure type="table">
<caption>Environment variables used by Ruby</caption>
<table>
<th>
  <td><b>Variable Name</b></td>
  <td><b>Description</b></td>
</th>
<tr>
  <td><tt>RUBYOPT</tt></td>
  <td>Additional command-line options to Ruby; examined after
                     real command-line options are parsed (<tt>$SAFE</tt>
                     must be 0).</td>
</tr>
<tr>
  <td><tt>RUBYLIB</tt></td>
  <td>Additional search path for Ruby programs
                     (<tt>$SAFE</tt> must be 0).</td>
</tr>
<tr>
  <td><tt>RUBYPATH</tt></td>
  <td>With <tt>-S</tt> option, search path for Ruby 
                     programs (defaults to <tt>PATH</tt>).</td>
</tr>
<tr>
  <td><tt>RUBYSHELL</tt></td>
  <td>Shell to use when spawning a process; if not
                    set, will also check <tt>SHELL</tt> or <tt>COMSPEC</tt>.</td>
</tr>
<tr>
  <td><tt>DLN_LIBRARY_PATH</tt></td>
  <td>Search path for dynamically loaded
                              modules.</td>
</tr>
<tr>
  <td><tt>RUBYLIB_PREFIX</tt></td>
  <td>(Windows only) Mangle the RUBYLIB search path by
                              adding this prefix to each component.</td>
</tr>
<bottomrule/></table>
<p/>
</figure>
<p/>
<subsection>Writing to Environment Variables</subsection>
<p/>
A Ruby program may write to the <const>ENV</const> object, which on most systems
changes the values of the corresponding environment variables. However,
this change is local to the process that makes it and to any
subsequently spawned child processes.
This inheritance of environment variables is illustrated in the code
that follows. A subprocess changes an environment variable and this
change is seen in a process that it then starts. However, the change
is not visible to the original parent. (This just goes to prove that
parents never really know what their children are doing.)
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  puts "In parent, term = #{ENV['TERM']}"
  fork do
    puts "Start of child 1, term = #{ENV['TERM']}"
    ENV['TERM'] = "ansi"
    fork do
      puts "Start of child 2, term = #{ENV['TERM']}"
    end
    Process.wait
    puts "End of child 1, term = #{ENV['TERM']}"
  end
  Process.wait
  puts "Back in parent, term = #{ENV['TERM']}"
]]></fullcode>
puts<nbsp/>"In<nbsp/>parent,<nbsp/>term<nbsp/>=<nbsp/>#{ENV['TERM']}"
fork<nbsp/>do
<nbsp/><nbsp/>puts<nbsp/>"Start<nbsp/>of<nbsp/>child<nbsp/>1,<nbsp/>term<nbsp/>=<nbsp/>#{ENV['TERM']}"
<nbsp/><nbsp/>ENV['TERM']<nbsp/>=<nbsp/>"ansi"
<nbsp/><nbsp/>fork<nbsp/>do
<nbsp/><nbsp/><nbsp/><nbsp/>puts<nbsp/>"Start<nbsp/>of<nbsp/>child<nbsp/>2,<nbsp/>term<nbsp/>=<nbsp/>#{ENV['TERM']}"
<nbsp/><nbsp/>end
<nbsp/><nbsp/>Process.wait
<nbsp/><nbsp/>puts<nbsp/>"End<nbsp/>of<nbsp/>child<nbsp/>1,<nbsp/>term<nbsp/>=<nbsp/>#{ENV['TERM']}"
end
Process.wait
puts<nbsp/>"Back<nbsp/>in<nbsp/>parent,<nbsp/>term<nbsp/>=<nbsp/>#{ENV['TERM']}"
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
In<nbsp/>parent,<nbsp/>term<nbsp/>=<nbsp/>xterm
Start<nbsp/>of<nbsp/>child<nbsp/>1,<nbsp/>term<nbsp/>=<nbsp/>xterm
Start<nbsp/>of<nbsp/>child<nbsp/>2,<nbsp/>term<nbsp/>=<nbsp/>ansi
End<nbsp/>of<nbsp/>child<nbsp/>1,<nbsp/>term<nbsp/>=<nbsp/>ansi
Back<nbsp/>in<nbsp/>parent,<nbsp/>term<nbsp/>=<nbsp/>xterm
</alltt>
</codefragment>
<section>Where Ruby Finds Its Modules</section>
<p/>
You use <tt>require</tt> or <tt>load</tt> to bring a library module into your
Ruby program. Some of these modules are supplied with Ruby, some you
installed off the Ruby Application Archive, and some you wrote
yourself. How does Ruby find them?
<p/>
When Ruby is built for your particular machine, it predefines a set
of standard directories to hold library stuff. Where these are
depends on the machine in question. You can
determine this from the command line with something like:
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  % ruby -e 'puts $:'
]]></fullcode>
%<nbsp/>ruby<nbsp/>-e<nbsp/>'puts<nbsp/>$:'
</alltt>
</codefragment>
<p/>
On a typical Linux box, you'll probably find something such as:
<p/>
<codefragment>
<alltt><fullcode><![CDATA[/usr/local/lib/ruby/site_ruby/1.6/i686-linux
/usr/local/lib/ruby/site_ruby/1.6
/usr/local/lib/ruby/site_ruby
/usr/local/lib/ruby/1.6/i686-linux
/usr/local/lib/ruby/1.6
.
]]></fullcode>
/usr/local/lib/ruby/site_ruby/1.6/i686-linux
/usr/local/lib/ruby/site_ruby/1.6
/usr/local/lib/ruby/site_ruby
/usr/local/lib/ruby/1.6/i686-linux
/usr/local/lib/ruby/1.6
.
</alltt>
</codefragment>
<p/>
The <tt>site_ruby</tt> directories are intended to hold modules and extensions that
you've added.
The architecture-dependent directories (<tt>i686-linux</tt>
in this case) hold executables and other things specific to this
particular machine. All these directories are automatically included
in Ruby's search for modules.
<p/>
Sometimes this isn't enough. Perhaps you're working on a large project
written in Ruby, and you and your colleagues have built a substantial
library of Ruby code. You want everyone on the team to have access to
all of this code.  You have a couple of options to accomplish this. If
your program runs at a safe level of zero (see 
Chapter 20 beginning on page 257),
you can set the environment variable
<tt>RUBYLIB</tt> to a list of one or more directories to be
searched.<footnote>The separator between entries depends on your
  platform. For Windows, it's a semicolon; for Unix, a colon.</footnote> If your
program is not <em>setuid</em>,
you can use the command-line parameter <cmdopt>-I</cmdopt>
to do the same thing.
<p/>
Finally,
the Ruby variable <var>$:</var> is an array of places to search
for loaded files. This variable is initialized to the list of standard 
directories, plus any additional ones you specified using <tt>RUBYLIB</tt> 
and <tt>-I</tt>. You can always add additional directories to this array
from within your running program. 
<section>Build Environment</section>
<p/>
When Ruby is compiled for a particular architecture, all of the
relevant settings used to build it (including the architecture of the
machine on which it was compiled, compiler options, source code
directory, and so on) are written to the module <modulename>Config</modulename> within the 
library file ``<tt>rbconfig.rb</tt>''.
After installation, any Ruby program can use this module to get
details on how Ruby was compiled.
<p/>
<codefragment>
<fullcode><![CDATA[require "rbconfig.rb"
include Config
CONFIG["host"]
CONFIG["LDFLAGS"]
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>require<nbsp/>"rbconfig.rb"</tt></td>
</tr>
<tr>
<td colspan="3"><tt>include<nbsp/>Config</tt></td>
</tr>
<tr>
  <td><tt>CONFIG["host"]</tt></td>
  <td>&#187;</td>
  <td><tt>"i686-pc-linux"</tt></td>
</tr>
<tr>
  <td><tt>CONFIG["LDFLAGS"]</tt></td>
  <td>&#187;</td>
  <td><tt>"-rdynamic"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
Extension libraries use this configuration file in order to compile
and link properly on any given architecture.  See Chapter
17 beginning on page 171, and the reference
for <tt>mkmf</tt> beginning on page 455 for details.
</chapter>
</ppdoc>