ruby.1

   1 .\"Ruby is copyrighted by Yukihiro Matsumoto <matz@netlab.jp>.
   2 .Dd December 31, 2002
   3 .Dt RUBY(1) "" "Ruby Programmers Reference Guide"
   4 .\".Dt RUBY 1
   5 .Os UNIX
   6 .Sh NAME
   7 .Nm ruby
   8 .Nd Interpreted object-oriented scripting language
   9 .Sh SYNOPSIS
  10 .Nm
  11 .Op Fl -copyright
  12 .Op Fl -version
  13 .Op Fl Sacdlnpswvy
  14 .Op Fl 0 Ns Op Ar octal
  15 .Op Fl C Ar directory
  16 .Op Fl E Ar encoding
  17 .Op Fl F Ar pattern
  18 .Op Fl I Ar directory
  19 .Op Fl K Ar c
  20 .Op Fl T Ns Op Ar level
  21 .Op Fl W Ns Op Ar level
  22 .Op Fl e Ar command
  23 .Op Fl i Ns Op Ar extension
  24 .Op Fl r Ar library
  25 .Op Fl x Ns Op Ar directory
  26 .Op - Ns Bro Cm enable Ns | Ns Cm disable Brc Ns - Ns Ar FEATURE
  27 .Op Fl -verbose
  28 .Op Fl -
  29 .Op Ar program_file
  30 .Op Ar argument ...
  31 .Sh DESCRIPTION
  32 Ruby is an interpreted scripting language for quick and easy
  33 object-oriented programming.  It has many features to process text
  34 files and to do system management tasks (as in Perl).  It is simple,
  35 straight-forward, and extensible.
  36 .Pp
  37 If you want a language for easy object-oriented programming, or you
  38 don't like the Perl ugliness, or you do like the concept of LISP, but
  39 don't like too much parentheses, Ruby may be the language of your
  40 choice.
  41 .Sh FEATURES
  42 Ruby's features are as follows:
  43 .Bl -tag -width 6n
  44 .It Sy "Interpretive"
  45 Ruby is an interpreted language, so you don't have to recompile
  46 programs written in Ruby to execute them.
  47 .Pp
  48 .It Sy "Variables have no type (dynamic typing)"
  49 Variables in Ruby can contain data of any type.  You don't have to
  50 worry about variable typing.  Consequently, it has a weaker compile
  51 time check.
  52 .Pp
  53 .It Sy "No declaration needed"
  54 You can use variables in your Ruby programs without any declarations.
  55 Variable names denote their scope, local, global, instance, etc.
  56 .Pp
  57 .It Sy "Simple syntax"
  58 Ruby has a simple syntax influenced slightly from Eiffel.
  59 .Pp
  60 .It Sy "No user-level memory management"
  61 Ruby has automatic memory management.  Objects no longer referenced
  62 from anywhere are automatically collected by the garbage collector
  63 built into the interpreter.
  64 .Pp
  65 .It Sy "Everything is an object"
  66 Ruby is the purely object-oriented language, and was so since its
  67 creation.  Even such basic data as integers are seen as objects.
  68 .Pp
  69 .It Sy "Class, inheritance, and methods"
  70 Of course, as an object-oriented language, Ruby has such basic
  71 features like classes, inheritance, and methods.
  72 .Pp
  73 .It Sy "Singleton methods"
  74 Ruby has the ability to define methods for certain objects.  For
  75 example, you can define a press-button action for certain widget by
  76 defining a singleton method for the button.  Or, you can make up your
  77 own prototype based object system using singleton methods, if you want
  78 to.
  79 .Pp
  80 .It Sy "Mix-in by modules"
  81 Ruby intentionally does not have the multiple inheritance as it is a
  82 source of confusion.  Instead, Ruby has the ability to share
  83 implementations across the inheritance tree.  This is often called
  84 .Sq Mix-in .
  85 .Pp
  86 .It Sy "Iterators"
  87 Ruby has iterators for loop abstraction.
  88 .Pp
  89 .It Sy "Closures"
  90 In Ruby, you can objectify the procedure.
  91 .Pp
  92 .It Sy "Text processing and regular expression"
  93 Ruby has a bunch of text processing features like in Perl.
  94 .Pp
  95 .It Sy "Bignums"
  96 With built-in bignums, you can for example calculate factorial(400).
  97 .Pp
  98 .It Sy "Exception handling"
  99 As in Java(tm).
 100 .Pp
 101 .It Sy "Direct access to the OS"
 102 Ruby can use most
 103 .Ux
 104 system calls, often used in system programming.
 105 .Pp
 106 .It Sy "Dynamic loading"
 107 On most
 108 .Ux
 109 systems, you can load object files into the Ruby interpreter
 110 on-the-fly.
 111 .El
 112 .Pp
 113 .Sh OPTIONS
 114 Ruby interpreter accepts following command-line options (switches).
 115 They are quite similar to those of
 116 .Xr perl 1 .
 117 .Bl -tag -width "1234567890123" -compact
 118 .Pp
 119 .It Fl -copyright
 120 Prints the copyright notice.
 121 .Pp
 122 .It Fl -version
 123 Prints the version of Ruby interpreter.
 124 .Pp
 125 .It Fl 0 Ns Op Ar octal
 126 (The digit
 127 .Dq zero . )
 128 Specifies the input record separator
 129 .Pf ( Li "$/" )
 130 as an octal number. If no digit is given, the null character is taken
 131 as the separator.  Other switches may follow the digits.
 132 .Fl 00
 133 turns Ruby into paragraph mode.
 134 .Fl 0777
 135 makes Ruby read whole file at once as a single string since there is
 136 no legal character with that value.
 137 .Pp
 138 .It Fl C Ar directory
 139 .It Fl X Ar directory
 140 Causes Ruby to switch to the directory.
 141 .Pp
 142 .It Fl E Ar encname
 143 .It Fl -encoding Ar encname
 144 Specifies the encoding for the program codes.
 145 .Pp
 146 .It Fl F Ar pattern
 147 Specifies input field separator
 148 .Pf ( Li "$;" ) .
 149 .Pp
 150 .It Fl I Ar directory
 151 Used to tell Ruby where to load the library scripts.  Directory path
 152 will be added to the load-path variable
 153 .Pf ( Li "$:" ) .
 154 .Pp
 155 .It Fl K Ar kcode
 156 Specifies KANJI (Japanese) encoding.
 157 .Pp
 158 .It Fl S
 159 Makes Ruby use the
 160 .Ev PATH
 161 environment variable to search for script, unless if its name begins
 162 with a slash.  This is used to emulate
 163 .Li #!
 164 on machines that don't support it, in the following manner:
 165 .Bd -literal -offset indent
 166 #! /usr/local/bin/ruby
 167 # This line makes the next one a comment in Ruby \e
 168   exec /usr/local/bin/ruby -S $0 $*
 169 .Ed
 170 .Pp
 171 .It Fl T Ns Op Ar level
 172 Turns on taint checks at the specified level (default 1).
 173 .Pp
 174 .It Fl W Ns Op Ar level
 175 Turns on verbose mode at the specified level, without printing version
 176 message at the beginning. The level can be;
 177 .Bl -hang -offset indent
 178 .It Sy 0
 179 Verbose mode is "silence". It sets the
 180 .Li "$VERBOSE"
 181 to nil.
 182 .Pp
 183 .It Sy 1
 184 Verbose mode is "medium". It sets the
 185 .Li "$VERBOSE"
 186 to false.
 187 .Pp
 188 .It Sy 2 (default)
 189 Verbose mode is "verbose". It sets the
 190 .Li "$VERBOSE"
 191 to true.
 192 .Fl W Ns
 193 2 is same as
 194 .Fl w
 195 .
 196 .El
 197 .Pp
 198 .It Fl a
 199 Turns on auto-split mode when used with
 200 .Fl n
 201 or
 202 .Fl p .
 203 In auto-split mode, Ruby executes
 204 .Dl $F = $_.split
 205 at beginning of each loop.
 206 .Pp
 207 .It Fl c
 208 Causes Ruby to check the syntax of the script and exit without
 209 executing. If there are no syntax errors, Ruby will print
 210 .Dq Syntax OK
 211 to the standard output.
 212 .Pp
 213 .It Fl d
 214 .It Fl -debug
 215 Turns on debug mode.
 216 .Li "$DEBUG"
 217 will be set to true.
 218 .Pp
 219 .It Fl e Ar command
 220 Specifies script from command-line while telling Ruby not to search
 221 the rest of arguments for a script file name.
 222 .Pp
 223 .It Fl h
 224 .It Fl -help
 225 Prints a summary of the options.
 226 .Pp
 227 .It Fl i Ar extension
 228 Specifies in-place-edit mode.  The extension, if specified, is added
 229 to old file name to make a backup copy.  For example:
 230 .Bd -literal -offset indent
 231 % echo matz > /tmp/junk
 232 % cat /tmp/junk
 233 matz
 234 % ruby -p -i.bak -e '$_.upcase!' /tmp/junk
 235 % cat /tmp/junk
 236 MATZ
 237 % cat /tmp/junk.bak
 238 matz
 239 .Ed
 240 .Pp
 241 .It Fl l
 242 (The lowercase letter
 243 .Dq ell . )
 244 Enables automatic line-ending processing, which means to firstly set
 245 .Li "$\e"
 246 to the value of
 247 .Li "$/" ,
 248 and secondly chops every line read using
 249 .Li chop! .
 250 .Pp
 251 .It Fl n
 252 Causes Ruby to assume the following loop around your script, which
 253 makes it iterate over file name arguments somewhat like
 254 .Nm sed
 255 .Fl n
 256 or
 257 .Nm awk .
 258 .Bd -literal -offset indent
 259 while gets
 260   ...
 261 end
 262 .Ed
 263 .Pp
 264 .It Fl p
 265 Acts mostly same as -n switch, but print the value of variable
 266 .Li "$_"
 267 at the each end of the loop.  For example:
 268 .Bd -literal -offset indent
 269 % echo matz | ruby -p -e '$_.tr! "a-z", "A-Z"'
 270 MATZ
 271 .Ed
 272 .Pp
 273 .It Fl r Ar library
 274 Causes Ruby to load the library using require.  It is useful when using
 275 .Fl n
 276 or
 277 .Fl p .
 278 .Pp
 279 .It Fl s
 280 Enables some switch parsing for switches after script name but before
 281 any file name arguments (or before a
 282 .Fl - ) .
 283 Any switches found there are removed from
 284 .Li ARGV
 285 and set the corresponding variable in the script.  For example:
 286 .Bd -literal -offset indent
 287 #! /usr/local/bin/ruby -s
 288 # prints "true" if invoked with `-xyz' switch.
 289 print "true\en" if $xyz
 290 .Ed
 291 .Pp
 292 On some systems
 293 .Li "$0"
 294 does not always contain the full pathname, so you need the
 295 .Fl S
 296 switch to tell Ruby to search for the script if necessary.  To handle
 297 embedded spaces or such.  A better construct than
 298 .Li "$*"
 299 would be
 300 .Li ${1+"$@"} ,
 301 but it does not work if the script is being interpreted by
 302 .Xr csh 1 .
 303 .Pp
 304 .It Fl v
 305 Enables verbose mode.  Ruby will print its version at the beginning,
 306 and set the variable
 307 .Li "$VERBOSE"
 308 to true.  Some methods print extra messages if this variable is true.
 309 If this switch is given, and no other switches are present, Ruby quits
 310 after printing its version.
 311 .Pp
 312 .It Fl w
 313 Enables verbose mode without printing version message at the
 314 beginning.  It sets the
 315 .Li "$VERBOSE"
 316 variable to true.
 317 .Pp
 318 .It Fl x Ns Op Ar directory
 319 Tells Ruby that the script is embedded in a message.  Leading garbage
 320 will be discarded until the first that starts with
 321 .Dq #!
 322 and contains the string,
 323 .Dq ruby .
 324 Any meaningful switches on that line will applied.  The end of script
 325 must be specified with either
 326 .Li EOF ,
 327 .Li "^D" ( Li "control-D" ) ,
 328 .Li "^Z" ( Li "control-Z" ) ,
 329 or reserved word
 330 .Li __END__ .
 331 If the directory name is specified, Ruby will switch to that directory
 332 before executing script.
 333 .Pp
 334 .It Fl y
 335 .It Fl -yydebug
 336 Turns on compiler debug mode.  Ruby will print a bunch of internal
 337 state messages during compiling scripts.  You don't have to specify
 338 this switch, unless you are going to debug the Ruby interpreter.
 339 .Pp
 340 .It Fl -disable- Ns Ar FEATURE
 341 .It Fl -enable- Ns Ar FEATURE
 342 Disables (or enables) the specified
 343 .Ar FEATURE Ns
 344 \&.
 345 .Pp
 346 .It Fl -disable-gems
 347 .It Fl -enable-gems
 348 Disables (or enables) RubyGems libraries.  By default, Ruby will load the latest
 349 version of each installed gem. The
 350 .Li Gem::Enable
 351 constant is true if RubyGems is enabled, false if otherwise.
 352 .Pp
 353 .It Fl -disable-rubyopt
 354 .It Fl -enable-rubyopt
 355 Ignores (or considers) the
 356 .Ev RUBYOPT
 357 environment variable. By default, Ruby considers the variable.
 358 .Pp
 359 .It Fl -disable-all
 360 .It Fl -enable-all
 361 Disables (or enables) all features.
 362 .Pp
 363 .It Fl -verbose
 364 Enables verbose mode without printing version message at the
 365 beginning.  It sets the
 366 .Li "$VERBOSE"
 367 variable to true.
 368 If this switch is given, and no other switches are present, Ruby quits
 369 after printing its version.
 370 .El
 371 .Pp
 372 .Sh ENVIRONMENT
 373 .Bl -tag -width "RUBYLIB_PREFIX" -compact
 374 .It Ev RUBYLIB
 375 A colon-separated list of directories that are added to Ruby's
 376 library load path
 377 .Pf ( Li "$:" ) . Directories from this environment variable are searched
 378 before the standard load path is searched.
 379 .Pp
 380 e.g.:
 381 .Dl RUBYLIB="$HOME/lib/ruby:$HOME/lib/rubyext"
 382 .Pp
 383 .It Ev RUBYOPT
 384 Additional Ruby options.
 385 .Pp
 386 e.g.
 387 .Dl RUBYOPT="-w -Ke"
 388 .Pp
 389 .It Ev RUBYPATH
 390 A colon-separated list of directories that Ruby searches for
 391 Ruby programs when the
 392 .Fl S
 393 flag is specified.  This variable precedes the
 394 .Ev PATH
 395 environment variable.
 396 .Pp
 397 .It Ev RUBYSHELL
 398 The path to the system shell command.  This environment variable is
 399 enabled for only mswin32, mingw32, and OS/2 platforms.  If this
 400 variable is not defined, Ruby refers to
 401 .Ev COMSPEC .
 402 .Pp
 403 .It Ev PATH
 404 Ruby refers to the
 405 .Ev PATH
 406 environment variable on calling Kernel#system.
 407 .Pp
 408 .It Ev RUBYLIB_PREFIX
 409 This variable is obsolete.
 410 .El
 411 .Pp
 412 .Sh AUTHORS
 413 Ruby is designed and implemented by
 414 .An Yukihiro Matsumoto Aq matz@netlab.jp .