diff options
Diffstat (limited to 'ruby.1')
| -rw-r--r-- | ruby.1 | 523 |
1 files changed, 269 insertions, 254 deletions
@@ -1,291 +1,306 @@ .\"Ruby is copyrighted by Yukihiro Matsumoto <matz@netlab.jp>. -.na -.TH RUBY 1 "ruby 1.6" "2000-09-11" "Ruby Programmers Reference Guide" -.SH NAME -ruby - Interpreted object-oriented scripting language -.SH SYNOPSIS -.B ruby \c - [ \c -.BI --version \c - ] [ \c -.BI -c \c - ] [ \c -.BI -w \c - ] [ \c -.BI -d \c - ] [ \c -.BI -l \c - ] - [ \c -.BI -p \c - ] [ \c -.BI -n \c - ] [ \c -.BI -a \c - ] [ \c -.BI -s \c - ] [ \c -.BI -0 "[octal]"\c - ] - [ \c -.BI -K "c"\c - ] [ \c -.BI -e "command"\c - ] [ \c -.BI -F "pattern"\c - ] - [ \c -.BI -i "[extension]"\c - ] [ \c -.BI -I "dir"\c - ] [ \c -.BI -r "library"\c - ] - [ \c -.BI -S \c - ] [ \c -.BI -v \c - ] [ \c -.BI -x "[directory]"\c - ] [ \c -.BI -C "directory"\c - ] - [ \c -.BI -y \c -] [ \c -.BI -- \c - ] [ programfile ] [ argument ] ... - -.SH PREFACE +.Dd December 31, 2002 +.Dt RUBY(1) "" "Ruby Programmers Reference Guide" +.\".Dt RUBY 1 +.Os UNIX +.Sh NAME +.Nm ruby +.Nd Interpreted object-oriented scripting language +.Sh SYNOPSIS +.Nm +.Op Fl -copyright +.Op Fl -version +.Op Fl Sacdlnpswvy +.Op Fl 0 Ns Op Ar octal +.Op Fl C Ar directory +.Op Fl F Ar pattern +.Op Fl I Ar directory +.Op Fl K Ar c +.Op Fl T Ns Op Ar level +.Op Fl e Ar command +.Op Fl i Ns Op Ar extension +.Op Fl r Ar library +.Op Fl x Ns Op Ar directory +.Op Fl - +.Op Ar program_file +.Op Ar argument ... +.Sh DESCRIPTION Ruby is an interpreted scripting language for quick and easy object-oriented programming. It has many features to process text files and to do system management tasks (as in Perl). It is simple, straight-forward, and extensible. -.PP +.Pp If you want a language for easy object-oriented programming, or you -don't like the Perl ugliness, or you do like the concept of lisp, but +don't like the Perl ugliness, or you do like the concept of LISP, but don't like too much parentheses, Ruby may be the language of your choice. -.SH DESCRIPTION +.Sh FEATURES Ruby's features are as follows: -.TP -.B "\(bu Interpretive" +.Bl -tag -width "12" +.It Sy "Interpretive" Ruby is an interpreted language, so you don't have to recompile programs written in Ruby to execute them. -.TP -.B "\(bu Variables have no type (dynamic typing)" +.Pp +.It Sy "Variables have no type (dynamic typing)" Variables in Ruby can contain data of any type. You don't have to worry about variable typing. Consequently, it has a weaker compile time check. -.TP -.B "\(bu No declaration needed" +.Pp +.It Sy "No declaration needed" You can use variables in your Ruby programs without any declarations. Variable names denote their scope, local, global, instance, etc. -.TP -.B "\(bu Simple syntax" +.Pp +.It Sy "Simple syntax" Ruby has a simple syntax influenced slightly from Eiffel. -.TP -.B "\(bu No user-level memory management" -Ruby has automatic memory management. Objects no longer -referenced from anywhere are automatically collected by the -garbage collector built into the interpreter. -.TP -.B "\(bu Everything is an object" +.Pp +.It Sy "No user-level memory management" +Ruby has automatic memory management. Objects no longer referenced +from anywhere are automatically collected by the garbage collector +built into the interpreter. +.Pp +.It Sy "Everything is an object" Ruby is the purely object-oriented language, and was so since its creation. Even such basic data as integers are seen as objects. -.TP -.B "\(bu Class, inheritance, methods" +.Pp +.It Sy "Class, inheritance, and methods" Of course, as an object-oriented language, Ruby has such basic features like classes, inheritance, and methods. -.TP -.B "\(bu Singleton methods" +.Pp +.It Sy "Singleton methods" Ruby has the ability to define methods for certain objects. For example, you can define a press-button action for certain widget by defining a singleton method for the button. Or, you can make up your own prototype based object system using singleton methods, if you want to. -.TP -.B "\(bu Mix-in by modules" +.Pp +.It Sy "Mix-in by modules" Ruby intentionally does not have the multiple inheritance as it is a source of confusion. Instead, Ruby has the ability to share implementations across the inheritance tree. This is often called -`Mix-in'. -.TP -.B "\(bu Iterators" +.Sq Mix-in . +.Pp +.It Sy "Iterators" Ruby has iterators for loop abstraction. -.TP -.B "\(bu Closures" +.Pp +.It Sy "Closures" In Ruby, you can objectify the procedure. -.TP -.B "\(bu Text processing and regular expression" +.Pp +.It Sy "Text processing and regular expression" Ruby has a bunch of text processing features like in Perl. -.TP -.B "\(bu Bignums" +.Pp +.It Sy "Bignums" With built-in bignums, you can for example calculate factorial(400). -.TP -.B "\(bu Exception handling" +.Pp +.It Sy "Exception handling" As in Java(tm). -.TP -.B "\(bu Direct access to the OS" -Ruby can use most UNIX system calls, often used in system programming. -.TP -.B "\(bu Dynamic loading" -On most UNIX systems, you can load object files into the Ruby -interpreter on-the-fly. -.PP -.SH COMMAND LINE OPTIONS +.Pp +.It Sy "Direct access to the OS" +Ruby can use most +.Ux +system calls, often used in system programming. +.Pp +.It Sy "Dynamic loading" +On most +.Ux +systems, you can load object files into the Ruby interpreter +on-the-fly. +.Pp +.Sh OPTIONS Ruby interpreter accepts following command-line options (switches). -They are quite similar to those of Perl. -.TP -.B -0[octal] -specifies the input record separator ($/) as an octal number. If no -digit is given, the null character is taken as the separator. Other -switches may follow the digits. -00 turns Ruby into paragraph mode. - -0777 makes Ruby read whole file at once as a single string since there -is no legal character with that value. -.TP -.B -a -turns on auto-split mode when used with -n or -p. In auto-split -mode, Ruby executes -.nf -.ne 1 -\& $F = $_.split +They are quite similar to those of +.Xr perl 1 . +.Bl -tag -width "12" -compact +.Pp +.It Fl -copyright +Prints the copyright notice. +.Pp +.It Fl -version +Prints the version of Ruby interpreter. +.Pp +.It Fl 0 Ns Op Ar octal +(The digit +.Dq zero . ) +Specifies the input record separator +.Pf ( Li "$/" ) +as an octal number. If no digit is given, the null character is taken +as the separator. Other switches may follow the digits. +.Fl 00 +turns Ruby into paragraph mode. +.Fl 0777 +makes Ruby read whole file at once as a single string since there is +no legal character with that value. +.Pp +.It Fl C Ar directory +Causes Ruby to switch to the directory. +.Pp +.It Fl F Ar pattern +Specifies input field separator +.Pf ( Li "$;" ) . +.Pp +.It Fl I Ar directory +Used to tell Ruby where to load the library scripts. Directory path +will be added to the load-path variable +.Pf ( Li "$:" ) . +.Pp +.It Fl K Ar kcode +Specifies KANJI (Japanese) encoding. +.Pp +.It Fl S +Makes Ruby use the +.Ev PATH +environment variable to search for script, unless if its name begins +with a slash. This is used to emulate #! on machines that don't +support it, in the following manner: +.Bd -literal -offset indent +#! /usr/local/bin/ruby +# This line makes the next one a comment in ruby \e + exec /usr/local/bin/ruby -S $0 $* +.Ed +.Pp +.It Fl T Ns Op Ar level +Turns on taint checks at the specified level (default 1). +.Pp +.It Fl a +Turns on auto-split mode when used with +.Fl n +or +.Fl p . +In auto-split mode, Ruby executes +.Dl $F = $_.split at beginning of each loop. -.fi -.TP -.B -c -causes Ruby to check the syntax of the script and exit without -executing. If there are no syntax errors, Ruby will print "Syntax -OK" to the standard output. -.TP -.B --copyright -prints the copyright notice. -.TP -.B -d --debug -turns on debug mode. $DEBUG will set true. -.TP -.B -e command -specifies script from command-line while telling Ruby to not -search argv for script filenames. -.TP -.B -F pattern -specifies input field separator ($;). -.TP -.B -h --help -prints a summary of the options. -.TP -.B -i extension -specifies in-place-edit mode. The extension, if specified, is -added to old filename to make a backup copy. -example: -.nf -.ne 8 -\& % echo matz > /tmp/junk -\& % cat /tmp/junk -\& matz -\& % ruby -p -i.bak -e '$_.upcase!' /tmp/junk -\& % cat /tmp/junk -\& MATZ -\& % cat /tmp/junk.bak -\& matz -.fi -.TP -.B -I directory -used to tell Ruby where to load the library scripts. Directory path -will be added to the load-path variable ($:'). -.TP -.B -Kkcode -specifies KANJI (Japanese) encoding. -.TP -.B -l -enables automatic line-ending processing, which means to firstly set -$\e to the value of $/, and secondly chops every line read using chop!. -.TP -.B -n -causes Ruby to assume the following loop around your script, -which makes it iterate over filename arguments somewhat like -sed -n or awk. -.nf -.ne 3 -\& while gets -\& ... -\& end -.fi -.TP -.B -p -acts mostly same as -n switch, but print the value of variable -$_ at the each end of the loop. -example: -.nf -.ne 2 -\& % echo matz | ruby -p -e '$_.tr! "a-z", "A-Z"' -\& MATZ -.fi -.TP -.B -r library -causes Ruby to load the library using require. It is useful -with switches -n or -p. -.TP -.B -s -enables some switch parsing for switches after script name but before -any filename arguments (or before a --). Any switches found there are -removed from ARGV and set the corresponding variable in the script. -example: -.nf -.ne 3 -\& #! /usr/local/bin/ruby -s -\& # prints "true" if invoked with `-xyz' switch. -\& print "true\en" if $xyz -.fi -.TP -.B -S -makes Ruby use the PATH environment variable to search for -script, unless if its name begins with a slash. This is used to -emulate #! on machines that don't support it, in the following -manner: -.nf -.ne 2 -\& #! /usr/local/bin/ruby -\& # This line makes the next one a comment in ruby \e -\& exec /usr/local/bin/ruby -S $0 $* -.fi -On some systems $0 does not always contain the full pathname, so you -need -S switch to tell Ruby to search for the script if necessary. To -handle embedded spaces or such. A better construct than $* would be -${1+"$@"}, but it does not work if the script is being interpreted by -csh. -.TP -.B -v --verbose -enables verbose mode. Ruby will print its version at the beginning, -and set the variable `$VERBOSE' to true. Some methods print extra -messages if this variable is true. If this switch is given, and no -other switches are present, Ruby quits after printing its version. -.TP -.B -T[level] -turns on taint checks at the specified level (default 1). -.TP -.B --version -prints the version of Ruby interpreter. -.TP -.B -w -enables verbose mode without printing version message at the -beginning. It set the `$VERBOSE' variable to true. -.TP -.B -x[directory] -tells Ruby that the script is embedded in a message. Leading garbage -will be discarded until the first that starts with "#!" and contains -the string, "ruby". Any meaningful switches on that line will applied. -The end of script must be specified with either EOF, ^D (control-D), -^Z (control-Z), or reserved word __END__.If the directory name is -specified, Ruby will switch to that directory before executing script. -.TP -.B -C directory -causes Ruby to switch to the directory. -.TP -.B -y --yydebug -turns on compiler debug mode. Ruby will print a bunch of internal -state messages during compiling scripts. You don't have to specify +.Pp +.It Fl c +Causes Ruby to check the syntax of the script and exit without +executing. If there are no syntax errors, Ruby will print +.Dq Syntax OK +to the standard output. +.Pp +.It Fl d +.It Fl -debug +Turns on debug mode. +.Li "$DEBUG" +will set true. +.Pp +.It Fl e Ar command +Specifies script from command-line while telling Ruby to not search +argv for script filenames. +.Pp +.It Fl h +.It Fl -help +Prints a summary of the options. +.Pp +.It Fl i Ar extension +Specifies in-place-edit mode. The extension, if specified, is added +to old filename to make a backup copy. For example: +.Bd -literal -offset indent +% echo matz > /tmp/junk +% cat /tmp/junk +matz +% ruby -p -i.bak -e '$_.upcase!' /tmp/junk +% cat /tmp/junk +MATZ +% cat /tmp/junk.bak +matz +.Ed +.Pp +.It Fl l +(The lowercase letter +.Dq ell . ) +Enables automatic line-ending processing, which means to firstly set +.Li "$\e" +to the value of +.Li "$/" , +and secondly chops every line read using +.Li chop! . +.Pp +.It Fl n +Causes Ruby to assume the following loop around your script, which +makes it iterate over filename arguments somewhat like +.Nm sed +.Fl n +or +.Nm awk . +.Bd -literal -offset indent +while gets + ... +end +.Ed +.Pp +.It Fl p +Acts mostly same as -n switch, but print the value of variable +.Li "$_" +at the each end of the loop. For example: +.Bd -literal -offset indent +% echo matz | ruby -p -e '$_.tr! "a-z", "A-Z"' +MATZ +.Ed +.Pp +.It Fl r Ar library +Causes Ruby to load the library using require. It is useful when using +.Fl n +or +.Fl p . +.Pp +.It Fl s +Enables some switch parsing for switches after script name but before +any filename arguments (or before a +.Fl - ) . +Any switches found there are removed from +.Li ARGV +and set the corresponding variable in the script. For example: +.Bd -literal -offset indent +#! /usr/local/bin/ruby -s +# prints "true" if invoked with `-xyz' switch. +print "true\en" if $xyz +.Ed +.Pp +On some systems +.Li "$0" +does not always contain the full pathname, so you need the +.Fl S +switch to tell Ruby to search for the script if necessary. To handle +embedded spaces or such. A better construct than +.Li "$*" +would be +.Li ${1+"$@"} , +but it does not work if the script is being interpreted by +.Xr csh 1 . +.Pp +.It Fl v +.It Fl -verbose +Enables verbose mode. Ruby will print its version at the beginning, +and set the variable +.Li "$VERBOSE" +to true. Some methods print extra messages if this variable is true. +If this switch is given, and no other switches are present, Ruby quits +after printing its version. +.Pp +.It Fl w +Enables verbose mode without printing version message at the +beginning. It sets the +.Li "$VERBOSE" +variable to true. +.Pp +.It Fl x Ns Op Ar directory +Tells Ruby that the script is embedded in a message. Leading garbage +will be discarded until the first that starts with +.Dq #! +and contains the string, +.Dq ruby . +Any meaningful switches on that line will applied. The end of script +must be specified with either EOF, ^D (control-D), ^Z (control-Z), or +reserved word +.Li __END__ . +If the directory name is specified, Ruby will switch to that directory +before executing script. +.Pp +.It Fl y +.It Fl -yydebug +Turns on compiler debug mode. Ruby will print a bunch of internal +state messages during compiling scripts. You don't have to specify this switch, unless you are going to debug the Ruby interpreter. -.PP -.SH AUTHOR - Ruby is designed and implemented by Yukihiro Matsumoto <matz@netlab.jp>. +.El +.Pp +.Sh AUTHORS +Ruby is designed and implemented by +.An Yukihiro Matsumoto Aq matz@netlab.jp . |