summaryrefslogtreecommitdiff
path: root/ruby.1
diff options
context:
space:
mode:
authorknu <knu@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2002-12-30 19:56:06 +0000
committerknu <knu@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2002-12-30 19:56:06 +0000
commit378a6bdea5106f02196e821a9574cca61aab9ed3 (patch)
treed0a409c7a47112de270a25baf411177f7c8da91d /ruby.1
parentc2e3d3971be8cc5b2a5b7ab624e516cc0d1ce496 (diff)
mdoc'ify.
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@3248 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'ruby.1')
-rw-r--r--ruby.1523
1 files changed, 269 insertions, 254 deletions
diff --git a/ruby.1 b/ruby.1
index 6d6bebf..64d734f 100644
--- a/ruby.1
+++ b/ruby.1
@@ -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 .