diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/erb.1 | 160 | ||||
| -rw-r--r-- | man/goruby.1 | 12 | ||||
| -rw-r--r-- | man/irb.1 | 145 | ||||
| -rw-r--r-- | man/rake.1 | 169 | ||||
| -rw-r--r-- | man/ruby.1 | 508 |
5 files changed, 583 insertions, 411 deletions
diff --git a/man/erb.1 b/man/erb.1 new file mode 100644 index 0000000000..38a4c14ea4 --- /dev/null +++ b/man/erb.1 @@ -0,0 +1,160 @@ +.\"Ruby is copyrighted by Yukihiro Matsumoto <matz@netlab.jp>. +.Dd March 27, 2026 +.Dt ERB 1 "Ruby Programmer's Reference Guide" +.Os UNIX +.Sh NAME +.Nm erb +.Nd Ruby Templating +.Sh SYNOPSIS +.Nm +.Op Fl -version +.Op Fl UPdnvx +.Op Fl E Ar ext Ns Op Ns : Ns int +.Op Fl S Ar level +.Op Fl T Ar mode +.Op Fl r Ar library +.Op Fl - +.Op file ... +.Pp +.Sh DESCRIPTION +.Nm +is a command line front-end for +.Li "ERB" +library, which is an implementation of eRuby. +.Pp +ERB provides an easy to use but powerful templating system for Ruby. +Using ERB, actual Ruby code can be added to any plain text document for the +purposes of generating document information details and/or flow control. +.Pp +.Nm +is a part of +.Nm Ruby . +.Pp +.Sh OPTIONS +.Bl -tag -width "1234567890123" -compact +.Pp +.It Fl -version +Prints the version of +.Nm . +.Pp +.It Fl E Ar external Ns Op : Ns Ar internal +.It Fl -encoding Ar external Ns Op : Ns Ar internal +Specifies the default value(s) for external encodings and internal encoding. Values should be separated with colon (:). +.Pp +You can omit the one for internal encodings, then the value +.Pf ( Li "Encoding.default_internal" ) will be nil. +.Pp +.It Fl P +Disables ruby code evaluation for lines beginning with +.Li "%" . +.Pp +.It Fl S Ar level +Specifies the safe level in which eRuby script will run. +.Pp +.It Fl T Ar mode +Specifies trim mode (default 0). +.Ar mode +can be one of +.Bl -hang -offset indent +.It Sy 0 +EOL remains after the embedded ruby script is evaluated. +.Pp +.It Sy 1 +EOL is removed if the line ends with +.Li "%>" . +.Pp +.It Sy 2 +EOL is removed if the line starts with +.Li "<%" +and ends with +.Li "%>" . +.Pp +.It Sy - +EOL is removed if the line ends with +.Li "-%>" . +And leading whitespaces are removed if the erb directive starts with +.Li "<%-" . +.Pp +.El +.It Fl r +Load a library +.Pp +.It Fl U +can be one of +Sets the default value for internal encodings +.Pf ( Li "Encoding.default_internal" ) to UTF-8. +.Pp +.It Fl d +.It Fl -debug +Turns on debug mode. +.Li "$DEBUG" +will be set to true. +.Pp +.It Fl h +.It Fl -help +Prints a summary of the options. +.Pp +.It Fl n +Used with +.Fl x . +Prepends the line number to each line in the output. +.Pp +.It Fl v +Enables verbose mode. +.Li "$VERBOSE" +will be set to true. +.Pp +.It Fl x +Converts the eRuby script into Ruby script and prints it without line numbers. +.Pp +.El +.Pp +.Sh EXAMPLES +Here is an eRuby script +.Bd -literal -offset indent +<?xml version="1.0" ?> +<% require 'prime' -%> +<erb-example> + <calc><%= 1+1 %></calc> + <var><%= __FILE__ %></var> + <library><%= Prime.each(10).to_a.join(", ") %></library> +</erb-example> +.Ed +.Pp +Command +.Dl "% erb -T - example.erb" +prints +.Bd -literal -offset indent +<?xml version="1.0" ?> +<erb-example> + <calc>2</calc> + <var>example.erb</var> + <library>2, 3, 5, 7</library> +</erb-example> +.Ed +.Pp +.Sh SEE ALSO +.Xr ruby 1 . +.Pp +And see +.Xr ri 1 +documentation for +.Li "ERB" +class. +.Pp +.Sh REPORTING BUGS +.Bl -bullet +.It +Security vulnerabilities should be reported via an email to +.Mt security@ruby-lang.org . +Reported problems will be published after being fixed. +.Pp +.It +Other bugs and feature requests can be reported via the +Ruby Issue Tracking System +.Pq Lk https://bugs.ruby-lang.org/ . +Do not report security vulnerabilities +via this system because it publishes the vulnerabilities immediately. +.El +.Sh AUTHORS +Written by Masatoshi SEKI. diff --git a/man/goruby.1 b/man/goruby.1 index f69b951a06..732ecaa663 100644 --- a/man/goruby.1 +++ b/man/goruby.1 @@ -1,10 +1,10 @@ .\"Ruby is copyrighted by Yukihiro Matsumoto <matz@netlab.jp>. -.Dd October 25, 2008 -.Dt GORUBY(1) "" "Ruby Programmers Reference Guide" +.Dd March 27, 2026 +.Dt GORUBY 1 "Ruby Programmer's Reference Guide" .Os UNIX .Sh NAME .Nm goruby -.Nd Code-golfer's best friend +.Nd A code-golfer's best friend .Sh SYNOPSIS .Nm .Op options ... @@ -14,12 +14,12 @@ .Sh DESCRIPTION .Sy goruby is a kind of Ruby language processor -which recognizes extremely shorten programs as bellow; +which recognizes extremely shortened programs as below: .Bd -literal -offset indent rq"date";s De.td .Ed .Pp -This means +Which means: .Bd -literal -offset indent require"date";puts Date.today .Ed @@ -35,5 +35,5 @@ The stiff version of Ruby interpreter. .El .Pp .Sh AUTHORS -Originally written by Nobuyoshi Nakada and developed by +Originally written by Nobuyoshi Nakada and developed by the Ruby core team. diff --git a/man/irb.1 b/man/irb.1 deleted file mode 100644 index e8c2ab01f9..0000000000 --- a/man/irb.1 +++ /dev/null @@ -1,145 +0,0 @@ -.\"Ruby is copyrighted by Yukihiro Matsumoto <matz@netlab.jp>. -.Dd October 25, 2008 -.Dt IRB(1) "" "Ruby Programmers Reference Guide" -.Os UNIX -.Sh NAME -.Nm irb -.Nd Interactive Ruby Shell -.Sh SYNOPSIS -.Nm -.Op Fl -version -.Op Fl Idfmrv -.Op Fl - Ns Oo no Oc Ns inspect -.Op Fl - Ns Oo no Oc Ns readline -.Op Fl -prompt Ar mode -.Op Fl -prompt-mode Ar mode -.Op Fl -inf-ruby-mode -.Op Fl -simple-prompt -.Op Fl -noprompt -.Op Fl -tracer -.Op Fl -back-trace-limit Ar n -.Op Fl -irb_debug Ar n -.Op Fl - -.Op program_file -.Op argument ... -.Pp -.Sh DESCRIPTION -irb is the REPL(read-eval&print loop) environment for Ruby programs. -.Pp -.Sh OPTIONS -.Bl -tag -width "1234567890123" -compact -.Pp -.It Fl d -Sets -.Li $DEBUG -to true (same as `ruby -d') -.Pp -.It Fl f -Suppresses read of ~/.irbrc -.Pp -.It Fl m -Bc mode (load mathn, fraction or matrix are available) -.Pp -.It Fl r Ar load-module -Same as `ruby -r' -.Pp -.It Fl I Ar path -Specifies -.Li $LOAD_PATH -directory -.Pp -.It Fl -inspect -Uses `inspect' for output (default except for bc mode) -.Pp -.It Fl -noinspect -Doesn't use inspect for output -.Pp -.It Fl -readline -Uses Readline extension module. -.Pp -.It Fl -noreadline -Doesn't use Readline extension module. -.Pp -.It Fl -prompt Ar mode -.It Fl -prompt-mode Ar mode -Switch prompt mode. Pre-defined prompt modes are -`default', `simple', `xmp' and `inf-ruby'. -.Pp -.It Fl -inf-ruby-mode -Uses prompt appropriate for inf-ruby-mode on emacs. -Suppresses --readline. -.Pp -.It Fl -simple-prompt -Makes prompts simple. -.Pp -.It Fl -noprompt -No prompt mode. -.Pp -.It Fl -tracer -Displays trace for each execution of commands. -.Pp -.It Fl -back-trace-limit Ar n -Displays backtrace top -.Ar n -and tail -.Ar n Ns . -The default value is 16. -.Pp -.It Fl -irb_debug Ar n -Sets internal debug level to n (not for popular use) -.Pp -.El -.Pp -.Sh ENVIRONMENT -.Bl -tag -width "RUBYLIB_PREFIX" -compact -.It Ev IRBRC -.Pp -.El -.Pp -Also -.Nm -depends on same variables as -.Xr ruby 1 . -.Pp -.Sh FILES -.Bl -tag -width "RUBYLIB_PREFIX" -compact -.It Pa ~/.irbrc -Personal irb initialization. -.Pp -.El -.Pp -.Sh EXAMPLES -.Dl % irb -.Dl irb(main):001:0> Ic 1 + 1 -.Dl 2 -.Dl irb(main):002:0> Ic def t(x) -.Dl irb(main):003:1> Ic x+1 -.Dl irb(main):004:1> Ic end -.Dl => nil -.Dl irb(main):005:0> Ic t(3) -.Dl => 4 -.Dl irb(main):006:0> Ic if t(3) == 4 -.Dl irb(main):007:1> Ic p :ok -.Dl irb(main):008:1> Ic end -.Dl :ok -.Dl => :ok -.Dl irb(main):009:0> Ic quit -.Dl % -.Pp -.Sh SEE ALSO -.Xr ruby 1 . -.Pp -.Sh REPORTING BUGS -.Bl -bullet -.Li Security vulnerabilities should be reported via an email to -.Aq security@ruby-lang.org Ns -.Li . -Reported problems will be published after fixed. -.Pp -.Li And you can report other bugs and feature requests via the -Ruby Issue Tracking System (http://redmine.ruby-lang.org). -Do not report security vulnerabilities -via the system because it publishes the vulnerabilities immedately. -.El -.Sh AUTHORS -Written by Keiju ISHITSUKA. diff --git a/man/rake.1 b/man/rake.1 deleted file mode 100644 index 3872026bf1..0000000000 --- a/man/rake.1 +++ /dev/null @@ -1,169 +0,0 @@ -.Dd November 30, 2008 -.Dt RAKE(1) "" "Ruby Programmers Reference Guide" -.Os UNIX -.Sh NAME -.Nm rake -.Nd Ruby Make -.Sh SYNOPSIS -.Nm -.Op Fl -f Ar Rakefile -.Op Fl -version -.Op Fl CGNPgnqstv -.Op Fl D Op Ar PATTERN -.Op Fl E Ar CODE -.Op Fl I Ar LIBDIR -.Op Fl R Ar RAKELIBDIR -.Op Fl T Op Ar PATTERN -.Op Fl e Ar CODE -.Op Fl p Ar CODE -.Op Fl r Ar MODULE -.Op Fl -rules -.Op Ar variable Ns = Ns Ar value -.Ar target ... -.Sh DESCRIPTION -.Nm Rake -is a simple -.Xr ruby 1 -build program with capabilities similar to the regular -.Xr make 1 -command. - -.Nm Rake -has the following features: -.Bl -bullet -.It -Rakefiles (Rake's version of Makefiles) are completely defined in standard Ruby syntax. -No XML files to edit. No quirky Makefile syntax to worry about (is that a tab or a space?). -.It -Users can specify tasks with prerequisites. -.It -Rake supports rule patterns to sythesize implicit tasks. -.It -Flexible FileLists that act like arrays but know about manipulating file names and paths. -.It -A library of prepackaged tasks to make building rakefiles easier. -.El -.Pp -.Sh OPTIONS -.Bl -tag -width "--execute-continue" -compact -.Pp -.It Fl -version -Display the program version. -.Pp -.It Fl C -.It Fl -classic-namespace -Put Task and FileTask in the top level namespace -.Pp -.It Fl D Op Ar PATTERN -.It Fl -describe Op Ar PATTERN -Describe the tasks (matching optional -.Ar PATTERN Ns -), then exit. -.Pp -.It Fl E Ar CODE -.It Fl -execute-continue Ar CODE -Execute some Ruby code, then continue with normal task processing. -.Pp -.It Fl G -.It Fl -no-system -.It Fl -nosystem -Use standard project Rakefile search paths, ignore system wide rakefiles. -.Pp -.It Fl I Ar LIBDIR -.It Fl -libdir Ar LIBDIR -Include -.Ar LIBDIR -in the search path for required modules. -.Pp -.It Fl N -.It Fl -no-search -.It Fl -nosearch -Do not search parent directories for the Rakefile. -.Pp -.It Fl P -.It Fl -prereqs -Display the tasks and dependencies, then exit. -.Pp -.It Fl R Ar RAKELIBDIR -.It Fl -rakelib Ar RAKELIBDIR -.It Fl -rakelibdir Ar RAKELIBDIR -Auto-import any .rake files in -.Ar RAKELIBDIR . -(default is -.Pa rakelib -) -.Pp -.It Fl T Op Ar PATTERN -.It Fl -tasks Op Ar PATTERN -Display the tasks (matching optional -.Ar PATTERN Ns -) with descriptions, then exit. -.Pp -.It Fl e Ar CODE -.It Fl -execute Ar CODE -Execute some Ruby code and exit. -.Pp -.It Fl f Ar FILE -.It Fl -rakefile Ar FILE -Use FILE as the rakefile. -.Pp -.It Fl h -.It Fl -help -Prints a summary of options. -.Pp -.It Fl g -.It Fl -system -Using system wide (global) rakefiles (usually -.Pa ~/.rake/*.rake -). -.Pp -.It Fl n -.It Fl -dry-run -Do a dry run without executing actions. -.Pp -.It Fl p Ar CODE -.It Fl -execute-print Ar CODE -Execute some Ruby code, print the result, then exit. -.Pp -.It Fl q -.It Fl -quiet -Do not log messages to standard output. -.Pp -.It Fl r Ar MODULE -.It Fl -require Ar MODULE -Require MODULE before executing rakefile. -.Pp -.It Fl s -.It Fl -silent -Like -.Fl -quiet , -but also suppresses the 'in directory' announcement. -.Pp -.It Fl t -.It Fl -trace -Turn on invoke/execute tracing, enable full backtrace. -.Pp -.It Fl v -.It Fl -verbose -Log message to standard output (default). -.Pp -.It Fl -rules -Trace the rules resolution. -.Pp -.El -.Pp -.Sh SEE ALSO -.Xr ruby 1 -.Xr make 1 -.Pp -http://rake.rubyforge.org/ -.Sh REPORTING BUGS -Bugs, features requests and other issues can be logged at -<\fBhttp://onestepback.org/redmine/projects/show/rake\fR>. -.Pp -You will need an account to before you can post issues. Register at <\fBhttp://onestepback.org/redmine/account/register\fR>. -Or you can send an email to the author. -.Sh AUTHOR -.Nm Rake -is written by -.An Jim Weirich Aq jim@weirichhouse.org diff --git a/man/ruby.1 b/man/ruby.1 index e2d0abdefd..bc776b8946 100644 --- a/man/ruby.1 +++ b/man/ruby.1 @@ -1,7 +1,6 @@ .\"Ruby is copyrighted by Yukihiro Matsumoto <matz@netlab.jp>. -.Dd October 25, 2008 -.Dt RUBY(1) "" "Ruby Programmers Reference Guide" -.\".Dt RUBY 1 +.Dd March 27, 2026 +.Dt RUBY 1 "Ruby Programmer's Reference Guide" .Os UNIX .Sh NAME .Nm ruby @@ -14,30 +13,31 @@ .Op Fl 0 Ns Op Ar octal .Op Fl C Ar directory .Op Fl E Ar external Ns Op : Ns Ar internal -.Op Fl F Ar pattern +.Op Fl F Ns Op Ar pattern .Op Fl I Ar directory -.Op Fl K Ar c +.Op Fl K Ns Op Ar c .Op Fl T Ns Op Ar level .Op Fl W 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 - Ns Bro Cm enable Ns | Ns Cm disable Brc Ns - Ns Ar FEATURE +.Op Fl - Ns Bro Cm enable Ns | Ns Cm disable Brc Ns - Ns Ar FEATURE .Op Fl -dump Ns = Ns Ar target .Op Fl -verbose +.Op Fl -crash-report Ns = Ns Ar template .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, +files and to do system management tasks (like in Perl). It is simple, straight-forward, and extensible. .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 too much parentheses, Ruby may be the language of your +don't like too many parentheses, Ruby might be your language of choice. .Sh FEATURES Ruby's features are as follows: @@ -53,7 +53,7 @@ time check. .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. +Variable names denote their scope - global, class, instance, or local. .Pp .It Sy "Simple syntax" Ruby has a simple syntax influenced slightly from Eiffel. @@ -64,11 +64,11 @@ 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 +Ruby is a purely object-oriented language, and was so since its creation. Even such basic data as integers are seen as objects. .Pp .It Sy "Class, inheritance, and methods" -Of course, as an object-oriented language, Ruby has such basic +Being an object-oriented language, Ruby naturally has basic features like classes, inheritance, and methods. .Pp .It Sy "Singleton methods" @@ -81,7 +81,7 @@ to. .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 +implementations across the inheritance tree. This is often called a .Sq Mix-in . .Pp .It Sy "Iterators" @@ -90,21 +90,21 @@ Ruby has iterators for loop abstraction. .It Sy "Closures" In Ruby, you can objectify the procedure. .Pp -.It Sy "Text processing and regular expression" +.It Sy "Text processing and regular expressions" Ruby has a bunch of text processing features like in Perl. .Pp .It Sy "M17N, character set independent" Ruby supports multilingualized programming. Easy to process texts -written in many different natural languages and encoded in many +written in many different natural languages and encoded in many different character encodings, without dependence on Unicode. .Pp .It Sy "Bignums" With built-in bignums, you can for example calculate factorial(400). .Pp -.It Sy "Reflection and domain specific languages" -Class is also an instance of Class class. Definition of classes and methods -is just an expression as 1+1 is. So your programs can even write and modify programs. -Thus you can write your application in your own programming language on top of Ruby. +.It Sy "Reflection and domain-specific languages" +Class is also an instance of the Class class. Definition of classes and methods +is an expression just as 1+1 is. So your programs can even write and modify programs. +Thus, you can write your application in your own programming language on top of Ruby. .Pp .It Sy "Exception handling" As in Java(tm). @@ -120,25 +120,36 @@ On most systems, you can load object files into the Ruby interpreter on-the-fly. .It Sy "Rich libraries" -Libraries called "builtin libraries" and "standard libraries" are bundled with Ruby. -And you can obtain more libraries via the package management system called `RubyGems'. - -Moreover there are thousands of Ruby projects in Rubyforge -.Pf ( "http://www.rubyforge.org" ) and RAA -.Pf ( "http://raa.ruby-lang.org" ) Ns . +In addition to the +.Dq builtin libraries +and +.Dq standard libraries +that are bundled with Ruby, a vast amount of third-party libraries +.Pq Dq gems +are available via the package management system called +.Sq RubyGems , +namely the +.Xr gem 1 +command. Visit RubyGems.org +.Pq Lk https://rubygems.org/ +to find the gems you need, and explore GitHub +.Pq Lk https://github.com/ +to see how they are being developed and used. .El .Pp .Sh OPTIONS -Ruby interpreter accepts following command-line options (switches). +The Ruby interpreter accepts the following command-line options (switches). They are quite similar to those of .Xr perl 1 . .Bl -tag -width "1234567890123" -compact .Pp .It Fl -copyright -Prints the copyright notice. +Prints the copyright notice, and quits immediately without running any +script. .Pp .It Fl -version -Prints the version of Ruby interpreter. +Prints the version of the Ruby interpreter, and quits immediately without +running any script. .Pp .It Fl 0 Ns Op Ar octal (The digit @@ -160,10 +171,14 @@ Causes Ruby to switch to the directory. .It Fl E Ar external Ns Op : Ns Ar internal .It Fl -encoding Ar external Ns Op : Ns Ar internal Specifies the default value(s) for external encodings and internal encoding. Values should be separated with colon (:). - -You can ommit the one for internal encodings, then the value +.Pp +You can omit the one for internal encodings, then the value .Pf ( Li "Encoding.default_internal" ) will be nil. .Pp +.It Fl -external-encoding Ns = Ns Ar encoding +.It Fl -internal-encoding Ns = Ns Ar encoding +Specify the default external or internal character encoding +.Pp .It Fl F Ar pattern Specifies input field separator .Pf ( Li "$;" ) . @@ -177,7 +192,7 @@ will be added to the load-path variable Specifies KANJI (Japanese) encoding. The default value for script encodings .Pf ( Li "__ENCODING__" ) and external encodings ( Li "Encoding.default_external" ) will be the specified one. .Ar kcode -can be one of +can be one of .Bl -hang -offset indent .It Sy e EUC-JP @@ -195,7 +210,7 @@ ASCII-8BIT (BINARY) .It Fl S Makes Ruby use the .Ev PATH -environment variable to search for script, unless if its name begins +environment variable to search for script, unless its name begins with a slash. This is used to emulate .Li #! on machines that don't support it, in the following manner: @@ -205,15 +220,27 @@ on machines that don't support it, in the following manner: exec /usr/local/bin/ruby -S $0 $* .Ed .Pp -.It Fl T Ns Op Ar level +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 and 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 T Ns Op Ar level=1 Turns on taint checks at the specified level (default 1). .Pp .It Fl U -Sets the defalut value for internal encodings +Sets the default value for internal encodings .Pf ( Li "Encoding.default_internal" ) to UTF-8. .Pp -.It Fl W Ns Op Ar level -Turns on verbose mode at the specified level, without printing version +.It Fl W Ns Op Ar level=2 +Turns on verbose mode at the specified level without printing the version message at the beginning. The level can be; .Bl -hang -offset indent .It Sy 0 @@ -231,7 +258,7 @@ Verbose mode is "verbose". It sets the .Li "$VERBOSE" to true. .Fl W Ns -2 is same as +2 is the same as .Fl w . .El @@ -245,6 +272,11 @@ In auto-split mode, Ruby executes .Dl $F = $_.split at beginning of each loop. .Pp +.It Fl -backtrace-limit Ns = Ns Ar num +Limits the maximum length of backtraces to +.Ar num +lines (default -1, meaning no limit). +.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 @@ -255,11 +287,13 @@ to the standard output. .It Fl -debug Turns on debug mode. .Li "$DEBUG" +and +.Li "$VERBOSE" will be set to true. .Pp .It Fl e Ar command Specifies script from command-line while telling Ruby not to search -the rest of arguments for a script file name. +the rest of the arguments for a script file name. .Pp .It Fl h .It Fl -help @@ -287,7 +321,7 @@ Enables automatic line-ending processing, which means to firstly set to the value of .Li "$/" , and secondly chops every line read using -.Li chop! . +.Li chomp! . .Pp .It Fl n Causes Ruby to assume the following loop around your script, which @@ -330,20 +364,8 @@ and set the corresponding variable in the script. For example: 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 -Enables verbose mode. Ruby will print its version at the beginning, +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. @@ -358,33 +380,32 @@ 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 +will be discarded until the first line that starts with .Dq #! and contains the string, .Dq ruby . -Any meaningful switches on that line will applied. The end of script +Any meaningful switches on that line will be applied. The end of the script must be specified with either .Li EOF , .Li "^D" ( Li "control-D" ) , .Li "^Z" ( Li "control-Z" ) , -or reserved word +or the 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 -DO NOT USE. - +This option is not guaranteed to be compatible. +.Pp 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. +state messages during compilation. Only specify this switch you are going to +debug the Ruby interpreter. .Pp .It Fl -disable- Ns Ar FEATURE .It Fl -enable- Ns Ar FEATURE Disables (or enables) the specified -.Ar FEATURE Ns -\&. +.Ar FEATURE . .Bl -tag -width "--disable-rubyopt" -compact .It Fl -disable-gems .It Fl -enable-gems @@ -406,30 +427,63 @@ Disables (or enables) all features. .El .Pp .It Fl -dump Ns = Ns Ar target -DO NOT USE. - +Dump some information. +.Pp Prints the specified target. .Ar target -can be one of; -.Bl -hang -offset indent -.It Sy insns -disassembed instructions +can be one of: +.Bl -hang -offset indent -width "version" +.It Sy version +Print version description (same as +.Fl -version). +.It Sy usage +Print a brief usage message (same as +.Fl h). +.It Sy help +Show long help message (same as +.Fl -help). +.It Sy syntax +Check syntax (same as +.Fl c +.Fl -yydebug). .Pp .El .Pp -You don't have to specify this switch, unless you are going to debug the Ruby interpreter. +Or one of the following, which are intended for debugging the interpreter: +.Bl -hang -offset indent -width "parsetree" +.It Sy yydebug +Enable compiler debug mode (same as +.Fl -yydebug). +.It Sy parsetree +Print a textual representation of the Ruby AST for the program. +.It Sy insns +Print a list of disassembled bytecode instructions. +.It Sy -optimize +Disable various optimizations to print a list disassembled bytecode instructions. +.It Sy +error-tolerant +Enable error-tolerant parsing, when yydebug or parsetree. +.It Sy +comment +Annotate a textual representation of the Ruby AST for the program with the associated Ruby source code. +.El .Pp .It Fl -verbose Enables verbose mode without printing version message at the beginning. It sets the .Li "$VERBOSE" variable to true. -If this switch is given, and no other switches are present, Ruby quits -after printing its version. +If this switch is given, and no script arguments (script file or +.Fl e +options) are present, Ruby quits immediately. +.Pp +.It Fl -crash-report Ns = Ns Ar template +Sets the template of path name to save crash report. +See +.Ev RUBY_CRASH_REPORT +environment variable for details. .El .Pp .Sh ENVIRONMENT -.Bl -tag -width "RUBYLIB_PREFIX" -compact +.Bl -tag -width "RUBYSHELL" -compact .It Ev RUBYLIB A colon-separated list of directories that are added to Ruby's library load path @@ -465,47 +519,319 @@ enabled for only mswin32, mingw32, and OS/2 platforms. If this variable is not defined, Ruby refers to .Ev COMSPEC . .Pp +.It Ev RUBY_FREE_AT_EXIT +If set, Ruby tries to free all dynamically allocated memories. +Introduced in Ruby 3.3, default: unset. +.Pp +.It Ev RUBY_BOX +If set to +.Li 1 , +Ruby Box is enabled and users will be able to execute +.Li Ruby::Box.new . +Ruby Box is an experimental feature introduced in Ruby 4.0. +.Pp +.It Ev RUBY_IO_BUFFER_DEFAULT_SIZE +The custom default buffer size of +.Li IO::Buffer . +.Pp +.It Ev RUBY_MAX_CPU +The maximum number of native threads used by M:N Threads scheduler +Introduced in Ruby 3.3, default: 8. +.Pp +.It Ev RUBY_MN_THREADS +If set to +.Li 1 , +M:N Thread scheduler is enabled on the main Ractor. +Introduced in Ruby 3.3, default: unset. +.Pp +.It Ev RUBY_PAGER +The pager command that will be used for +.Fl -help +option. +Introduced in Ruby 3.0, default: +.Ev PAGER +environment variable. +.Pp +.It Ev RUBY_THREAD_TIMESLICE +Sets the default thread time slice (thread quantum) in milliseconds. +Introduced in Ruby 3.4, default: 100ms. +.Pp .It Ev PATH Ruby refers to the .Ev PATH environment variable on calling Kernel#system. -.Pp -.It Ev RUBYLIB_PREFIX -This variable is obsolete. .El .Pp -And Ruby depends on some RubyGems related environment variables unless disabled RubyGems. +And Ruby depends on some RubyGems related environment variables unless RubyGems is disabled. See the help of .Xr gem 1 -as bellow. +as below. .Bd -literal -offset indent % gem help .Ed .Pp +.Sh GC ENVIRONMENT +The Ruby garbage collector (GC) tracks objects in fixed-sized slots, +but each object may have auxiliary memory allocations handled by the +malloc family of C standard library calls ( +.Xr malloc 3 , +.Xr calloc 3 , +and +.Xr realloc 3 ) . +In this documentation, the "heap" refers to the Ruby object heap +of fixed-sized slots, while "malloc" refers to auxiliary +allocations commonly referred to as the "process heap". +Thus there are at least two possible ways to trigger GC: +.Bl -hang -offset indent +.It Sy 1 +Reaching the object limit. +.It Sy 2 +Reaching the malloc limit. +.Pp +.El +In Ruby 2.1, the generational GC was introduced and the limits are divided +into young and old generations, providing two additional ways to trigger +a GC: +.Bl -hang -offset indent +.It Sy 3 +Reaching the old object limit. +.It Sy 4 +Reaching the old malloc limit. +.El +.Pp +There are currently 4 possible areas where the GC may be tuned by +the following environment variables: +.Bl -hang -compact -width "RUBY_GC_HEAP_n_INIT_SLOTS" +.Pp +.It Ev RUBY_GC_HEAP_ Ns Ar n Ns Ev _INIT_SLOTS +Initial allocation of slots in a specific heap. +The available heaps can be found in the keys of +.Li GC.stat_heap . +.Ar n +is a decimal number between 0 and 4. +Introduced in Ruby 3.3. +.Pp +.It Ev RUBY_GC_HEAP_FREE_SLOTS +Prepare at least this amount of slots after GC. +Allocate this number slots if there are not enough slots. +Introduced in Ruby 2.1, default: 4096 +.Pp +.It Ev RUBY_GC_HEAP_GROWTH_FACTOR +Increase allocation rate of heap slots by this factor. +Introduced in Ruby 2.1, default: 1.8, minimum: 1.0 (no growth) +.Pp +.It Ev RUBY_GC_HEAP_GROWTH_MAX_SLOTS +Allocation rate is limited to this number of slots, +preventing excessive allocation due to RUBY_GC_HEAP_GROWTH_FACTOR. +Introduced in Ruby 2.1, default: 0 (no limit) +.Pp +.It Ev RUBY_GC_HEAP_OLDOBJECT_LIMIT_FACTOR +Perform a full GC when the number of old objects is more than R * N, +where R is this factor and N is the number of old objects after the +last full GC. +Introduced in Ruby 2.1.1, default: 2.0 +.Pp +.It Ev RUBY_GC_HEAP_REMEMBERED_WB_UNPROTECTED_OBJECTS_LIMIT_RATIO +Used to calculate the +.Li remembered_wb_unprotected_objects_limit +using a ratio of +.Li old_objects . +Introduced in Ruby 3.3, default: 0.1, minimum: 0.0 +.It Ev RUBY_GC_MALLOC_LIMIT +The initial limit of young generation allocation from the malloc-family. +GC will start when this limit is reached. +Default: 16MB +.Pp +.It Ev RUBY_GC_MALLOC_LIMIT_MAX +The maximum limit of young generation allocation from malloc before GC starts. +Prevents excessive malloc growth due to RUBY_GC_MALLOC_LIMIT_GROWTH_FACTOR. +Introduced in Ruby 2.1, default: 32MB. +.Pp +.It Ev RUBY_GC_MALLOC_LIMIT_GROWTH_FACTOR +Increases the limit of young generation malloc calls, reducing +GC frequency but increasing malloc growth until RUBY_GC_MALLOC_LIMIT_MAX +is reached. +Introduced in Ruby 2.1, default: 1.4, minimum: 1.0 (no growth) +.Pp +.It Ev RUBY_GC_HEAP_FREE_SLOTS_MIN_RATIO +Allocate additional pages when the number of free slots is +lower than the value +.Li (total_slots * (this ratio)) . +Introduced in Ruby 2.4, default: 0.2, minimum: 0.0, maximum: 1.0 +.Pp +.It Ev RUBY_GC_HEAP_FREE_SLOTS_MAX_RATIO +Allow to free pages when the number of free slots is greater than the value +.Li (total_slots * (this ratio)) . +Introduced in Ruby 2.4, default: 0.4, minimum: +.Li RUBY_GC_HEAP_FREE_SLOTS_MIN_RATIO, +maximum: 1.0 +.Pp +.It Ev RUBY_GC_HEAP_FREE_SLOTS_GOAL_RATIO +Allocate slots to satisfy this formula: +.Li free_slots = total_slots * goal_ratio +In other words, prepare +.Li (total_slots * goal_ratio) +free slots. +if this value is 0.0, then use RUBY_GC_HEAP_GROWTH_FACTOR directly. +Introduced in Ruby 2.4, default: 0.65, minimum: +.Li RUBY_GC_HEAP_FREE_SLOTS_MIN_RATIO, +maximum: +.Li RUBY_GC_HEAP_FREE_SLOTS_MAX_RATIO +.Pp +.It Ev RUBY_GC_OLDMALLOC_LIMIT +The initial limit of old generation allocation from malloc, +a full GC will start when this limit is reached. +Introduced in Ruby 2.1, default: 16MB +.Pp +.It Ev RUBY_GC_OLDMALLOC_LIMIT_MAX +The maximum limit of old generation allocation from malloc before a +full GC starts. +Prevents excessive malloc growth due to RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR. +Introduced in Ruby 2.1, default: 128MB +.Pp +.It Ev RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR +Increases the limit of old generation malloc allocation, reducing full +GC frequency but increasing malloc growth until RUBY_GC_OLDMALLOC_LIMIT_MAX +is reached. +Introduced in Ruby 2.1, default: 1.2, minimum: 1.0 (no growth) +.Pp +.It Ev RUBY_SHARED_FIBER_POOL_FREE_STACKS +Frees stacks of pooled fibers, if set to 1. +Do not free the stacks if set to 0. +Introduced in Ruby 2.7, default: 1 (no growth) +.Pp +.It Ev RUBY_SHARED_FIBER_POOL_MAXIMUM_COUNT +If set to a non-negative integer, the shared fiber pool cannot allocate more +than that many stacks; further fiber creation may fail with +.Va FiberError . +Unset or 0 means no explicit cap (subject to process limits). +.Pp +.It Ev RUBY_SHARED_FIBER_POOL_MINIMUM_COUNT +Initial and minimum growth chunk size for the shared fiber pool (stacks). +Unset uses the implementation default. +.Pp +.El +.Sh STACK SIZE ENVIRONMENT +Stack size environment variables are implementation-dependent and +subject to change with different versions of Ruby. The VM stack is used +for pure-Ruby code and managed by the virtual machine. Machine stack is +used by the operating system and its usage is dependent on C extensions +as well as C compiler options. Using lower values for these may allow +applications to keep more Fibers or Threads running; but increases the +chance of SystemStackError exceptions and segmentation faults (SIGSEGV). +These environment variables are available since Ruby 2.0.0. +All values are specified in bytes. +.Pp +.Bl -hang -compact -width "RUBY_THREAD_MACHINE_STACK_SIZE" +.It Ev RUBY_THREAD_VM_STACK_SIZE +VM stack size used at thread creation. +default: 524288 (32-bit CPU) or 1048576 (64-bit) +.Pp +.It Ev RUBY_THREAD_MACHINE_STACK_SIZE +Machine stack size used at thread creation. +default: 524288 or 1048576 +.Pp +.It Ev RUBY_FIBER_VM_STACK_SIZE +VM stack size used at fiber creation. +default: 65536 or 131072 +.Pp +.It Ev RUBY_FIBER_MACHINE_STACK_SIZE +Machine stack size used at fiber creation. +default: 262144 or 524288 +.Pp +.El +.Sh CRASH REPORT ENVIRONMENT +.Pp +.Bl -tag -compact -width "RUBY_CRASH_REPORT" +.It Ev RUBY_CRASH_REPORT +The template of path name to save crash report. +default: none +.El +.Ss Naming crash report files +The template can contain +.Li \fB%\fP +specifiers which are substituted by the following values when a crash +report file is created: +.Pp +.Bl -hang -compact -width "%NNN" +.It Li \fB%%\fP +A single +.Li \fB%\fP +character. +.It Li \fB%e\fP +Basename of executable. +.It Li \fB%E\fP +Pathname of executable, +with slashes (\fB/\fP) replaced by exclamation marks (\fB!\fP). +.It Li \fB%f\fP +Basename of the program name, +.Li "$0" . +.It Li \fB%F\fP +Pathname of the program name, +.Li "$0", +with slashes (\fB/\fP) replaced by exclamation marks (\fB!\fP). +.It Li \fB%p\fP +PID of dumped process. +.It Li \fB%t\fP +Time of dump, expressed as seconds since the +Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.It Li \fB%NNN\fP +A character code in octal. +.El +.Pp +A single +.Li \fB%\fP +at the end of the template is dropped from the core filename, as is +the combination of a +.Li \fB%\fP +followed by any character other than those listed above. All other +characters in the template become a literal part of the core filename. +The template may include \(aq/\(aq characters, which are interpreted +as delimiters for directory names. +.Ss Piping crash reports to a program +If the first character of this file is a pipe symbol (\fB|\fP), +then the remainder of the line is interpreted as the command-line for +a program (or script) that is to be executed. +.Pp +The pipe template is split on spaces into an argument list before the +template parameters are expanded. +.Sh MISC ENVIRONMENT +.Pp +.Bl -hang -compact -width "RUBY_TCP_NO_FAST_FALLBACK" +.It Ev RUBY_TCP_NO_FAST_FALLBACK +If set to +.Li 1 , +disables the fast fallback feature by default in TCPSocket.new and Socket.tcp. +When set to +.Li 0 +or left unset, the fast fallback feature is enabled. +Introduced in Ruby 3.4, default: unset. .Sh SEE ALSO -.Bl -hang -compact -width "http://www.ruby-lang.org/123" -.It http://www.ruby-lang.org +.Bl -hang -compact -width "https://www.ruby-toolbox.com/" +.It Lk https://www.ruby-lang.org/ The official web site. -.It http://www.rubyforge.org -hosting many open source ruby projects. -.It http://raa.ruby-lang.org -Ruby Application Archive. +.It Lk https://www.ruby-toolbox.com/ +Comprehensive catalog of Ruby libraries. .El .Pp .Sh REPORTING BUGS .Bl -bullet -.Li Security vulnerabilities should be reported via an email to -.Aq security@ruby-lang.org Ns -.Li . -Reported problems will be published after fixed. -.Pp -.Li And you can report other bugs and feature requests via the -Ruby Issue Tracking System (http://redmine.ruby-lang.org). +.It +Security vulnerabilities should be reported via an email to +.Mt security@ruby-lang.org . +Reported problems will be published after being fixed. +.Pp +.It +Other bugs and feature requests can be reported via the +Ruby Issue Tracking System +.Pq Lk https://bugs.ruby-lang.org/ . Do not report security vulnerabilities -via the system because it publishes the vulnerabilities immedately. +via this system because it publishes the vulnerabilities immediately. .El .Sh AUTHORS Ruby is designed and implemented by .An Yukihiro Matsumoto Aq matz@netlab.jp . - -See <\fBhttp://redmine.ruby-lang.org/wiki/ruby/Contributors\fR> for contributors to Ruby. +.Pp +See +.Aq Lk https://github.com/ruby/ruby/graphs/contributors +for contributors to Ruby. |