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