doc/command_line/environment.md

   1 ## Environment
   2
   3 Certain command-line options affect the execution environment
   4 of the invoked Ruby program.
   5
   6 ### About the Examples
   7
   8 The examples here use command-line option `-e`,
   9 which passes the Ruby code to be executed on the command line itself:
  10
  11 ```sh
  12 $ ruby -e 'puts "Hello, World."'
  13 ```
  14
  15 ### Option `-C`
  16
  17 The argument to option `-C` specifies a working directory
  18 for the invoked Ruby program;
  19 does not change the working directory for the current process:
  20
  21 ```sh
  22 $ basename `pwd`
  23 ruby
  24 $ ruby -C lib -e 'puts File.basename(Dir.pwd)'
  25 lib
  26 $ basename `pwd`
  27 ruby
  28 ```
  29
  30 Whitespace between the option and its argument may be omitted.
  31
  32 ### Option `-I`
  33
  34 The argument to option `-I` specifies a directory
  35 to be added to the array in global variable `$LOAD_PATH`;
  36 the option may be given more than once:
  37
  38 ```sh
  39 $ pushd /tmp
  40 $ ruby -e 'p $LOAD_PATH.size'
  41 8
  42 $ ruby -I my_lib -I some_lib -e 'p $LOAD_PATH.size'
  43 10
  44 $ ruby -I my_lib -I some_lib -e 'p $LOAD_PATH.take(2)'
  45 ["/tmp/my_lib", "/tmp/some_lib"]
  46 $ popd
  47 ```
  48
  49 Whitespace between the option and its argument may be omitted.
  50
  51 ### Option `-r`
  52
  53 The argument to option `-r` specifies a library to be required
  54 before executing the Ruby program;
  55 the option may be given more than once:
  56
  57 ```sh
  58 $ ruby -e 'p defined?(JSON); p defined?(CSV)'
  59 nil
  60 nil
  61 $ ruby -r CSV -r JSON -e 'p defined?(JSON); p defined?(CSV)'
  62 "constant"
  63 "constant"
  64 ```
  65
  66 Whitespace between the option and its argument may be omitted.
  67
  68 ### Option `-0`
  69
  70 Option `-0` defines the input record separator `$/`
  71 for the invoked Ruby program.
  72
  73 The optional argument to the option must be octal digits,
  74 each in the range `0..7`;
  75 these digits are prefixed with digit `0` to form an octal value:
  76
  77 - If no argument is given, the input record separator is `0x00`.
  78 - If the argument is `0`, the input record separator is `''`;
  79   see {Special Line Separator Values}[rdoc-ref:IO@Special+Line+Separator+Values].
  80 - If the argument is in range `(1..0377)`,
  81   it becomes the character value of the input record separator `$/`.
  82 - Otherwise, the input record separator is `nil`.
  83
  84 Examples:
  85
  86 ```sh
  87 $ ruby -0 -e 'p $/'
  88 "\x00"
  89 ruby -00 -e 'p $/'
  90 ""
  91 $ ruby -012 -e 'p $/'
  92 "\n"
  93 $ ruby -015 -e 'p $/'
  94 "\r"
  95 $ ruby -0377 -e 'p $/'
  96 "\xFF"
  97 $ ruby -0400 -e 'p $/'
  98 nil
  99 ```
 100
 101 The option may not be separated from its argument by whitespace.
 102
 103 ### Option `-d`
 104
 105 Some code in (or called by) the Ruby program may include statements or blocks
 106 conditioned by the global variable `$DEBUG` (e.g., `if $DEBUG`);
 107 these commonly write to `$stdout` or `$stderr`.
 108
 109 The default value for `$DEBUG` is `false`;
 110 option `-d` (or `--debug`) sets it to `true`:
 111
 112 ```sh
 113 $ ruby -e 'p $DEBUG'
 114 false
 115 $ ruby -d -e 'p $DEBUG'
 116 true
 117 ```
 118
 119 ### Option '-w'
 120
 121 Option `-w` (lowercase letter) is equivalent to option `-W1` (uppercase letter).
 122
 123 ### Option `-W`
 124
 125 Any Ruby code can create a <i>warning message</i> by calling method Kernel#warn;
 126 methods in the Ruby core and standard libraries can also create warning messages.
 127 Such a message may be printed on `$stderr`
 128 (or not, depending on certain settings).
 129
 130 Option `-W` helps determine whether a particular warning message
 131 will be written,
 132 by setting the initial value of global variable `$-W`:
 133
 134 - `-W0`: Sets `$-W` to `0` (silent; no warnings).
 135 - `-W1`: Sets `$-W` to `1` (moderate verbosity).
 136 - `-W2`: Sets `$-W` to `2` (high verbosity).
 137 - `-W`: Same as `-W2` (high verbosity).
 138 - Option not given: Same as `-W1` (moderate verbosity).
 139
 140 The value of `$-W`, in turn, determines which warning messages (if any)
 141 are to be printed to `$stdout` (see Kernel#warn):
 142
 143 ```sh
 144 $ ruby -W1 -e 'p $foo'
 145 nil
 146 $ ruby -W2 -e 'p $foo'
 147 -e:1: warning: global variable '$foo' not initialized
 148 nil
 149 ```
 150
 151 Ruby code may also define warnings for certain categories;
 152 these are the default settings for the defined categories:
 153
 154 ```
 155 Warning[:experimental] # => true
 156 Warning[:deprecated]   # => false
 157 Warning[:performance]  # => false
 158 ```
 159
 160 They may also be set:
 161 ```
 162 Warning[:experimental] = false
 163 Warning[:deprecated]   = true
 164 Warning[:performance]  = true
 165 ```
 166
 167 You can suppress a category by prefixing `no-` to the category name:
 168
 169 ```
 170 $ ruby -W:no-experimental -e 'p IO::Buffer.new'
 171 #<IO::Buffer>
 172 ```
 173