diff options
Diffstat (limited to 'doc')
154 files changed, 13906 insertions, 2631 deletions
diff --git a/doc/.document b/doc/.document index ad17aada6d..8174394f48 100644 --- a/doc/.document +++ b/doc/.document @@ -1,4 +1,12 @@ *.md -*.rdoc -NEWS-* +*.rb +[^_]*.rdoc +contributing +NEWS syntax +optparse +rdoc +regexp +rjit +yjit +ruby diff --git a/doc/ChangeLog-0.06_to_0.52 b/doc/ChangeLog/ChangeLog-0.06_to_0.52 index 63826081b3..63826081b3 100644 --- a/doc/ChangeLog-0.06_to_0.52 +++ b/doc/ChangeLog/ChangeLog-0.06_to_0.52 diff --git a/doc/ChangeLog-0.50_to_0.60 b/doc/ChangeLog/ChangeLog-0.50_to_0.60 index 5f5b03ff40..5f5b03ff40 100644 --- a/doc/ChangeLog-0.50_to_0.60 +++ b/doc/ChangeLog/ChangeLog-0.50_to_0.60 diff --git a/doc/ChangeLog-0.60_to_1.1 b/doc/ChangeLog/ChangeLog-0.60_to_1.1 index ff3c376f4d..59d195e780 100644 --- a/doc/ChangeLog-0.60_to_1.1 +++ b/doc/ChangeLog/ChangeLog-0.60_to_1.1 @@ -3573,7 +3573,7 @@ Fri Mar 17 15:56:44 1995 Yukihiro Matsumoto (matz@ix-02) * dln.c: dlopenのあるマシンではそちらを使うように．ただし，ちゃん と動いているかどうかは自信がない． - * regex.c: virtual concatinationをやめた． + * regex.c: virtual concatenationをやめた． Thu Mar 16 11:32:57 1995 Yukihiro Matsumoto (matz@ix-02) diff --git a/doc/ChangeLog-1.8.0 b/doc/ChangeLog/ChangeLog-1.8.0 index 6d9453d011..6d9453d011 100644 --- a/doc/ChangeLog-1.8.0 +++ b/doc/ChangeLog/ChangeLog-1.8.0 diff --git a/doc/ChangeLog-1.9.3 b/doc/ChangeLog/ChangeLog-1.9.3 index 58e3b6f67d..0f80eed2d5 100644 --- a/doc/ChangeLog-1.9.3 +++ b/doc/ChangeLog/ChangeLog-1.9.3 @@ -23228,7 +23228,7 @@ Fri Sep 11 10:38:33 2009 URABE Shyouhei <shyouhei@ruby-lang.org> * lib/net/http.rb (Net::HTTPHeader::encode_kvpair): also call to_s to k. A patch from swdyh <youhei@gmail.com> - http://github.com/swdyh/ruby/tree/c847f43c2ccb679b9ff728f8b1b16c6ceeb57f39 + https://github.com/swdyh/ruby/tree/c847f43c2ccb679b9ff728f8b1b16c6ceeb57f39 Fri Sep 11 09:45:11 2009 Nobuyoshi Nakada <nobu@ruby-lang.org> diff --git a/doc/ChangeLog-2.0.0 b/doc/ChangeLog/ChangeLog-2.0.0 index b51d742203..9e654db189 100644 --- a/doc/ChangeLog-2.0.0 +++ b/doc/ChangeLog/ChangeLog-2.0.0 @@ -16451,7 +16451,7 @@ Mon Mar 5 17:11:44 2012 Nobuyoshi Nakada <nobu@ruby-lang.org> Exception#initialize doesn't use visible instance variable for the exception message, so call the method with the message. patched by Jingwen Owen Ou <jingweno AT gmail.com>. - http://github.com/ruby/ruby/pull/41 + https://github.com/ruby/ruby/pull/41 Mon Mar 5 16:50:22 2012 NAKAMURA Usaku <usa@ruby-lang.org> @@ -16858,13 +16858,13 @@ Fri Feb 24 13:54:33 2012 Aaron Patterson <aaron@tenderlovemaking.com> Fri Feb 24 12:07:34 2012 Ayumu AIZAWA <ayumu.aizawa@gmail.com> * lib/net/http.rb: Fix documentation. Patched from Florian Mhun - via http://github.com/ruby/ruby/pull/96 + via https://github.com/ruby/ruby/pull/96 Fri Feb 24 11:48:07 2012 Ayumu AIZAWA <ayumu.aizawa@gmail.com> * string.c (rb_str_prepend): Fix documentation for String#prepend. - Patched from Franck Verrot via http://github.com/ruby/ruby/pull/98 - and Andrew Horsman via http://github.com/ruby/ruby/pull/55 + Patched from Franck Verrot via https://github.com/ruby/ruby/pull/98 + and Andrew Horsman via https://github.com/ruby/ruby/pull/55 Fri Feb 24 10:08:33 2012 Eric Hodel <drbrain@segment7.net> diff --git a/doc/ChangeLog-2.1.0 b/doc/ChangeLog/ChangeLog-2.1.0 index 5b670b31c9..7964a682eb 100644 --- a/doc/ChangeLog-2.1.0 +++ b/doc/ChangeLog/ChangeLog-2.1.0 @@ -659,7 +659,7 @@ Mon Dec 9 02:10:32 2013 NARUSE, Yui <naruse@ruby-lang.org> * lib/net/http/responses.rb: Add `HTTPIMUsed`, as it is also supported by rack/rails. - RFC - http://tools.ietf.org/html/rfc3229 + RFC - https://www.rfc-editor.org/rfc/rfc3229 by Vipul A M <vipulnsward@gmail.com> https://github.com/ruby/ruby/pull/447 fix GH-447 diff --git a/doc/ChangeLog-2.2.0 b/doc/ChangeLog/ChangeLog-2.2.0 index 5a7dbf826d..0edcf0122b 100644 --- a/doc/ChangeLog-2.2.0 +++ b/doc/ChangeLog/ChangeLog-2.2.0 @@ -5648,7 +5648,7 @@ Wed Aug 6 04:16:05 2014 NARUSE, Yui <naruse@ruby-lang.org> * lib/net/http/requests.rb (Net::HTTP::Options::RESPONSE_HAS_BODY): OPTIONS requests may have response bodies. [Feature #8429] - http://tools.ietf.org/html/rfc7231#section-4.3.7 + https://www.rfc-editor.org/rfc/rfc7231#section-4.3.7 Wed Aug 6 03:18:04 2014 NARUSE, Yui <naruse@ruby-lang.org> diff --git a/doc/ChangeLog-2.3.0 b/doc/ChangeLog/ChangeLog-2.3.0 index 7f3c4e672a..94996cffd0 100644 --- a/doc/ChangeLog-2.3.0 +++ b/doc/ChangeLog/ChangeLog-2.3.0 @@ -170,7 +170,7 @@ Tue Dec 22 14:31:28 2015 Toru Iwase <tietew@tietew.net> should return unfrozen new string. [ruby-core:72426] [Bug #11858] -Tue Dec 22 05:39:58 2015 Takashi Kokubun <takashikkbn@gmail.com> +Tue Dec 22 05:39:58 2015 Takashi Kokubun <k0kubun@ruby-lang.org> * ext/cgi/escape/escape.c (preserve_original_state): Preserve original state for tainted and frozen. [Fix GH-1166] @@ -208,7 +208,7 @@ Mon Dec 21 09:33:17 2015 Karol Bucek <kares@users.noreply.github.com> * ext/openssl/lib/openssl/ssl.rb (OpenSSL::SSL::SSLSocket): fix NotImplementedError typo. [Fix GH-1165] -Sun Dec 20 20:54:51 2015 Takashi Kokubun <takashikkbn@gmail.com> +Sun Dec 20 20:54:51 2015 Takashi Kokubun <k0kubun@ruby-lang.org> * cgi/escape/escape.c: Optimize CGI.escapeHTML for ASCII-compatible encodings. [Fix GH-1164] @@ -476,7 +476,7 @@ Tue Dec 15 17:57:57 2015 Martin Duerst <duerst@it.aoyama.ac.jp> to the correct one in the IANA registry (IBM037) and added an alias (ebcdic-cp-us) -Tue Dec 15 16:19:26 2015 Takashi Kokubun <takashikkbn@gmail.com> +Tue Dec 15 16:19:26 2015 Takashi Kokubun <k0kubun@ruby-lang.org> * lib/erb.rb: Render erb with array buffer for function call optimization. [fix GH-1143] @@ -488,7 +488,7 @@ Tue Dec 15 13:50:05 2015 Nobuyoshi Nakada <nobu@ruby-lang.org> * string.c (rb_str_oct): [DOC] mention radix indicators. [ruby-core:71310] [Bug #11648] -Tue Dec 15 12:20:30 2015 Takashi Kokubun <takashikkbn@gmail.com> +Tue Dec 15 12:20:30 2015 Takashi Kokubun <k0kubun@ruby-lang.org> * lib/erb.rb: Simplify regexp to optimize erb scanner. [fix GH-1144] @@ -2670,7 +2670,7 @@ Sat Nov 7 09:51:38 2015 Koichi Sasada <ko1@atdot.net> * vm_trace.c (rb_threadptr_exec_event_hooks_orig): maintain trace_running counter on internal events. - This patch is made by Takashi Kokubun <takashikkbn@gmail.com>. + This patch is made by Takashi Kokubun <k0kubun@ruby-lang.org>. [Bug #11603] https://github.com/ruby/ruby/pull/1059 Sat Nov 7 03:32:27 2015 Koichi Sasada <ko1@atdot.net> @@ -5283,7 +5283,7 @@ Sat Aug 1 06:54:36 2015 Aaron Patterson <tenderlove@ruby-lang.org> * ext/openssl/ossl_ssl.c (Init_ossl_ssl): OpenSSL declares these constants as longs, so we should follow that and use LONG2NUM. - http://git.io/vOqxD + https://github.com/openssl/openssl/blob/34750dc25d74e3db4c1ba43cd219d3f4825e4c65/include/openssl/ssl.h#L391 Sat Aug 1 04:06:29 2015 Aaron Patterson <tenderlove@ruby-lang.org> @@ -6754,7 +6754,8 @@ Thu Jul 2 09:51:44 2015 SHIBATA Hiroshi <hsbt@ruby-lang.org> Thu Jul 2 06:49:44 2015 SHIBATA Hiroshi <hsbt@ruby-lang.org> * lib/rubygems: Update to RubyGems HEAD(c202db2). - this version contains many enhancements see http://git.io/vtNwF + this version contains many enhancements see + https://github.com/rubygems/rubygems/blob/c202db2d681eb3c3a02f187d346fbb2e8d733b26/History.txt#L3 * test/rubygems: ditto. Wed Jul 1 23:50:34 2015 Kazuhiro NISHIYAMA <zn@mbf.nifty.com> diff --git a/doc/ChangeLog-2.4.0 b/doc/ChangeLog/ChangeLog-2.4.0 index a297a579d1..30e9ccab3d 100644 --- a/doc/ChangeLog-2.4.0 +++ b/doc/ChangeLog/ChangeLog-2.4.0 @@ -7356,7 +7356,7 @@ Thu Mar 17 11:51:48 2016 NARUSE, Yui <naruse@ruby-lang.org> Note: CryptGenRandom function is PRNG and doesn't check its entropy, so it won't block. [Bug #12139] https://msdn.microsoft.com/ja-jp/library/windows/desktop/aa379942.aspx - https://tools.ietf.org/html/rfc4086#section-7.1.3 + https://www.rfc-editor.org/rfc/rfc4086#section-7.1.3 https://eprint.iacr.org/2007/419.pdf http://www.cs.huji.ac.il/~dolev/pubs/thesis/msc-thesis-leo.pdf diff --git a/doc/ChangeLog-YARV b/doc/ChangeLog/ChangeLog-YARV index 83df05c52c..83df05c52c 100644 --- a/doc/ChangeLog-YARV +++ b/doc/ChangeLog/ChangeLog-YARV diff --git a/doc/NEWS-1.8.7 b/doc/NEWS/NEWS-1.8.7 index 5da39ff265..5da39ff265 100644 --- a/doc/NEWS-1.8.7 +++ b/doc/NEWS/NEWS-1.8.7 diff --git a/doc/NEWS-1.9.1 b/doc/NEWS/NEWS-1.9.1 index fb11026d60..fb11026d60 100644 --- a/doc/NEWS-1.9.1 +++ b/doc/NEWS/NEWS-1.9.1 diff --git a/doc/NEWS-1.9.2 b/doc/NEWS/NEWS-1.9.2 index 430c6cc4f5..430c6cc4f5 100644 --- a/doc/NEWS-1.9.2 +++ b/doc/NEWS/NEWS-1.9.2 diff --git a/doc/NEWS-1.9.3 b/doc/NEWS/NEWS-1.9.3 index 484660f420..484660f420 100644 --- a/doc/NEWS-1.9.3 +++ b/doc/NEWS/NEWS-1.9.3 diff --git a/doc/NEWS-2.0.0 b/doc/NEWS/NEWS-2.0.0 index 712d3a693b..e070b19976 100644 --- a/doc/NEWS-2.0.0 +++ b/doc/NEWS/NEWS-2.0.0 @@ -376,7 +376,7 @@ with all sufficient information, see the ChangeLog file. :TLSv1_2, :TLSv1_2_server, :TLSv1_2_client or :TLSv1_1, :TLSv1_1_server :TLSv1_1_client. The version being effectively used can be queried with OpenSSL::SSL#ssl_version. Furthermore, it is also possible to - blacklist the new TLS versions with OpenSSL::SSL:OP_NO_TLSv1_1 and + blacklist the new TLS versions with OpenSSL::SSL::OP_NO_TLSv1_1 and OpenSSL::SSL::OP_NO_TLSv1_2. * Added OpenSSL::SSL::SSLContext#renegotiation_cb. A user-defined callback may be set which gets called whenever a new handshake is negotiated. This diff --git a/doc/NEWS-2.1.0 b/doc/NEWS/NEWS-2.1.0 index 26f2374e94..26f2374e94 100644 --- a/doc/NEWS-2.1.0 +++ b/doc/NEWS/NEWS-2.1.0 diff --git a/doc/NEWS-2.2.0 b/doc/NEWS/NEWS-2.2.0 index 8b2bd0ba0a..8b2bd0ba0a 100644 --- a/doc/NEWS-2.2.0 +++ b/doc/NEWS/NEWS-2.2.0 diff --git a/doc/NEWS-2.3.0 b/doc/NEWS/NEWS-2.3.0 index 065515257e..065515257e 100644 --- a/doc/NEWS-2.3.0 +++ b/doc/NEWS/NEWS-2.3.0 diff --git a/doc/NEWS-2.4.0 b/doc/NEWS/NEWS-2.4.0 index 8a02f03809..8a02f03809 100644 --- a/doc/NEWS-2.4.0 +++ b/doc/NEWS/NEWS-2.4.0 diff --git a/doc/NEWS-2.5.0 b/doc/NEWS/NEWS-2.5.0 index c891317b61..af7f3ada01 100644 --- a/doc/NEWS-2.5.0 +++ b/doc/NEWS/NEWS-2.5.0 @@ -466,7 +466,7 @@ with all sufficient information, see the ChangeLog file or Redmine === Compatibility issues (excluding feature bug fixes) -* Socket +* BasicSocket * BasicSocket#read_nonblock and BasicSocket#write_nonblock no longer set the O_NONBLOCK file description flag as side effect diff --git a/doc/NEWS-2.6.0 b/doc/NEWS/NEWS-2.6.0 index 6e70696de2..6e70696de2 100644 --- a/doc/NEWS-2.6.0 +++ b/doc/NEWS/NEWS-2.6.0 diff --git a/doc/NEWS-2.7.0 b/doc/NEWS/NEWS-2.7.0 index 184b47fb8b..7607a473de 100644 --- a/doc/NEWS-2.7.0 +++ b/doc/NEWS/NEWS-2.7.0 @@ -357,6 +357,16 @@ See also Warning in {Core classes updates}[#label-Core+classes+updates+-28outsta can be directly passed to another method as a block argument. [Feature #15618] + * Added Enumerator::Lazy#with_index be lazy + Previously, Enumerator::Lazy#with_index was not defined, so it + picked up the default implementation from Enumerator, which was + not lazy. [Bug #7877] + + ("a"..).lazy.with_index(1) { |it, index| puts "#{index}:#{it}" }.take(3).force + # => 1:a + # 2:b + # 3:c + [Fiber] [New method] diff --git a/doc/NEWS-3.0.0.md b/doc/NEWS/NEWS-3.0.0.md index 00c26fe585..bdbd47327b 100644 --- a/doc/NEWS-3.0.0.md +++ b/doc/NEWS/NEWS-3.0.0.md @@ -512,6 +512,18 @@ Outstanding ones only. * This version is Ractor compatible. +* URI + + * URI.escape and URI.unescape have been removed. + Instead, use the following methods depending on your specific use case. + + * CGI.escape + * URI.encode_www_form + * URI.encode_www_form_component + * CGI.unescape + * URI.decode_www_form + * URI.decode_www_form_component + ## Compatibility issues Excluding feature bug fixes. diff --git a/doc/NEWS/NEWS-3.1.0.md b/doc/NEWS/NEWS-3.1.0.md new file mode 100644 index 0000000000..fe292fc414 --- /dev/null +++ b/doc/NEWS/NEWS-3.1.0.md @@ -0,0 +1,660 @@ +# NEWS for Ruby 3.1.0 + +This document is a list of user-visible feature changes +since the **3.0.0** release, except for bug fixes. + +Note that each entry is kept to a minimum, see links for details. + +## Language changes + +* The block argument can now be anonymous if the block will + only be passed to another method. [[Feature #11256]] + + ```ruby + def foo(&) + bar(&) + end + ``` + +* Pin operator now takes an expression. [[Feature #17411]] + + ```ruby + Prime.each_cons(2).lazy.find_all{_1 in [n, ^(n + 2)]}.take(3).to_a + #=> [[3, 5], [5, 7], [11, 13]] + ``` + +* Pin operator now supports instance, class, and global variables. + [[Feature #17724]] + + ```ruby + @n = 5 + Prime.each_cons(2).lazy.find{_1 in [n, ^@n]} + #=> [3, 5] + ``` + +* One-line pattern matching is no longer experimental. + +* Parentheses can be omitted in one-line pattern matching. + [[Feature #16182]] + + ```ruby + [0, 1] => _, x + {y: 2} => y: + x #=> 1 + y #=> 2 + ``` + +* Multiple assignment evaluation order has been made consistent with + single assignment evaluation order. With single assignment, Ruby + uses a left-to-right evaluation order. With this code: + + ```ruby + foo[0] = bar + ``` + + The following evaluation order is used: + + 1. `foo` + 2. `bar` + 3. `[]=` called on the result of `foo` + + In Ruby before 3.1.0, multiple assignment did not follow this + evaluation order. With this code: + + ```ruby + foo[0], bar.baz = a, b + ``` + + Versions of Ruby before 3.1.0 would evaluate in the following + order + + 1. `a` + 2. `b` + 3. `foo` + 4. `[]=` called on the result of `foo` + 5. `bar` + 6. `baz=` called on the result of `bar` + + Starting in Ruby 3.1.0, the evaluation order is now consistent with + single assignment, with the left-hand side being evaluated before + the right-hand side: + + 1. `foo` + 2. `bar` + 3. `a` + 4. `b` + 5. `[]=` called on the result of `foo` + 6. `baz=` called on the result of `bar` + + [[Bug #4443]] + +* Values in Hash literals and keyword arguments can be omitted. + [[Feature #14579]] + + For example, + + * `{x:, y:}` is a syntax sugar of `{x: x, y: y}`. + * `foo(x:, y:)` is a syntax sugar of `foo(x: x, y: y)`. + + Constant names, local variable names, and method names are allowed as + key names. Note that a reserved word is considered as a local + variable or method name even if it's a pseudo variable name such as + `self`. + +* Non main-Ractors can get instance variables (ivars) of classes/modules + if ivars refer to shareable objects. + [[Feature #17592]] + +* A command syntax is allowed in endless method definitions, i.e., + you can now write `def foo = puts "Hello"`. + Note that `private def foo = puts "Hello"` does not parse. + [[Feature #17398]] + +## Command line options + +* `--disable-gems` is now explicitly declared as "just for debugging". + Never use it in any real-world codebase. + [[Feature #17684]] + +## Core classes updates + +Note: We're only listing outstanding class updates. + +* Array + + * Array#intersect? is added. [[Feature #15198]] + +* Class + + * Class#subclasses, which returns an array of classes + directly inheriting from the receiver, not + including singleton classes. + [[Feature #18273]] + + ```ruby + class A; end + class B < A; end + class C < B; end + class D < A; end + A.subclasses #=> [D, B] + B.subclasses #=> [C] + C.subclasses #=> [] + ``` + +* Enumerable + + * Enumerable#compact is added. [[Feature #17312]] + + * Enumerable#tally now accepts an optional hash to count. [[Feature #17744]] + + * Enumerable#each_cons and each_slice to return a receiver. [[GH-1509]] + + ```ruby + [1, 2, 3].each_cons(2){} + # 3.0 => nil + # 3.1 => [1, 2, 3] + + [1, 2, 3].each_slice(2){} + # 3.0 => nil + # 3.1 => [1, 2, 3] + ``` + +* Enumerator::Lazy + + * Enumerator::Lazy#compact is added. [[Feature #17312]] + +* File + + * File.dirname now accepts an optional argument for the level to + strip path components. [[Feature #12194]] + +* GC + + * "GC.measure_total_time = true" enables the measurement of GC. + Measurement can introduce overhead. It is enabled by default. + GC.measure_total_time returns the current setting. + GC.stat[:time] or GC.stat(:time) returns measured time + in milli-seconds. [[[Feature #10917]]] + + * GC.total_time returns measured time in nano-seconds. [[[Feature #10917]]] + +* Integer + + * Integer.try_convert is added. [[Feature #15211]] + +* Kernel + + * Kernel#load now accepts a module as the second argument, + and will load the file using the given module as the + top-level module. [[Feature #6210]] + +* Marshal + + * Marshal.load now accepts a `freeze: true` option. + All returned objects are frozen except for `Class` and + `Module` instances. Strings are deduplicated. [[Feature #18148]] + +* MatchData + + * MatchData#match is added [[Feature #18172]] + + * MatchData#match_length is added [[Feature #18172]] + +* Method / UnboundMethod + + * Method#public?, Method#private?, Method#protected?, + UnboundMethod#public?, UnboundMethod#private?, + UnboundMethod#protected? have been added. [[Feature #11689]] + +* Module + + * Module#prepend now modifies the ancestor chain if the receiver + already includes the argument. Module#prepend still does not + modify the ancestor chain if the receiver has already prepended + the argument. [[Bug #17423]] + + * Module#private, #public, #protected, and #module_function will + now return their arguments. If a single argument is given, it + is returned. If no arguments are given, nil is returned. If + multiple arguments are given, they are returned as an array. + [[Feature #12495]] + +* Process + + * Process.\_fork is added. This is a core method for fork(2). + Do not call this method directly; it is called by existing + fork methods: Kernel.#fork, Process.fork, and IO.popen("-"). + Application monitoring libraries can overwrite this method to + hook fork events. [[Feature #17795]] + +* Struct + + * Passing only keyword arguments to Struct#initialize is warned. + You need to use a Hash literal to set a Hash to a first member. + [[Feature #16806]] + + * StructClass#keyword_init? is added [[Feature #18008]] + +* String + + * Update Unicode version to 13.0.0 [[Feature #17750]] + and Emoji version to 13.0 [[Feature #18029]] + + * String#unpack and String#unpack1 now accept an `offset:` keyword + argument to start the unpacking after an arbitrary number of bytes + have been skipped. If `offset` is outside of the string bounds + `ArgumentError` is raised. [[Feature #18254]] + +* Thread + + * Thread#native_thread_id is added. [[Feature #17853]] + +* Thread::Backtrace + + * Thread::Backtrace.limit, which returns the value to limit backtrace + length set by `--backtrace-limit` command line option, is added. + [[Feature #17479]] + +* Thread::Queue + + * Thread::Queue.new now accepts an Enumerable of initial values. + [[Feature #17327]] + +* Time + + * Time.new now accepts optional `in:` keyword argument for the + timezone, as well as `Time.at` and `Time.now`, so that is now + you can omit minor arguments to `Time.new`. [[Feature #17485]] + + ```ruby + Time.new(2021, 12, 25, in: "+07:00") + #=> 2021-12-25 00:00:00 +0700 + ``` + + At the same time, time component strings are converted to + integers more strictly now. + + ```ruby + Time.new(2021, 12, 25, "+07:30") + #=> invalid value for Integer(): "+07:30" (ArgumentError) + ``` + + Ruby 3.0 or earlier returned probably unexpected result + `2021-12-25 07:00:00`, not `2021-12-25 07:30:00` nor + `2021-12-25 00:00:00 +07:30`. + + * Time#strftime supports RFC 3339 UTC for unknown offset local + time, `-0000`, as `%-z`. [[Feature #17544]] + +* TracePoint + + * TracePoint.allow_reentry is added to allow reenter while TracePoint + callback. + [[Feature #15912]] + +* $LOAD_PATH + + * $LOAD_PATH.resolve_feature_path does not raise. [[Feature #16043]] + +* Fiber Scheduler + + * Add support for `Addrinfo.getaddrinfo` using `address_resolve` hook. + [[Feature #17370]] + + * Introduce non-blocking `Timeout.timeout` using `timeout_after` hook. + [[Feature #17470]] + + * Introduce new scheduler hooks `io_read` and `io_write` along with a + low level `IO::Buffer` for zero-copy read/write. [[Feature #18020]] + + * IO hooks `io_wait`, `io_read`, `io_write`, receive the original IO object + where possible. [[Bug #18003]] + + * Make `Monitor` fiber-safe. [[Bug #17827]] + + * Replace copy coroutine with pthread implementation. [[Feature #18015]] + +* Refinement + + * New class which represents a module created by Module#refine. + `include` and `prepend` are deprecated, and `import_methods` is added + instead. [[Bug #17429]] + +## Stdlib updates + +* The following default gem are updated. + * RubyGems 3.3.3 + * base64 0.1.1 + * benchmark 0.2.0 + * bigdecimal 3.1.1 + * bundler 2.3.3 + * cgi 0.3.1 + * csv 3.2.2 + * date 3.2.2 + * did_you_mean 1.6.1 + * digest 3.1.0 + * drb 2.1.0 + * erb 2.2.3 + * error_highlight 0.3.0 + * etc 1.3.0 + * fcntl 1.0.1 + * fiddle 1.1.0 + * fileutils 1.6.0 + * find 0.1.1 + * io-console 0.5.10 + * io-wait 0.2.1 + * ipaddr 1.2.3 + * irb 1.4.1 + * json 2.6.1 + * logger 1.5.0 + * net-http 0.2.0 + * net-protocol 0.1.2 + * nkf 0.1.1 + * open-uri 0.2.0 + * openssl 3.0.0 + * optparse 0.2.0 + * ostruct 0.5.2 + * pathname 0.2.0 + * pp 0.3.0 + * prettyprint 0.1.1 + * psych 4.0.3 + * racc 1.6.0 + * rdoc 6.4.0 + * readline 0.0.3 + * readline-ext 0.1.4 + * reline 0.3.0 + * resolv 0.2.1 + * rinda 0.1.1 + * ruby2_keywords 0.0.5 + * securerandom 0.1.1 + * set 1.0.2 + * stringio 3.0.1 + * strscan 3.0.1 + * tempfile 0.1.2 + * time 0.2.0 + * timeout 0.2.0 + * tmpdir 0.1.2 + * un 0.2.0 + * uri 0.11.0 + * yaml 0.2.0 + * zlib 2.1.1 +* The following bundled gems are updated. + * minitest 5.15.0 + * power_assert 2.0.1 + * rake 13.0.6 + * test-unit 3.5.3 + * rexml 3.2.5 + * rbs 2.0.0 + * typeprof 0.21.1 +* The following default gems are now bundled gems. + * net-ftp 0.1.3 + * net-imap 0.2.2 + * net-pop 0.1.1 + * net-smtp 0.3.1 + * matrix 0.4.2 + * prime 0.1.2 + * debug 1.4.0 +* The following gems has been removed from the Ruby standard library. + * dbm + * gdbm + * tracer + +* Coverage measurement now supports suspension. You can use `Coverage.suspend` + to stop the measurement temporarily, and `Coverage.resume` to restart it. + See [[Feature #18176]] in detail. + +* Random::Formatter is moved to random/formatter.rb, so that you can + use `Random#hex`, `Random#base64`, and so on without SecureRandom. + [[Feature #18190]] + +## Compatibility issues + +Note: Excluding feature bug fixes. + +* `rb_io_wait_readable`, `rb_io_wait_writable` and `rb_wait_for_single_fd` are + deprecated in favour of `rb_io_maybe_wait_readable`, + `rb_io_maybe_wait_writable` and `rb_io_maybe_wait` respectively. + `rb_thread_wait_fd` and `rb_thread_fd_writable` are deprecated. [[Bug #18003]] + +## Stdlib compatibility issues + +* `ERB#initialize` warns `safe_level` and later arguments even without -w. + [[Feature #14256]] + +* `lib/debug.rb` is replaced with `debug.gem` + +* `Kernel#pp` in `lib/pp.rb` uses the width of `IO#winsize` by default. + This means that the output width is automatically changed depending on + your terminal size. [[Feature #12913]] + +* Psych 4.0 changes `Psych.load` as `safe_load` by the default. + You may need to use Psych 3.3.2 for migrating to this behavior. + [[Bug #17866]] + +## C API updates + +* Documented. [[GH-4815]] + +* `rb_gc_force_recycle` is deprecated and has been changed to a no-op. + [[Feature #18290]] + +## Implementation improvements + +* Inline cache mechanism is introduced for reading class variables. + [[Feature #17763]] + +* `instance_eval` and `instance_exec` now only allocate a singleton class when + required, avoiding extra objects and improving performance. [[GH-5146]] + +* The performance of `Struct` accessors is improved. [[GH-5131]] + +* `mandatory_only?` builtin special form to improve performance on + builtin methods. [[GH-5112]] + +* Experimental feature Variable Width Allocation in the garbage collector. + This feature is turned off by default and can be enabled by compiling Ruby + with flag `USE_RVARGC=1` set. [[Feature #18045]] [[Feature #18239]] + +## JIT + +* Rename Ruby 3.0's `--jit` to `--mjit`, and alias `--jit` to `--yjit` + on non-Windows x86-64 platforms and to `--mjit` on others. + +### MJIT + +* The default `--mjit-max-cache` is changed from 100 to 10000. + +* JIT-ed code is no longer cancelled when a TracePoint for class events + is enabled. + +* The JIT compiler no longer skips compilation of methods longer than + 1000 instructions. + +* `--mjit-verbose` and `--mjit-warning` output "JIT cancel" when JIT-ed + code is disabled because TracePoint or GC.compact is used. + +### YJIT: New experimental in-process JIT compiler + +New JIT compiler available as an experimental feature. [[Feature #18229]] + +See [this blog post](https://shopify.engineering/yjit-just-in-time-compiler-cruby +) introducing the project. + +* Disabled by default, use `--yjit` command-line option to enable YJIT. + +* Performance improvements on benchmarks based on real-world software, + up to 22% on railsbench, 39% on liquid-render. + +* Fast warm-up times. + +* Limited to Unix-like x86-64 platforms for now. + +## Static analysis + +### RBS + +* Generics type parameters can be bounded ([PR](https://github.com/ruby/rbs/pull/844)). + + ```rbs + # `T` must be compatible with the `_Output` interface. + # `PrettyPrint[String]` is ok, but `PrettyPrint[Integer]` is a type error. + class PrettyPrint[T < _Output] + interface _Output + def <<: (String) -> void + end + + attr_reader output: T + + def initialize: (T output) -> void + end + ``` + +* Type aliases can be generic. ([PR](https://github.com/ruby/rbs/pull/823)) + + ```rbs + # Defines a generic type `list`. + type list[T] = [ T, list[T] ] + | nil + + type str_list = list[String] + type int_list = list[Integer] + ``` + +* [rbs collection](https://github.com/ruby/rbs/blob/cdd6a3a896001e25bd1feda3eab7f470bae935c1/docs/collection.md) has been introduced to manage gems’ RBSs. + +* Many signatures for built-in and standard libraries have been added/updated. + +* It includes many bug fixes and performance improvements too. + +See the [CHANGELOG.md](https://github.com/ruby/rbs/blob/cdd6a3a896001e25bd1feda3eab7f470bae935c1/CHANGELOG.md) for more information. + +### TypeProf + +* [Experimental IDE support](https://github.com/ruby/typeprof/blob/ca15c5dae9bd62668463165f8409bd66ce7de223/doc/ide.md) has been implemented. +* Many bug fixes and performance improvements since Ruby 3.0.0. + +## Debugger + +* A new debugger [debug.gem](https://github.com/ruby/debug) is bundled. + debug.gem is a fast debugger implementation, and it provides many features + like remote debugging, colorful REPL, IDE (VSCode) integration, and more. + It replaces `lib/debug.rb` standard library. + +* `rdbg` command is also installed into `bin/` directory to start and control + debugging execution. + +## error_highlight + +A built-in gem called error_highlight has been introduced. +It shows fine-grained error locations in the backtrace. + +Example: `title = json[:article][:title]` + +If `json` is nil, it shows: + +``` +$ ruby test.rb +test.rb:2:in `<main>': undefined method `[]' for nil:NilClass (NoMethodError) + +title = json[:article][:title] + ^^^^^^^^^^ +``` + +If `json[:article]` returns nil, it shows: + +``` +$ ruby test.rb +test.rb:2:in `<main>': undefined method `[]' for nil:NilClass (NoMethodError) + +title = json[:article][:title] + ^^^^^^^^ +``` + +This feature is enabled by default. +You can disable it by using a command-line option `--disable-error_highlight`. +See [the repository](https://github.com/ruby/error_highlight) in detail. + +## IRB Autocomplete and Document Display + +The IRB now has an autocomplete feature, where you can just type in the code, and the completion candidates dialog will appear. You can use Tab and Shift+Tab to move up and down. + +If documents are installed when you select a completion candidate, the documentation dialog will appear next to the completion candidates dialog, showing part of the content. You can read the full document by pressing Alt+d. + +## Miscellaneous changes + +* lib/objspace/trace.rb is added, which is a tool for tracing the object + allocation. Just by requiring this file, tracing is started *immediately*. + Just by `Kernel#p`, you can investigate where an object was created. + Note that just requiring this file brings a large performance overhead. + This is only for debugging purposes. Do not use this in production. + [[Feature #17762]] + +* Now exceptions raised in finalizers will be printed to `STDERR`, unless + `$VERBOSE` is `nil`. [[Feature #17798]] + +* `ruby -run -e httpd` displays URLs to access. [[Feature #17847]] + +* Add `ruby -run -e colorize` to colorize Ruby code using + `IRB::Color.colorize_code`. + +[Bug #4443]: https://bugs.ruby-lang.org/issues/4443 +[Feature #6210]: https://bugs.ruby-lang.org/issues/6210 +[Feature #10917]: https://bugs.ruby-lang.org/issues/10917 +[Feature #11256]: https://bugs.ruby-lang.org/issues/11256 +[Feature #11689]: https://bugs.ruby-lang.org/issues/11689 +[Feature #12194]: https://bugs.ruby-lang.org/issues/12194 +[Feature #12495]: https://bugs.ruby-lang.org/issues/12495 +[Feature #12913]: https://bugs.ruby-lang.org/issues/12913 +[Feature #14256]: https://bugs.ruby-lang.org/issues/14256 +[Feature #14579]: https://bugs.ruby-lang.org/issues/14579 +[Feature #15198]: https://bugs.ruby-lang.org/issues/15198 +[Feature #15211]: https://bugs.ruby-lang.org/issues/15211 +[Feature #15912]: https://bugs.ruby-lang.org/issues/15912 +[Feature #16043]: https://bugs.ruby-lang.org/issues/16043 +[Feature #16182]: https://bugs.ruby-lang.org/issues/16182 +[Feature #16806]: https://bugs.ruby-lang.org/issues/16806 +[Feature #17312]: https://bugs.ruby-lang.org/issues/17312 +[Feature #17327]: https://bugs.ruby-lang.org/issues/17327 +[Feature #17370]: https://bugs.ruby-lang.org/issues/17370 +[Feature #17398]: https://bugs.ruby-lang.org/issues/17398 +[Feature #17411]: https://bugs.ruby-lang.org/issues/17411 +[Bug #17423]: https://bugs.ruby-lang.org/issues/17423 +[Bug #17429]: https://bugs.ruby-lang.org/issues/17429 +[Feature #17470]: https://bugs.ruby-lang.org/issues/17470 +[Feature #17479]: https://bugs.ruby-lang.org/issues/17479 +[Feature #17485]: https://bugs.ruby-lang.org/issues/17485 +[Feature #17544]: https://bugs.ruby-lang.org/issues/17544 +[Feature #17592]: https://bugs.ruby-lang.org/issues/17592 +[Feature #17684]: https://bugs.ruby-lang.org/issues/17684 +[Feature #17724]: https://bugs.ruby-lang.org/issues/17724 +[Feature #17744]: https://bugs.ruby-lang.org/issues/17744 +[Feature #17750]: https://bugs.ruby-lang.org/issues/17750 +[Feature #17762]: https://bugs.ruby-lang.org/issues/17762 +[Feature #17763]: https://bugs.ruby-lang.org/issues/17763 +[Feature #17795]: https://bugs.ruby-lang.org/issues/17795 +[Feature #17798]: https://bugs.ruby-lang.org/issues/17798 +[Bug #17827]: https://bugs.ruby-lang.org/issues/17827 +[Feature #17847]: https://bugs.ruby-lang.org/issues/17847 +[Feature #17853]: https://bugs.ruby-lang.org/issues/17853 +[Bug #17866]: https://bugs.ruby-lang.org/issues/17866 +[Bug #18003]: https://bugs.ruby-lang.org/issues/18003 +[Feature #18008]: https://bugs.ruby-lang.org/issues/18008 +[Feature #18015]: https://bugs.ruby-lang.org/issues/18015 +[Feature #18020]: https://bugs.ruby-lang.org/issues/18020 +[Feature #18029]: https://bugs.ruby-lang.org/issues/18029 +[Feature #18045]: https://bugs.ruby-lang.org/issues/18045 +[Feature #18148]: https://bugs.ruby-lang.org/issues/18148 +[Feature #18172]: https://bugs.ruby-lang.org/issues/18172 +[Feature #18176]: https://bugs.ruby-lang.org/issues/18176 +[Feature #18190]: https://bugs.ruby-lang.org/issues/18190 +[Feature #18229]: https://bugs.ruby-lang.org/issues/18229 +[Feature #18239]: https://bugs.ruby-lang.org/issues/18239 +[Feature #18254]: https://bugs.ruby-lang.org/issues/18254 +[Feature #18273]: https://bugs.ruby-lang.org/issues/18273 +[Feature #18290]: https://bugs.ruby-lang.org/issues/18290 + +[GH-1509]: https://github.com/ruby/ruby/pull/1509 +[GH-4815]: https://github.com/ruby/ruby/pull/4815 +[GH-5112]: https://github.com/ruby/ruby/pull/5112 +[GH-5131]: https://github.com/ruby/ruby/pull/5131 +[GH-5146]: https://github.com/ruby/ruby/pull/5146 diff --git a/doc/NEWS/NEWS-3.2.0.md b/doc/NEWS/NEWS-3.2.0.md new file mode 100644 index 0000000000..33a7b85c47 --- /dev/null +++ b/doc/NEWS/NEWS-3.2.0.md @@ -0,0 +1,820 @@ +# NEWS for Ruby 3.2.0 + +This document is a list of user-visible feature changes +since the **3.1.0** release, except for bug fixes. + +Note that each entry is kept to a minimum, see links for details. + +## Language changes + +* Anonymous rest and keyword rest arguments can now be passed as + arguments, instead of just used in method parameters. + [[Feature #18351]] + + ```ruby + def foo(*) + bar(*) + end + def baz(**) + quux(**) + end + ``` + +* A proc that accepts a single positional argument and keywords will + no longer autosplat. [[Bug #18633]] + + ```ruby + proc{|a, **k| a}.call([1, 2]) + # Ruby 3.1 and before + # => 1 + # Ruby 3.2 and after + # => [1, 2] + ``` + +* Constant assignment evaluation order for constants set on explicit + objects has been made consistent with single attribute assignment + evaluation order. With this code: + + ```ruby + foo::BAR = baz + ``` + + `foo` is now called before `baz`. Similarly, for multiple assignments + to constants, left-to-right evaluation order is used. With this + code: + + ```ruby + foo1::BAR1, foo2::BAR2 = baz1, baz2 + ``` + + The following evaluation order is now used: + + 1. `foo1` + 2. `foo2` + 3. `baz1` + 4. `baz2` + + [[Bug #15928]] + +* "Find pattern" is no longer experimental. + [[Feature #18585]] + +* Methods taking a rest parameter (like `*args`) and wishing to delegate keyword + arguments through `foo(*args)` must now be marked with `ruby2_keywords` + (if not already the case). In other words, all methods wishing to delegate + keyword arguments through `*args` must now be marked with `ruby2_keywords`, + with no exception. This will make it easier to transition to other ways of + delegation once a library can require Ruby 3+. Previously, the `ruby2_keywords` + flag was kept if the receiving method took `*args`, but this was a bug and an + inconsistency. A good technique to find the potentially-missing `ruby2_keywords` + is to run the test suite, for where it fails find the last method which must + receive keyword arguments, use `puts nil, caller, nil` there, and check each + method/block on the call chain which must delegate keywords is correctly marked + as `ruby2_keywords`. [[Bug #18625]] [[Bug #16466]] + + ```ruby + def target(**kw) + end + + # Accidentally worked without ruby2_keywords in Ruby 2.7-3.1, ruby2_keywords + # needed in 3.2+. Just like (*args, **kwargs) or (...) would be needed on + # both #foo and #bar when migrating away from ruby2_keywords. + ruby2_keywords def bar(*args) + target(*args) + end + + ruby2_keywords def foo(*args) + bar(*args) + end + + foo(k: 1) + ``` + +## Core classes updates + +Note: We're only listing outstanding class updates. + +* Fiber + + * Introduce Fiber.[] and Fiber.[]= for inheritable fiber storage. + Introduce Fiber#storage and Fiber#storage= (experimental) for + getting and resetting the current storage. Introduce + `Fiber.new(storage:)` for setting the storage when creating a + fiber. [[Feature #19078]] + + Existing Thread and Fiber local variables can be tricky to use. + Thread-local variables are shared between all fibers, making it + hard to isolate, while Fiber-local variables can be hard to + share. It is often desirable to define unit of execution + ("execution context") such that some state is shared between all + fibers and threads created in that context. This is what Fiber + storage provides. + + ```ruby + def log(message) + puts "#{Fiber[:request_id]}: #{message}" + end + + def handle_requests + while request = read_request + Fiber.schedule do + Fiber[:request_id] = SecureRandom.uuid + + request.messages.each do |message| + Fiber.schedule do + log("Handling #{message}") # Log includes inherited request_id. + end + end + end + end + end + ``` + + You should generally consider Fiber storage for any state which + you want to be shared implicitly between all fibers and threads + created in a given context, e.g. a connection pool, a request + id, a logger level, environment variables, configuration, etc. + +* Fiber::Scheduler + + * Introduce `Fiber::Scheduler#io_select` for non-blocking IO.select. + [[Feature #19060]] + +* IO + + * Introduce IO#timeout= and IO#timeout which can cause + IO::TimeoutError to be raised if a blocking operation exceeds the + specified timeout. [[Feature #18630]] + + ```ruby + STDIN.timeout = 1 + STDIN.read # => Blocking operation timed out! (IO::TimeoutError) + ``` + + * Introduce `IO.new(..., path:)` and promote `File#path` to `IO#path`. + [[Feature #19036]] + +* Class + + * Class#attached_object, which returns the object for which + the receiver is the singleton class. Raises TypeError if the + receiver is not a singleton class. + [[Feature #12084]] + + ```ruby + class Foo; end + + Foo.singleton_class.attached_object #=> Foo + Foo.new.singleton_class.attached_object #=> #<Foo:0x000000010491a370> + Foo.attached_object #=> TypeError: `Foo' is not a singleton class + nil.singleton_class.attached_object #=> TypeError: `NilClass' is not a singleton class + ``` + +* Data + + * New core class to represent simple immutable value object. The class is + similar to Struct and partially shares an implementation, but has more + lean and strict API. [[Feature #16122]] + + ```ruby + Measure = Data.define(:amount, :unit) + distance = Measure.new(100, 'km') #=> #<data Measure amount=100, unit="km"> + weight = Measure.new(amount: 50, unit: 'kg') #=> #<data Measure amount=50, unit="kg"> + weight.with(amount: 40) #=> #<data Measure amount=40, unit="kg"> + weight.amount #=> 50 + weight.amount = 40 #=> NoMethodError: undefined method `amount=' + ``` + +* Encoding + + * Encoding#replicate has been deprecated and will be removed in 3.3. [[Feature #18949]] + * The dummy `Encoding::UTF_16` and `Encoding::UTF_32` encodings no longer + try to dynamically guess the endian based on a byte order mark. + Use `Encoding::UTF_16BE`/`UTF_16LE` and `Encoding::UTF_32BE`/`UTF_32LE` instead. + This change speeds up getting the encoding of a String. [[Feature #18949]] + * Limit maximum encoding set size by 256. + If exceeding maximum size, `EncodingError` will be raised. [[Feature #18949]] + +* Enumerator + + * Enumerator.product has been added. Enumerator::Product is the implementation. [[Feature #18685]] + +* Exception + + * Exception#detailed_message has been added. + The default error printer calls this method on the Exception object + instead of #message. [[Feature #18564]] + +* Hash + + * Hash#shift now always returns nil if the hash is + empty, instead of returning the default value or + calling the default proc. [[Bug #16908]] + +* Integer + + * Integer#ceildiv has been added. [[Feature #18809]] + +* Kernel + + * Kernel#binding raises RuntimeError if called from a non-Ruby frame + (such as a method defined in C). [[Bug #18487]] + +* MatchData + + * MatchData#byteoffset has been added. [[Feature #13110]] + * MatchData#deconstruct has been added. [[Feature #18821]] + * MatchData#deconstruct_keys has been added. [[Feature #18821]] + +* Module + + * Module.used_refinements has been added. [[Feature #14332]] + * Module#refinements has been added. [[Feature #12737]] + * Module#const_added has been added. [[Feature #17881]] + * Module#undefined_instance_methods has been added. [[Feature #12655]] + +* Proc + + * Proc#dup returns an instance of subclass. [[Bug #17545]] + * Proc#parameters now accepts lambda keyword. [[Feature #15357]] + +* Process + * Added `RLIMIT_NPTS` constant to FreeBSD platform + +* Regexp + + * The cache-based optimization is introduced. + Many (but not all) Regexp matching is now in linear time, which + will prevent regular expression denial of service (ReDoS) + vulnerability. [[Feature #19104]] + + * Regexp.linear_time? is introduced. [[Feature #19194]] + + * Regexp.new now supports passing the regexp flags not only as an Integer, + but also as a String. Unknown flags raise ArgumentError. + Otherwise, anything other than `true`, `false`, `nil` or Integer will be warned. + [[Feature #18788]] + + * Regexp.timeout= has been added. Also, Regexp.new new supports timeout keyword. + See [[Feature #17837]] + +* Refinement + + * Refinement#refined_class has been added. [[Feature #12737]] + +* RubyVM::AbstractSyntaxTree + + * Add `error_tolerant` option for `parse`, `parse_file` and `of`. [[Feature #19013]] + With this option + + 1. SyntaxError is suppressed + 2. AST is returned for invalid input + 3. `end` is complemented when a parser reaches to the end of input but `end` is insufficient + 4. `end` is treated as keyword based on indent + + ```ruby + # Without error_tolerant option + root = RubyVM::AbstractSyntaxTree.parse(<<~RUBY) + def m + a = 10 + if + end + RUBY + # => <internal:ast>:33:in `parse': syntax error, unexpected `end' (SyntaxError) + + # With error_tolerant option + root = RubyVM::AbstractSyntaxTree.parse(<<~RUBY, error_tolerant: true) + def m + a = 10 + if + end + RUBY + p root # => #<RubyVM::AbstractSyntaxTree::Node:SCOPE@1:0-4:3> + + # `end` is treated as keyword based on indent + root = RubyVM::AbstractSyntaxTree.parse(<<~RUBY, error_tolerant: true) + module Z + class Foo + foo. + end + + def bar + end + end + RUBY + p root.children[-1].children[-1].children[-1].children[-2..-1] + # => [#<RubyVM::AbstractSyntaxTree::Node:CLASS@2:2-4:5>, #<RubyVM::AbstractSyntaxTree::Node:DEFN@6:2-7:5>] + ``` + + * Add `keep_tokens` option for `parse`, `parse_file` and `of`. Add `#tokens` and `#all_tokens` + for RubyVM::AbstractSyntaxTree::Node [[Feature #19070]] + + ```ruby + root = RubyVM::AbstractSyntaxTree.parse("x = 1 + 2", keep_tokens: true) + root.tokens # => [[0, :tIDENTIFIER, "x", [1, 0, 1, 1]], [1, :tSP, " ", [1, 1, 1, 2]], ...] + root.tokens.map{_1[2]}.join # => "x = 1 + 2" + ``` + +* Set + + * Set is now available as a built-in class without the need for `require "set"`. [[Feature #16989]] + It is currently autoloaded via the Set constant or a call to Enumerable#to_set. + +* String + + * String#byteindex and String#byterindex have been added. [[Feature #13110]] + * Update Unicode to Version 15.0.0 and Emoji Version 15.0. [[Feature #18639]] + (also applies to Regexp) + * String#bytesplice has been added. [[Feature #18598]] + * String#dedup has been added as an alias to String#-@. [[Feature #18595]] + +* Struct + + * A Struct class can also be initialized with keyword arguments + without `keyword_init: true` on Struct.new [[Feature #16806]] + + ```ruby + Post = Struct.new(:id, :name) + Post.new(1, "hello") #=> #<struct Post id=1, name="hello"> + # From Ruby 3.2, the following code also works without keyword_init: true. + Post.new(id: 1, name: "hello") #=> #<struct Post id=1, name="hello"> + ``` + +* Thread + + * Thread.each_caller_location is added. [[Feature #16663]] + +* Thread::Queue + + * Thread::Queue#pop(timeout: sec) is added. [[Feature #18774]] + +* Thread::SizedQueue + + * Thread::SizedQueue#pop(timeout: sec) is added. [[Feature #18774]] + * Thread::SizedQueue#push(timeout: sec) is added. [[Feature #18944]] + +* Time + + * Time#deconstruct_keys is added, allowing to use Time instances + in pattern-matching expressions [[Feature #19071]] + + * Time.new now can parse a string like generated by Time#inspect + and return a Time instance based on the given argument. + [[Feature #18033]] + +* SyntaxError + * SyntaxError#path has been added. [[Feature #19138]] + +* TracePoint + + * TracePoint#binding now returns `nil` for `c_call`/`c_return` TracePoints. + [[Bug #18487]] + * TracePoint#enable `target_thread` keyword argument now defaults to the + current thread if a block is given and `target` and `target_line` keyword + arguments are not passed. [[Bug #16889]] + +* UnboundMethod + + * `UnboundMethod#==` returns `true` if the actual method is same. For example, + `String.instance_method(:object_id) == Array.instance_method(:object_id)` + returns `true`. [[Feature #18798]] + + * `UnboundMethod#inspect` does not show the receiver of `instance_method`. + For example `String.instance_method(:object_id).inspect` returns + `"#<UnboundMethod: Kernel#object_id()>"` + (was `"#<UnboundMethod: String(Kernel)#object_id()>"`). + +* GC + + * Expose `need_major_gc` via `GC.latest_gc_info`. [GH-6791] + +* ObjectSpace + + * `ObjectSpace.dump_all` dump shapes as well. [GH-6868] + +## Stdlib updates + +* Bundler + + * Bundler now uses [PubGrub] resolver instead of [Molinillo] for performance improvement. + * Add --ext=rust support to bundle gem for creating simple gems with Rust extensions. + [[GH-rubygems-6149]] + * Make cloning git repos faster [[GH-rubygems-4475]] + +* RubyGems + + * Add mswin support for cargo builder. [[GH-rubygems-6167]] + +* CGI + + * `CGI.escapeURIComponent` and `CGI.unescapeURIComponent` are added. + [[Feature #18822]] + +* Coverage + + * `Coverage.setup` now accepts `eval: true`. By this, `eval` and related methods are + able to generate code coverage. [[Feature #19008]] + + * `Coverage.supported?(mode)` enables detection of what coverage modes are + supported. [[Feature #19026]] + +* Date + + * Added `Date#deconstruct_keys` and `DateTime#deconstruct_keys` same as [[Feature #19071]] + +* ERB + + * `ERB::Util.html_escape` is made faster than `CGI.escapeHTML`. + * It no longer allocates a String object when no character needs to be escaped. + * It skips calling `#to_s` method when an argument is already a String. + * `ERB::Escape.html_escape` is added as an alias to `ERB::Util.html_escape`, + which has not been monkey-patched by Rails. + * `ERB::Util.url_encode` is made faster using `CGI.escapeURIComponent`. + * `-S` option is removed from `erb` command. + +* FileUtils + + * Add FileUtils.ln_sr method and `relative:` option to FileUtils.ln_s. + [[Feature #18925]] + +* IRB + + * debug.gem integration commands have been added: `debug`, `break`, `catch`, + `next`, `delete`, `step`, `continue`, `finish`, `backtrace`, `info` + * They work even if you don't have `gem "debug"` in your Gemfile. + * See also: [What's new in Ruby 3.2's IRB?](https://st0012.dev/whats-new-in-ruby-3-2-irb) + * More Pry-like commands and features have been added. + * `edit` and `show_cmds` (like Pry's `help`) are added. + * `ls` takes `-g` or `-G` option to filter out outputs. + * `show_source` is aliased from `$` and accepts unquoted inputs. + * `whereami` is aliased from `@`. + +* Net::Protocol + + * Improve `Net::BufferedIO` performance. [[GH-net-protocol-14]] + +* Pathname + + * Added `Pathname#lutime`. [[GH-pathname-20]] + +* Socket + + * Added the following constants for supported platforms. + * `SO_INCOMING_CPU` + * `SO_INCOMING_NAPI_ID` + * `SO_RTABLE` + * `SO_SETFIB` + * `SO_USER_COOKIE` + * `TCP_KEEPALIVE` + * `TCP_CONNECTION_INFO` + +* SyntaxSuggest + + * The feature of `syntax_suggest` formerly `dead_end` is integrated in Ruby. + [[Feature #18159]] + +* UNIXSocket + + * Add support for UNIXSocket on Windows. Emulate anonymous sockets. Add + support for File.socket? and File::Stat#socket? where possible. + [[Feature #19135]] + +* The following default gems are updated. + + * RubyGems 3.4.1 + * abbrev 0.1.1 + * benchmark 0.2.1 + * bigdecimal 3.1.3 + * bundler 2.4.1 + * cgi 0.3.6 + * csv 3.2.6 + * date 3.3.3 + * delegate 0.3.0 + * did_you_mean 1.6.3 + * digest 3.1.1 + * drb 2.1.1 + * english 0.7.2 + * erb 4.0.2 + * error_highlight 0.5.1 + * etc 1.4.2 + * fcntl 1.0.2 + * fiddle 1.1.1 + * fileutils 1.7.0 + * forwardable 1.3.3 + * getoptlong 0.2.0 + * io-console 0.6.0 + * io-nonblock 0.2.0 + * io-wait 0.3.0 + * ipaddr 1.2.5 + * irb 1.6.2 + * json 2.6.3 + * logger 1.5.3 + * mutex_m 0.1.2 + * net-http 0.3.2 + * net-protocol 0.2.1 + * nkf 0.1.2 + * open-uri 0.3.0 + * open3 0.1.2 + * openssl 3.1.0 + * optparse 0.3.1 + * ostruct 0.5.5 + * pathname 0.2.1 + * pp 0.4.0 + * pstore 0.1.2 + * psych 5.0.1 + * racc 1.6.2 + * rdoc 6.5.0 + * readline-ext 0.1.5 + * reline 0.3.2 + * resolv 0.2.2 + * resolv-replace 0.1.1 + * securerandom 0.2.2 + * set 1.0.3 + * stringio 3.0.4 + * strscan 3.0.5 + * syntax_suggest 1.0.2 + * syslog 0.1.1 + * tempfile 0.1.3 + * time 0.2.1 + * timeout 0.3.1 + * tmpdir 0.1.3 + * tsort 0.1.1 + * un 0.2.1 + * uri 0.12.0 + * weakref 0.1.2 + * win32ole 1.8.9 + * yaml 0.2.1 + * zlib 3.0.0 + +* The following bundled gems are updated. + + * minitest 5.16.3 + * power_assert 2.0.3 + * test-unit 3.5.7 + * net-ftp 0.2.0 + * net-imap 0.3.4 + * net-pop 0.1.2 + * net-smtp 0.3.3 + * rbs 2.8.2 + * typeprof 0.21.3 + * debug 1.7.1 + +See GitHub releases like [GitHub Releases of Logger](https://github.com/ruby/logger/releases) or changelog for details of the default gems or bundled gems. + +## Supported platforms + +* WebAssembly/WASI is added. See [wasm/README.md] and [ruby.wasm] for more details. [[Feature #18462]] + +## Compatibility issues + +* `String#to_c` currently treat a sequence of underscores as an end of Complex + string. [[Bug #19087]] + +* Now `ENV.clone` raises `TypeError` as well as `ENV.dup` [[Bug #17767]] + +### Removed constants + +The following deprecated constants are removed. + +* `Fixnum` and `Bignum` [[Feature #12005]] +* `Random::DEFAULT` [[Feature #17351]] +* `Struct::Group` +* `Struct::Passwd` + +### Removed methods + +The following deprecated methods are removed. + +* `Dir.exists?` [[Feature #17391]] +* `File.exists?` [[Feature #17391]] +* `Kernel#=~` [[Feature #15231]] +* `Kernel#taint`, `Kernel#untaint`, `Kernel#tainted?` + [[Feature #16131]] +* `Kernel#trust`, `Kernel#untrust`, `Kernel#untrusted?` + [[Feature #16131]] +* `Method#public?`, `Method#private?`, `Method#protected?`, + `UnboundMethod#public?`, `UnboundMethod#private?`, `UnboundMethod#protected?` + [[Bug #18729]] [[Bug #18751]] [[Bug #18435]] + +### Source code incompatibility of extension libraries + +* Extension libraries provide PRNG, subclasses of Random, need updates. + See [PRNG update] below for more information. [[Bug #19100]] + +### Error printer + +* Ruby no longer escapes control characters and backslashes in an + error message. [[Feature #18367]] + +### Constant lookup when defining a class/module + +* When defining a class/module directly under the Object class by class/module + statement, if there is already a class/module defined by `Module#include` + with the same name, the statement was handled as "open class" in Ruby 3.1 or before. + Since Ruby 3.2, a new class is defined instead. [[Feature #18832]] + +## Stdlib compatibility issues + +* Psych no longer bundles libyaml sources. + And also Fiddle no longer bundles libffi sources. + Users need to install the libyaml/libffi library themselves via the package + manager like apt, yum, brew, etc. + + Psych and fiddle supported the static build with specific version of libyaml + and libffi sources. You can build psych with libyaml-0.2.5 like this. + + ```bash + $ ./configure --with-libyaml-source-dir=/path/to/libyaml-0.2.5 + ``` + + And you can build fiddle with libffi-3.4.4 like this. + + ```bash + $ ./configure --with-libffi-source-dir=/path/to/libffi-3.4.4 + ``` + + [[Feature #18571]] + +* Check cookie name/path/domain characters in `CGI::Cookie`. [[CVE-2021-33621]] + +* `URI.parse` return empty string in host instead of nil. [[sec-156615]] + +## C API updates + +### Updated C APIs + +The following APIs are updated. + +* PRNG update + + `rb_random_interface_t` in ruby/random.h updated and versioned. + Extension libraries which use this interface and built for older + versions need to rebuild with adding `init_int32` function. + +### Added C APIs + +* `VALUE rb_hash_new_capa(long capa)` was added to created hashes with the desired capacity. +* `rb_internal_thread_add_event_hook` and `rb_internal_thread_add_event_hook` were added to instrument threads scheduling. + The following events are available: + * `RUBY_INTERNAL_THREAD_EVENT_STARTED` + * `RUBY_INTERNAL_THREAD_EVENT_READY` + * `RUBY_INTERNAL_THREAD_EVENT_RESUMED` + * `RUBY_INTERNAL_THREAD_EVENT_SUSPENDED` + * `RUBY_INTERNAL_THREAD_EVENT_EXITED` +* `rb_debug_inspector_current_depth` and `rb_debug_inspector_frame_depth` are added for debuggers. + +### Removed C APIs + +The following deprecated APIs are removed. + +* `rb_cData` variable. +* "taintedness" and "trustedness" functions. [[Feature #16131]] + +## Implementation improvements + +* Fixed several race conditions in Kernel#autoload. [[Bug #18782]] +* Cache invalidation for expressions referencing constants is now + more fine-grained. `RubyVM.stat(:global_constant_state)` was + removed because it was closely tied to the previous caching scheme + where setting any constant invalidates all caches in the system. + New keys, `:constant_cache_invalidations` and `:constant_cache_misses`, + were introduced to help with use cases for `:global_constant_state`. + [[Feature #18589]] +* The cache-based optimization for Regexp matching is introduced. + [[Feature #19104]] +* [Variable Width Allocation](https://shopify.engineering/ruby-variable-width-allocation) + is now enabled by default. [[Feature #18239]] +* Added a new instance variable caching mechanism, called object shapes, which + improves inline cache hits for most objects and allows us to generate very + efficient JIT code. Objects whose instance variables are defined in a + consistent order will see the most performance benefits. + [[Feature #18776]] +* Speed up marking instruction sequences by using a bitmap to find "markable" + objects. This change results in faster major collections. + [[Feature #18875]] + +## JIT + +### YJIT + +* YJIT is no longer experimental + * Has been tested on production workloads for over a year and proven to be quite stable. +* YJIT now supports both x86-64 and arm64/aarch64 CPUs on Linux, MacOS, BSD and other UNIX platforms. + * This release brings support for Mac M1/M2, AWS Graviton and Raspberry Pi 4. +* Building YJIT now requires Rust 1.58.0+. [[Feature #18481]] + * In order to ensure that CRuby is built with YJIT, please install `rustc` >= 1.58.0 + before running `./configure` + * Please reach out to the YJIT team should you run into any issues. +* Physical memory for JIT code is lazily allocated. Unlike Ruby 3.1, + the RSS of a Ruby process is minimized because virtual memory pages + allocated by `--yjit-exec-mem-size` will not be mapped to physical + memory pages until actually utilized by JIT code. +* Introduce Code GC that frees all code pages when the memory consumption + by JIT code reaches `--yjit-exec-mem-size`. + * `RubyVM::YJIT.runtime_stats` returns Code GC metrics in addition to + existing `inline_code_size` and `outlined_code_size` keys: + `code_gc_count`, `live_page_count`, `freed_page_count`, and `freed_code_size`. +* Most of the statistics produced by `RubyVM::YJIT.runtime_stats` are now available in release builds. + * Simply run ruby with `--yjit-stats` to compute and dump stats (incurs some run-time overhead). +* YJIT is now optimized to take advantage of object shapes. [[Feature #18776]] +* Take advantage of finer-grained constant invalidation to invalidate less code when defining new constants. [[Feature #18589]] +* The default `--yjit-exec-mem-size` is changed to 64 (MiB). +* The default `--yjit-call-threshold` is changed to 30. + +### MJIT + +* The MJIT compiler is re-implemented in Ruby as `ruby_vm/mjit/compiler`. +* MJIT compiler is executed under a forked Ruby process instead of + doing it in a native thread called MJIT worker. [[Feature #18968]] + * As a result, Microsoft Visual Studio (MSWIN) is no longer supported. +* MinGW is no longer supported. [[Feature #18824]] +* Rename `--mjit-min-calls` to `--mjit-call-threshold`. +* Change default `--mjit-max-cache` back from 10000 to 100. + +[Feature #12005]: https://bugs.ruby-lang.org/issues/12005 +[Feature #12084]: https://bugs.ruby-lang.org/issues/12084 +[Feature #12655]: https://bugs.ruby-lang.org/issues/12655 +[Feature #12737]: https://bugs.ruby-lang.org/issues/12737 +[Feature #13110]: https://bugs.ruby-lang.org/issues/13110 +[Feature #14332]: https://bugs.ruby-lang.org/issues/14332 +[Feature #15231]: https://bugs.ruby-lang.org/issues/15231 +[Feature #15357]: https://bugs.ruby-lang.org/issues/15357 +[Bug #15928]: https://bugs.ruby-lang.org/issues/15928 +[Feature #16122]: https://bugs.ruby-lang.org/issues/16122 +[Feature #16131]: https://bugs.ruby-lang.org/issues/16131 +[Bug #16466]: https://bugs.ruby-lang.org/issues/16466 +[Feature #16663]: https://bugs.ruby-lang.org/issues/16663 +[Feature #16806]: https://bugs.ruby-lang.org/issues/16806 +[Bug #16889]: https://bugs.ruby-lang.org/issues/16889 +[Bug #16908]: https://bugs.ruby-lang.org/issues/16908 +[Feature #16989]: https://bugs.ruby-lang.org/issues/16989 +[Feature #17351]: https://bugs.ruby-lang.org/issues/17351 +[Feature #17391]: https://bugs.ruby-lang.org/issues/17391 +[Bug #17545]: https://bugs.ruby-lang.org/issues/17545 +[Bug #17767]: https://bugs.ruby-lang.org/issues/17767 +[Feature #17837]: https://bugs.ruby-lang.org/issues/17837 +[Feature #17881]: https://bugs.ruby-lang.org/issues/17881 +[Feature #18033]: https://bugs.ruby-lang.org/issues/18033 +[Feature #18159]: https://bugs.ruby-lang.org/issues/18159 +[Feature #18239]: https://bugs.ruby-lang.org/issues/18239#note-17 +[Feature #18351]: https://bugs.ruby-lang.org/issues/18351 +[Feature #18367]: https://bugs.ruby-lang.org/issues/18367 +[Bug #18435]: https://bugs.ruby-lang.org/issues/18435 +[Feature #18462]: https://bugs.ruby-lang.org/issues/18462 +[Feature #18481]: https://bugs.ruby-lang.org/issues/18481 +[Bug #18487]: https://bugs.ruby-lang.org/issues/18487 +[Feature #18564]: https://bugs.ruby-lang.org/issues/18564 +[Feature #18571]: https://bugs.ruby-lang.org/issues/18571 +[Feature #18585]: https://bugs.ruby-lang.org/issues/18585 +[Feature #18589]: https://bugs.ruby-lang.org/issues/18589 +[Feature #18595]: https://bugs.ruby-lang.org/issues/18595 +[Feature #18598]: https://bugs.ruby-lang.org/issues/18598 +[Bug #18625]: https://bugs.ruby-lang.org/issues/18625 +[Feature #18630]: https://bugs.ruby-lang.org/issues/18630 +[Bug #18633]: https://bugs.ruby-lang.org/issues/18633 +[Feature #18639]: https://bugs.ruby-lang.org/issues/18639 +[Feature #18685]: https://bugs.ruby-lang.org/issues/18685 +[Bug #18729]: https://bugs.ruby-lang.org/issues/18729 +[Bug #18751]: https://bugs.ruby-lang.org/issues/18751 +[Feature #18774]: https://bugs.ruby-lang.org/issues/18774 +[Feature #18776]: https://bugs.ruby-lang.org/issues/18776 +[Bug #18782]: https://bugs.ruby-lang.org/issues/18782 +[Feature #18788]: https://bugs.ruby-lang.org/issues/18788 +[Feature #18798]: https://bugs.ruby-lang.org/issues/18798 +[Feature #18809]: https://bugs.ruby-lang.org/issues/18809 +[Feature #18821]: https://bugs.ruby-lang.org/issues/18821 +[Feature #18822]: https://bugs.ruby-lang.org/issues/18822 +[Feature #18824]: https://bugs.ruby-lang.org/issues/18824 +[Feature #18832]: https://bugs.ruby-lang.org/issues/18832 +[Feature #18875]: https://bugs.ruby-lang.org/issues/18875 +[Feature #18925]: https://bugs.ruby-lang.org/issues/18925 +[Feature #18944]: https://bugs.ruby-lang.org/issues/18944 +[Feature #18949]: https://bugs.ruby-lang.org/issues/18949 +[Feature #18968]: https://bugs.ruby-lang.org/issues/18968 +[Feature #19008]: https://bugs.ruby-lang.org/issues/19008 +[Feature #19013]: https://bugs.ruby-lang.org/issues/19013 +[Feature #19026]: https://bugs.ruby-lang.org/issues/19026 +[Feature #19036]: https://bugs.ruby-lang.org/issues/19036 +[Feature #19060]: https://bugs.ruby-lang.org/issues/19060 +[Feature #19070]: https://bugs.ruby-lang.org/issues/19070 +[Feature #19071]: https://bugs.ruby-lang.org/issues/19071 +[Feature #19078]: https://bugs.ruby-lang.org/issues/19078 +[Bug #19087]: https://bugs.ruby-lang.org/issues/19087 +[Bug #19100]: https://bugs.ruby-lang.org/issues/19100 +[Feature #19104]: https://bugs.ruby-lang.org/issues/19104 +[Feature #19135]: https://bugs.ruby-lang.org/issues/19135 +[Feature #19138]: https://bugs.ruby-lang.org/issues/19138 +[Feature #19194]: https://bugs.ruby-lang.org/issues/19194 +[Molinillo]: https://github.com/CocoaPods/Molinillo +[PubGrub]: https://github.com/jhawthorn/pub_grub +[GH-net-protocol-14]: https://github.com/ruby/net-protocol/pull/14 +[GH-pathname-20]: https://github.com/ruby/pathname/pull/20 +[GH-6791]: https://github.com/ruby/ruby/pull/6791 +[GH-6868]: https://github.com/ruby/ruby/pull/6868 +[GH-rubygems-4475]: https://github.com/rubygems/rubygems/pull/4475 +[GH-rubygems-6149]: https://github.com/rubygems/rubygems/pull/6149 +[GH-rubygems-6167]: https://github.com/rubygems/rubygems/pull/6167 +[sec-156615]: https://hackerone.com/reports/156615 +[CVE-2021-33621]: https://www.ruby-lang.org/en/news/2022/11/22/http-response-splitting-in-cgi-cve-2021-33621/ +[wasm/README.md]: https://github.com/ruby/ruby/blob/master/wasm/README.md +[ruby.wasm]: https://github.com/ruby/ruby.wasm diff --git a/doc/NEWS/NEWS-3.3.0.md b/doc/NEWS/NEWS-3.3.0.md new file mode 100644 index 0000000000..364786d754 --- /dev/null +++ b/doc/NEWS/NEWS-3.3.0.md @@ -0,0 +1,529 @@ +# NEWS for Ruby 3.3.0 + +This document is a list of user-visible feature changes +since the **3.2.0** release, except for bug fixes. + +Note that each entry is kept to a minimum, see links for details. + +## Command line options + +* A new `performance` warning category was introduced. + They are not displayed by default even in verbose mode. + Turn them on with `-W:performance` or `Warning[:performance] = true`. [[Feature #19538]] + +* A new `RUBY_CRASH_REPORT` environment variable was introduced to allow + redirecting Ruby crash reports to a file or sub command. See the `BUG REPORT ENVIRONMENT` + section of the ruby manpage for further details. [[Feature #19790]] + +## Core classes updates + +Note: We're only listing outstanding class updates. + +* Array + + * Array#pack now raises ArgumentError for unknown directives. [[Bug #19150]] + +* Dir + + * Dir.for_fd added for returning a Dir object for the directory specified + by the provided directory file descriptor. [[Feature #19347]] + * Dir.fchdir added for changing the directory to the directory specified + by the provided directory file descriptor. [[Feature #19347]] + * Dir#chdir added for changing the directory to the directory specified by + the provided `Dir` object. [[Feature #19347]] + +* Encoding + + * `Encoding#replicate` has been removed, it was already deprecated. [[Feature #18949]] + +* Fiber + + * Introduce Fiber#kill. [[Bug #595]] + + ```ruby + fiber = Fiber.new do + while true + puts "Yielding..." + Fiber.yield + end + ensure + puts "Exiting..." + end + + fiber.resume + # Yielding... + fiber.kill + # Exiting... + ``` + +* MatchData + + * MatchData#named_captures now accepts optional `symbolize_names` + keyword. [[Feature #19591]] + +* Module + + * Module#set_temporary_name added for setting a temporary name for a + module. [[Feature #19521]] + +* ObjectSpace::WeakKeyMap + + * New core class to build collections with weak references. + The class use equality semantic to lookup keys like a regular hash, + but it doesn't hold strong references on the keys. [[Feature #18498]] + +* ObjectSpace::WeakMap + + * ObjectSpace::WeakMap#delete was added to eagerly clear weak map + entries. [[Feature #19561]] + +* Proc + * Now Proc#dup and Proc#clone call `#initialize_dup` and `#initialize_clone` + hooks respectively. [[Feature #19362]] + +* Process + + * New Process.warmup method that notify the Ruby virtual machine that the boot sequence is finished, + and that now is a good time to optimize the application. This is useful + for long-running applications. The actual optimizations performed are entirely + implementation-specific and may change in the future without notice. [[Feature #18885]] + +* Process::Status + + * Process::Status#& and Process::Status#>> are deprecated. [[Bug #19868]] + +* Range + + * Range#reverse_each can now process beginless ranges with an Integer endpoint. [[Feature #18515]] + * Range#reverse_each now raises TypeError for endless ranges. [[Feature #18551]] + * Range#overlap? added for checking if two ranges overlap. [[Feature #19839]] + +* Refinement + + * Add Refinement#target as an alternative of Refinement#refined_class. + Refinement#refined_class is deprecated and will be removed in Ruby + 3.4. [[Feature #19714]] + +* Regexp + + * The cache-based optimization now supports lookarounds and atomic groupings. That is, match + for Regexp containing these extensions can now also be performed in linear time to the length + of the input string. However, these cannot contain captures and cannot be nested. [[Feature #19725]] + +* String + + * String#unpack now raises ArgumentError for unknown directives. [[Bug #19150]] + * String#bytesplice now accepts new arguments index/length or range of the + source string to be copied. [[Feature #19314]] + +* Thread::Queue + + * Thread::Queue#freeze now raises TypeError. [[Bug #17146]] + +* Thread::SizedQueue + + * Thread::SizedQueue#freeze now raises TypeError. [[Bug #17146]] + +* Time + + * Time.new with a string argument became stricter. [[Bug #19293]] + + ```ruby + Time.new('2023-12-20') + # no time information (ArgumentError) + ``` + +* TracePoint + + * TracePoint supports `rescue` event. When the raised exception was rescued, + the TracePoint will fire the hook. `rescue` event only supports Ruby-level + `rescue`. [[Feature #19572]] + +## Stdlib updates + +* RubyGems and Bundler warn if users do `require` the following gems without adding them to Gemfile or gemspec. + This is because they will become the bundled gems in the future version of Ruby. This warning is suppressed + if you use bootsnap gem. We recommend to run your application with `DISABLE_BOOTSNAP=1` environmental variable + at least once. This is limitation of this version. + [[Feature #19351]] [[Feature #19776]] [[Feature #19843]] + * abbrev + * base64 + * bigdecimal + * csv + * drb + * getoptlong + * mutex_m + * nkf + * observer + * racc + * resolv-replace + * rinda + * syslog + +* Socket#recv and Socket#recv_nonblock returns `nil` instead of an empty string on closed + connections. Socket#recvmsg and Socket#recvmsg_nonblock returns `nil` instead of an empty packet on closed + connections. [[Bug #19012]] + +* Name resolution such as Socket.getaddrinfo, Socket.getnameinfo, Addrinfo.getaddrinfo, etc. + can now be interrupted. [[Feature #19965]] + +* Random::Formatter#alphanumeric is extended to accept optional `chars` + keyword argument. [[Feature #18183]] + +The following default gem is added. + +* prism 0.19.0 + +The following default gems are updated. + +* RubyGems 3.5.3 +* abbrev 0.1.2 +* base64 0.2.0 +* benchmark 0.3.0 +* bigdecimal 3.1.5 +* bundler 2.5.3 +* cgi 0.4.1 +* csv 3.2.8 +* date 3.3.4 +* delegate 0.3.1 +* drb 2.2.0 +* english 0.8.0 +* erb 4.0.3 +* error_highlight 0.6.0 +* etc 1.4.3 +* fcntl 1.1.0 +* fiddle 1.1.2 +* fileutils 1.7.2 +* find 0.2.0 +* getoptlong 0.2.1 +* io-console 0.7.1 +* io-nonblock 0.3.0 +* io-wait 0.3.1 +* ipaddr 1.2.6 +* irb 1.11.0 +* json 2.7.1 +* logger 1.6.0 +* mutex_m 0.2.0 +* net-http 0.4.0 +* net-protocol 0.2.2 +* nkf 0.1.3 +* observer 0.1.2 +* open-uri 0.4.1 +* open3 0.2.1 +* openssl 3.2.0 +* optparse 0.4.0 +* ostruct 0.6.0 +* pathname 0.3.0 +* pp 0.5.0 +* prettyprint 0.2.0 +* pstore 0.1.3 +* psych 5.1.2 +* rdoc 6.6.2 +* readline 0.0.4 +* reline 0.4.1 +* resolv 0.3.0 +* rinda 0.2.0 +* securerandom 0.3.1 +* set 1.1.0 +* shellwords 0.2.0 +* singleton 0.2.0 +* stringio 3.1.0 +* strscan 3.0.7 +* syntax_suggest 2.0.0 +* syslog 0.1.2 +* tempfile 0.2.1 +* time 0.3.0 +* timeout 0.4.1 +* tmpdir 0.2.0 +* tsort 0.2.0 +* un 0.3.0 +* uri 0.13.0 +* weakref 0.1.3 +* win32ole 1.8.10 +* yaml 0.3.0 +* zlib 3.1.0 + +The following bundled gem is promoted from default gems. + +* racc 1.7.3 + +The following bundled gems are updated. + +* minitest 5.20.0 +* rake 13.1.0 +* test-unit 3.6.1 +* rexml 3.2.6 +* rss 0.3.0 +* net-ftp 0.3.3 +* net-imap 0.4.9 +* net-smtp 0.4.0 +* rbs 3.4.0 +* typeprof 0.21.9 +* debug 1.9.1 + +See GitHub releases like [Logger](https://github.com/ruby/logger/releases) or +changelog for details of the default gems or bundled gems. + +### Prism + +* Introduced [the Prism parser](https://github.com/ruby/prism) as a default gem + * Prism is a portable, error tolerant, and maintainable recursive descent parser for the Ruby language +* Prism is production ready and actively maintained, you can use it in place of Ripper + * There is [extensive documentation](https://ruby.github.io/prism/) on how to use Prism + * Prism is both a C library that will be used internally by CRuby and a Ruby gem that can be used by any tooling which needs to parse Ruby code + * Notable methods in the Prism API are: + * `Prism.parse(source)` which returns the AST as part of a parse result object + * `Prism.parse_comments(source)` which returns the comments + * `Prism.parse_success?(source)` which returns true if there are no errors +* You can make pull requests or issues directly on [the Prism repository](https://github.com/ruby/prism) if you are interested in contributing +* You can now use `ruby --parser=prism` or `RUBYOPT="--parser=prism"` to experiment with the Prism compiler. Please note that this flag is for debugging only. + +## Compatibility issues + +* Subprocess creation/forking via the following file open methods is deprecated. [[Feature #19630]] + * Kernel#open + * URI.open + * IO.binread + * IO.foreach + * IO.readlines + * IO.read + * IO.write + +* When given a non-lambda, non-literal block, Kernel#lambda with now raises + ArgumentError instead of returning it unmodified. These usages have been + issuing warnings under the `Warning[:deprecated]` category since Ruby 3.0.0. + [[Feature #19777]] + +* The `RUBY_GC_HEAP_INIT_SLOTS` environment variable has been deprecated and + removed. Environment variables `RUBY_GC_HEAP_%d_INIT_SLOTS` should be + used instead. [[Feature #19785]] + +* `it` calls without arguments in a block with no ordinary parameters are + deprecated. `it` will be a reference to the first block parameter in Ruby 3.4. + [[Feature #18980]] + +* Error message for NoMethodError have changed to not use the target object's `#inspect` + for efficiency, and says "instance of ClassName" instead. [[Feature #18285]] + + ```ruby + ([1] * 100).nonexisting + # undefined method `nonexisting' for an instance of Array (NoMethodError) + ``` + +* Now anonymous parameters forwarding is disallowed inside a block + that uses anonymous parameters. [[Feature #19370]] + +## Stdlib compatibility issues + +* `racc` is promoted to bundled gems. + * You need to add `racc` to your `Gemfile` if you use `racc` under bundler environment. +* `ext/readline` is retired + * We have `reline` that is pure Ruby implementation compatible with `ext/readline` API. + We rely on `reline` in the future. If you need to use `ext/readline`, you can install + `ext/readline` via rubygems.org with `gem install readline-ext`. + * We no longer need to install libraries like `libreadline` or `libedit`. + +## C API updates + +* `rb_postponed_job` updates + * New APIs and deprecated APIs (see comments for details) + * added: `rb_postponed_job_preregister()` + * added: `rb_postponed_job_trigger()` + * deprecated: `rb_postponed_job_register()` (and semantic change. see below) + * deprecated: `rb_postponed_job_register_one()` + * The postponed job APIs have been changed to address some rare crashes. + To solve the issue, we introduced new two APIs and deprecated current APIs. + The semantics of these functions have also changed slightly; `rb_postponed_job_register` + now behaves like the `once` variant in that multiple calls with the same + `func` might be coalesced into a single execution of the `func` + [[Feature #20057]] + +* Some updates for internal thread event hook APIs + * `rb_internal_thread_event_data_t` with a target Ruby thread (VALUE) + and callback functions (`rb_internal_thread_event_callback`) receive it. + https://github.com/ruby/ruby/pull/8885 + * The following functions are introduced to manipulate Ruby thread local data + from internal thread event hook APIs (they are introduced since Ruby 3.2). + https://github.com/ruby/ruby/pull/8936 + * `rb_internal_thread_specific_key_create()` + * `rb_internal_thread_specific_get()` + * `rb_internal_thread_specific_set()` + +* `rb_profile_thread_frames()` is introduced to get a frames from + a specific thread. + [[Feature #10602]] + +* `rb_data_define()` is introduced to define `Data`. [[Feature #19757]] + +* `rb_ext_resolve_symbol()` is introduced to search a function from + extension libraries. [[Feature #20005]] + +* IO related updates: + * The details of `rb_io_t` will be hidden and deprecated attributes + are added for each members. [[Feature #19057]] + * `rb_io_path(VALUE io)` is introduced to get a path of `io`. + * `rb_io_closed_p(VALUE io)` to get opening or closing of `io`. + * `rb_io_mode(VALUE io)` to get the mode of `io`. + * `rb_io_open_descriptor()` is introduced to make an IO object from a file + descriptor. + +## Implementation improvements + +### Parser + +* Replace Bison with [Lrama LALR parser generator](https://github.com/ruby/lrama). + No need to install Bison to build Ruby from source code anymore. + We will no longer suffer bison compatibility issues and we can use new features by just implementing it to Lrama. [[Feature #19637]] + * See [The future vision of Ruby Parser](https://rubykaigi.org/2023/presentations/spikeolaf.html) for detail. + * Lrama internal parser is a LR parser generated by Racc for maintainability. + * Parameterizing Rules `(?, *, +)` are supported, it will be used in Ruby parse.y. + +### GC / Memory management + +* Major performance improvements over Ruby 3.2 + * Young objects referenced by old objects are no longer immediately + promoted to the old generation. This significantly reduces the frequency of + major GC collections. [[Feature #19678]] + * A new `REMEMBERED_WB_UNPROTECTED_OBJECTS_LIMIT_RATIO` tuning variable was + introduced to control the number of unprotected objects cause a major GC + collection to trigger. The default is set to `0.01` (1%). This significantly + reduces the frequency of major GC collection. [[Feature #19571]] + * Write Barriers were implemented for many core types that were missing them, + notably `Time`, `Enumerator`, `MatchData`, `Method`, `File::Stat`, `BigDecimal` + and several others. This significantly reduces minor GC collection time and major + GC collection frequency. + * Most core classes are now using Variable Width Allocation, notably `Hash`, `Time`, + `Thread::Backtrace`, `Thread::Backtrace::Location`, `File::Stat`, `Method`. + This makes these classes faster to allocate and free, use less memory and reduce + heap fragmentation. +* `defined?(@ivar)` is optimized with Object Shapes. + +### YJIT + +* Major performance improvements over Ruby 3.2 + * Support for splat and rest arguments has been improved. + * Registers are allocated for stack operations of the virtual machine. + * More calls with optional arguments are compiled. Exception handlers are also compiled. + * Unsupported call types and megamorphic call sites no longer exit to the interpreter. + * Basic methods like Rails `#blank?` and + [specialized `#present?`](https://github.com/rails/rails/pull/49909) are inlined. + * `Integer#*`, `Integer#!=`, `String#!=`, `String#getbyte`, + `Kernel#block_given?`, `Kernel#is_a?`, `Kernel#instance_of?`, and `Module#===` + are specially optimized. + * Compilation speed is now slightly faster than Ruby 3.2. + * Now more than 3x faster than the interpreter on Optcarrot! +* Significantly improved memory usage over Ruby 3.2 + * Metadata for compiled code uses a lot less memory. + * `--yjit-call-threshold` is automatically raised from 30 to 120 + when the application has more than 40,000 ISEQs. + * `--yjit-cold-threshold` is added to skip compiling cold ISEQs. + * More compact code is generated on Arm64. +* Code GC is now disabled by default + * `--yjit-exec-mem-size` is treated as a hard limit where compilation of new code stops. + * No sudden drops in performance due to code GC. + Better copy-on-write behavior on servers reforking with + [Pitchfork](https://github.com/shopify/pitchfork). + * You can still enable code GC if desired with `--yjit-code-gc` +* Add `RubyVM::YJIT.enable` that can enable YJIT at run-time + * You can start YJIT without modifying command-line arguments or environment variables. + Rails 7.2 will [enable YJIT by default](https://github.com/rails/rails/pull/49947) + using this method. + * This can also be used to enable YJIT only once your application is + done booting. `--yjit-disable` can be used if you want to use other + YJIT options while disabling YJIT at boot. +* More YJIT stats are available by default + * `yjit_alloc_size` and several more metadata-related stats are now available by default. + * `ratio_in_yjit` stat produced by `--yjit-stats` is now available in release builds, + a special stats or dev build is no longer required to access most stats. +* Add more profiling capabilities + * `--yjit-perf` is added to facilitate profiling with Linux perf. + * `--yjit-trace-exits` now supports sampling with `--yjit-trace-exits-sample-rate=N` +* More thorough testing and multiple bug fixes +* `--yjit-stats=quiet` is added to avoid printing stats on exit. + +### MJIT + +* MJIT is removed. + * `--disable-jit-support` is removed. Consider using `--disable-yjit --disable-rjit` instead. + +### RJIT + +* Introduced a pure-Ruby JIT compiler RJIT. + * RJIT supports only x86\_64 architecture on Unix platforms. + * Unlike MJIT, it doesn't require a C compiler at runtime. +* RJIT exists only for experimental purposes. + * You should keep using YJIT in production. + +### M:N Thread scheduler + +* M:N Thread scheduler is introduced. [[Feature #19842]] + * Background: Ruby 1.8 and before, M:1 thread scheduler (M Ruby threads + with 1 native thread. Called as User level threads or Green threads) + is used. Ruby 1.9 and later, 1:1 thread scheduler (1 Ruby thread with + 1 native thread). M:1 threads takes lower resources compare with 1:1 + threads because it needs only 1 native threads. However it is difficult + to support context switching for all of blocking operation so 1:1 + threads are employed from Ruby 1.9. M:N thread scheduler uses N native + threads for M Ruby threads (N is small number in general). It doesn't + need same number of native threads as Ruby threads (similar to the M:1 + thread scheduler). Also our M:N threads supports blocking operations + well same as 1:1 threads. See the ticket for more details. + Our M:N thread scheduler refers on the goroutine scheduler in the + Go language. + * In a ractor, only 1 thread can run in a same time because of + implementation. Therefore, applications that use only one Ractor + (most applications) M:N thread scheduler works as M:1 thread scheduler + with further extension from Ruby 1.8. + * M:N thread scheduler can introduce incompatibility for C-extensions, + so it is disabled by default on the main Ractors. + `RUBY_MN_THREADS=1` environment variable will enable it. + On non-main Ractors, M:N thread scheduler is enabled (and can not + disable it now). + * `N` (the number of native threads) can be specified with `RUBY_MAX_CPU` + environment variable. The default is 8. + Note that more than `N` native threads are used to support many kind of + blocking operations. + +[Bug #595]: https://bugs.ruby-lang.org/issues/595 +[Feature #10602]: https://bugs.ruby-lang.org/issues/10602 +[Bug #17146]: https://bugs.ruby-lang.org/issues/17146 +[Feature #18183]: https://bugs.ruby-lang.org/issues/18183 +[Feature #18285]: https://bugs.ruby-lang.org/issues/18285 +[Feature #18498]: https://bugs.ruby-lang.org/issues/18498 +[Feature #18515]: https://bugs.ruby-lang.org/issues/18515 +[Feature #18551]: https://bugs.ruby-lang.org/issues/18551 +[Feature #18885]: https://bugs.ruby-lang.org/issues/18885 +[Feature #18949]: https://bugs.ruby-lang.org/issues/18949 +[Feature #18980]: https://bugs.ruby-lang.org/issues/18980 +[Bug #19012]: https://bugs.ruby-lang.org/issues/19012 +[Feature #19057]: https://bugs.ruby-lang.org/issues/19057 +[Bug #19150]: https://bugs.ruby-lang.org/issues/19150 +[Bug #19293]: https://bugs.ruby-lang.org/issues/19293 +[Feature #19314]: https://bugs.ruby-lang.org/issues/19314 +[Feature #19347]: https://bugs.ruby-lang.org/issues/19347 +[Feature #19351]: https://bugs.ruby-lang.org/issues/19351 +[Feature #19362]: https://bugs.ruby-lang.org/issues/19362 +[Feature #19370]: https://bugs.ruby-lang.org/issues/19370 +[Feature #19521]: https://bugs.ruby-lang.org/issues/19521 +[Feature #19538]: https://bugs.ruby-lang.org/issues/19538 +[Feature #19561]: https://bugs.ruby-lang.org/issues/19561 +[Feature #19571]: https://bugs.ruby-lang.org/issues/19571 +[Feature #19572]: https://bugs.ruby-lang.org/issues/19572 +[Feature #19591]: https://bugs.ruby-lang.org/issues/19591 +[Feature #19630]: https://bugs.ruby-lang.org/issues/19630 +[Feature #19637]: https://bugs.ruby-lang.org/issues/19637 +[Feature #19678]: https://bugs.ruby-lang.org/issues/19678 +[Feature #19714]: https://bugs.ruby-lang.org/issues/19714 +[Feature #19725]: https://bugs.ruby-lang.org/issues/19725 +[Feature #19757]: https://bugs.ruby-lang.org/issues/19757 +[Feature #19776]: https://bugs.ruby-lang.org/issues/19776 +[Feature #19777]: https://bugs.ruby-lang.org/issues/19777 +[Feature #19785]: https://bugs.ruby-lang.org/issues/19785 +[Feature #19790]: https://bugs.ruby-lang.org/issues/19790 +[Feature #19839]: https://bugs.ruby-lang.org/issues/19839 +[Feature #19842]: https://bugs.ruby-lang.org/issues/19842 +[Feature #19843]: https://bugs.ruby-lang.org/issues/19843 +[Bug #19868]: https://bugs.ruby-lang.org/issues/19868 +[Feature #19965]: https://bugs.ruby-lang.org/issues/19965 +[Feature #20005]: https://bugs.ruby-lang.org/issues/20005 +[Feature #20057]: https://bugs.ruby-lang.org/issues/20057 diff --git a/doc/_regexp.rdoc b/doc/_regexp.rdoc new file mode 100644 index 0000000000..7b71eee984 --- /dev/null +++ b/doc/_regexp.rdoc @@ -0,0 +1,1276 @@ +A {regular expression}[https://en.wikipedia.org/wiki/Regular_expression] +(also called a _regexp_) is a <i>match pattern</i> (also simply called a _pattern_). + +A common notation for a regexp uses enclosing slash characters: + + /foo/ + +A regexp may be applied to a <i>target string</i>; +The part of the string (if any) that matches the pattern is called a _match_, +and may be said <i>to match</i>: + + re = /red/ + re.match?('redirect') # => true # Match at beginning of target. + re.match?('bored') # => true # Match at end of target. + re.match?('credit') # => true # Match within target. + re.match?('foo') # => false # No match. + +== \Regexp Uses + +A regexp may be used: + +- To extract substrings based on a given pattern: + + re = /foo/ # => /foo/ + re.match('food') # => #<MatchData "foo"> + re.match('good') # => nil + + See sections {Method match}[rdoc-ref:Regexp@Method+match] + and {Operator =~}[rdoc-ref:Regexp@Operator+-3D~]. + +- To determine whether a string matches a given pattern: + + re.match?('food') # => true + re.match?('good') # => false + + See section {Method match?}[rdoc-ref:Regexp@Method+match-3F]. + +- As an argument for calls to certain methods in other classes and modules; + most such methods accept an argument that may be either a string + or the (much more powerful) regexp. + + See {Regexp Methods}[rdoc-ref:regexp/methods.rdoc]. + +== \Regexp Objects + +A regexp object has: + +- A source; see {Sources}[rdoc-ref:Regexp@Sources]. + +- Several modes; see {Modes}[rdoc-ref:Regexp@Modes]. + +- A timeout; see {Timeouts}[rdoc-ref:Regexp@Timeouts]. + +- An encoding; see {Encodings}[rdoc-ref:Regexp@Encodings]. + +== Creating a \Regexp + +A regular expression may be created with: + +- A regexp literal using slash characters + (see {Regexp Literals}[rdoc-ref:syntax/literals.rdoc@Regexp+Literals]): + + # This is a very common usage. + /foo/ # => /foo/ + +- A <tt>%r</tt> regexp literal + (see {%r: Regexp Literals}[rdoc-ref:syntax/literals.rdoc@25r-3A+Regexp+Literals]): + + # Same delimiter character at beginning and end; + # useful for avoiding escaping characters + %r/name\/value pair/ # => /name\/value pair/ + %r:name/value pair: # => /name\/value pair/ + %r|name/value pair| # => /name\/value pair/ + + # Certain "paired" characters can be delimiters. + %r[foo] # => /foo/ + %r{foo} # => /foo/ + %r(foo) # => /foo/ + %r<foo> # => /foo/ + +- \Method Regexp.new. + +== \Method <tt>match</tt> + +Each of the methods Regexp#match, String#match, and Symbol#match +returns a MatchData object if a match was found, +nil+ otherwise; +each also sets {global variables}[rdoc-ref:Regexp@Global+Variables]: + + 'food'.match(/foo/) # => #<MatchData "foo"> + 'food'.match(/bar/) # => nil + +== Operator <tt>=~</tt> + +Each of the operators Regexp#=~, String#=~, and Symbol#=~ +returns an integer offset if a match was found, +nil+ otherwise; +each also sets {global variables}[rdoc-ref:Regexp@Global+Variables]: + + /bar/ =~ 'foo bar' # => 4 + 'foo bar' =~ /bar/ # => 4 + /baz/ =~ 'foo bar' # => nil + +== \Method <tt>match?</tt> + +Each of the methods Regexp#match?, String#match?, and Symbol#match? +returns +true+ if a match was found, +false+ otherwise; +none sets {global variables}[rdoc-ref:Regexp@Global+Variables]: + + 'food'.match?(/foo/) # => true + 'food'.match?(/bar/) # => false + +== Global Variables + +Certain regexp-oriented methods assign values to global variables: + +- <tt>#match</tt>: see {Method match}[rdoc-ref:Regexp@Method+match]. +- <tt>#=~</tt>: see {Operator =~}[rdoc-ref:Regexp@Operator+-3D~]. + +The affected global variables are: + +- <tt>$~</tt>: Returns a MatchData object, or +nil+. +- <tt>$&</tt>: Returns the matched part of the string, or +nil+. +- <tt>$`</tt>: Returns the part of the string to the left of the match, or +nil+. +- <tt>$'</tt>: Returns the part of the string to the right of the match, or +nil+. +- <tt>$+</tt>: Returns the last group matched, or +nil+. +- <tt>$1</tt>, <tt>$2</tt>, etc.: Returns the first, second, etc., + matched group, or +nil+. + Note that <tt>$0</tt> is quite different; + it returns the name of the currently executing program. + +Examples: + + # Matched string, but no matched groups. + 'foo bar bar baz'.match('bar') + $~ # => #<MatchData "bar"> + $& # => "bar" + $` # => "foo " + $' # => " bar baz" + $+ # => nil + $1 # => nil + + # Matched groups. + /s(\w{2}).*(c)/.match('haystack') + $~ # => #<MatchData "stac" 1:"ta" 2:"c"> + $& # => "stac" + $` # => "hay" + $' # => "k" + $+ # => "c" + $1 # => "ta" + $2 # => "c" + $3 # => nil + + # No match. + 'foo'.match('bar') + $~ # => nil + $& # => nil + $` # => nil + $' # => nil + $+ # => nil + $1 # => nil + +Note that Regexp#match?, String#match?, and Symbol#match? +do not set global variables. + +== Sources + +As seen above, the simplest regexp uses a literal expression as its source: + + re = /foo/ # => /foo/ + re.match('food') # => #<MatchData "foo"> + re.match('good') # => nil + +A rich collection of available _subexpressions_ +gives the regexp great power and flexibility: + +- {Special characters}[rdoc-ref:Regexp@Special+Characters] +- {Source literals}[rdoc-ref:Regexp@Source+Literals] +- {Character classes}[rdoc-ref:Regexp@Character+Classes] +- {Shorthand character classes}[rdoc-ref:Regexp@Shorthand+Character+Classes] +- {Anchors}[rdoc-ref:Regexp@Anchors] +- {Alternation}[rdoc-ref:Regexp@Alternation] +- {Quantifiers}[rdoc-ref:Regexp@Quantifiers] +- {Groups and captures}[rdoc-ref:Regexp@Groups+and+Captures] +- {Unicode}[rdoc-ref:Regexp@Unicode] +- {POSIX Bracket Expressions}[rdoc-ref:Regexp@POSIX+Bracket+Expressions] +- {Comments}[rdoc-ref:Regexp@Comments] + +=== Special Characters + +\Regexp special characters, called _metacharacters_, +have special meanings in certain contexts; +depending on the context, these are sometimes metacharacters: + + . ? - + * ^ \ | $ ( ) [ ] { } + +To match a metacharacter literally, backslash-escape it: + + # Matches one or more 'o' characters. + /o+/.match('foo') # => #<MatchData "oo"> + # Would match 'o+'. + /o\+/.match('foo') # => nil + +To match a backslash literally, backslash-escape it: + + /\./.match('\.') # => #<MatchData "."> + /\\./.match('\.') # => #<MatchData "\\."> + +Method Regexp.escape returns an escaped string: + + Regexp.escape('.?-+*^\|$()[]{}') + # => "\\.\\?\\-\\+\\*\\^\\\\\\|\\$\\(\\)\\[\\]\\{\\}" + +=== Source Literals + +The source literal largely behaves like a double-quoted string; +see {String Literals}[rdoc-ref:syntax/literals.rdoc@String+Literals]. + +In particular, a source literal may contain interpolated expressions: + + s = 'foo' # => "foo" + /#{s}/ # => /foo/ + /#{s.capitalize}/ # => /Foo/ + /#{2 + 2}/ # => /4/ + +There are differences between an ordinary string literal and a source literal; +see {Shorthand Character Classes}[rdoc-ref:Regexp@Shorthand+Character+Classes]. + +- <tt>\s</tt> in an ordinary string literal is equivalent to a space character; + in a source literal, it's shorthand for matching a whitespace character. +- In an ordinary string literal, these are (needlessly) escaped characters; + in a source literal, they are shorthands for various matching characters: + + \w \W \d \D \h \H \S \R + +=== Character Classes + +A <i>character class</i> is delimited by square brackets; +it specifies that certain characters match at a given point in the target string: + + # This character class will match any vowel. + re = /B[aeiou]rd/ + re.match('Bird') # => #<MatchData "Bird"> + re.match('Bard') # => #<MatchData "Bard"> + re.match('Byrd') # => nil + +A character class may contain hyphen characters to specify ranges of characters: + + # These regexps have the same effect. + /[abcdef]/.match('foo') # => #<MatchData "f"> + /[a-f]/.match('foo') # => #<MatchData "f"> + /[a-cd-f]/.match('foo') # => #<MatchData "f"> + +When the first character of a character class is a caret (<tt>^</tt>), +the sense of the class is inverted: it matches any character _except_ those specified. + + /[^a-eg-z]/.match('f') # => #<MatchData "f"> + +A character class may contain another character class. +By itself this isn't useful because <tt>[a-z[0-9]]</tt> +describes the same set as <tt>[a-z0-9]</tt>. + +However, character classes also support the <tt>&&</tt> operator, +which performs set intersection on its arguments. +The two can be combined as follows: + + /[a-w&&[^c-g]z]/ # ([a-w] AND ([^c-g] OR z)) + +This is equivalent to: + + /[abh-w]/ + +=== Shorthand Character Classes + +Each of the following metacharacters serves as a shorthand +for a character class: + +- <tt>/./</tt>: Matches any character except a newline: + + /./.match('foo') # => #<MatchData "f"> + /./.match("\n") # => nil + +- <tt>/./m</tt>: Matches any character, including a newline; + see {Multiline Mode}[rdoc-ref:Regexp@Multiline+Mode]: + + /./m.match("\n") # => #<MatchData "\n"> + +- <tt>/\w/</tt>: Matches a word character: equivalent to <tt>[a-zA-Z0-9_]</tt>: + + /\w/.match(' foo') # => #<MatchData "f"> + /\w/.match(' _') # => #<MatchData "_"> + /\w/.match(' ') # => nil + +- <tt>/\W/</tt>: Matches a non-word character: equivalent to <tt>[^a-zA-Z0-9_]</tt>: + + /\W/.match(' ') # => #<MatchData " "> + /\W/.match('_') # => nil + +- <tt>/\d/</tt>: Matches a digit character: equivalent to <tt>[0-9]</tt>: + + /\d/.match('THX1138') # => #<MatchData "1"> + /\d/.match('foo') # => nil + +- <tt>/\D/</tt>: Matches a non-digit character: equivalent to <tt>[^0-9]</tt>: + + /\D/.match('123Jump!') # => #<MatchData "J"> + /\D/.match('123') # => nil + +- <tt>/\h/</tt>: Matches a hexdigit character: equivalent to <tt>[0-9a-fA-F]</tt>: + + /\h/.match('xyz fedcba9876543210') # => #<MatchData "f"> + /\h/.match('xyz') # => nil + +- <tt>/\H/</tt>: Matches a non-hexdigit character: equivalent to <tt>[^0-9a-fA-F]</tt>: + + /\H/.match('fedcba9876543210xyz') # => #<MatchData "x"> + /\H/.match('fedcba9876543210') # => nil + +- <tt>/\s/</tt>: Matches a whitespace character: equivalent to <tt>/[ \t\r\n\f\v]/</tt>: + + /\s/.match('foo bar') # => #<MatchData " "> + /\s/.match('foo') # => nil + +- <tt>/\S/</tt>: Matches a non-whitespace character: equivalent to <tt>/[^ \t\r\n\f\v]/</tt>: + + /\S/.match(" \t\r\n\f\v foo") # => #<MatchData "f"> + /\S/.match(" \t\r\n\f\v") # => nil + +- <tt>/\R/</tt>: Matches a linebreak, platform-independently: + + /\R/.match("\r") # => #<MatchData "\r"> # Carriage return (CR) + /\R/.match("\n") # => #<MatchData "\n"> # Newline (LF) + /\R/.match("\f") # => #<MatchData "\f"> # Formfeed (FF) + /\R/.match("\v") # => #<MatchData "\v"> # Vertical tab (VT) + /\R/.match("\r\n") # => #<MatchData "\r\n"> # CRLF + /\R/.match("\u0085") # => #<MatchData "\u0085"> # Next line (NEL) + /\R/.match("\u2028") # => #<MatchData "\u2028"> # Line separator (LSEP) + /\R/.match("\u2029") # => #<MatchData "\u2029"> # Paragraph separator (PSEP) + +=== Anchors + +An anchor is a metasequence that matches a zero-width position between +characters in the target string. + +For a subexpression with no anchor, +matching may begin anywhere in the target string: + + /real/.match('surrealist') # => #<MatchData "real"> + +For a subexpression with an anchor, +matching must begin at the matched anchor. + +==== Boundary Anchors + +Each of these anchors matches a boundary: + +- <tt>^</tt>: Matches the beginning of a line: + + /^bar/.match("foo\nbar") # => #<MatchData "bar"> + /^ar/.match("foo\nbar") # => nil + +- <tt>$</tt>: Matches the end of a line: + + /bar$/.match("foo\nbar") # => #<MatchData "bar"> + /ba$/.match("foo\nbar") # => nil + +- <tt>\A</tt>: Matches the beginning of the string: + + /\Afoo/.match('foo bar') # => #<MatchData "foo"> + /\Afoo/.match(' foo bar') # => nil + +- <tt>\Z</tt>: Matches the end of the string; + if string ends with a single newline, + it matches just before the ending newline: + + /foo\Z/.match('bar foo') # => #<MatchData "foo"> + /foo\Z/.match('foo bar') # => nil + /foo\Z/.match("bar foo\n") # => #<MatchData "foo"> + /foo\Z/.match("bar foo\n\n") # => nil + +- <tt>\z</tt>: Matches the end of the string: + + /foo\z/.match('bar foo') # => #<MatchData "foo"> + /foo\z/.match('foo bar') # => nil + /foo\z/.match("bar foo\n") # => nil + +- <tt>\b</tt>: Matches word boundary when not inside brackets; + matches backspace (<tt>"0x08"</tt>) when inside brackets: + + /foo\b/.match('foo bar') # => #<MatchData "foo"> + /foo\b/.match('foobar') # => nil + +- <tt>\B</tt>: Matches non-word boundary: + + /foo\B/.match('foobar') # => #<MatchData "foo"> + /foo\B/.match('foo bar') # => nil + +- <tt>\G</tt>: Matches first matching position: + + In methods like String#gsub and String#scan, it changes on each iteration. + It initially matches the beginning of subject, and in each following iteration it matches where the last match finished. + + " a b c".gsub(/ /, '_') # => "____a_b_c" + " a b c".gsub(/\G /, '_') # => "____a b c" + + In methods like Regexp#match and String#match + that take an optional offset, it matches where the search begins. + + "hello, world".match(/,/, 3) # => #<MatchData ","> + "hello, world".match(/\G,/, 3) # => nil + +==== Lookaround Anchors + +Lookahead anchors: + +- <tt>(?=_pat_)</tt>: Positive lookahead assertion: + ensures that the following characters match _pat_, + but doesn't include those characters in the matched substring. + +- <tt>(?!_pat_)</tt>: Negative lookahead assertion: + ensures that the following characters <i>do not</i> match _pat_, + but doesn't include those characters in the matched substring. + +Lookbehind anchors: + +- <tt>(?<=_pat_)</tt>: Positive lookbehind assertion: + ensures that the preceding characters match _pat_, but + doesn't include those characters in the matched substring. + +- <tt>(?<!_pat_)</tt>: Negative lookbehind assertion: + ensures that the preceding characters do not match + _pat_, but doesn't include those characters in the matched substring. + +The pattern below uses positive lookahead and positive lookbehind to match +text appearing in <tt><b></tt>...<tt></b></tt> tags +without including the tags in the match: + + /(?<=<b>)\w+(?=<\/b>)/.match("Fortune favors the <b>bold</b>.") + # => #<MatchData "bold"> + +==== Match-Reset Anchor + +- <tt>\K</tt>: Match reset: + the matched content preceding <tt>\K</tt> in the regexp is excluded from the result. + For example, the following two regexps are almost equivalent: + + /ab\Kc/.match('abc') # => #<MatchData "c"> + /(?<=ab)c/.match('abc') # => #<MatchData "c"> + + These match same string and <tt>$&</tt> equals <tt>'c'</tt>, + while the matched position is different. + + As are the following two regexps: + + /(a)\K(b)\Kc/ + /(?<=(?<=(a))(b))c/ + +=== Alternation + +The vertical bar metacharacter (<tt>|</tt>) may be used within parentheses +to express alternation: +two or more subexpressions any of which may match the target string. + +Two alternatives: + + re = /(a|b)/ + re.match('foo') # => nil + re.match('bar') # => #<MatchData "b" 1:"b"> + +Four alternatives: + + re = /(a|b|c|d)/ + re.match('shazam') # => #<MatchData "a" 1:"a"> + re.match('cold') # => #<MatchData "c" 1:"c"> + +Each alternative is a subexpression, and may be composed of other subexpressions: + + re = /([a-c]|[x-z])/ + re.match('bar') # => #<MatchData "b" 1:"b"> + re.match('ooz') # => #<MatchData "z" 1:"z"> + +\Method Regexp.union provides a convenient way to construct +a regexp with alternatives. + +=== Quantifiers + +A simple regexp matches one character: + + /\w/.match('Hello') # => #<MatchData "H"> + +An added _quantifier_ specifies how many matches are required or allowed: + +- <tt>*</tt> - Matches zero or more times: + + /\w*/.match('') + # => #<MatchData ""> + /\w*/.match('x') + # => #<MatchData "x"> + /\w*/.match('xyz') + # => #<MatchData "yz"> + +- <tt>+</tt> - Matches one or more times: + + /\w+/.match('') # => nil + /\w+/.match('x') # => #<MatchData "x"> + /\w+/.match('xyz') # => #<MatchData "xyz"> + +- <tt>?</tt> - Matches zero or one times: + + /\w?/.match('') # => #<MatchData ""> + /\w?/.match('x') # => #<MatchData "x"> + /\w?/.match('xyz') # => #<MatchData "x"> + +- <tt>{</tt>_n_<tt>}</tt> - Matches exactly _n_ times: + + /\w{2}/.match('') # => nil + /\w{2}/.match('x') # => nil + /\w{2}/.match('xyz') # => #<MatchData "xy"> + +- <tt>{</tt>_min_<tt>,}</tt> - Matches _min_ or more times: + + /\w{2,}/.match('') # => nil + /\w{2,}/.match('x') # => nil + /\w{2,}/.match('xy') # => #<MatchData "xy"> + /\w{2,}/.match('xyz') # => #<MatchData "xyz"> + +- <tt>{,</tt>_max_<tt>}</tt> - Matches _max_ or fewer times: + + /\w{,2}/.match('') # => #<MatchData ""> + /\w{,2}/.match('x') # => #<MatchData "x"> + /\w{,2}/.match('xyz') # => #<MatchData "xy"> + +- <tt>{</tt>_min_<tt>,</tt>_max_<tt>}</tt> - + Matches at least _min_ times and at most _max_ times: + + /\w{1,2}/.match('') # => nil + /\w{1,2}/.match('x') # => #<MatchData "x"> + /\w{1,2}/.match('xyz') # => #<MatchData "xy"> + +==== Greedy, Lazy, or Possessive Matching + +Quantifier matching may be greedy, lazy, or possessive: + +- In _greedy_ matching, as many occurrences as possible are matched + while still allowing the overall match to succeed. + Greedy quantifiers: <tt>*</tt>, <tt>+</tt>, <tt>?</tt>, + <tt>{min, max}</tt> and its variants. +- In _lazy_ matching, the minimum number of occurrences are matched. + Lazy quantifiers: <tt>*?</tt>, <tt>+?</tt>, <tt>??</tt>, + <tt>{min, max}?</tt> and its variants. +- In _possessive_ matching, once a match is found, there is no backtracking; + that match is retained, even if it jeopardises the overall match. + Possessive quantifiers: <tt>*+</tt>, <tt>++</tt>, <tt>?+</tt>. + Note that <tt>{min, max}</tt> and its variants do _not_ support possessive matching. + +More: + +- About greedy and lazy matching, see + {Choosing Minimal or Maximal Repetition}[https://doc.lagout.org/programmation/Regular%20Expressions/Regular%20Expressions%20Cookbook_%20Detailed%20Solutions%20in%20Eight%20Programming%20Languages%20%282nd%20ed.%29%20%5BGoyvaerts%20%26%20Levithan%202012-09-06%5D.pdf#tutorial-backtrack]. +- About possessive matching, see + {Eliminate Needless Backtracking}[https://doc.lagout.org/programmation/Regular%20Expressions/Regular%20Expressions%20Cookbook_%20Detailed%20Solutions%20in%20Eight%20Programming%20Languages%20%282nd%20ed.%29%20%5BGoyvaerts%20%26%20Levithan%202012-09-06%5D.pdf#tutorial-backtrack]. + +=== Groups and Captures + +A simple regexp has (at most) one match: + + re = /\d\d\d\d-\d\d-\d\d/ + re.match('1943-02-04') # => #<MatchData "1943-02-04"> + re.match('1943-02-04').size # => 1 + re.match('foo') # => nil + +Adding one or more pairs of parentheses, <tt>(_subexpression_)</tt>, +defines _groups_, which may result in multiple matched substrings, +called _captures_: + + re = /(\d\d\d\d)-(\d\d)-(\d\d)/ + re.match('1943-02-04') # => #<MatchData "1943-02-04" 1:"1943" 2:"02" 3:"04"> + re.match('1943-02-04').size # => 4 + +The first capture is the entire matched string; +the other captures are the matched substrings from the groups. + +A group may have a {quantifier}[rdoc-ref:Regexp@Quantifiers]: + + re = /July 4(th)?/ + re.match('July 4') # => #<MatchData "July 4" 1:nil> + re.match('July 4th') # => #<MatchData "July 4th" 1:"th"> + + re = /(foo)*/ + re.match('') # => #<MatchData "" 1:nil> + re.match('foo') # => #<MatchData "foo" 1:"foo"> + re.match('foofoo') # => #<MatchData "foofoo" 1:"foo"> + + re = /(foo)+/ + re.match('') # => nil + re.match('foo') # => #<MatchData "foo" 1:"foo"> + re.match('foofoo') # => #<MatchData "foofoo" 1:"foo"> + +The returned \MatchData object gives access to the matched substrings: + + re = /(\d\d\d\d)-(\d\d)-(\d\d)/ + md = re.match('1943-02-04') + # => #<MatchData "1943-02-04" 1:"1943" 2:"02" 3:"04"> + md[0] # => "1943-02-04" + md[1] # => "1943" + md[2] # => "02" + md[3] # => "04" + +==== Non-Capturing Groups + +A group may be made non-capturing; +it is still a group (and, for example, can have a quantifier), +but its matching substring is not included among the captures. + +A non-capturing group begins with <tt>?:</tt> (inside the parentheses): + + # Don't capture the year. + re = /(?:\d\d\d\d)-(\d\d)-(\d\d)/ + md = re.match('1943-02-04') # => #<MatchData "1943-02-04" 1:"02" 2:"04"> + +==== Backreferences + +A group match may also be referenced within the regexp itself; +such a reference is called a +backreference+: + + /[csh](..) [csh]\1 in/.match('The cat sat in the hat') + # => #<MatchData "cat sat in" 1:"at"> + +This table shows how each subexpression in the regexp above +matches a substring in the target string: + + | Subexpression in Regexp | Matching Substring in Target String | + |---------------------------|-------------------------------------| + | First '[csh]' | Character 'c' | + | '(..)' | First substring 'at' | + | First space ' ' | First space character ' ' | + | Second '[csh]' | Character 's' | + | '\1' (backreference 'at') | Second substring 'at' | + | ' in' | Substring ' in' | + +A regexp may contain any number of groups: + +- For a large number of groups: + + - The ordinary <tt>\\_n_</tt> notation applies only for _n_ in range (1..9). + - The <tt>MatchData[_n_]</tt> notation applies for any non-negative _n_. + +- <tt>\0</tt> is a special backreference, referring to the entire matched string; + it may not be used within the regexp itself, + but may be used outside it (for example, in a substitution method call): + + 'The cat sat in the hat'.gsub(/[csh]at/, '\0s') + # => "The cats sats in the hats" + +==== Named Captures + +As seen above, a capture can be referred to by its number. +A capture can also have a name, +prefixed as <tt>?<_name_></tt> or <tt>?'_name_'</tt>, +and the name (symbolized) may be used as an index in <tt>MatchData[]</tt>: + + md = /\$(?<dollars>\d+)\.(?'cents'\d+)/.match("$3.67") + # => #<MatchData "$3.67" dollars:"3" cents:"67"> + md[:dollars] # => "3" + md[:cents] # => "67" + # The capture numbers are still valid. + md[2] # => "67" + +When a regexp contains a named capture, there are no unnamed captures: + + /\$(?<dollars>\d+)\.(\d+)/.match("$3.67") + # => #<MatchData "$3.67" dollars:"3"> + +A named group may be backreferenced as <tt>\k<_name_></tt>: + + /(?<vowel>[aeiou]).\k<vowel>.\k<vowel>/.match('ototomy') + # => #<MatchData "ototo" vowel:"o"> + +When (and only when) a regexp contains named capture groups +and appears before the <tt>=~</tt> operator, +the captured substrings are assigned to local variables with corresponding names: + + /\$(?<dollars>\d+)\.(?<cents>\d+)/ =~ '$3.67' + dollars # => "3" + cents # => "67" + +\Method Regexp#named_captures returns a hash of the capture names and substrings; +method Regexp#names returns an array of the capture names. + +==== Atomic Grouping + +A group may be made _atomic_ with <tt>(?></tt>_subexpression_<tt>)</tt>. + +This causes the subexpression to be matched +independently of the rest of the expression, +so that the matched substring becomes fixed for the remainder of the match, +unless the entire subexpression must be abandoned and subsequently revisited. + +In this way _subexpression_ is treated as a non-divisible whole. +Atomic grouping is typically used to optimise patterns +to prevent needless backtracking . + +Example (without atomic grouping): + + /".*"/.match('"Quote"') # => #<MatchData "\"Quote\""> + +Analysis: + +1. The leading subexpression <tt>"</tt> in the pattern matches the first character + <tt>"</tt> in the target string. +2. The next subexpression <tt>.*</tt> matches the next substring <tt>Quote“</tt> + (including the trailing double-quote). +3. Now there is nothing left in the target string to match + the trailing subexpression <tt>"</tt> in the pattern; + this would cause the overall match to fail. +4. The matched substring is backtracked by one position: <tt>Quote</tt>. +5. The final subexpression <tt>"</tt> now matches the final substring <tt>"</tt>, + and the overall match succeeds. + +If subexpression <tt>.*</tt> is grouped atomically, +the backtracking is disabled, and the overall match fails: + + /"(?>.*)"/.match('"Quote"') # => nil + +Atomic grouping can affect performance; +see {Atomic Group}[https://www.regular-expressions.info/atomic.html]. + +==== Subexpression Calls + +As seen above, a backreference number (<tt>\\_n_</tt>) or name (<tt>\k<_name_></tt>) +gives access to a captured _substring_; +the corresponding regexp _subexpression_ may also be accessed, +via the number (<tt>\\g<i>n</i></tt>) or name (<tt>\g<_name_></tt>): + + /\A(?<paren>\(\g<paren>*\))*\z/.match('(())') + # ^1 + # ^2 + # ^3 + # ^4 + # ^5 + # ^6 + # ^7 + # ^8 + # ^9 + # ^10 + +The pattern: + +1. Matches at the beginning of the string, i.e. before the first character. +2. Enters a named group +paren+. +3. Matches the first character in the string, <tt>'('</tt>. +4. Calls the +paren+ group again, i.e. recurses back to the second step. +5. Re-enters the +paren+ group. +6. Matches the second character in the string, <tt>'('</tt>. +7. Attempts to call +paren+ a third time, + but fails because doing so would prevent an overall successful match. +8. Matches the third character in the string, <tt>')'</tt>; + marks the end of the second recursive call +9. Matches the fourth character in the string, <tt>')'</tt>. +10. Matches the end of the string. + +See {Subexpression calls}[https://learnbyexample.github.io/Ruby_Regexp/groupings-and-backreferences.html?highlight=subexpression#subexpression-calls]. + +==== Conditionals + +The conditional construct takes the form <tt>(?(_cond_)_yes_|_no_)</tt>, where: + +- _cond_ may be a capture number or name. +- The match to be applied is _yes_ if _cond_ is captured; + otherwise the match to be applied is _no_. +- If not needed, <tt>|_no_</tt> may be omitted. + +Examples: + + re = /\A(foo)?(?(1)(T)|(F))\z/ + re.match('fooT') # => #<MatchData "fooT" 1:"foo" 2:"T" 3:nil> + re.match('F') # => #<MatchData "F" 1:nil 2:nil 3:"F"> + re.match('fooF') # => nil + re.match('T') # => nil + + re = /\A(?<xyzzy>foo)?(?(<xyzzy>)(T)|(F))\z/ + re.match('fooT') # => #<MatchData "fooT" xyzzy:"foo"> + re.match('F') # => #<MatchData "F" xyzzy:nil> + re.match('fooF') # => nil + re.match('T') # => nil + + +==== Absence Operator + +The absence operator is a special group that matches anything which does _not_ match the contained subexpressions. + + /(?~real)/.match('surrealist') # => #<MatchData "surrea"> + /(?~real)ist/.match('surrealist') # => #<MatchData "ealist"> + /sur(?~real)ist/.match('surrealist') # => nil + +=== Unicode + +==== Unicode Properties + +The <tt>/\p{_property_name_}/</tt> construct (with lowercase +p+) +matches characters using a Unicode property name, +much like a character class; +property +Alpha+ specifies alphabetic characters: + + /\p{Alpha}/.match('a') # => #<MatchData "a"> + /\p{Alpha}/.match('1') # => nil + +A property can be inverted +by prefixing the name with a caret character (<tt>^</tt>): + + /\p{^Alpha}/.match('1') # => #<MatchData "1"> + /\p{^Alpha}/.match('a') # => nil + +Or by using <tt>\P</tt> (uppercase +P+): + + /\P{Alpha}/.match('1') # => #<MatchData "1"> + /\P{Alpha}/.match('a') # => nil + +See {Unicode Properties}[rdoc-ref:regexp/unicode_properties.rdoc] +for regexps based on the numerous properties. + +Some commonly-used properties correspond to POSIX bracket expressions: + +- <tt>/\p{Alnum}/</tt>: Alphabetic and numeric character +- <tt>/\p{Alpha}/</tt>: Alphabetic character +- <tt>/\p{Blank}/</tt>: Space or tab +- <tt>/\p{Cntrl}/</tt>: Control character +- <tt>/\p{Digit}/</tt>: Digit + characters, and similar) +- <tt>/\p{Lower}/</tt>: Lowercase alphabetical character +- <tt>/\p{Print}/</tt>: Like <tt>\p{Graph}</tt>, but includes the space character +- <tt>/\p{Punct}/</tt>: Punctuation character +- <tt>/\p{Space}/</tt>: Whitespace character (<tt>[:blank:]</tt>, newline, + carriage return, etc.) +- <tt>/\p{Upper}/</tt>: Uppercase alphabetical +- <tt>/\p{XDigit}/</tt>: Digit allowed in a hexadecimal number (i.e., 0-9a-fA-F) + +These are also commonly used: + +- <tt>/\p{Emoji}/</tt>: Unicode emoji. +- <tt>/\p{Graph}/</tt>: Non-blank character + (excludes spaces, control characters, and similar). +- <tt>/\p{Word}/</tt>: A member in one of these Unicode character + categories (see below) or having one of these Unicode properties: + + - Unicode categories: + - +Mark+ (+M+). + - <tt>Decimal Number</tt> (+Nd+) + - <tt>Connector Punctuation</tt> (+Pc+). + + - Unicode properties: + - +Alpha+ + - <tt>Join_Control</tt> + +- <tt>/\p{ASCII}/</tt>: A character in the ASCII character set. +- <tt>/\p{Any}/</tt>: Any Unicode character (including unassigned characters). +- <tt>/\p{Assigned}/</tt>: An assigned character. + +==== Unicode Character Categories + +A Unicode character category name: + +- May be either its full name or its abbreviated name. +- Is case-insensitive. +- Treats a space, a hyphen, and an underscore as equivalent. + +Examples: + + /\p{lu}/ # => /\p{lu}/ + /\p{LU}/ # => /\p{LU}/ + /\p{Uppercase Letter}/ # => /\p{Uppercase Letter}/ + /\p{Uppercase_Letter}/ # => /\p{Uppercase_Letter}/ + /\p{UPPERCASE-LETTER}/ # => /\p{UPPERCASE-LETTER}/ + +Below are the Unicode character category abbreviations and names. +Enumerations of characters in each category are at the links. + +Letters: + +- +L+, +Letter+: +LC+, +Lm+, or +Lo+. +- +LC+, +Cased_Letter+: +Ll+, +Lt+, or +Lu+. +- {Lu, Lowercase_Letter}[https://www.compart.com/en/unicode/category/Ll]. +- {Lu, Modifier_Letter}[https://www.compart.com/en/unicode/category/Lm]. +- {Lu, Other_Letter}[https://www.compart.com/en/unicode/category/Lo]. +- {Lu, Titlecase_Letter}[https://www.compart.com/en/unicode/category/Lt]. +- {Lu, Uppercase_Letter}[https://www.compart.com/en/unicode/category/Lu]. + +Marks: + +- +M+, +Mark+: +Mc+, +Me+, or +Mn+. +- {Mc, Spacing_Mark}[https://www.compart.com/en/unicode/category/Mc]. +- {Me, Enclosing_Mark}[https://www.compart.com/en/unicode/category/Me]. +- {Mn, Nonapacing_Mark}[https://www.compart.com/en/unicode/category/Mn]. + +Numbers: + +- +N+, +Number+: +Nd+, +Nl+, or +No+. +- {Nd, Decimal_Number}[https://www.compart.com/en/unicode/category/Nd]. +- {Nl, Letter_Number}[https://www.compart.com/en/unicode/category/Nl]. +- {No, Other_Number}[https://www.compart.com/en/unicode/category/No]. + +Punctation: + +- +P+, +Punctuation+: +Pc+, +Pd+, +Pe+, +Pf+, +Pi+, +Po+, or +Ps+. +- {Pc, Connector_Punctuation}[https://www.compart.com/en/unicode/category/Pc]. +- {Pd, Dash_Punctuation}[https://www.compart.com/en/unicode/category/Pd]. +- {Pe, Close_Punctuation}[https://www.compart.com/en/unicode/category/Pe]. +- {Pf, Final_Punctuation}[https://www.compart.com/en/unicode/category/Pf]. +- {Pi, Initial_Punctuation}[https://www.compart.com/en/unicode/category/Pi]. +- {Po, Other_Punctuation}[https://www.compart.com/en/unicode/category/Po]. +- {Ps, Open_Punctuation}[https://www.compart.com/en/unicode/category/Ps]. + +- +S+, +Symbol+: +Sc+, +Sk+, +Sm+, or +So+. +- {Sc, Currency_Symbol}[https://www.compart.com/en/unicode/category/Sc]. +- {Sk, Modifier_Symbol}[https://www.compart.com/en/unicode/category/Sk]. +- {Sm, Math_Symbol}[https://www.compart.com/en/unicode/category/Sm]. +- {So, Other_Symbol}[https://www.compart.com/en/unicode/category/So]. + +- +Z+, +Separator+: +Zl+, +Zp+, or +Zs+. +- {Zl, Line_Separator}[https://www.compart.com/en/unicode/category/Zl]. +- {Zp, Paragraph_Separator}[https://www.compart.com/en/unicode/category/Zp]. +- {Zs, Space_Separator}[https://www.compart.com/en/unicode/category/Zs]. + +- +C+, +Other+: +Cc+, +Cf+, +Cn+, +Co+, or +Cs+. +- {Cc, Control}[https://www.compart.com/en/unicode/category/Cc]. +- {Cf, Format}[https://www.compart.com/en/unicode/category/Cf]. +- {Cn, Unassigned}[https://www.compart.com/en/unicode/category/Cn]. +- {Co, Private_Use}[https://www.compart.com/en/unicode/category/Co]. +- {Cs, Surrogate}[https://www.compart.com/en/unicode/category/Cs]. + +==== Unicode Scripts and Blocks + +Among the Unicode properties are: + +- {Unicode scripts}[https://en.wikipedia.org/wiki/Script_(Unicode)]; + see {supported scripts}[https://www.unicode.org/standard/supported.html]. +- {Unicode blocks}[https://en.wikipedia.org/wiki/Unicode_block]; + see {supported blocks}[http://www.unicode.org/Public/UNIDATA/Blocks.txt]. + +=== POSIX Bracket Expressions + +A POSIX <i>bracket expression</i> is also similar to a character class. +These expressions provide a portable alternative to the above, +with the added benefit of encompassing non-ASCII characters: + +- <tt>/\d/</tt> matches only ASCII decimal digits +0+ through +9+. +- <tt>/[[:digit:]]/</tt> matches any character in the Unicode + <tt>Decimal Number</tt> (+Nd+) category; + see below. + +The POSIX bracket expressions: + +- <tt>/[[:digit:]]/</tt>: Matches a {Unicode digit}[https://www.compart.com/en/unicode/category/Nd]: + + /[[:digit:]]/.match('9') # => #<MatchData "9"> + /[[:digit:]]/.match("\u1fbf9") # => #<MatchData "9"> + +- <tt>/[[:xdigit:]]/</tt>: Matches a digit allowed in a hexadecimal number; + equivalent to <tt>[0-9a-fA-F]</tt>. + +- <tt>/[[:upper:]]/</tt>: Matches a {Unicode uppercase letter}[https://www.compart.com/en/unicode/category/Lu]: + + /[[:upper:]]/.match('A') # => #<MatchData "A"> + /[[:upper:]]/.match("\u00c6") # => #<MatchData "Æ"> + +- <tt>/[[:lower:]]/</tt>: Matches a {Unicode lowercase letter}[https://www.compart.com/en/unicode/category/Ll]: + + /[[:lower:]]/.match('a') # => #<MatchData "a"> + /[[:lower:]]/.match("\u01fd") # => #<MatchData "ǽ"> + +- <tt>/[[:alpha:]]/</tt>: Matches <tt>/[[:upper:]]/</tt> or <tt>/[[:lower:]]/</tt>. + +- <tt>/[[:alnum:]]/</tt>: Matches <tt>/[[:alpha:]]/</tt> or <tt>/[[:digit:]]/</tt>. + +- <tt>/[[:space:]]/</tt>: Matches {Unicode space character}[https://www.compart.com/en/unicode/category/Zs]: + + /[[:space:]]/.match(' ') # => #<MatchData " "> + /[[:space:]]/.match("\u2005") # => #<MatchData " "> + +- <tt>/[[:blank:]]/</tt>: Matches <tt>/[[:space:]]/</tt> or tab character: + + /[[:blank:]]/.match(' ') # => #<MatchData " "> + /[[:blank:]]/.match("\u2005") # => #<MatchData " "> + /[[:blank:]]/.match("\t") # => #<MatchData "\t"> + +- <tt>/[[:cntrl:]]/</tt>: Matches {Unicode control character}[https://www.compart.com/en/unicode/category/Cc]: + + /[[:cntrl:]]/.match("\u0000") # => #<MatchData "\u0000"> + /[[:cntrl:]]/.match("\u009f") # => #<MatchData "\u009F"> + +- <tt>/[[:graph:]]/</tt>: Matches any character + except <tt>/[[:space:]]/</tt> or <tt>/[[:cntrl:]]/</tt>. + +- <tt>/[[:print:]]/</tt>: Matches <tt>/[[:graph:]]/</tt> or space character. + +- <tt>/[[:punct:]]/</tt>: Matches any (Unicode punctuation character}[https://www.compart.com/en/unicode/category/Po]: + +Ruby also supports these (non-POSIX) bracket expressions: + +- <tt>/[[:ascii:]]/</tt>: Matches a character in the ASCII character set. +- <tt>/[[:word:]]/</tt>: Matches a character in one of these Unicode character + categories or having one of these Unicode properties: + + - Unicode categories: + - +Mark+ (+M+). + - <tt>Decimal Number</tt> (+Nd+) + - <tt>Connector Punctuation</tt> (+Pc+). + + - Unicode properties: + - +Alpha+ + - <tt>Join_Control</tt> + +=== Comments + +A comment may be included in a regexp pattern +using the <tt>(?#</tt>_comment_<tt>)</tt> construct, +where _comment_ is a substring that is to be ignored. +arbitrary text ignored by the regexp engine: + + /foo(?#Ignore me)bar/.match('foobar') # => #<MatchData "foobar"> + +The comment may not include an unescaped terminator character. + +See also {Extended Mode}[rdoc-ref:Regexp@Extended+Mode]. + +== Modes + +Each of these modifiers sets a mode for the regexp: + +- +i+: <tt>/_pattern_/i</tt> sets + {Case-Insensitive Mode}[rdoc-ref:Regexp@Case-Insensitive+Mode]. +- +m+: <tt>/_pattern_/m</tt> sets + {Multiline Mode}[rdoc-ref:Regexp@Multiline+Mode]. +- +x+: <tt>/_pattern_/x</tt> sets + {Extended Mode}[rdoc-ref:Regexp@Extended+Mode]. +- +o+: <tt>/_pattern_/o</tt> sets + {Interpolation Mode}[rdoc-ref:Regexp@Interpolation+Mode]. + +Any, all, or none of these may be applied. + +Modifiers +i+, +m+, and +x+ may be applied to subexpressions: + +- <tt>(?_modifier_)</tt> turns the mode "on" for ensuing subexpressions +- <tt>(?-_modifier_)</tt> turns the mode "off" for ensuing subexpressions +- <tt>(?_modifier_:_subexp_)</tt> turns the mode "on" for _subexp_ within the group +- <tt>(?-_modifier_:_subexp_)</tt> turns the mode "off" for _subexp_ within the group + +Example: + + re = /(?i)te(?-i)st/ + re.match('test') # => #<MatchData "test"> + re.match('TEst') # => #<MatchData "TEst"> + re.match('TEST') # => nil + re.match('teST') # => nil + + re = /t(?i:e)st/ + re.match('test') # => #<MatchData "test"> + re.match('tEst') # => #<MatchData "tEst"> + re.match('tEST') # => nil + +\Method Regexp#options returns an integer whose value showing +the settings for case-insensitivity mode, multiline mode, and extended mode. + +=== Case-Insensitive Mode + +By default, a regexp is case-sensitive: + + /foo/.match('FOO') # => nil + +Modifier +i+ enables case-insensitive mode: + + /foo/i.match('FOO') + # => #<MatchData "FOO"> + +\Method Regexp#casefold? returns whether the mode is case-insensitive. + +=== Multiline Mode + +The multiline-mode in Ruby is what is commonly called a "dot-all mode": + +- Without the +m+ modifier, the subexpression <tt>.</tt> does not match newlines: + + /a.c/.match("a\nc") # => nil + +- With the modifier, it does match: + + /a.c/m.match("a\nc") # => #<MatchData "a\nc"> + +Unlike other languages, the modifier +m+ does not affect the anchors <tt>^</tt> and <tt>$</tt>. +These anchors always match at line-boundaries in Ruby. + +=== Extended Mode + +Modifier +x+ enables extended mode, which means that: + +- Literal white space in the pattern is to be ignored. +- Character <tt>#</tt> marks the remainder of its containing line as a comment, + which is also to be ignored for matching purposes. + +In extended mode, whitespace and comments may be used +to form a self-documented regexp. + +Regexp not in extended mode (matches some Roman numerals): + + pattern = '^M{0,3}(CM|CD|D?C{0,3})(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})$' + re = /#{pattern}/ + re.match('MCMXLIII') # => #<MatchData "MCMXLIII" 1:"CM" 2:"XL" 3:"III"> + +Regexp in extended mode: + + pattern = <<-EOT + ^ # beginning of string + M{0,3} # thousands - 0 to 3 Ms + (CM|CD|D?C{0,3}) # hundreds - 900 (CM), 400 (CD), 0-300 (0 to 3 Cs), + # or 500-800 (D, followed by 0 to 3 Cs) + (XC|XL|L?X{0,3}) # tens - 90 (XC), 40 (XL), 0-30 (0 to 3 Xs), + # or 50-80 (L, followed by 0 to 3 Xs) + (IX|IV|V?I{0,3}) # ones - 9 (IX), 4 (IV), 0-3 (0 to 3 Is), + # or 5-8 (V, followed by 0 to 3 Is) + $ # end of string + EOT + re = /#{pattern}/x + re.match('MCMXLIII') # => #<MatchData "MCMXLIII" 1:"CM" 2:"XL" 3:"III"> + +=== Interpolation Mode + +Modifier +o+ means that the first time a literal regexp with interpolations +is encountered, +the generated Regexp object is saved and used for all future evaluations +of that literal regexp. +Without modifier +o+, the generated Regexp is not saved, +so each evaluation of the literal regexp generates a new Regexp object. + +Without modifier +o+: + + def letters; sleep 5; /[A-Z][a-z]/; end + words = %w[abc def xyz] + start = Time.now + words.each {|word| word.match(/\A[#{letters}]+\z/) } + Time.now - start # => 15.0174892 + +With modifier +o+: + + start = Time.now + words.each {|word| word.match(/\A[#{letters}]+\z/o) } + Time.now - start # => 5.0010866 + +Note that if the literal regexp does not have interpolations, +the +o+ behavior is the default. + +== Encodings + +By default, a regexp with only US-ASCII characters has US-ASCII encoding: + + re = /foo/ + re.source.encoding # => #<Encoding:US-ASCII> + re.encoding # => #<Encoding:US-ASCII> + +A regular expression containing non-US-ASCII characters +is assumed to use the source encoding. +This can be overridden with one of the following modifiers. + +- <tt>/_pat_/n</tt>: US-ASCII if only containing US-ASCII characters, + otherwise ASCII-8BIT: + + /foo/n.encoding # => #<Encoding:US-ASCII> + /foo\xff/n.encoding # => #<Encoding:ASCII-8BIT> + /foo\x7f/n.encoding # => #<Encoding:US-ASCII> + +- <tt>/_pat_/u</tt>: UTF-8 + + /foo/u.encoding # => #<Encoding:UTF-8> + +- <tt>/_pat_/e</tt>: EUC-JP + + /foo/e.encoding # => #<Encoding:EUC-JP> + +- <tt>/_pat_/s</tt>: Windows-31J + + /foo/s.encoding # => #<Encoding:Windows-31J> + +A regexp can be matched against a target string when either: + +- They have the same encoding. +- The regexp's encoding is a fixed encoding and the string + contains only ASCII characters. + Method Regexp#fixed_encoding? returns whether the regexp + has a <i>fixed</i> encoding. + +If a match between incompatible encodings is attempted an +<tt>Encoding::CompatibilityError</tt> exception is raised. + +Example: + + re = eval("# encoding: ISO-8859-1\n/foo\\xff?/") + re.encoding # => #<Encoding:ISO-8859-1> + re =~ "foo".encode("UTF-8") # => 0 + re =~ "foo\u0100" # Raises Encoding::CompatibilityError + +The encoding may be explicitly fixed by including Regexp::FIXEDENCODING +in the second argument for Regexp.new: + + # Regexp with encoding ISO-8859-1. + re = Regexp.new("a".force_encoding('iso-8859-1'), Regexp::FIXEDENCODING) + re.encoding # => #<Encoding:ISO-8859-1> + # Target string with encoding UTF-8. + s = "a\u3042" + s.encoding # => #<Encoding:UTF-8> + re.match(s) # Raises Encoding::CompatibilityError. + +== Timeouts + +When either a regexp source or a target string comes from untrusted input, +malicious values could become a denial-of-service attack; +to prevent such an attack, it is wise to set a timeout. + +\Regexp has two timeout values: + +- A class default timeout, used for a regexp whose instance timeout is +nil+; + this default is initially +nil+, and may be set by method Regexp.timeout=: + + Regexp.timeout # => nil + Regexp.timeout = 3.0 + Regexp.timeout # => 3.0 + +- An instance timeout, which defaults to +nil+ and may be set in Regexp.new: + + re = Regexp.new('foo', timeout: 5.0) + re.timeout # => 5.0 + +When regexp.timeout is +nil+, the timeout "falls through" to Regexp.timeout; +when regexp.timeout is non-+nil+, that value controls timing out: + + | regexp.timeout Value | Regexp.timeout Value | Result | + |----------------------|----------------------|-----------------------------| + | nil | nil | Never times out. | + | nil | Float | Times out in Float seconds. | + | Float | Any | Times out in Float seconds. | + +== Optimization + +For certain values of the pattern and target string, +matching time can grow polynomially or exponentially in relation to the input size; +the potential vulnerability arising from this is the {regular expression denial-of-service}[https://en.wikipedia.org/wiki/ReDoS] (ReDoS) attack. + +\Regexp matching can apply an optimization to prevent ReDoS attacks. +When the optimization is applied, matching time increases linearly (not polynomially or exponentially) +in relation to the input size, and a ReDoS attach is not possible. + +This optimization is applied if the pattern meets these criteria: + +- No backreferences. +- No subexpression calls. +- No nested lookaround anchors or atomic groups. +- No nested quantifiers with counting (i.e. no nested <tt>{n}</tt>, + <tt>{min,}</tt>, <tt>{,max}</tt>, or <tt>{min,max}</tt> style quantifiers) + +You can use method Regexp.linear_time? to determine whether a pattern meets these criteria: + + Regexp.linear_time?(/a*/) # => true + Regexp.linear_time?('a*') # => true + Regexp.linear_time?(/(a*)\1/) # => false + +However, an untrusted source may not be safe even if the method returns +true+, +because the optimization uses memoization (which may invoke large memory consumption). + +== References + +Read (online PDF books): + +- {Mastering Regular Expressions}[https://ia902508.us.archive.org/10/items/allitebooks-02/Mastering%20Regular%20Expressions%2C%203rd%20Edition.pdf] + by Jeffrey E.F. Friedl. +- {Regular Expressions Cookbook}[https://doc.lagout.org/programmation/Regular%20Expressions/Regular%20Expressions%20Cookbook_%20Detailed%20Solutions%20in%20Eight%20Programming%20Languages%20%282nd%20ed.%29%20%5BGoyvaerts%20%26%20Levithan%202012-09-06%5D.pdf] + by Jan Goyvaerts & Steven Levithan. + +Explore, test (interactive online editor): + +- {Rubular}[https://rubular.com/]. diff --git a/doc/_timezones.rdoc b/doc/_timezones.rdoc new file mode 100644 index 0000000000..c5230ea67d --- /dev/null +++ b/doc/_timezones.rdoc @@ -0,0 +1,156 @@ +== Timezone Specifiers + +Certain +Time+ methods accept arguments that specify timezones: + +- Time.at: keyword argument +in:+. +- Time.new: positional argument +zone+ or keyword argument +in:+. +- Time.now: keyword argument +in:+. +- Time#getlocal: positional argument +zone+. +- Time#localtime: positional argument +zone+. + +The value given with any of these must be one of the following +(each detailed below): + +- {Hours/minutes offset}[rdoc-ref:Time@Hours-2FMinutes+Offsets]. +- {Single-letter offset}[rdoc-ref:Time@Single-Letter+Offsets]. +- {Integer offset}[rdoc-ref:Time@Integer+Offsets]. +- {Timezone object}[rdoc-ref:Time@Timezone+Objects]. +- {Timezone name}[rdoc-ref:Time@Timezone+Names]. + +=== Hours/Minutes Offsets + +The zone value may be a string offset from UTC +in the form <tt>'+HH:MM'</tt> or <tt>'-HH:MM'</tt>, +where: + +- +HH+ is the 2-digit hour in the range <tt>0..23</tt>. +- +MM+ is the 2-digit minute in the range <tt>0..59</tt>. + +Examples: + + t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC + Time.at(t, in: '-23:59') # => 1999-12-31 20:16:01 -2359 + Time.at(t, in: '+23:59') # => 2000-01-02 20:14:01 +2359 + +=== Single-Letter Offsets + +The zone value may be a letter in the range <tt>'A'..'I'</tt> +or <tt>'K'..'Z'</tt>; +see {List of military time zones}[https://en.wikipedia.org/wiki/List_of_military_time_zones]: + + t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC + Time.at(t, in: 'A') # => 2000-01-01 21:15:01 +0100 + Time.at(t, in: 'I') # => 2000-01-02 05:15:01 +0900 + Time.at(t, in: 'K') # => 2000-01-02 06:15:01 +1000 + Time.at(t, in: 'Y') # => 2000-01-01 08:15:01 -1200 + Time.at(t, in: 'Z') # => 2000-01-01 20:15:01 UTC + +=== \Integer Offsets + +The zone value may be an integer number of seconds +in the range <tt>-86399..86399</tt>: + + t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC + Time.at(t, in: -86399) # => 1999-12-31 20:15:02 -235959 + Time.at(t, in: 86399) # => 2000-01-02 20:15:00 +235959 + +=== Timezone Objects + +The zone value may be an object responding to certain timezone methods, an +instance of {Timezone}[https://github.com/panthomakos/timezone] and +{TZInfo}[https://tzinfo.github.io] for example. + +The timezone methods are: + +- +local_to_utc+: + + - Called when Time.new is invoked with +tz+ + as the value of positional argument +zone+ or keyword argument +in:+. + - Argument: a {Time-like object}[rdoc-ref:Time@Time-Like+Objects]. + - Returns: a {Time-like object}[rdoc-ref:Time@Time-Like+Objects] in the UTC timezone. + +- +utc_to_local+: + + - Called when Time.at or Time.now is invoked with +tz+ + as the value for keyword argument +in:+, + and when Time#getlocal or Time#localtime is called with +tz+ + as the value for positional argument +zone+. + - Argument: a {Time-like object}[rdoc-ref:Time@Time-Like+Objects]. + - Returns: a {Time-like object}[rdoc-ref:Time@Time-Like+Objects] in the local timezone. + +A custom timezone class may have these instance methods, +which will be called if defined: + +- +abbr+: + + - Called when Time#strftime is invoked with a format involving <tt>%Z</tt>. + - Argument: a {Time-like object}[rdoc-ref:Time@Time-Like+Objects]. + - Returns: a string abbreviation for the timezone name. + +- +dst?+: + + - Called when Time.at or Time.now is invoked with +tz+ + as the value for keyword argument +in:+, + and when Time#getlocal or Time#localtime is called with +tz+ + as the value for positional argument +zone+. + - Argument: a {Time-like object}[rdoc-ref:Time@Time-Like+Objects]. + - Returns: whether the time is daylight saving time. + +- +name+: + + - Called when <tt>Marshal.dump(t)</tt> is invoked + - Argument: none. + - Returns: the string name of the timezone. + +==== +Time+-Like Objects + +A +Time+-like object is a container object capable of interfacing with +timezone libraries for timezone conversion. + +The argument to the timezone conversion methods above will have attributes +similar to Time, except that timezone related attributes are meaningless. + +The objects returned by +local_to_utc+ and +utc_to_local+ methods of the +timezone object may be of the same class as their arguments, of arbitrary +object classes, or of class Integer. + +For a returned class other than +Integer+, the class must have the +following methods: + +- +year+ +- +mon+ +- +mday+ +- +hour+ +- +min+ +- +sec+ +- +isdst+ +- +to_i+ + +For a returned +Integer+, its components, decomposed in UTC, are +interpreted as times in the specified timezone. + +=== Timezone Names + +If the class (the receiver of class methods, or the class of the receiver +of instance methods) has +find_timezone+ singleton method, this method is +called to achieve the corresponding timezone object from a timezone name. + +For example, using {Timezone}[https://github.com/panthomakos/timezone]: + class TimeWithTimezone < Time + require 'timezone' + def self.find_timezone(z) = Timezone[z] + end + + TimeWithTimezone.now(in: "America/New_York") #=> 2023-12-25 00:00:00 -0500 + TimeWithTimezone.new("2023-12-25 America/New_York") #=> 2023-12-25 00:00:00 -0500 + +Or, using {TZInfo}[https://tzinfo.github.io]: + class TimeWithTZInfo < Time + require 'tzinfo' + def self.find_timezone(z) = TZInfo::Timezone.get(z) + end + + TimeWithTZInfo.now(in: "America/New_York") #=> 2023-12-25 00:00:00 -0500 + TimeWithTZInfo.new("2023-12-25 America/New_York") #=> 2023-12-25 00:00:00 -0500 + +You can define this method per subclasses, or on the toplevel Time class. diff --git a/doc/bsearch.rdoc b/doc/bsearch.rdoc index ca8091fc0d..90705853d7 100644 --- a/doc/bsearch.rdoc +++ b/doc/bsearch.rdoc @@ -1,4 +1,4 @@ -== Binary Searching += Binary Searching A few Ruby methods support binary searching in a collection: diff --git a/doc/case_mapping.rdoc b/doc/case_mapping.rdoc new file mode 100644 index 0000000000..57c037b9d8 --- /dev/null +++ b/doc/case_mapping.rdoc @@ -0,0 +1,116 @@ += Case Mapping + +Some string-oriented methods use case mapping. + +In String: + +- String#capitalize +- String#capitalize! +- String#casecmp +- String#casecmp? +- String#downcase +- String#downcase! +- String#swapcase +- String#swapcase! +- String#upcase +- String#upcase! + +In Symbol: + +- Symbol#capitalize +- Symbol#casecmp +- Symbol#casecmp? +- Symbol#downcase +- Symbol#swapcase +- Symbol#upcase + +== Default Case Mapping + +By default, all of these methods use full Unicode case mapping, +which is suitable for most languages. +See {Section 3.13 (Default Case Algorithms) of the Unicode standard}[https://www.unicode.org/versions/latest/ch03.pdf]. + +Non-ASCII case mapping and folding are supported for UTF-8, +UTF-16BE/LE, UTF-32BE/LE, and ISO-8859-1~16 Strings/Symbols. + +Context-dependent case mapping as described in +{Table 3-17 (Context Specification for Casing) of the Unicode standard}[https://www.unicode.org/versions/latest/ch03.pdf] +is currently not supported. + +In most cases, case conversions of a string have the same number of characters. +There are exceptions (see also +:fold+ below): + + s = "\u00DF" # => "ß" + s.upcase # => "SS" + s = "\u0149" # => "ʼn" + s.upcase # => "ʼN" + +Case mapping may also depend on locale (see also +:turkic+ below): + + s = "\u0049" # => "I" + s.downcase # => "i" # Dot above. + s.downcase(:turkic) # => "ı" # No dot above. + +Case changes may not be reversible: + + s = 'Hello World!' # => "Hello World!" + s.downcase # => "hello world!" + s.downcase.upcase # => "HELLO WORLD!" # Different from original s. + +Case changing methods may not maintain Unicode normalization. +See String#unicode_normalize). + +== Options for Case Mapping + +Except for +casecmp+ and +casecmp?+, +each of the case-mapping methods listed above +accepts optional arguments, <tt>*options</tt>. + +The arguments may be: + +- +:ascii+ only. +- +:fold+ only. +- +:turkic+ or +:lithuanian+ or both. + +The options: + +- +:ascii+: + ASCII-only mapping: + uppercase letters ('A'..'Z') are mapped to lowercase letters ('a'..'z); + other characters are not changed + + s = "Foo \u00D8 \u00F8 Bar" # => "Foo Ø ø Bar" + s.upcase # => "FOO Ø Ø BAR" + s.downcase # => "foo ø ø bar" + s.upcase(:ascii) # => "FOO Ø ø BAR" + s.downcase(:ascii) # => "foo Ø ø bar" + +- +:turkic+: + Full Unicode case mapping, adapted for the Turkic languages + that distinguish dotted and dotless I, for example Turkish and Azeri. + + s = 'Türkiye' # => "Türkiye" + s.upcase # => "TÜRKIYE" + s.upcase(:turkic) # => "TÜRKİYE" # Dot above. + + s = 'TÜRKIYE' # => "TÜRKIYE" + s.downcase # => "türkiye" + s.downcase(:turkic) # => "türkıye" # No dot above. + +- +:lithuanian+: + Not yet implemented. + +- +:fold+ (available only for String#downcase, String#downcase!, + and Symbol#downcase): + Unicode case folding, + which is more far-reaching than Unicode case mapping. + + s = "\u00DF" # => "ß" + s.downcase # => "ß" + s.downcase(:fold) # => "ss" + s.upcase # => "SS" + + s = "\uFB04" # => "ffl" + s.downcase # => "ffl" + s.upcase # => "FFL" + s.downcase(:fold) # => "ffl" diff --git a/doc/character_selectors.rdoc b/doc/character_selectors.rdoc new file mode 100644 index 0000000000..47cf242be7 --- /dev/null +++ b/doc/character_selectors.rdoc @@ -0,0 +1,97 @@ += Character Selectors + +== Character Selector + +A _character_ _selector_ is a string argument accepted by certain Ruby methods. +Each of these instance methods accepts one or more character selectors: + +- String#tr(selector, replacements): returns a new string. +- String#tr!(selector, replacements): returns +self+ or +nil+. +- String#tr_s(selector, replacements): returns a new string. +- String#tr_s!(selector, replacements): returns +self+ or +nil+. +- String#count(*selectors): returns the count of the specified characters. +- String#delete(*selectors): returns a new string. +- String#delete!(*selectors): returns +self+ or +nil+. +- String#squeeze(*selectors): returns a new string. +- String#squeeze!(*selectors): returns +self+ or +nil+. + +A character selector identifies zero or more characters in +self+ +that are to be operands for the method. + +In this section, we illustrate using method String#delete(selector), +which deletes the selected characters. + +In the simplest case, the characters selected are exactly those +contained in the selector itself: + + 'abracadabra'.delete('a') # => "brcdbr" + 'abracadabra'.delete('ab') # => "rcdr" + 'abracadabra'.delete('abc') # => "rdr" + '0123456789'.delete('258') # => "0134679" + '!@#$%&*()_+'.delete('+&#') # => "!@$%*()_" + 'тест'.delete('т') # => "ес" + 'こんにちは'.delete('に') # => "こんちは" + +Note that order and repetitions do not matter: + + 'abracadabra'.delete('dcab') # => "rr" + 'abracadabra'.delete('aaaa') # => "brcdbr" + +In a character selector, these three characters get special treatment: + +- A leading caret (<tt>'^'</tt>) functions as a "not" operator + for the characters to its right: + + 'abracadabra'.delete('^bc') # => "bcb" + '0123456789'.delete('^852') # => "258" + +- A hyphen (<tt>'-'</tt>) between two other characters + defines a range of characters instead of a plain string of characters: + + 'abracadabra'.delete('a-d') # => "rr" + '0123456789'.delete('4-7') # => "012389" + '!@#$%&*()_+'.delete(' -/') # => "@^_" + + # May contain more than one range. + 'abracadabra'.delete('a-cq-t') # => "d" + + # Ranges may be mixed with plain characters. + '0123456789'.delete('67-950-23') # => "4" + + # Ranges may be mixed with negations. + 'abracadabra'.delete('^a-c') # => "abacaaba" + +- A backslash (<tt>'\'</tt>) acts as an escape for a caret, a hyphen, + or another backslash: + + 'abracadabra^'.delete('\^bc') # => "araadara" + 'abracadabra-'.delete('a\-d') # => "brcbr" + "hello\r\nworld".delete("\r") # => "hello\nworld" + "hello\r\nworld".delete("\\r") # => "hello\r\nwold" + "hello\r\nworld".delete("\\\r") # => "hello\nworld" + +== Multiple Character Selectors + +These instance methods accept multiple character selectors: + +- String#count(*selectors): returns the count of the specified characters. +- String#delete(*selectors): returns a new string. +- String#delete!(*selectors): returns +self+ or +nil+. +- String#squeeze(*selectors): returns a new string. +- String#squeeze!(*selectors): returns +self+ or +nil+. + +In effect, the given selectors are formed into a single selector +consisting of only those characters common to _all_ of the given selectors. + +All forms of selectors may be used, including negations, ranges, and escapes. + +Each of these pairs of method calls is equivalent: + + s.delete('abcde', 'dcbfg') + s.delete('bcd') + + s.delete('^abc', '^def') + s.delete('^abcdef') + + s.delete('a-e', 'c-g') + s.delete('cde') diff --git a/doc/command_injection.rdoc b/doc/command_injection.rdoc new file mode 100644 index 0000000000..ee33d4a04e --- /dev/null +++ b/doc/command_injection.rdoc @@ -0,0 +1,37 @@ += Command Injection + +Some Ruby core methods accept string data +that includes text to be executed as a system command. + +They should not be called with unknown or unsanitized commands. + +These methods include: + +- Kernel.exec +- Kernel.spawn +- Kernel.system +- {\`command` (backtick method)}[rdoc-ref:Kernel#`] + (also called by the expression <tt>%x[command]</tt>). +- IO.popen (when called with other than <tt>"-"</tt>). + +Some methods execute a system command only if the given path name starts +with a <tt>|</tt>: + +- Kernel.open(command). +- IO.read(command). +- IO.write(command). +- IO.binread(command). +- IO.binwrite(command). +- IO.readlines(command). +- IO.foreach(command). +- URI.open(command). + +Note that some of these methods do not execute commands when called +from subclass +File+: + +- File.read(path). +- File.write(path). +- File.binread(path). +- File.binwrite(path). +- File.readlines(path). +- File.foreach(path). diff --git a/doc/command_line/environment.md b/doc/command_line/environment.md new file mode 100644 index 0000000000..abdfd5cfeb --- /dev/null +++ b/doc/command_line/environment.md @@ -0,0 +1,173 @@ +## Environment + +Certain command-line options affect the execution environment +of the invoked Ruby program. + +### About the Examples + +The examples here use command-line option `-e`, +which passes the Ruby code to be executed on the command line itself: + +```sh +$ ruby -e 'puts "Hello, World."' +``` + +### Option `-C` + +The argument to option `-C` specifies a working directory +for the invoked Ruby program; +does not change the working directory for the current process: + +```sh +$ basename `pwd` +ruby +$ ruby -C lib -e 'puts File.basename(Dir.pwd)' +lib +$ basename `pwd` +ruby +``` + +Whitespace between the option and its argument may be omitted. + +### Option `-I` + +The argument to option `-I` specifies a directory +to be added to the array in global variable `$LOAD_PATH`; +the option may be given more than once: + +```sh +$ pushd /tmp +$ ruby -e 'p $LOAD_PATH.size' +8 +$ ruby -I my_lib -I some_lib -e 'p $LOAD_PATH.size' +10 +$ ruby -I my_lib -I some_lib -e 'p $LOAD_PATH.take(2)' +["/tmp/my_lib", "/tmp/some_lib"] +$ popd +``` + +Whitespace between the option and its argument may be omitted. + +### Option `-r` + +The argument to option `-r` specifies a library to be required +before executing the Ruby program; +the option may be given more than once: + +```sh +$ ruby -e 'p defined?(JSON); p defined?(CSV)' +nil +nil +$ ruby -r CSV -r JSON -e 'p defined?(JSON); p defined?(CSV)' +"constant" +"constant" +``` + +Whitespace between the option and its argument may be omitted. + +### Option `-0` + +Option `-0` defines the input record separator `$/` +for the invoked Ruby program. + +The optional argument to the option must be octal digits, +each in the range `0..7`; +these digits are prefixed with digit `0` to form an octal value: + +- If no argument is given, the input record separator is `0x00`. +- If the argument is `0`, the input record separator is `''`; + see {Special Line Separator Values}[rdoc-ref:IO@Special+Line+Separator+Values]. +- If the argument is in range `(1..0377)`, + it becomes the character value of the input record separator `$/`. +- Otherwise, the input record separator is `nil`. + +Examples: + +```sh +$ ruby -0 -e 'p $/' +"\x00" +ruby -00 -e 'p $/' +"" +$ ruby -012 -e 'p $/' +"\n" +$ ruby -015 -e 'p $/' +"\r" +$ ruby -0377 -e 'p $/' +"\xFF" +$ ruby -0400 -e 'p $/' +nil +``` + +The option may not be separated from its argument by whitespace. + +### Option `-d` + +Some code in (or called by) the Ruby program may include statements or blocks +conditioned by the global variable `$DEBUG` (e.g., `if $DEBUG`); +these commonly write to `$stdout` or `$stderr`. + +The default value for `$DEBUG` is `false`; +option `-d` (or `--debug`) sets it to `true`: + +```sh +$ ruby -e 'p $DEBUG' +false +$ ruby -d -e 'p $DEBUG' +true +``` + +### Option '-w' + +Option `-w` (lowercase letter) is equivalent to option `-W1` (uppercase letter). + +### Option `-W` + +Any Ruby code can create a <i>warning message</i> by calling method Kernel#warn; +methods in the Ruby core and standard libraries can also create warning messages. +Such a message may be printed on `$stderr` +(or not, depending on certain settings). + +Option `-W` helps determine whether a particular warning message +will be written, +by setting the initial value of global variable `$-W`: + +- `-W0`: Sets `$-W` to `0` (silent; no warnings). +- `-W1`: Sets `$-W` to `1` (moderate verbosity). +- `-W2`: Sets `$-W` to `2` (high verbosity). +- `-W`: Same as `-W2` (high verbosity). +- Option not given: Same as `-W1` (moderate verbosity). + +The value of `$-W`, in turn, determines which warning messages (if any) +are to be printed to `$stdout` (see Kernel#warn): + +```sh +$ ruby -W1 -e 'p $foo' +nil +$ ruby -W2 -e 'p $foo' +-e:1: warning: global variable '$foo' not initialized +nil +``` + +Ruby code may also define warnings for certain categories; +these are the default settings for the defined categories: + +``` +Warning[:experimental] # => true +Warning[:deprecated] # => false +Warning[:performance] # => false +``` + +They may also be set: +``` +Warning[:experimental] = false +Warning[:deprecated] = true +Warning[:performance] = true +``` + +You can suppress a category by prefixing `no-` to the category name: + +``` +$ ruby -W:no-experimental -e 'p IO::Buffer.new' +#<IO::Buffer> +``` + diff --git a/doc/contributing.md b/doc/contributing.md new file mode 100644 index 0000000000..a6c63de9b2 --- /dev/null +++ b/doc/contributing.md @@ -0,0 +1,12 @@ +# Contributing to Ruby + +This guide outlines ways to get started with contributing to Ruby: + +* [Reporting issues](contributing/reporting_issues.md): How to report issues, how to request features, and how backporting works +* [Building Ruby](contributing/building_ruby.md): How to build Ruby on your local machine for development +* [Testing Ruby](contributing/testing_ruby.md): How to test Ruby on your local machine once you've built it +* [Making changes to Ruby](contributing/making_changes_to_ruby.md): How to submit pull requests + to change Ruby's documentation, code, test suite, or standard libraries +* [Making changes to Ruby standard libraries](contributing/making_changes_to_stdlibs.md): How to build, test, and contribute to Ruby standard libraries +* [Making changes to Ruby documentation](contributing/documentation_guide.md): How to make changes to Ruby documentation +* [Benchmarking Ruby](https://github.com/ruby/ruby/tree/master/benchmark#make-benchmark): How to benchmark Ruby diff --git a/doc/contributing.rdoc b/doc/contributing.rdoc deleted file mode 100644 index 00875d1428..0000000000 --- a/doc/contributing.rdoc +++ /dev/null @@ -1,402 +0,0 @@ -= Contributing to Ruby - -Ruby has a vast and friendly community with hundreds of people contributing to -a thriving open-source ecosystem. This guide is designed to cover ways for -participating in the development of CRuby. - -There are plenty of ways for you to help even if you're not ready to write -code or documentation. You can help by reporting issues, testing patches, and -trying out beta releases with your applications. - -== How To Report - -If you've encountered a bug in Ruby please report it to the redmine issue -tracker available at {bugs.ruby-lang.org}[https://bugs.ruby-lang.org/]. Do not -report security vulnerabilities here, there is a {separate -channel}[rdoc-label:label-Reporting+Security+Issues] for them. - -There are a few simple steps you should follow in order to receive feedback -on your ticket. - -* If you haven't already, - {sign up for an account}[https://bugs.ruby-lang.org/account/register] on the - bug tracker. -* Try the latest version. - - If you aren't already using the latest version, try installing a newer - stable release. See - {Downloading Ruby}[https://www.ruby-lang.org/en/downloads/]. -* Look to see if anyone already reported your issue, try - {searching on redmine}[https://bugs.ruby-lang.org/projects/ruby-master/issues] - for your problem. -* If you can't find a ticket addressing your issue, - {create a new one}[https://bugs.ruby-lang.org/projects/ruby-master/issues/new]. -* Choose the target version, usually current. Bugs will be first fixed in the - current release and then {backported}[rdoc-label:label-Backport+Requests]. -* Fill in the Ruby version you're using when experiencing this issue - (<code>ruby -v</code>). -* Attach any logs or reproducible programs to provide additional information. - Reproducible scripts should be as small as possible. -* Briefly describe your problem. A 2-3 sentence description will help give a - quick response. -* Pick a category, such as core for common problems, or lib for a standard - library. -* Check the {Maintainers - list}[https://bugs.ruby-lang.org/projects/ruby/wiki/Maintainers] and assign - the ticket if there is an active maintainer for the library or feature. -* If the ticket doesn't have any replies after 10 days, you can send a - reminder. -* Please reply to feedback requests. If a bug report doesn't get any feedback, - it'll eventually get rejected. - -=== Reporting to downstream distributions - -You can report downstream issues for the following distributions via their bug tracker: - -* {debian}[https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=ruby-defaults] -* {freebsd}[http://www.freebsd.org/cgi/query-pr-summary.cgi?text=ruby] -* {redhat}[https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=MODIFIED] -* {macports}[https://trac.macports.org/query?status=assigned&status=new&status=reopened&port=~ruby] -* etc (add your distribution bug tracker here) - -== Reporting Security Issues - -Security vulnerabilities receive special treatment since they may negatively -affect many users. There is a private mailing list that all security issues -should be reported to and will be handled discretely. Email the -mailto:security@ruby-lang.org list and the problem will be published after -fixes have been released. You can also encrypt the issue using {the PGP public -key}[https://www.ruby-lang.org/security.asc] for the list. - -== Reporting Other Issues - -If you're having an issue with the website, or maybe the mailing list, you can -contact the webmaster to help resolve the problem. - -The current webmaster is: - -* Hiroshi SHIBATA (hsbt) - -You can also report issues with the ruby-lang.org website on the issue tracker: - -* {issue tracker}[https://github.com/ruby/www.ruby-lang.org/issues] - -== Resolve Existing Issues - -As a next step beyond reporting issues you can help the core team resolve -existing issues. If you check the Everyone's Issues list in GitHub Issues, -you will find a lot of issues already requiring attention. What can you do for -these? Quite a bit, actually: - -When a bug report goes for a while without any feedback, it goes to the bug -graveyard which is unfortunate. If you check the {issues -list}[https://bugs.ruby-lang.org/projects/ruby-master/issues] you will find lots -of delinquent bugs that require attention. - -You can help by verifying the existing tickets, try to reproduce the reported -issue on your own and comment if you still experience the bug. Some issues -lack attention because of too much ambiguity, to help you can narrow down the -problem and provide more specific details or instructions to reproduce the -bug. You might also try contributing a failing test in the form of a patch, -which we will cover later in this guide. - -It may also help to try out patches other contributors have submitted to -redmine, if gone without notice. In this case the +patch+ command is your -friend, see <code>man patch</code> for more information. Basically this would -go something like this: - - cd path/to/ruby - patch -p0 < path/to/patch - -You will then be prompted to apply the patch with the associated files. After -building ruby again, you should try to run the tests and verify if the change -actually worked or fixed the bug. It's important to provide valuable feedback -on the patch that can help reach the overall goal, try to answer some of these -questions: - -* What do you like about this change? -* What would you do differently? -* Are there any other edge cases not tested? -* Is there any documentation that would be affected by this change? - -If you can answer some or all of these questions, you're on the right track. -If your comment simply says "+1", then odds are that other reviewers aren't -going to take it too seriously. Show that you took the time to review the -patch. - -== How To Request Features - -If there's a new feature that you want to see added to Ruby, you will need to -write a convincing proposal and patch to implement the feature. - -For new features in CRuby, use the {'Feature' -tracker}[https://bugs.ruby-lang.org/projects/ruby-master/issues?set_filter=1&tracker_id=2] -on ruby-master. For non-CRuby dependent features, features that would apply to -alternate Ruby implementations such as JRuby and Rubinius, use the {CommonRuby -tracker}[https://bugs.ruby-lang.org/projects/common-ruby]. - -When writing a proposal be sure to check for previous discussions on the -topic and have a solid use case. You will need to be persuasive and convince -Matz on your new feature. You should also consider the potential compatibility -issues that this new feature might raise. - -Consider making your feature into a gem, and if there are enough people who -benefit from your feature it could help persuade ruby-core. Although feature -requests can seem like an alluring way to contribute to Ruby, often these -discussions can lead nowhere and exhaust time and energy that could be better -spent fixing bugs. Choose your battles. - -A good template for a feature proposal should look something like this: - -[Abstract] - Summary of your feature -[Background] - Describe current behavior and why it is problem. Related work, such as - solutions in other language helps us to understand the problem. -[Proposal] - Describe your proposal in details -[Details] - If it has complicated feature, describe it -[Usecase] - How would your feature be used? Who will benefit from it? -[Discussion] - Discuss about this proposal. A list of pros and cons will help start - discussion. -[Limitation] - Limitation of your proposal -[Another alternative proposal] - If there are alternative proposals, show them. -[See also] - Links to the other related resources - -== Backport Requests - -When a new version of Ruby is released, it starts at patch level 0 (p0), and -bugs will be fixed first on the master branch. If it's determined that a bug -exists in a previous version of Ruby that is still in the bug fix stage of -maintenance, then a patch will be backported. After the maintenance stage of a -particular Ruby version ends, it goes into "security fix only" mode which -means only security related vulnerabilities will be backported. Versions in -End-of-life (EOL) will not receive any updates and it is recommended you -upgrade as soon as possible. - -If a major security issue is found or after a certain amount of time since the -last patch level release, a new patch-level release will be made. - -When submitting a backport request please confirm the bug has been fixed in -newer versions and exists in maintenance mode versions. There is a backport -tracker for each major version still in maintenance where you can request a -particular revision merged in the affected version of Ruby. - -Each major version of Ruby has a release manager that should be assigned to -handle backport requests. You can find the list of release managers on the -{wiki}[https://bugs.ruby-lang.org/projects/ruby/wiki/ReleaseEngineering]. - -=== Branches - -Status and maintainers of branches are listed on the -{wiki}[https://bugs.ruby-lang.org/projects/ruby/wiki/ReleaseEngineering]. - -== Running tests - -In order to help resolve existing issues and contributing patches to Ruby you -need to be able to run the test suite. - -CRuby uses git for source control, the {git homepage}[https://git-scm.com/] -has installation instructions with links to documentation for learning more -about git. There is a mirror of the repository on {github}[https://github.com/ruby/ruby]. -For other resources see the {ruby-core documentation on -ruby-lang.org}[https://www.ruby-lang.org/en/community/ruby-core/]. - -Install the prerequisite dependencies for building the CRuby interpreter to -run tests. - -* C compiler -* autoconf - 2.67 or later, preferably 2.69. -* bison - 2.0 or later, preferably 3.4. -* gperf - 3.0.3 or later, preferably 3.1. -* ruby - Ruby itself is prerequisite in order to build Ruby from source. - You should use [a maintained version of Ruby](https://www.ruby-lang.org/en/downloads/). - -You should also have access to development headers for the following -libraries, but these are not required: - -* NDBM/QDBM -* GDBM -* OpenSSL/LibreSSL -* readline/editline(libedit) -* zlib -* libffi -* libyaml -* libexecinfo (FreeBSD) - -Now let's build CRuby: - -* Checkout the CRuby source code: - - git clone https://github.com/ruby/ruby.git ruby-master - -* Generate the configuration files and build: - - cd ruby-master - ./autogen.sh - mkdir build && cd build # its good practice to build outside of source dir - mkdir ~/.rubies # we will install to .rubies/ruby-master in our home dir - ../configure --prefix="${HOME}/.rubies/ruby-master" - make up && make install - -After adding Ruby to your PATH, you should be ready to run the test suite: - - make test - -You can also use +test-all+ to run all of the tests with the RUNRUBY -interpreter just built. Use TESTS or RUNRUBYOPT to pass parameters, such as: - - make test-all TESTS=-v - -This is also how you can run a specific test from our build dir: - - make test-all TESTS=drb/test_drb.rb - -You can run +test+ and +test-all+ at once by +check+ . - - make check - -For older versions of Ruby you will need to run the build setup again after -checking out the associated branch in git, for example if you wanted to -checkout 1.9.3: - - git clone https://github.com/ruby/ruby.git --branch ruby_1_9_3 - -Once you checked out the source code, you can update the local copy by: - - make up - -Or, update, build, install and check, by just: - - make love - -== Contributing Documentation - -If you're interested in contributing documentation directly to CRuby there is -some information available at -{Contributing}[https://github.com/ruby/ruby#contributing]. - -There is also the {Ruby Reference -Manual}[https://github.com/rurema/doctree/wiki] in Japanese. - -== Contributing A Patch - -=== Deciding what to patch - -Before you submit a patch, there are a few things you should know: - -* Pay attention to the maintenance policy for stable and maintained versions of Ruby. -* Released versions in security mode will not merge feature changes. -* Search for previous discussions on ruby-core to verify the maintenance policy -* Patches must be distributed under Ruby's license. -* This license may change in the future, you must join the discussion if you don't agree to the change - -To improve the chance your patch will be accepted please follow these simple rules: - -* Bug fixes should be committed on master first -* Format of the patch file must be a unified diff (ie: diff -pu, svn diff, or git diff) -* Don't introduce cosmetic changes -* Follow the original coding style of the code -* Don't mix different changes in one commit - -First thing you should do is check out the code if you haven't already: - - git clone https://github.com/ruby/ruby.git ruby-master - -Now create a dedicated branch: - - cd ruby-master - git checkout -b my_new_branch - -The name of your branch doesn't really matter because it will only exist on -your local computer and won't be part of the official Ruby repository. It will -be used to create patches based on the differences between your branch and -master, or edge Ruby. - -=== Coding style - -Here are some general rules to follow when writing Ruby and C code for CRuby: - -* Indent 4 spaces for C without tabs (old codes might use tabs for eight-space indentation, - but newer codes recommend to use spaces only) -* Indent 2 space tabs for Ruby -* Do not use TABs in ruby codes -* ANSI C style for 1.9+ for function declarations -* Follow C90 (not C99) Standard -* PascalStyle for class/module names. -* UNDERSCORE_SEPARATED_UPPER_CASE for other constants. -* Capitalize words. -* ABBRs should be all upper case. -* Do as others do - -=== Commit messages - -When you're ready to commit: - - git commit path/to/files - -This will open your editor in which you write your commit message. -Use the following style for commit messages: - -* Use a succinct subject line. -* Include reasoning behind the change in the commit message, focusing on why - the change is being made. -* Refer to redmine issue (such as Fixes [Bug #1234] or Implements - [Feature #3456]), or discussion on the mailing list - (such as [ruby-core:12345]). -* For GitHub issues, use [GH-#] (such as [Fixes GH-234]). -* Follow the style used by other committers. - -=== Contributing your code - -Now that you've got some code you want to contribute, let's get set up to -generate a patch. Start by forking the github mirror, check the {github docs on -forking}[https://help.github.com/articles/fork-a-repo] if you get stuck here. -You will only need a github account if you intend to host your repository -on github. - -Next copy the writable url for your fork and add it as a git remote, replace -"my_username" with your github account name: - - git remote add my_fork git@github.com:my_username/ruby.git - # Now we can push our branch to our fork - git push my_fork my_new_branch - -In order to generate a patch that you can upload to the bug tracker, we can use -the github interface to review our changes just visit -https://github.com/my_username/ruby/compare/master...my_new_branch - -Next, you can simply add '.patch' to the end of this URL and it will generate -the patch for you, save the file to your computer and upload it to the bug -tracker. Alternatively you can submit a pull request, but for the best chances -to receive feedback add it is recommended you add it to redmine. - -Since git is a distributed system, you are welcome to host your git repository -on any {publicly accessible hosting -site}[https://git.wiki.kernel.org/index.php/GitHosting], including {hosting your -own}[https://www.kernel.org/pub/software/scm/git/docs/user-manual.html#public-repositories] -You may use the {'git format-patch'}[https://git-scm.com/docs/git-format-patch] -command to generate patch files to upload to redmine. You may also use -the {'git request-pull'}[https://git-scm.com/docs/git-request-pull] command for -formatting pull request messages to redmine. - -=== Updating the official repository - -If you are a committer, you can push changes directly into the official -repository: - - git push origin your-branch-name:master - -However, it is likely will have become outdated, and you will have to -update it. In that case, run: - - git fetch origin - git rebase remotes/origin/master - -and then try pushing your changes again. diff --git a/doc/contributing/building_ruby.md b/doc/contributing/building_ruby.md new file mode 100644 index 0000000000..96cee40cb4 --- /dev/null +++ b/doc/contributing/building_ruby.md @@ -0,0 +1,227 @@ +# Building Ruby + +## Dependencies + +1. Install the prerequisite dependencies for building the CRuby interpreter: + + * C compiler + + For RubyGems, you will also need: + + * OpenSSL 1.1.x or 3.0.x / LibreSSL + * libyaml 0.1.7 or later + * zlib + + If you want to build from the git repository, you will also need: + + * autoconf - 2.67 or later + * gperf - 3.1 or later + * Usually unneeded; only if you edit some source files using gperf + * ruby - 3.0 or later + * We can upgrade this version to system ruby version of the latest Ubuntu LTS. + +2. Install optional, recommended dependencies: + + * libffi (to build fiddle) + * gmp (if you with to accelerate Bignum operations) + * libexecinfo (FreeBSD) + * rustc - 1.58.0 or later, if you wish to build + [YJIT](https://docs.ruby-lang.org/en/master/RubyVM/YJIT.html). + + If you installed the libraries needed for extensions (openssl, readline, libyaml, zlib) into other than the OS default place, + typically using Homebrew on macOS, add `--with-EXTLIB-dir` options to `CONFIGURE_ARGS` environment variable. + + ``` shell + export CONFIGURE_ARGS="" + for ext in openssl readline libyaml zlib; do + CONFIGURE_ARGS="${CONFIGURE_ARGS} --with-$ext-dir=$(brew --prefix $ext)" + done + ``` + +## Quick start guide + +1. Download ruby source code: + + Select one of the below. + + 1. Build from the tarball: + + Download the latest tarball from [ruby-lang.org](https://www.ruby-lang.org/en/downloads/) and + extract it. Example for Ruby 3.0.2: + + ``` shell + tar -xzf ruby-3.0.2.tar.gz + cd ruby-3.0.2 + ``` + + 2. Build from the git repository: + + Checkout the CRuby source code: + + ``` shell + git clone https://github.com/ruby/ruby.git + cd ruby + ``` + + Generate the configure file: + + ``` shell + ./autogen.sh + ``` + +2. Create a `build` directory separate from the source directory: + + ``` shell + mkdir build && cd build + ``` + + While it's not necessary to build in a separate directory, it's good practice to do so. + +3. We'll install Ruby in `~/.rubies/ruby-master`, so create the directory: + + ``` shell + mkdir ~/.rubies + ``` + +4. Run configure: + + ``` shell + ../configure --prefix="${HOME}/.rubies/ruby-master" + ``` + + - Also `-C` (or `--config-cache`) would reduce time to configure from the next time. + +5. Build Ruby: + + ``` shell + make + ``` + +6. [Run tests](testing_ruby.md) to confirm your build succeeded. + +7. Install Ruby: + + ``` shell + make install + ``` + + - If you need to run `make install` with `sudo` and want to avoid document generation with different permissions, you can use + `make SUDO=sudo install`. + +### Unexplainable Build Errors + +If you are having unexplainable build errors, after saving all your work, try running `git clean -xfd` in the source root to remove all git ignored local files. If you are working from a source directory that's been updated several times, you may have temporary build artifacts from previous releases which can cause build failures. + +## Building on Windows + +The documentation for building on Windows can be found [here](../windows.md). + +## More details + +If you're interested in continuing development on Ruby, here are more details +about Ruby's build to help out. + +### Running make scripts in parallel + +In GNU make and BSD make implementations, to run a specific make script in parallel, pass the flag `-j<number of processes>`. For instance, +to run tests on 8 processes, use: + +``` shell +make test-all -j8 +``` + +We can also set `MAKEFLAGS` to run _all_ `make` commands in parallel. + +Having the right `--jobs` flag will ensure all processors are utilized when building software projects. To do this effectively, you can set `MAKEFLAGS` in your shell configuration/profile: + +``` shell +# On macOS with Fish shell: +export MAKEFLAGS="--jobs "(sysctl -n hw.ncpu) + +# On macOS with Bash/ZSH shell: +export MAKEFLAGS="--jobs $(sysctl -n hw.ncpu)" + +# On Linux with Fish shell: +export MAKEFLAGS="--jobs "(nproc) + +# On Linux with Bash/ZSH shell: +export MAKEFLAGS="--jobs $(nproc)" +``` + +### Miniruby vs Ruby + +Miniruby is a version of Ruby which has no external dependencies and lacks certain features. +It can be useful in Ruby development because it allows for faster build times. Miniruby is +built before Ruby. A functional Miniruby is required to build Ruby. To build Miniruby: + +``` shell +make miniruby +``` + +## Debugging + +You can use either lldb or gdb for debugging. Before debugging, you need to create a `test.rb` +with the Ruby script you'd like to run. You can use the following make targets: + +* `make run`: Runs `test.rb` using Miniruby +* `make lldb`: Runs `test.rb` using Miniruby in lldb +* `make gdb`: Runs `test.rb` using Miniruby in gdb +* `make runruby`: Runs `test.rb` using Ruby +* `make lldb-ruby`: Runs `test.rb` using Ruby in lldb +* `make gdb-ruby`: Runs `test.rb` using Ruby in gdb + +### Compiling for Debugging + +You should configure Ruby without optimization and other flags that may interfere with debugging: + +``` shell +./configure --enable-debug-env optflags="-O0 -fno-omit-frame-pointer" +``` + +### Building with Address Sanitizer + +Using the address sanitizer (ASAN) is a great way to detect memory issues. It can detect memory safety issues in Ruby itself, and also in any C extensions compiled with and loaded into a Ruby compiled with ASAN. + +``` shell +./autogen.sh +mkdir build && cd build +../configure CC=clang cflags="-fsanitize=address -fno-omit-frame-pointer -DUSE_MN_THREADS=0" # and any other options you might like +make +``` +The compiled Ruby will now automatically crash with a report and a backtrace if ASAN detects a memory safety issue. To run Ruby's test suite under ASAN, issue the following command. Note that this will take quite a long time (over two hours on my laptop); the `RUBY_TEST_TIMEOUT_SCALE` and `SYNTAX_SUGEST_TIMEOUT` variables are required to make sure tests don't spuriously fail with timeouts when in fact they're just slow. + +``` shell +RUBY_TEST_TIMEOUT_SCALE=5 SYNTAX_SUGGEST_TIMEOUT=600 make check +``` + +Please note, however, the following caveats! + +* ASAN will not work properly on any currently released version of Ruby; the necessary support is currently only present on Ruby's master branch (and the whole test suite passes only as of commit [9d0a5148ae062a0481a4a18fbeb9cfd01dc10428](https://bugs.ruby-lang.org/projects/ruby-master/repository/git/revisions/9d0a5148ae062a0481a4a18fbeb9cfd01dc10428)) +* Due to [this bug](https://bugs.ruby-lang.org/issues/20243), Clang generates code for threadlocal variables which doesn't work with M:N threading. Thus, it's necessary to disable M:N threading support at build time for now (with the `-DUSE_MN_THREADS=0` configure argument). +* Currently, ASAN will only work correctly when using a recent head build of LLVM/Clang - it requires [this bugfix](https://github.com/llvm/llvm-project/pull/75290) related to multithreaded `fork`, which is not yet in any released version. See [here](https://llvm.org/docs/CMake.html) for instructions on how to build LLVM/Clang from source (note you will need at least the `clang` and `compiler-rt` projects enabled). Then, you will need to replace `CC=clang` in the instructions with an explicit path to your built Clang binary. +* ASAN has only been tested so far with Clang on Linux. It may or may not work with other compilers or on other platforms - please file an issue on [https://bugs.ruby-lang.org](https://bugs.ruby-lang.org) if you run into problems with such configurations (or, to report that they actually work properly!) +* In particular, although I have not yet tried it, I have reason to believe ASAN will _not_ work properly on macOS yet - the fix for the multithreaded fork issue was actually reverted for macOS (see [here](https://github.com/llvm/llvm-project/commit/2a03854e4ce9bb1bcd79a211063bc63c4657f92c)). Please open an issue on [https://bugs.ruby-lang.org](https://bugs.ruby-lang.org) if this is a problem for you. + +## How to measure coverage of C and Ruby code + +You need to be able to use gcc (gcov) and lcov visualizer. + +``` shell +./autogen.sh +./configure --enable-gcov +make +make update-coverage +rm -f test-coverage.dat +make test-all COVERAGE=true +make lcov +open lcov-out/index.html +``` + +If you need only C code coverage, you can remove `COVERAGE=true` from the above process. +You can also use `gcov` command directly to get per-file coverage. + +If you need only Ruby code coverage, you can remove `--enable-gcov`. +Note that `test-coverage.dat` accumulates all runs of `make test-all`. +Make sure that you remove the file if you want to measure one test run. + +You can see the coverage result of CI: https://rubyci.org/coverage diff --git a/doc/contributing/documentation_guide.md b/doc/contributing/documentation_guide.md new file mode 100644 index 0000000000..59953d0d52 --- /dev/null +++ b/doc/contributing/documentation_guide.md @@ -0,0 +1,505 @@ +# Documentation Guide + +This guide discusses recommendations for documenting +classes, modules, and methods +in the Ruby core and in the Ruby standard library. + +## Generating documentation + +Most Ruby documentation lives in the source files and is written in +[RDoc format](rdoc-ref:RDoc::Markup). + +Some pages live under the `doc` folder and can be written in either +`.rdoc` or `.md` format, determined by the file extension. + +To generate the output of documentation changes in HTML in the +`{build folder}/.ext/html` directory, run the following inside your +build directory: + +```sh +make html +``` + +If you don't have a build directory, follow the [quick start +guide](building_ruby.md#label-Quick+start+guide) up to step 4. + +Then you can preview your changes by opening +`{build folder}/.ext/html/index.html` file in your browser. + +## Goal + +The goal of Ruby documentation is to impart the most important +and relevant information in the shortest time. +The reader should be able to quickly understand the usefulness +of the subject code and how to use it. + +Providing too little information is bad, but providing unimportant +information or unnecessary examples is not good either. +Use your judgment about what the user needs to know. + +## General Guidelines + +- Keep in mind that the reader may not be fluent in \English. +- Write short declarative or imperative sentences. +- Group sentences into (ideally short) paragraphs, + each covering a single topic. +- Organize material with + [headings](rdoc-ref:RDoc::MarkupReference@Headings). +- Refer to authoritative and relevant sources using + [links](rdoc-ref:RDoc::MarkupReference@Links). +- Use simple verb tenses: simple present, simple past, simple future. +- Use simple sentence structure, not compound or complex structure. +- Avoid: + - Excessive comma-separated phrases; + consider a [list](rdoc-ref:RDoc::MarkupReference@Lists). + - Idioms and culture-specific references. + - Overuse of headings. + - Using US-ASCII-incompatible characters in C source files; + see [Characters](#label-Characters) below. + +### Characters + +Use only US-ASCII-compatible characters in a C source file. +(If you use other characters, the Ruby CI will gently let you know.) + +If want to put ASCII-incompatible characters into the documentation +for a C-coded class, module, or method, there are workarounds +involving new files `doc/*.rdoc`: + +- For class `Foo` (defined in file `foo.c`), + create file `doc/foo.rdoc`, declare `class Foo; end`, + and place the class documentation above that declaration: + + ```ruby + # Documentation for class Foo goes here. + class Foo; end + ``` + +- Similarly, for module `Bar` (defined in file `bar.c`, + create file `doc/bar.rdoc`, declare `module Bar; end`, + and place the module documentation above that declaration: + + ```ruby + # Documentation for module Bar goes here. + module Bar; end + ``` + +- For a method, things are different. + Documenting a method as above disables the "click to toggle source" feature + in the rendered documentation. + + Therefore it's best to use file inclusion: + + - Retain the `call-seq` in the C code. + - Use file inclusion (`:include:`) to include text from an .rdoc file. + + Example: + + ``` + /* + * call-seq: + * each_byte {|byte| ... } -> self + * each_byte -> enumerator + * + * :include: doc/string/each_byte.rdoc + * + */ + ``` + +### \RDoc + +Ruby is documented using RDoc. +For information on \RDoc syntax and features, see the +[RDoc Markup Reference](rdoc-ref:RDoc::Markup@RDoc+Markup+Reference). + +### Output from `irb` + +For code examples, consider using interactive Ruby, +[irb](https://ruby-doc.org/stdlib/libdoc/irb/rdoc/IRB.html). + +For a code example that includes `irb` output, +consider aligning `# => ...` in successive lines. +Alignment may sometimes aid readability: + +```ruby +a = [1, 2, 3] #=> [1, 2, 3] +a.shuffle! #=> [2, 3, 1] +a #=> [2, 3, 1] +``` + +### Headings + +Organize a long discussion for a class or module with [headings](rdoc-ref:RDoc::MarkupReference@Headings). + +Do not use formal headings in the documentation for a method or constant. + +In the rare case where heading-like structures are needed +within the documentation for a method or constant, use +[bold text](rdoc-ref:RDoc::MarkupReference@Bold) +as pseudo-headings. + +### Blank Lines + +A blank line begins a new paragraph. + +A [code block](rdoc-ref:RDoc::MarkupReference@Code+Blocks) +or [list](rdoc-ref:RDoc::MarkupReference@Lists) +should be preceded by and followed by a blank line. +This is unnecessary for the HTML output, but helps in the `ri` output. + +### \Method Names + +For a method name in text: + +- For a method in the current class or module, + use a double-colon for a singleton method, + or a hash mark for an instance method: + <tt>::bar</tt>, <tt>#baz</tt>. +- Otherwise, include the class or module name + and use a dot for a singleton method, + or a hash mark for an instance method: + <tt>Foo.bar</tt>, <tt>Foo#baz</tt>. + +### Embedded Code and Commands + +Code or commands embedded in running text (i.e., not in a code block) +should marked up as +[monofont](rdoc-ref:RDoc::MarkupReference@Monofont). + +Code that is a simple string should include the quote marks. + +### Auto-Linking + +In general, \RDoc's auto-linking should not be suppressed. +For example, we should write `Array`, not `\Array`. + +However, suppress when the word in question: + +- Does not refer to a Ruby entity + (e.g., some uses of _Class_ or _English_). +- Refers to the current document + (e.g., _Array_ in the documentation for class `Array`); + in that case, the word should be forced to + [monofont](rdoc-ref:RDoc::MarkupReference@Monofont). + +Most often, the name of a class, module, or method +will be auto-linked: + +- Array. +- Enumerable. +- File.new +- File#read. + +If not, or if you suppress autolinking, consider forcing +[monofont](rdoc-ref:RDoc::MarkupReference@Monofont). + +### Explicit Links + +When writing an explicit link, follow these guidelines. + +#### +rdoc-ref+ Scheme + +Use the +rdoc-ref+ scheme for: + +- A link in core documentation to other core documentation. +- A link in core documentation to documentation in a standard library package. +- A link in a standard library package to other documentation in that same + standard library package. + +See section "+rdoc-ref+ Scheme" in {Links}[rdoc-ref:RDoc::MarkupReference@Links]. + +#### URL-Based Link + +Use a full URL-based link for: + +- A link in standard library documentation to documentation in the core. +- A link in standard library documentation to documentation in a different + standard library package. + +Doing so ensures that the link will valid even when the package documentation +is built independently (separately from the core documentation). + +The link should lead to a target in https://docs.ruby-lang.org/en/master/. + +Also use a full URL-based link for a link to an off-site document. + +### Variable Names + +The name of a variable (as specified in its call-seq) should be marked up as +[monofont](rdoc-ref:RDoc::MarkupReference@Monofont). + +Also, use monofont text for the name of a transient variable +(i.e., one defined and used only in the discussion, such as +n+). + +### HTML Tags + +In general, avoid using HTML tags (even in formats where it's allowed) +because `ri` (the Ruby Interactive reference tool) +may not render them properly. + +### Tables + +In particular, avoid building tables with HTML tags +(<tt><table></tt>, etc.). + +Alternatives: + +- A {verbatim text block}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks], + using spaces and punctuation to format the text; + note that {text markup}[rdoc-ref:RDoc::MarkupReference@Text+Markup] + will not be honored: + + - Example {source}[https://github.com/ruby/ruby/blob/34d802f32f00df1ac0220b62f72605827c16bad8/file.c#L6570-L6596]. + - Corresponding {output}[rdoc-ref:File@Read-2FWrite+Mode]. + +- (Markdown format only): A {Github Flavored Markdown (GFM) table}[https://github.github.com/gfm/#tables-extension-], + using special formatting for the text: + + - Example {source}[https://github.com/ruby/ruby/blob/34d802f32f00df1ac0220b62f72605827c16bad8/doc/contributing/glossary.md?plain=1]. + - Corresponding {output}[https://docs.ruby-lang.org/en/master/contributing/glossary_md.html]. + +## Documenting Classes and Modules + +The general structure of the class or module documentation should be: + +- Synopsis +- Common uses, with examples +- "What's Here" summary (optional) + +### Synopsis + +The synopsis is a short description of what the class or module does +and why the reader might want to use it. +Avoid details in the synopsis. + +### Common Uses + +Show common uses of the class or module. +Depending on the class or module, this section may vary greatly +in both length and complexity. + +### What's Here Summary + +The documentation for a class or module may include a "What's Here" section. + +Guidelines: + +- The section title is `What's Here`. +- Consider listing the parent class and any included modules; consider + [links](rdoc-ref:RDoc::MarkupReference@Links) + to their "What's Here" sections if those exist. +- All methods mentioned in the left-pane table of contents + should be listed (including any methods extended from another class). +- Attributes (which are not included in the TOC) may also be listed. +- Display methods as items in one or more bullet lists: + + - Begin each item with the method name, followed by a colon + and a short description. + - If the method has aliases, mention them in parentheses before the colon + (and do not list the aliases separately). + - Check the rendered documentation to determine whether \RDoc has recognized + the method and linked to it; if not, manually insert a + [link](rdoc-ref:RDoc::MarkupReference@Links). + +- If there are numerous entries, consider grouping them into subsections with headings. +- If there are more than a few such subsections, + consider adding a table of contents just below the main section title. + +## Documenting Methods + +### General Structure + +The general structure of the method documentation should be: + +- Calling sequence (for methods written in C). +- Synopsis (short description). +- Details and examples. +- Argument description (if necessary). +- Corner cases and exceptions. +- Related methods (optional). + +### Calling Sequence (for methods written in C) + +For methods written in Ruby, \RDoc documents the calling sequence automatically. + +For methods written in C, \RDoc cannot determine what arguments +the method accepts, so those need to be documented using \RDoc directive +[`call-seq:`](rdoc-ref:RDoc::MarkupReference@Directives+for+Method+Documentation). + +For a singleton method, use the form: + +``` +class_name.method_name(method_args) {|block_args| ... } -> return_type +``` + +Example: + +``` +* call-seq: +* Hash.new(default_value = nil) -> new_hash +* Hash.new {|hash, key| ... } -> new_hash +``` + +For an instance method, use the form +(omitting any prefix, just as RDoc does for a Ruby-coded method): + +``` +method_name(method_args) {|block_args| ... } -> return_type +``` +For example, in Array, use: + +``` +* call-seq: +* count -> integer +* count(obj) -> integer +* count {|element| ... } -> integer +``` + +``` +* call-seq: +* <=> other -> -1, 0, 1, or nil +``` + +Arguments: + +- If the method does not accept arguments, omit the parentheses. +- If the method accepts optional arguments: + + - Separate each argument name and its default value with ` = ` + (equal-sign with surrounding spaces). + - If the method has the same behavior with either an omitted + or an explicit argument, use a `call-seq` with optional arguments. + For example, use: + + ``` + respond_to?(symbol, include_all = false) -> true or false + ``` + + - If the behavior is different with an omitted or an explicit argument, + use a `call-seq` with separate lines. + For example, in Enumerable, use: + + ``` + * max -> element + * max(n) -> array + ``` + +Block: + +- If the method does not accept a block, omit the block. +- If the method accepts a block, the `call-seq` should have `{|args| ... }`, + not `{|args| block }` or `{|args| code }`. + +Return types: + +- If the method can return multiple different types, + separate the types with "or" and, if necessary, commas. +- If the method can return multiple types, use +object+. +- If the method returns the receiver, use +self+. +- If the method returns an object of the same class, + prefix `new_` if an only if the object is not +self+; + example: `new_array`. + +Aliases: + +- Omit aliases from the `call-seq`, unless the alias is an + operator method. If listing both a regular method and an + operator method in the `call-seq`, explain in the details and + examples section when it is recommended to use the regular method + and when it is recommended to use the operator method. + +### Synopsis + +The synopsis comes next, and is a short description of what the +method does and why you would want to use it. Ideally, this +is a single sentence, but for more complex methods it may require +an entire paragraph. + +For `Array#count`, the synopsis is: + +``` +Returns a count of specified elements. +``` + +This is great as it is short and descriptive. Avoid documenting +too much in the synopsis, stick to the most important information +for the benefit of the reader. + +### Details and Examples + +Most non-trivial methods benefit from examples, as well as details +beyond what is given in the synopsis. In the details and examples +section, you can document how the method handles different types +of arguments, and provides examples on proper usage. In this +section, focus on how to use the method properly, not on how the +method handles improper arguments or corner cases. + +Not every behavior of a method requires an example. If the method +is documented to return `self`, you don't need to provide an example +showing the return value is the same as the receiver. If the method +is documented to return `nil`, you don't need to provide an example +showing that it returns `nil`. If the details mention that for a +certain argument type, an empty array is returned, you don't need +to provide an example for that. + +Only add an example if it provides the user additional information, +do not add an example if it provides the same information given +in the synopsis or details. The purpose of examples is not to prove +what the details are stating. + +### Argument Description (if necessary) + +For methods that require arguments, if not obvious and not explicitly +mentioned in the details or implicitly shown in the examples, you can +provide details about the types of arguments supported. When discussing +the types of arguments, use simple language even if less-precise, such +as "level must be an integer", not "level must be an Integer-convertible +object". The vast majority of use will be with the expected type, not an +argument that is explicitly convertible to the expected type, and +documenting the difference is not important. + +For methods that take blocks, it can be useful to document the type of +argument passed if it is not obvious, not explicitly mentioned in the +details, and not implicitly shown in the examples. + +If there is more than one argument or block argument, use a +[labeled list](rdoc-ref:RDoc::MarkupReference@Labeled+Lists). + +### Corner Cases and Exceptions + +For corner cases of methods, such as atypical usage, briefly mention +the behavior, but do not provide any examples. + +Only document exceptions raised if they are not obvious. For example, +if you have stated earlier than an argument type must be an integer, +you do not need to document that a `TypeError` is raised if a non-integer +is passed. Do not provide examples of exceptions being raised unless +that is a common case, such as `Hash#fetch` raising a `KeyError`. + +### Related Methods (optional) + +In some cases, it is useful to document which methods are related to +the current method. For example, documentation for `Hash#[]` might +mention `Hash#fetch` as a related method, and `Hash#merge` might mention +`Hash#merge!` as a related method. + +- Consider which methods may be related + to the current method, and if you think the reader would benefit it, + at the end of the method documentation, add a line starting with + "Related: " (e.g. "Related: #fetch."). +- Don't list more than three related methods. + If you think more than three methods are related, + list the three you think are most important. +- Consider adding: + + - A phrase suggesting how the related method is similar to, + or different from,the current method. + See an example at Time#getutc. + - Example code that illustrates the similarities and differences. + See examples at Time#ctime, Time#inspect, Time#to_s. + +### Methods Accepting Multiple Argument Types + +For methods that accept multiple argument types, in some cases it can +be useful to document the different argument types separately. It's +best to use a separate paragraph for each case you are discussing. diff --git a/doc/contributing/glossary.md b/doc/contributing/glossary.md new file mode 100644 index 0000000000..86c6671fbd --- /dev/null +++ b/doc/contributing/glossary.md @@ -0,0 +1,41 @@ +# Ruby Internals Glossary + +Just a list of acronyms I've run across in the Ruby source code and their meanings. + +| Term | Definition | +| --- | -----------| +| `BIN` | Basic Instruction Name. Used as a macro to reference the YARV instruction. Converts pop into YARVINSN_pop. | +| `bop` | Basic Operator. Relates to methods like `Integer` plus and minus which can be optimized as long as they haven't been redefined. | +| `cc` | Call Cache. An inline cache structure for the call site. Stored in the `cd` | +| `cd` | Call Data. A data structure that points at the `ci` and the `cc`. `iseq` objects points at the `cd`, and access call information and call caches via this structure | +| `cfp`| Control Frame Pointer. Represents a Ruby stack frame. Calling a method pushes a new frame (cfp), returning pops a frame. Points at the `pc`, `sp`, `ep`, and the corresponding `iseq`| +| `ci` | Call Information. Refers to an `rb_callinfo` struct. Contains call information about the call site, including number of parameters to be passed, whether it they are keyword arguments or not, etc. Used in conjunction with the `cc` and `cd`. | +| `cref` | Class reference. A structure pointing to the class reference where `klass_or_self`, visibility scope, and refinements are stored. It also stores a pointer to the next class in the hierarchy referenced by `rb_cref_struct * next`. The Class reference is lexically scoped. | +| CRuby | Implementation of Ruby written in C | +| `cvar` | Class Variable. Refers to a Ruby class variable like `@@foo` | +| `dvar` | Dynamic Variable. Used by the parser to refer to local variables that are defined outside of the current lexical scope. For example `def foo; bar = 1; -> { p bar }; end` the "bar" inside the block is a `dvar` | +| `ec` | Execution Context. The top level VM context, points at the current `cfp` | +| `ep` | Environment Pointer. Local variables, including method parameters are stored in the `ep` array. The `ep` is pointed to by the `cfp` | +| GC | Garbage Collector | +| `gvar` | Global Variable. Refers to a Ruby global variable like `$$`, etc | +| `ICLASS` | Internal Class. When a module is included, the target class gets a new superclass which is an instance of an `ICLASS`. The `ICLASS` represents the module in the inheritance chain. | +| `ifunc` | Internal FUNCtion. A block implemented in C. | +| `iseq` | Instruction Sequence. Usually "iseq" in the C code will refer to an `rb_iseq_t` object that holds a reference to the actual instruction sequences which are executed by the VM. The object also holds information about the code, like the method name associated with the code. | +| `insn` | Instruction. Refers to a YARV instruction. | +| `insns` | Instructions. Usually an array of YARV instructions. | +| `ivar` | Instance Variable. Refers to a Ruby instance variable like `@foo` | +| `imemo` | Internal Memo. A tagged struct whose memory is managed by Ruby's GC, but contains internal information and isn't meant to be exposed to Ruby programs. Contains various information depending on the type. See the `imemo_type` enum for different types. | +| JIT | Just In Time compiler | +| `lep` | Local Environment Pointer. An `ep` which is tagged `VM_ENV_FLAG_LOCAL`. Usually this is the `ep` of a method (rather than a block, whose `ep` isn't "local") | +| `local` | Local. Refers to a local variable. | +| `me` | Method Entry. Refers to an `rb_method_entry_t` struct, the internal representation of a Ruby method. +| MRI | Matz's Ruby Implementation | +| `pc` | Program Counter. Usually the instruction that will be executed _next_ by the VM. Pointed to by the `cfp` and incremented by the VM | +| `sp` | Stack Pointer. The top of the stack. The VM executes instructions in the `iseq` and instructions will push and pop values on the stack. The VM updates the `sp` on the `cfp` to point at the top of the stack| +| `svar` | Special Variable. Refers to special local variables like `$~` and `$_`. See the `getspecial` instruction in `insns.def` | +| `VALUE` | VALUE is a pointer to a ruby object from the Ruby C code. | +| VM | Virtual Machine. In MRI's case YARV (Yet Another Ruby VM) +| WB | Write Barrier. To do with GC write barriers | +| WC | Wild Card. As seen in instructions like `getlocal_WC_0`. It means this instruction takes a "wild card" for the parameter (in this case an index for a local) | +| YARV | Yet Another Ruby VM. The virtual machine that CRuby uses | +| ZOMBIE | A zombie object. An object that has a finalizer which hasn't been executed yet. The object has been collected, so is "dead", but the finalizer hasn't run yet so it's still somewhat alive. | diff --git a/doc/contributing/making_changes_to_ruby.md b/doc/contributing/making_changes_to_ruby.md new file mode 100644 index 0000000000..260fadb7e3 --- /dev/null +++ b/doc/contributing/making_changes_to_ruby.md @@ -0,0 +1,28 @@ +# Contributing a pull request + +## Code style + +Here are some general rules to follow when writing Ruby and C code for CRuby: + +* Do not change code unrelated to your pull request (including style fixes) +* Indent 4 spaces for C without tabs (tabs are two levels of indentation, equivalent to 8 spaces) +* Indent 2 spaces for Ruby without tabs +* ANSI C style for function declarations +* Follow C99 Standard +* PascalStyle for class/module names +* UNDERSCORE_SEPARATED_UPPER_CASE for other constants +* Abbreviations should be all upper case + +## Commit messages + +Use the following style for commit messages: + +* Use a succinct subject line +* Include reasoning behind the change in the commit message, focusing on why the change is being made +* Refer to issue (such as `Fixes [Bug #1234]` or `Implements [Feature #3456]`), or discussion on the mailing list (such as [ruby-core:12345]) + +## CI + +GitHub actions will run on each pull request. + +There is [a CI that runs on master](https://rubyci.org/). It has broad coverage of different systems and architectures, such as Solaris SPARC and macOS. diff --git a/doc/contributing/making_changes_to_stdlibs.md b/doc/contributing/making_changes_to_stdlibs.md new file mode 100644 index 0000000000..3b33092fea --- /dev/null +++ b/doc/contributing/making_changes_to_stdlibs.md @@ -0,0 +1,49 @@ +# Making Changes To Standard Libraries + +Everything in the [lib](https://github.com/ruby/ruby/tree/master/lib) directory is mirrored from a standalone repository into the Ruby repository. +If you'd like to make contributions to standard libraries, do so in the standalone repositories, and the +changes will be automatically mirrored into the Ruby repository. + +For example, CSV lives in [a separate repository](https://github.com/ruby/csv) and is mirrored into [Ruby](https://github.com/ruby/ruby/tree/master/lib/csv). + +## Maintainers + +You can find the list of maintainers [here](https://docs.ruby-lang.org/en/master/maintainers_md.html#label-Maintainers). + +## Build + +First, install its dependencies using: + +``` +bundle install +``` + +### Libraries with C-extension + +If the library has a `/ext` directory, it has C files that you need to compile with: + +``` +bundle exec rake compile +``` + +## Running tests + +All standard libraries use [test-unit](https://github.com/test-unit/test-unit) as the test framework. + +To run all tests: + +``` +bundle exec rake test +``` + +To run a single test file: + +``` +bundle exec rake test TEST="test/test_foo.rb" +``` + +To run a single test case: + +``` +bundle exec rake test TEST="test/test_foo.rb" TESTOPS="--name=/test_mytest/" +``` diff --git a/doc/contributing/reporting_issues.md b/doc/contributing/reporting_issues.md new file mode 100644 index 0000000000..25516ffc6b --- /dev/null +++ b/doc/contributing/reporting_issues.md @@ -0,0 +1,91 @@ +# Reporting Issues +## Reporting security issues + +If you've found a security vulnerability, please follow +[these instructions](https://www.ruby-lang.org/en/security/). + +## Reporting bugs + +If you've encountered a bug in Ruby, please report it to the Redmine issue +tracker available at [bugs.ruby-lang.org](https://bugs.ruby-lang.org/), by +following these steps: + +* Check if anyone has already reported your issue by + searching [the Redmine issue tracker](https://bugs.ruby-lang.org/projects/ruby-master/issues). +* If you haven't already, + [sign up for an account](https://bugs.ruby-lang.org/account/register) on the + Redmine issue tracker. +* If you can't find a ticket addressing your issue, please [create a new issue](https://bugs.ruby-lang.org/projects/ruby-master/issues/new). You will need to fill in the subject, description and Ruby version. + + * Ensure the issue exists on Ruby master by trying to replicate your bug on + the head of master (see ["making changes to Ruby"](making_changes_to_ruby.md)). + * Write a concise subject and briefly describe your problem in the description section. If + your issue affects [a released version of Ruby](#label-Backport+requests), please say so. + * Fill in the Ruby version you're using when experiencing this issue + (the output of running `ruby -v`). + * Attach any logs or reproducible programs to provide additional information. + Any scripts should be as small as possible. +* If the ticket doesn't have any replies after 10 days, you can send a + reminder. +* Please reply to feedback requests. If a bug report doesn't get any feedback, + it'll eventually get rejected. + +### Reporting website issues + +If you're having an issue with the bug tracker or the mailing list, you can +contact the webmaster, Hiroshi SHIBATA (hsbt@ruby-lang.org). + +You can report issues with ruby-lang.org on the +[repo's issue tracker](https://github.com/ruby/www.ruby-lang.org/issues). + +## Requesting features + +If there's a new feature that you want to see added to Ruby, you will need to +write a proposal on [the Redmine issue tracker](https://bugs.ruby-lang.org/projects/ruby-master/issues/new). +When you open the issue, select `Feature` in the Tracker dropdown. + +When writing a proposal, be sure to check for previous discussions on the +topic and have a solid use case. You should also consider the potential +compatibility issues that this new feature might raise. Consider making +your feature into a gem, and if there are enough people who benefit from +your feature it could help persuade Ruby core. + +Here is a template you can use for a feature proposal: + +``` +[Abstract] + Briefly summarize your feature +[Background] + Describe current behavior +[Proposal] + Describe your feature in detail +[Use cases] + Give specific example uses of your feature +[Discussion] + Describe why this feature is necessary and better than using existing features +[See also] + Link to other related resources (such as implementations in other languages) +``` + +## Backport requests + +If a bug exists in a released version of Ruby, please report this in the issue. +Once this bug is fixed, the fix can be backported if deemed necessary. Only Ruby +committers can request backporting, and backporting is done by the backport manager. +New patch versions are released at the discretion of the backport manager. + +[Ruby versions](https://www.ruby-lang.org/en/downloads/) can be in one of three maintenance states: + +* Stable releases: backport any bug fixes +* Security maintenance: only backport security fixes +* End of life: no backports, please upgrade your Ruby version + +## Add context to existing issues + +There are several ways you can help with a bug that aren't directly +resolving it. These include: + +* Verifying or reproducing the existing issue and reporting it +* Adding more specific reproduction instructions +* Contributing a failing test as a patch (see ["making changes to Ruby"](making_changes_to_ruby.md)) +* Testing patches that others have submitted (see ["making changes to Ruby"](making_changes_to_ruby.md)) diff --git a/doc/contributing/testing_ruby.md b/doc/contributing/testing_ruby.md new file mode 100644 index 0000000000..dfb7fb3a65 --- /dev/null +++ b/doc/contributing/testing_ruby.md @@ -0,0 +1,156 @@ +# Testing Ruby + +## Test suites + +There are several test suites in the Ruby codebase: + +We can run any of the make scripts [in parallel](building_ruby.md#label-Running+make+scripts+in+parallel) to speed them up. + +1. [bootstraptest/](https://github.com/ruby/ruby/tree/master/bootstraptest) + + This is a small test suite that runs on Miniruby (see [building Ruby](building_ruby.md#label-Miniruby+vs+Ruby)). We can run it with: + + ``` + make btest + ``` + + To run it with logs, we can use: + + ``` + make btest OPTS=-v + ``` + + To run individual bootstrap tests, we can either specify a list of filenames or use the `--sets` flag in the variable `BTESTS`: + + ``` + make btest BTESTS="bootstraptest/test_fork.rb bootstraptest/tes_gc.rb" + make btest BTESTS="--sets=fork,gc" + ``` + + If we want to run the bootstrap test suite on Ruby (not Miniruby), we can use: + + ``` + make test + ``` + + To run it with logs, we can use: + + ``` + make test OPTS=-v + ``` + + To run a file or directory with GNU make, we can use: + + ``` + make test/ruby/test_foo.rb + make test/ruby/test_foo.rb TESTOPTS="-n /test_bar/" + ``` + +2. [test/](https://github.com/ruby/ruby/tree/master/test) + + This is a more comprehensive test suite that runs on Ruby. We can run it with: + + ``` + make test-all + ``` + + We can run a specific test directory in this suite using the `TESTS` option, for example: + + ``` + make test-all TESTS=test/rubygems + ``` + + We can run a specific test file in this suite by also using the `TESTS` option, for example: + + ``` + make test-all TESTS=test/ruby/test_array.rb + ``` + + We can run a specific test in this suite using the `TESTS` option, specifying + first the file name, and then the test name, prefixed with `--name`. For example: + + ``` + make test-all TESTS="../test/ruby/test_alias.rb --name=TestAlias#test_alias_with_zsuper_method" + ``` + + To run these specs with logs, we can use: + + ``` + make test-all TESTS=-v + ``` + + We can display the help of the `TESTS` option: + + ``` + make test-all TESTS=--help + ``` + + If we would like to run the `test/`, `bootstraptest/` and `spec/` test suites (the `spec/` is explained in a later section), we can run + + ``` + make check + ``` + +3. [spec/ruby](https://github.com/ruby/ruby/tree/master/spec/ruby) + + This is a test suite that exists in [the Ruby spec repository](https://github.com/ruby/spec) and is mirrored into the `spec/ruby` directory in the Ruby repository. It tests the behavior of the Ruby programming language. We can run this using: + + ``` + make test-spec + ``` + + To run a specific directory, we can use `SPECOPTS` to specify the directory: + + ``` + make test-spec SPECOPTS=spec/ruby/core/array + ``` + + To run a specific file, we can also use `SPECOPTS` to specify the file: + + ``` + make test-spec SPECOPTS=spec/ruby/core/array/any_spec.rb + ``` + + To run a specific test, we can use the `--example` flag to match against the test name: + + ``` + make test-spec SPECOPTS="../spec/ruby/core/array/any_spec.rb --example='is false if the array is empty'" + ``` + + To run these specs with logs, we can use: + + ``` + make test-spec SPECOPTS=-Vfs + ``` + + To run a ruby-spec file or directory with GNU make, we can use + + ``` + make spec/ruby/core/foo/bar_spec.rb + ``` + +4. [spec/bundler](https://github.com/ruby/ruby/tree/master/spec/bundler) + + The bundler test suite exists in [the RubyGems repository](https://github.com/rubygems/rubygems/tree/master/bundler/spec) and is mirrored into the `spec/bundler` directory in the Ruby repository. We can run this using: + + ``` + make test-bundler + ``` + + To run a specific bundler spec file, we can use `BUNDLER_SPECS` as follows: + + ``` + make test-bundler BUNDLER_SPECS=commands/exec_spec.rb + ``` + +## Troubleshooting + +### Running test suites on s390x CPU Architecture + +If we see failing tests related to the zlib library on s390x CPU architecture, we can run the test suites with `DFLTCC=0` to pass: + +``` +DFLTCC=0 make check +``` + +The failures can happen with the zlib library applying the patch [madler/zlib#410](https://github.com/madler/zlib/pull/410) to enable the deflate algorithm producing a different compressed byte stream. We manage this issue at [[ruby-core:114942][Bug #19909]](https://bugs.ruby-lang.org/issues/19909). diff --git a/doc/csv/options/common/col_sep.rdoc b/doc/csv/options/common/col_sep.rdoc index 05769b5773..3f23c6d2d3 100644 --- a/doc/csv/options/common/col_sep.rdoc +++ b/doc/csv/options/common/col_sep.rdoc @@ -55,9 +55,3 @@ Raises an exception if parsing with the empty \String: # Raises ArgumentError (:col_sep must be 1 or more characters: "") CSV.parse("foo0\nbar1\nbaz2\n", col_sep: col_sep) -Raises an exception if the given value is not String-convertible: - col_sep = BasicObject.new - # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>) - CSV.generate(line, col_sep: col_sep) - # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>) - CSV.parse(str, col_sep: col_sep) diff --git a/doc/csv/options/common/row_sep.rdoc b/doc/csv/options/common/row_sep.rdoc index 872d9d1f3f..eae15b4a84 100644 --- a/doc/csv/options/common/row_sep.rdoc +++ b/doc/csv/options/common/row_sep.rdoc @@ -89,12 +89,3 @@ if any of the following is true: * The stream is only available for output. Obviously, discovery takes a little time. Set manually if speed is important. Also note that IO objects should be opened in binary mode on Windows if this feature will be used as the line-ending translation can cause problems with resetting the document position to where it was before the read ahead. - ---- - -Raises an exception if the given value is not String-convertible: - row_sep = BasicObject.new - # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>) - CSV.generate(ary, row_sep: row_sep) - # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>) - CSV.parse(str, row_sep: row_sep) diff --git a/doc/csv/options/generating/write_converters.rdoc b/doc/csv/options/generating/write_converters.rdoc index 6e5fae5fda..d1a9cc748f 100644 --- a/doc/csv/options/generating/write_converters.rdoc +++ b/doc/csv/options/generating/write_converters.rdoc @@ -23,11 +23,3 @@ With two write converters (called in order): str # => "a,b,c\n" See also {Write Converters}[#class-CSV-label-Write+Converters] - ---- - -Raises an exception if the converter returns a value that is neither +nil+ -nor \String-convertible: - bad_converter = proc {|field| BasicObject.new } - # Raises NoMethodError (undefined method `is_a?' for #<BasicObject:>) - CSV.generate_line(['a', 'b', 'c'], write_converters: bad_converter)
\ No newline at end of file diff --git a/doc/csv/options/generating/write_headers.rdoc b/doc/csv/options/generating/write_headers.rdoc index f9faa9d438..c56aa48adb 100644 --- a/doc/csv/options/generating/write_headers.rdoc +++ b/doc/csv/options/generating/write_headers.rdoc @@ -19,7 +19,7 @@ Without +write_headers+: With +write_headers+": CSV.open(file_path,'w', - :write_headers=> true, + :write_headers => true, :headers => ['Name','Value'] ) do |csv| csv << ['foo', '0'] diff --git a/doc/csv/options/parsing/liberal_parsing.rdoc b/doc/csv/options/parsing/liberal_parsing.rdoc index b8b9b00c98..603de28613 100644 --- a/doc/csv/options/parsing/liberal_parsing.rdoc +++ b/doc/csv/options/parsing/liberal_parsing.rdoc @@ -1,13 +1,13 @@ ====== Option +liberal_parsing+ -Specifies the boolean value that determines whether +Specifies the boolean or hash value that determines whether CSV will attempt to parse input not conformant with RFC 4180, such as double quotes in unquoted fields. Default value: CSV::DEFAULT_OPTIONS.fetch(:liberal_parsing) # => false -For examples in this section: +For the next two examples: str = 'is,this "three, or four",fields' Without +liberal_parsing+: @@ -17,3 +17,22 @@ Without +liberal_parsing+: With +liberal_parsing+: ary = CSV.parse_line(str, liberal_parsing: true) ary # => ["is", "this \"three", " or four\"", "fields"] + +Use the +backslash_quote+ sub-option to parse values that use +a backslash to escape a double-quote character. This +causes the parser to treat <code>\"</code> as if it were +<code>""</code>. + +For the next two examples: + str = 'Show,"Harry \"Handcuff\" Houdini, the one and only","Tampa Theater"' + +With +liberal_parsing+, but without the +backslash_quote+ sub-option: + # Incorrect interpretation of backslash; incorrectly interprets the quoted comma as a field separator. + ary = CSV.parse_line(str, liberal_parsing: true) + ary # => ["Show", "\"Harry \\\"Handcuff\\\" Houdini", " the one and only\"", "Tampa Theater"] + puts ary[1] # => "Harry \"Handcuff\" Houdini + +With +liberal_parsing+ and its +backslash_quote+ sub-option: + ary = CSV.parse_line(str, liberal_parsing: { backslash_quote: true }) + ary # => ["Show", "Harry \"Handcuff\" Houdini, the one and only", "Tampa Theater"] + puts ary[1] # => Harry "Handcuff" Houdini, the one and only diff --git a/doc/csv/recipes/filtering.rdoc b/doc/csv/recipes/filtering.rdoc index 470649d09a..1552bf0fb8 100644 --- a/doc/csv/recipes/filtering.rdoc +++ b/doc/csv/recipes/filtering.rdoc @@ -1,5 +1,7 @@ == Recipes for Filtering \CSV +These recipes are specific code examples for specific \CSV filtering tasks. + For other recipes, see {Recipes for CSV}[./recipes_rdoc.html]. All code snippets on this page assume that the following has been executed: diff --git a/doc/csv/recipes/generating.rdoc b/doc/csv/recipes/generating.rdoc index 3ef6df99b4..e61838d31a 100644 --- a/doc/csv/recipes/generating.rdoc +++ b/doc/csv/recipes/generating.rdoc @@ -1,5 +1,7 @@ == Recipes for Generating \CSV +These recipes are specific code examples for specific \CSV generating tasks. + For other recipes, see {Recipes for CSV}[./recipes_rdoc.html]. All code snippets on this page assume that the following has been executed: @@ -144,7 +146,7 @@ This example defines and uses a custom write converter to strip whitespace from ==== Recipe: Specify Multiple Write Converters -Use option <tt>:write_converters</tt> and multiple custom coverters +Use option <tt>:write_converters</tt> and multiple custom converters to convert field values when generating \CSV. This example defines and uses two custom write converters to strip and upcase generated fields: @@ -161,7 +163,7 @@ This example defines and uses two custom write converters to strip and upcase ge === RFC 4180 Compliance By default, \CSV generates data that is compliant with -{RFC 4180}[https://tools.ietf.org/html/rfc4180] +{RFC 4180}[https://www.rfc-editor.org/rfc/rfc4180] with respect to: - Column separator. - Quote character. diff --git a/doc/csv/recipes/parsing.rdoc b/doc/csv/recipes/parsing.rdoc index 7ac96a934b..1b7071e33f 100644 --- a/doc/csv/recipes/parsing.rdoc +++ b/doc/csv/recipes/parsing.rdoc @@ -1,5 +1,7 @@ == Recipes for Parsing \CSV +These recipes are specific code examples for specific \CSV parsing tasks. + For other recipes, see {Recipes for CSV}[./recipes_rdoc.html]. All code snippets on this page assume that the following has been executed: @@ -189,7 +191,7 @@ Output: === RFC 4180 Compliance By default, \CSV parses data that is compliant with -{RFC 4180}[https://tools.ietf.org/html/rfc4180] +{RFC 4180}[https://www.rfc-editor.org/rfc/rfc4180] with respect to: - Row separator. - Column separator. @@ -518,7 +520,7 @@ Apply multiple header converters by defining and registering a custom header con To capture unconverted field values, use option +:unconverted_fields+: source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" parsed = CSV.parse(source, converters: :integer, unconverted_fields: true) - parsed # => [["foo", "0"], ["bar", "1"], ["baz", "2"]] + parsed # => [["Name", "Value"], ["foo", 0], ["bar", 1], ["baz", 2]] parsed.each {|row| p row.unconverted_fields } Output: ["Name", "Value"] diff --git a/doc/csv/recipes/recipes.rdoc b/doc/csv/recipes/recipes.rdoc index 9e4eaa1da4..9bf7885b1e 100644 --- a/doc/csv/recipes/recipes.rdoc +++ b/doc/csv/recipes/recipes.rdoc @@ -1,6 +1,6 @@ == Recipes for \CSV -See: +The recipes are specific code examples for specific tasks. See: - {Recipes for Parsing CSV}[./parsing_rdoc.html] - {Recipes for Generating CSV}[./generating_rdoc.html] - {Recipes for Filtering CSV}[./filtering_rdoc.html] diff --git a/doc/date/calendars.rdoc b/doc/date/calendars.rdoc new file mode 100644 index 0000000000..b8690841b1 --- /dev/null +++ b/doc/date/calendars.rdoc @@ -0,0 +1,62 @@ +== Julian and Gregorian Calendars + +The difference between the +{Julian calendar}[https://en.wikipedia.org/wiki/Julian_calendar] +and the +{Gregorian calendar}[https://en.wikipedia.org/wiki/Gregorian_calendar] +may matter to your program if it uses dates before the switchovers. + +- October 15, 1582. +- September 14, 1752. + +A date will be different in the two calendars, in general. + +=== Different switchover dates + +The reasons for the difference are religious/political histories. + +- On October 15, 1582, several countries changed + from the Julian calendar to the Gregorian calendar; + these included Italy, Poland, Portugal, and Spain. + Other contries in the Western world retained the Julian calendar. +- On September 14, 1752, most of the British empire + changed from the Julian calendar to the Gregorian calendar. + +When your code uses a date before these switchover dates, +it will matter whether it considers the switchover date +to be the earlier date or the later date (or neither). + +See also {a concrete example here}[rdoc-ref:DateTime@When+should+you+use+DateTime+and+when+should+you+use+Time-3F]. + +=== Argument +start+ + +Certain methods in class \Date handle differences in the +{Julian and Gregorian calendars}[rdoc-ref:calendars.rdoc@Julian+and+Gregorian+Calendars] +by accepting an optional argument +start+, whose value may be: + +- Date::ITALY (the default): the created date is Julian + if before October 15, 1582, Gregorian otherwise: + + d = Date.new(1582, 10, 15) + d.prev_day.julian? # => true + d.julian? # => false + d.gregorian? # => true + +- Date::ENGLAND: the created date is Julian if before September 14, 1752, + Gregorian otherwise: + + d = Date.new(1752, 9, 14, Date::ENGLAND) + d.prev_day.julian? # => true + d.julian? # => false + d.gregorian? # => true + +- Date::JULIAN: the created date is Julian regardless of its value: + + d = Date.new(1582, 10, 15, Date::JULIAN) + d.julian? # => true + +- Date::GREGORIAN: the created date is Gregorian regardless of its value: + + d = Date.new(1752, 9, 14, Date::GREGORIAN) + d.prev_day.gregorian? # => true + diff --git a/doc/distribution.md b/doc/distribution.md new file mode 100644 index 0000000000..bc89a7500a --- /dev/null +++ b/doc/distribution.md @@ -0,0 +1,47 @@ +# Distribution + +This document outlines the expected way to distribute Ruby, with a specific focus on building Ruby packages. + +## Getting the Ruby Tarball + +### Official Releases + +The tarball for official releases is created by the release manager. The release manager uploads the tarball to the [Ruby website](https://www.ruby-lang.org/en/downloads/). + +Downstream distributors should use the official release tarballs as part of their build process. This ensures that the tarball is created in a consistent way, and that the tarball is crytographically verified. + +### Using the nightly tarball for testing + +See the Snapshots section of the [Ruby website](https://www.ruby-lang.org/en/downloads/). + +### Building a manual snapshot tarball for testing + +This can be useful if the nightly tarball does not have all changes yet. + +At Ruby source tree cloned using git: +```sh-session +$ ./autogen.sh +$ ./configure -C +$ make +$ make dist +``` + +This will create several tarball in the `tmp` directory. The tarball will be named e.g. `ruby-<version>.tar.gz` (several different compression formats will be generated). + +## Building the Tarball + +See [Building Ruby](contributing/building_ruby.md). + +## Updating the Ruby Standard Library + +The Ruby standard library is a collection of Ruby files that are included with Ruby. These files are used to provide the basic functionality of Ruby. The standard library is located in the `lib` directory and is distributed as part of the Ruby tarball. + +Occasionally, the standard library needs to be updated, for example a security issue might be found in a default gem or standard gem. There are two main ways that Ruby would update this code. + +### Releasing an Updated Ruby Gem + +Normally, the Ruby gem maintainer will release an updated gem. This gem can be installed alongside the default gem. This allows the user to update the gem without having to update Ruby. + +### Releasing a New Ruby Version + +If the update is critical, then the Ruby maintainers may decide to release a new version of Ruby. This new version will include the updated standard library. diff --git a/doc/documentation_guide.rdoc b/doc/documentation_guide.rdoc deleted file mode 100644 index 38438e94b4..0000000000 --- a/doc/documentation_guide.rdoc +++ /dev/null @@ -1,281 +0,0 @@ -= Documentation Guide - -This guide discusses recommendations for documenting -classes, modules, and methods -in the Ruby core and in the Ruby standard library. - -== Goal - -The goal of Ruby documentation is to impart the most important -and relevant in the shortest time. -The reader should be able to quickly understand the usefulness -of the subject code and how to use it. - -Providing too little information is bad, but providing unimportant -information or unnecessary examples is not good either. -Use your judgment about what the user needs to know. - -== General Guidelines - -- Keep in mind that the reader may not be fluent in \English. -- Write short declarative or imperative sentences. -- Group sentences into (ideally short) paragraphs, - each covering a single topic. -- Organize material with - {headers}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-Headers]. -- Refer to authoritative and relevant sources using - {links}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-Links]. -- Use simple verb tenses: simple present, simple past, simple future. -- Use simple sentence structure, not compound or complex structure. -- Avoid: - - - Excessive comma-separated phrases; - consider a {list}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-Simple+Lists]. - - Idioms and culture-specific references. - - Overuse of headers. - -=== \RDoc - -Ruby is documented using RDoc. -For information on \RDoc syntax and features, see the -{RDoc Markup Reference}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-RDoc+Markup+Reference]. - -=== Output from <tt>irb</tt> - -For code examples, consider using interactive Ruby, -{irb}[https://ruby-doc.org/stdlib/libdoc/irb/rdoc/IRB.html]. - -For a code example that includes +irb+ output, -consider aligning <tt># => ...</tt> in successive lines. -Alignment may sometimes aid readability: - - a = [1, 2, 3] #=> [1, 2, 3] - a.shuffle! #=> [2, 3, 1] - a #=> [2, 3, 1] - -=== Headers - -Organize a long discussion with -{headers}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-Headers]. - -=== Blank Lines - -A blank line begins a new paragraph. - -A {code block}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-Paragraphs+and+Verbatim] -or {list}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-Simple+Lists] -should be preceded by and followed by a blank line. -This is unnecessary for the HTML output, but helps in the +ri+ output. - -=== Auto-Linking - -In general, \RDoc's auto-linking should not be suppressed. -For example, we should write +Array+, not <tt>\Array</tt>. - -We might consider whether to suppress when: - -- The word in question does not refer to a Ruby entity - (e.g., some uses of _Class_ or _English_). -- The reference is to the current class document - (e.g., _Array_ in the documentation for class +Array+). -- The same reference is repeated many times - (e.g., _RDoc_ on this page). - -== Documenting Classes and Modules - -The general structure of the class or module documentation should be: - -* Synopsis -* Common uses, with examples -* "What's Here" summary (optional) - -=== Synopsis - -The synopsis is a short description of what the class or module does -and why the reader might want to use it. -Avoid details in the synopsis. - -=== Common Uses - -Show common uses of the class or module. -Depending on the class or module, this section may vary greatly -in both length and complexity. - -=== What's Here Summary - -The documentation for a class or module may include a "What's Here" section. - -Guidelines: - -- The section title is <tt>What's Here</tt>. -- Consider listing the parent class and any included modules; consider - {links}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-Links] - to their "What's Here" sections if those exist. -- List methods as a {labeled list}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-Labeled+Lists]. -- Each list entry's label is a method name; - if the method has aliases, include those with the "base" method method, - and do not list them separately. -- Check the rendered documentation to determine whether \RDoc has recognized - the method and linked to it; if not, manually insert a - {link}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-Links]. -- Each entry's description is a 1-line synopsis for the method. -- Keep the description short. -- If there are more entries, consider gouping them into subsections with headers. -- If there are more than a few such subsections, - consider adding a table of contents just below the main section title. - -== Documenting Methods - -=== General Structure - -The general structure of the method documentation should be: - -* Calling sequence (for methods written in C). -* Synopsis (short description). -* Details and examples. -* Argument description (if necessary). -* Corner cases and exceptions. -* Aliases. -* Related methods (optional). - -=== Calling Sequence (for methods written in C) - -For methods written in Ruby, \RDoc documents the calling sequence automatically. - -For methods written in C, \RDoc cannot determine what arguments -the method accepts, so those need to be documented using \RDoc directive -{:call-seq:}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-Method+arguments]. - -Example: - - * call-seq: - * array.count -> integer - * array.count(obj) -> integer - * array.count {|element| ... } -> integer - -When creating the <tt>call-seq</tt>, use the form - - receiver_type.method_name(arguments) {|block_arguments|} -> return_type - -Omit the parentheses for cases where the method does not accept arguments, -and omit the block for cases where a block is not accepted. - -In the cases where method can return multiple different types, separate the -types with "or". If the method can return any type, use "object". If the -method returns the receiver, use "self". - -In cases where the method accepts optional arguments, use a <tt>call-seq</tt> -with an optional argument if the method has the same behavior when an argument -is omitted as when the argument is passed with the default value. For example, -use: - - * obj.respond_to?(symbol, include_all=false) -> true or false - -Instead of: - - * obj.respond_to?(symbol) -> true or false - * obj.respond_to?(symbol, include_all) -> true or false - -However, as shown above for <tt>Array#count</tt>, use separate lines if the -behavior is different if the argument is omitted. - -Omit aliases from the call-seq, but mention them near the end (see below). - - -A +call-seq+ block should have <tt>{|x| ... }</tt>, not <tt>{|x| block }</tt> or <tt>{|x| code }</tt>. - -A +call-seq+ output should: - -- Have +self+, not +receiver+ or +array+. -- Begin with +new_+ if and only if the output object is a new instance - of the receiver's class, to emphasize that the output object is not +self+. - -=== Synopsis - -The synopsis comes next, and is a short description of what the -method does and why you would want to use it. Ideally, this -is a single sentence, but for more complex methods it may require -an entire paragraph. - -For <tt>Array#count</tt>, the synopsis is: - - Returns a count of specified elements. - -This is great as it is short and descriptive. Avoid documenting -too much in the synopsis, stick to the most important information -for the benefit of the reader. - -=== Details and Examples - -Most non-trivial methods benefit from examples, as well as details -beyond what is given in the synopsis. In the details and examples -section, you can document how the method handles different types -of arguments, and provides examples on proper usage. In this -section, focus on how to use the method properly, not on how the -method handles improper arguments or corner cases. - -Not every behavior of a method requires an example. If the method -is documented to return +self+, you don't need to provide an example -showing the return value is the same as the receiver. If the method -is documented to return +nil+, you don't need to provide an example -showing that it returns +nil+. If the details mention that for a -certain argument type, an empty array is returned, you don't need -to provide an example for that. - -Only add an example if it provides the user additional information, -do not add an example if it provides the same information given -in the synopsis or details. The purpose of examples is not to prove -what the details are stating. - -=== Argument Description (if necessary) - -For methods that require arguments, if not obvious and not explicitly -mentioned in the details or implicitly shown in the examples, you can -provide details about the types of arguments supported. When discussing -the types of arguments, use simple language even if less-precise, such -as "level must be an integer", not "level must be an Integer-convertible -object". The vast majority of use will be with the expected type, not an -argument that is explicitly convertible to the expected type, and -documenting the difference is not important. - -For methods that take blocks, it can be useful to document the type of -argument passed if it is not obvious, not explicitly mentioned in the -details, and not implicitly shown in the examples. - -If there is more than one argument or block argument, use a -{labeled list}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-Labeled+Lists]} - -=== Corner Cases and Exceptions - -For corner cases of methods, such as atypical usage, briefly mention -the behavior, but do not provide any examples. - -Only document exceptions raised if they are not obvious. For example, -if you have stated earlier than an argument type must be an integer, -you do not need to document that a \TypeError is raised if a non-integer -is passed. Do not provide examples of exceptions being raised unless -that is a common case, such as \Hash#fetch raising a \KeyError. - -=== Aliases - -Mention aliases in the form - - Array#find_index is an alias for Array#index. - -=== Related Methods (optional) - -In some cases, it is useful to document which methods are related to -the current method. For example, documentation for \Hash#[] might -mention \Hash#fetch as a related method, and \Hash#merge might mention -\Hash#merge! as a related method. Consider which methods may be related -to the current method, and if you think the reader would benefit it, -at the end of the method documentation, add a line starting with -"Related: " (e.g. "Related: #fetch"). Don't list more than three -related methods. If you think more than three methods are related, -pick the three you think are most important and list those three. - -=== Methods Accepting Multiple Argument Types - -For methods that accept multiple argument types, in some cases it can -be useful to document the different argument types separately. It's -best to use a separate paragraph for each case you are discussing. diff --git a/doc/encodings.rdoc b/doc/encodings.rdoc new file mode 100644 index 0000000000..97c0d22616 --- /dev/null +++ b/doc/encodings.rdoc @@ -0,0 +1,481 @@ += Encodings + +== The Basics + +A {character encoding}[https://en.wikipedia.org/wiki/Character_encoding], +often shortened to _encoding_, is a mapping between: + +- A sequence of 8-bit bytes (each byte in the range <tt>0..255</tt>). +- Characters in a specific character set. + +Some character sets contain only 1-byte characters; +{US-ASCII}[https://en.wikipedia.org/wiki/ASCII], for example, has 256 1-byte characters. +This string, encoded in US-ASCII, has six characters that are stored as six bytes: + + s = 'Hello!'.encode('US-ASCII') # => "Hello!" + s.encoding # => #<Encoding:US-ASCII> + s.bytes # => [72, 101, 108, 108, 111, 33] + +Other encodings may involve multi-byte characters. +{UTF-8}[https://en.wikipedia.org/wiki/UTF-8], for example, +encodes more than one million characters, encoding each in one to four bytes. +The lowest-valued of these characters correspond to ASCII characters, +and so are 1-byte characters: + + s = 'Hello!' # => "Hello!" + s.bytes # => [72, 101, 108, 108, 111, 33] + +Other characters, such as the Euro symbol, are multi-byte: + + s = "\u20ac" # => "€" + s.bytes # => [226, 130, 172] + +== The \Encoding \Class + +=== \Encoding Objects + +Ruby encodings are defined by constants in class \Encoding. +There can be only one instance of \Encoding for each of these constants. +\Method Encoding.list returns an array of \Encoding objects (one for each constant): + + Encoding.list.size # => 103 + Encoding.list.first.class # => Encoding + Encoding.list.take(3) + # => [#<Encoding:ASCII-8BIT>, #<Encoding:UTF-8>, #<Encoding:US-ASCII>] + +=== Names and Aliases + +\Method Encoding#name returns the name of an \Encoding: + + Encoding::ASCII_8BIT.name # => "ASCII-8BIT" + Encoding::WINDOWS_31J.name # => "Windows-31J" + +An \Encoding object has zero or more aliases; +method Encoding#names returns an array containing the name and all aliases: + + Encoding::ASCII_8BIT.names + # => ["ASCII-8BIT", "BINARY"] + Encoding::WINDOWS_31J.names + #=> ["Windows-31J", "CP932", "csWindows31J", "SJIS", "PCK"] + +\Method Encoding.aliases returns a hash of all alias/name pairs: + + Encoding.aliases.size # => 71 + Encoding.aliases.take(3) + # => [["BINARY", "ASCII-8BIT"], ["CP437", "IBM437"], ["CP720", "IBM720"]] + +\Method Encoding.name_list returns an array of all the encoding names and aliases: + + Encoding.name_list.size # => 175 + Encoding.name_list.take(3) + # => ["ASCII-8BIT", "UTF-8", "US-ASCII"] + +\Method +name_list+ returns more entries than method +list+ +because it includes both the names and their aliases. + +\Method Encoding.find returns the \Encoding for a given name or alias, if it exists: + + Encoding.find("US-ASCII") # => #<Encoding:US-ASCII> + Encoding.find("US-ASCII").class # => Encoding + +=== Default Encodings + +\Method Encoding.find, above, also returns a default \Encoding +for each of these special names: + +- +external+: the default external \Encoding: + + Encoding.find("external") # => #<Encoding:UTF-8> + +- +internal+: the default internal \Encoding (may be +nil+): + + Encoding.find("internal") # => nil + +- +locale+: the default \Encoding for a string from the environment: + + Encoding.find("locale") # => #<Encoding:UTF-8> # Linux + Encoding.find("locale") # => #<Encoding:IBM437> # Windows + +- +filesystem+: the default \Encoding for a string from the filesystem: + + Encoding.find("filesystem") # => #<Encoding:UTF-8> + +\Method Encoding.default_external returns the default external \Encoding: + + Encoding.default_external # => #<Encoding:UTF-8> + +\Method Encoding.default_external= sets that value: + + Encoding.default_external = 'US-ASCII' # => "US-ASCII" + Encoding.default_external # => #<Encoding:US-ASCII> + +\Method Encoding.default_internal returns the default internal \Encoding: + + Encoding.default_internal # => nil + +\Method Encoding.default_internal= sets the default internal \Encoding: + + Encoding.default_internal = 'US-ASCII' # => "US-ASCII" + Encoding.default_internal # => #<Encoding:US-ASCII> + +=== Compatible Encodings + +\Method Encoding.compatible? returns whether two given objects are encoding-compatible +(that is, whether they can be concatenated); +returns the \Encoding of the concatenated string, or +nil+ if incompatible: + + rus = "\u{442 435 441 442}" + eng = 'text' + Encoding.compatible?(rus, eng) # => #<Encoding:UTF-8> + + s0 = "\xa1\xa1".force_encoding('iso-8859-1') # => "\xA1\xA1" + s1 = "\xa1\xa1".force_encoding('euc-jp') # => "\x{A1A1}" + Encoding.compatible?(s0, s1) # => nil + +== \String \Encoding + +A Ruby String object has an encoding that is an instance of class \Encoding. +The encoding may be retrieved by method String#encoding. + +The default encoding for a string literal is the script encoding; +see {Script Encoding}[rdoc-ref:encodings.rdoc@Script+Encoding]. + + 's'.encoding # => #<Encoding:UTF-8> + +The default encoding for a string created with method String.new is: + +- For a \String object argument, the encoding of that string. +- For a string literal, the script encoding; + see {Script Encoding}[rdoc-ref:encodings.rdoc@Script+Encoding]. + +In either case, any encoding may be specified: + + s = String.new(encoding: 'UTF-8') # => "" + s.encoding # => #<Encoding:UTF-8> + s = String.new('foo', encoding: 'ASCII-8BIT') # => "foo" + s.encoding # => #<Encoding:ASCII-8BIT> + +The encoding for a string may be changed: + + s = "R\xC3\xA9sum\xC3\xA9" # => "Résumé" + s.encoding # => #<Encoding:UTF-8> + s.force_encoding('ISO-8859-1') # => "R\xC3\xA9sum\xC3\xA9" + s.encoding # => #<Encoding:ISO-8859-1> + +Changing the assigned encoding does not alter the content of the string; +it changes only the way the content is to be interpreted: + + s # => "R\xC3\xA9sum\xC3\xA9" + s.force_encoding('UTF-8') # => "Résumé" + +The actual content of a string may also be altered; +see {Transcoding a String}[#label-Transcoding+a+String]. + +Here are a couple of useful query methods: + + s = "abc".force_encoding("UTF-8") # => "abc" + s.ascii_only? # => true + s = "abc\u{6666}".force_encoding("UTF-8") # => "abc晦" + s.ascii_only? # => false + + s = "\xc2\xa1".force_encoding("UTF-8") # => "¡" + s.valid_encoding? # => true + s = "\xc2".force_encoding("UTF-8") # => "\xC2" + s.valid_encoding? # => false + +== \Symbol and \Regexp Encodings + +The string stored in a Symbol or Regexp object also has an encoding; +the encoding may be retrieved by method Symbol#encoding or Regexp#encoding. + +The default encoding for these, however, is: + +- US-ASCII, if all characters are US-ASCII. +- The script encoding, otherwise; + see (Script Encoding)[rdoc-ref:encodings.rdoc@Script+Encoding]. + +== Filesystem \Encoding + +The filesystem encoding is the default \Encoding for a string from the filesystem: + + Encoding.find("filesystem") # => #<Encoding:UTF-8> + +== Locale \Encoding + +The locale encoding is the default encoding for a string from the environment, +other than from the filesystem: + + Encoding.find('locale') # => #<Encoding:IBM437> + +== Stream Encodings + +Certain stream objects can have two encodings; these objects include instances of: + +- IO. +- File. +- ARGF. +- StringIO. + +The two encodings are: + +- An _external_ _encoding_, which identifies the encoding of the stream. +- An _internal_ _encoding_, which (if not +nil+) specifies the encoding + to be used for the string constructed from the stream. + +=== External \Encoding + +The external encoding, which is an \Encoding object, specifies how bytes read +from the stream are to be interpreted as characters. + +The default external encoding is: + +- UTF-8 for a text stream. +- ASCII-8BIT for a binary stream. + +The default external encoding is returned by method Encoding.default_external, +and may be set by: + +- Ruby command-line options <tt>--external_encoding</tt> or <tt>-E</tt>. + +You can also set the default external encoding using method Encoding.default_external=, +but doing so may cause problems; strings created before and after the change +may have a different encodings. + +For an \IO or \File object, the external encoding may be set by: + +- Open options +external_encoding+ or +encoding+, when the object is created; + see {Open Options}[rdoc-ref:IO@Open+Options]. + +For an \IO, \File, \ARGF, or \StringIO object, the external encoding may be set by: + +- \Methods +set_encoding+ or (except for \ARGF) +set_encoding_by_bom+. + +=== Internal \Encoding + +The internal encoding, which is an \Encoding object or +nil+, +specifies how characters read from the stream +are to be converted to characters in the internal encoding; +those characters become a string whose encoding is set to the internal encoding. + +The default internal encoding is +nil+ (no conversion). +It is returned by method Encoding.default_internal, +and may be set by: + +- Ruby command-line options <tt>--internal_encoding</tt> or <tt>-E</tt>. + +You can also set the default internal encoding using method Encoding.default_internal=, +but doing so may cause problems; strings created before and after the change +may have a different encodings. + +For an \IO or \File object, the internal encoding may be set by: + +- Open options +internal_encoding+ or +encoding+, when the object is created; + see {Open Options}[rdoc-ref:IO@Open+Options]. + +For an \IO, \File, \ARGF, or \StringIO object, the internal encoding may be set by: + +- \Method +set_encoding+. + +== Script \Encoding + +A Ruby script has a script encoding, which may be retrieved by: + + __ENCODING__ # => #<Encoding:UTF-8> + +The default script encoding is UTF-8; +a Ruby source file may set its script encoding with a magic comment +on the first line of the file (or second line, if there is a shebang on the first). +The comment must contain the word +coding+ or +encoding+, +followed by a colon, space and the Encoding name or alias: + + # encoding: ISO-8859-1 + __ENCODING__ #=> #<Encoding:ISO-8859-1> + +== Transcoding + +_Transcoding_ is the process of changing a sequence of characters +from one encoding to another. + +As far as possible, the characters remain the same, +but the bytes that represent them may change. + +The handling for characters that cannot be represented in the destination encoding +may be specified by @Encoding+Options. + +=== Transcoding a \String + +Each of these methods transcodes a string: + +- String#encode: Transcodes +self+ into a new string + according to given encodings and options. +- String#encode!: Like String#encode, but transcodes +self+ in place. +- String#scrub: Transcodes +self+ into a new string + by replacing invalid byte sequences with a given or default replacement string. +- String#scrub!: Like String#scrub, but transcodes +self+ in place. +- String#unicode_normalize: Transcodes +self+ into a new string + according to Unicode normalization. +- String#unicode_normalize!: Like String#unicode_normalize, + but transcodes +self+ in place. + +== Transcoding a Stream + +Each of these methods may transcode a stream; +whether it does so depends on the external and internal encodings: + +- IO.foreach: Yields each line of given stream to the block. +- IO.new: Creates and returns a new \IO object for the given integer file descriptor. +- IO.open: Creates a new \IO object. +- IO.pipe: Creates a connected pair of reader and writer \IO objects. +- IO.popen: Creates an \IO object to interact with a subprocess. +- IO.read: Returns a string with all or a subset of bytes from the given stream. +- IO.readlines: Returns an array of strings, which are the lines from the given stream. +- IO.write: Writes a given string to the given stream. + +This example writes a string to a file, encoding it as ISO-8859-1, +then reads the file into a new string, encoding it as UTF-8: + + s = "R\u00E9sum\u00E9" + path = 't.tmp' + ext_enc = 'ISO-8859-1' + int_enc = 'UTF-8' + + File.write(path, s, external_encoding: ext_enc) + raw_text = File.binread(path) + + transcoded_text = File.read(path, external_encoding: ext_enc, internal_encoding: int_enc) + + p raw_text + p transcoded_text + +Output: + + "R\xE9sum\xE9" + "Résumé" + +== \Encoding Options + +A number of methods in the Ruby core accept keyword arguments as encoding options. + +Some of the options specify or utilize a _replacement_ _string_, to be used +in certain transcoding operations. +A replacement string may be in any encoding that can be converted +to the encoding of the destination string. + +These keyword-value pairs specify encoding options: + +- For an invalid byte sequence: + + - <tt>:invalid: nil</tt> (default): Raise exception. + - <tt>:invalid: :replace</tt>: Replace each invalid byte sequence + with the replacement string. + + Examples: + + s = "\x80foo\x80" + s.encode('ISO-8859-3') # Raises Encoding::InvalidByteSequenceError. + s.encode('ISO-8859-3', invalid: :replace) # => "?foo?" + +- For an undefined character: + + - <tt>:undef: nil</tt> (default): Raise exception. + - <tt>:undef: :replace</tt>: Replace each undefined character + with the replacement string. + + Examples: + + s = "\x80foo\x80" + "\x80".encode('UTF-8', 'ASCII-8BIT') # Raises Encoding::UndefinedConversionError. + s.encode('UTF-8', 'ASCII-8BIT', undef: :replace) # => "�foo�" + + +- Replacement string: + + - <tt>:replace: nil</tt> (default): Set replacement string to default value: + <tt>"\uFFFD"</tt> ("�") for a Unicode encoding, <tt>'?'</tt> otherwise. + - <tt>:replace: _some_string_</tt>: Set replacement string to the given +some_string+; + overrides +:fallback+. + + Examples: + + s = "\xA5foo\xA5" + options = {:undef => :replace, :replace => 'xyzzy'} + s.encode('UTF-8', 'ISO-8859-3', **options) # => "xyzzyfooxyzzy" + +- Replacement fallback: + + One of these may be specified: + + - <tt>:fallback: nil</tt> (default): No replacement fallback. + - <tt>:fallback: _hash_like_object_</tt>: Set replacement fallback to the given + +hash_like_object+; the replacement string is <tt>_hash_like_object_[X]</tt>. + - <tt>:fallback: _method_</tt>: Set replacement fallback to the given + +method+; the replacement string is <tt>_method_(X)</tt>. + - <tt>:fallback: _proc_</tt>: Set replacement fallback to the given + +proc+; the replacement string is <tt>_proc_[X]</tt>. + + Examples: + + s = "\u3042foo\u3043" + + hash = {"\u3042" => 'xyzzy'} + hash.default = 'XYZZY' + s.encode('ASCII', fallback: h) # => "xyzzyfooXYZZY" + + def (fallback = "U+%.4X").escape(x) + self % x.unpack("U") + end + "\u{3042}".encode("US-ASCII", fallback: fallback.method(:escape)) # => "U+3042" + + proc = Proc.new {|x| x == "\u3042" ? 'xyzzy' : 'XYZZY' } + s.encode('ASCII', fallback: proc) # => "XYZZYfooXYZZY" + +- XML entities: + + One of these may be specified: + + - <tt>:xml: nil</tt> (default): No handling for XML entities. + - <tt>:xml: :text</tt>: Treat source text as XML; + replace each undefined character + with its upper-case hexdecimal numeric character reference, + except that: + + - <tt>&</tt> is replaced with <tt>&</tt>. + - <tt><</tt> is replaced with <tt><</tt>. + - <tt>></tt> is replaced with <tt>></tt>. + + - <tt>:xml: :attr</tt>: Treat source text as XML attribute value; + replace each undefined character + with its upper-case hexdecimal numeric character reference, + except that: + + - The replacement string <tt>r</tt> is double-quoted (<tt>"r"</tt>). + - Each embedded double-quote is replaced with <tt>"</tt>. + - <tt>&</tt> is replaced with <tt>&</tt>. + - <tt><</tt> is replaced with <tt><</tt>. + - <tt>></tt> is replaced with <tt>></tt>. + + Examples: + + s = 'foo"<&>"bar' + "\u3042" + s.encode('ASCII', xml: :text) # => "foo\"<&>\"barあ" + s.encode('ASCII', xml: :attr) # => "\"foo"<&>"barあ\"" + + +- Newlines: + + One of these may be specified: + + - <tt>:cr_newline: true</tt>: Replace each line-feed character (<tt>"\n"</tt>) + with a carriage-return character (<tt>"\r"</tt>). + - <tt>:crlf_newline: true</tt>: Replace each line-feed character (<tt>"\n"</tt>) + with a carriage-return/line-feed string (<tt>"\r\n"</tt>). + - <tt>:universal_newline: true</tt>: Replace each carriage-return + character (<tt>"\r"</tt>) and each carriage-return/line-feed string + (<tt>"\r\n"</tt>) with a line-feed character (<tt>"\n"</tt>). + + Examples: + + s = "\n \r \r\n" # => "\n \r \r\n" + s.encode('ASCII', cr_newline: true) # => "\r \r \r\r" + s.encode('ASCII', crlf_newline: true) # => "\r\n \r \r\r\n" + s.encode('ASCII', universal_newline: true) # => "\n \n \n" diff --git a/doc/examples/files.rdoc b/doc/examples/files.rdoc new file mode 100644 index 0000000000..f736132770 --- /dev/null +++ b/doc/examples/files.rdoc @@ -0,0 +1,26 @@ +# English text with newlines. +text = <<~EOT + First line + Second line + + Fourth line + Fifth line +EOT + +# Russian text. +russian = "\u{442 435 441 442}" # => "тест" + +# Binary data. +data = "\u9990\u9991\u9992\u9993\u9994" + +# Text file. +File.write('t.txt', text) + +# File with Russian text. +File.write('t.rus', russian) + +# File with binary data. +f = File.new('t.dat', 'wb:UTF-16') +f.write(data) +f.close + diff --git a/doc/extension.ja.rdoc b/doc/extension.ja.rdoc index 5087b6785a..2f7856f3d4 100644 --- a/doc/extension.ja.rdoc +++ b/doc/extension.ja.rdoc @@ -617,12 +617,14 @@ C言語とRubyの間で情報を共有する方法について解説します． Qtrue :: Qfalse :: - 真偽値．QfalseはC言語でも偽とみなされます(つまり0)． + 真偽値．C言語から見た「true」と「false」． Qnil :: C言語から見た「nil」． +RTEST(obj)というマクロはobjがQfalseかQnilのとき0を返します． + === CとRubyで共有される大域変数 CとRubyで大域変数を使って情報を共有できます．共有できる大域 @@ -778,9 +780,14 @@ RUBY_TYPED_WB_PROTECTED :: メソッドの実装に適切にライトバリアを挿入する責任があります． さもなくばRubyは実行時にクラッシュする可能性があります． - ライトバリアについてはdoc/extension.ja.rdocのAppendix D - "世代別GC"も参照してください． + ライトバリアについては{世代別 + GC}[rdoc-ref:@Appendix+D.+-E4-B8-96-E4-BB-A3-E5-88-A5GC] + も参照してください． +このマクロは例外を発生させる可能性があることに注意してくださ +い． ラップされる sval が，解放する必要があるリソース (割り +当てられたメモリ，外部ライブラリからのハンドルなど) を保持し +ている場合は，rb_protect を使用する必要があります． Cの構造体の割当と対応するオブジェクトの生成を同時に行うマク ロとして以下のものが提供されています． @@ -886,12 +893,12 @@ dbm.cではTypedData_Make_Structを以下のように使っています． obj = TypedData_Make_Struct(klass, struct dbmdata, &dbm_type, dbmp); -ここではdbmdata構造体へのポインタをDataにカプセル化してい -ます．DBM*を直接カプセル化しないのはclose()した時の処理を考 -えてのことです． +ここではdbmdata構造体へのポインタをRubyオブジェクトにカプセ +ル化しています．DBM*を直接カプセル化しないのはclose()した時 +の処理を考えてのことです． -Dataオブジェクトからdbmstruct構造体のポインタを取り出すため -に以下のマクロを使っています． +Rubyオブジェクトからdbmdata構造体のポインタを取り出すために +以下のマクロを使っています． #define GetDBM(obj, dbmp) do {\ TypedData_Get_Struct((obj), struct dbmdata, &dbm_type, (dbmp));\ @@ -1064,6 +1071,20 @@ Rubyのソースはいくつかに分類することが出来ます．このう ています．これらのソースは今までの説明でほとんど理解できると 思います． +=== Rubyのヘッダファイル + +<tt>$repo_root/include/ruby</tt>以下はすべて<tt>make +install</tt>でインストールされます．拡張ライブラリからは， +<tt>#include <ruby.h></tt>でインクルードする必要があります． ++rbimpl_+，+RBIMPL_+のプレフィックスが付いた実装の詳細のため +のシンボルを除き，すべてのシンボルは公開APIです． + +拡張ライブラリで直接インクルードできるのは， +<tt>$repo_root/include/ruby/*.h</tt>のうち，対応する +<tt>HAVE_RUBY_*_H</tt>マクロが +<tt>$repo_root/include/ruby.h</tt>ヘッダーで定義されているも +のです． + === Ruby言語のコア class.c :: クラスとモジュール @@ -1679,6 +1700,9 @@ HAVE_RUBY_*_H :: を意味する．たとえば，HAVE_RUBY_ST_H が定義されている場合は 単なる st.h ではなく ruby/st.h を使用する． + これらのマクロに対応するヘッダーファイルは，拡張ライブラリ + から直接インクルードしてもよい． + RB_EVENT_HOOKS_HAVE_CALLBACK_DATA :: rb_add_event_hook() がフック関数に渡す data を第3引数として @@ -1712,7 +1736,7 @@ have_func(func, header) :: ックする．funcが標準ではリンクされないライブラリ内のもので ある時には先にhave_libraryでそのライブラリをチェックしてお く事．チェックに成功すると，プリプロセッサマクロ - `HAVE_{FUNC}` を定義し，trueを返す． + <tt>HAVE_{FUNC}</tt> を定義し，trueを返す． have_var(var, header) :: @@ -1720,41 +1744,49 @@ have_var(var, header) :: クする．varが標準ではリンクされないライブラリ内のものであ る時には先にhave_libraryでそのライブラリをチェックしておく 事．チェックに成功すると，プリプロセッサマクロ - `HAVE_{VAR}` を定義し，trueを返す． + <tt>HAVE_{VAR}</tt> を定義し，trueを返す． have_header(header) :: ヘッダファイルの存在をチェックする．チェックに成功すると， - プリプロセッサマクロ `HAVE_{HEADER_H}` を定義し，trueを返す． + プリプロセッサマクロ <tt>HAVE_{HEADER_H}</tt> を定義し，trueを返す． (スラッシュやドットはアンダースコアに置換される) find_header(header, path...) :: ヘッダファイルheaderの存在を -Ipath を追加しながらチェック する．チェックに成功すると，プリプロセッサマクロ - `HAVE_{HEADER_H}` を定義し，trueを返す． + <tt>HAVE_{HEADER_H}</tt> を定義し，trueを返す． (スラッシュやドットはアンダースコアに置換される) have_struct_member(type, member[, header[, opt]]) :: ヘッダファイルheaderをインクルードして型typeが定義され， なおかつメンバmemberが存在するかをチェックする．チェックに - 成功すると，プリプロセッサマクロ `HAVE_{TYPE}_{MEMBER}` を + 成功すると，プリプロセッサマクロ <tt>HAVE_{TYPE}_{MEMBER}</tt> を 定義し，trueを返す． have_type(type, header, opt) :: ヘッダファイルheaderをインクルードして型typeが存在するかを チェックする．チェックに成功すると，プリプロセッサマクロ - `HAVE_TYPE_{TYPE}` を定義し，trueを返す． + <tt>HAVE_TYPE_{TYPE}</tt> を定義し，trueを返す． check_sizeof(type, header) :: ヘッダファイルheaderをインクルードして型typeのchar単位サイ ズを調べる．チェックに成功すると，プリプロセッサマクロ - `SIZEOF_{TYPE}` を定義し，そのサイズを返す．定義されていな + <tt>SIZEOF_{TYPE}</tt> を定義し，そのサイズを返す．定義されていな いときはnilを返す． +append_cppflags(array-of-flags[, opt]) :: +append_cflags(array-of-flags[, opt]) :: +append_ldflags(array-of-flags[, opt]) :: + + 各flagが使用可能であれば，それぞれ$CPPFLAGS, $CFLAGS, + $LDFLAGSに追加する．コンパイラのフラグには移植性がないので， + 変数に直接追加せずこれらを使うことが望ましい． + create_makefile(target[, target_prefix]) :: 拡張ライブラリ用のMakefileを生成する．この関数を呼ばなけれ @@ -1823,8 +1855,9 @@ RGenGCは，過去の拡張ライブラリに（ほぼ）互換性を保つよ スするようなコードは書かないようにして下さい．代わりに，rb_ary_aref(), rb_ary_store() などの，適切な API 関数を利用するようにして下さい． -そのほか，対応についての詳細は extension.rdoc の「Appendix D. Generational -GC」を参照して下さい． +そのほか，対応についての詳細は {Appendix D. Generational +GC}[rdoc-ref:extension.rdoc@Appendix+D.+Generational+GC]を参 +照して下さい． == Appendix E. Ractor サポート @@ -1833,10 +1866,12 @@ Ruby 3.0 から、Ruby プログラムを並列に実行するための仕組み なります。サポートしていないライブラリは、メイン Ractor 以外で実行すると エラーになります（Ractor::UnsafeError）。 -Ractor をサポートするための詳細は、extension.rdoc の「Appendix F. Ractor -support」を参照してください。 - +Ractor をサポートするための詳細は、{Appendix F. Ractor +support}[rdoc-ref:extension.rdoc@Appendix+F.+Ractor+support] +を参照してください。 -:enddoc: Local variables: -:enddoc: fill-column: 60 -:enddoc: end: +-- +Local variables: +fill-column: 60 +end: +++ diff --git a/doc/extension.rdoc b/doc/extension.rdoc index 1054e6a6af..ba59d107ab 100644 --- a/doc/extension.rdoc +++ b/doc/extension.rdoc @@ -1,6 +1,6 @@ # extension.rdoc - -*- RDoc -*- created at: Mon Aug 7 16:45:54 JST 1995 -= Creating Extension Libraries for Ruby += Creating extension libraries for Ruby This document explains how to make extension libraries for Ruby. @@ -10,8 +10,8 @@ In C, variables have types and data do not have types. In contrast, Ruby variables do not have a static type, and data themselves have types, so data will need to be converted between the languages. -Data in Ruby are represented by the C type `VALUE'. Each VALUE data -has its data type. +Objects in Ruby are represented by the C type `VALUE'. Each VALUE +data has its data type. To retrieve C data from a VALUE, you need to: @@ -20,7 +20,7 @@ To retrieve C data from a VALUE, you need to: Converting to the wrong data type may cause serious problems. -=== Data Types +=== Ruby data types The Ruby interpreter has the following data types: @@ -54,7 +54,7 @@ T_ZOMBIE :: object awaiting finalization Most of the types are represented by C structures. -=== Check Data Type of the VALUE +=== Check type of the VALUE data The macro TYPE() defined in ruby.h shows the data type of the VALUE. TYPE() returns the constant number T_XXXX described above. To handle @@ -88,12 +88,14 @@ There are also faster check macros for fixnums and nil. FIXNUM_P(obj) NIL_P(obj) -=== Convert VALUE into C Data +=== Convert VALUE into C data The data for type T_NIL, T_FALSE, T_TRUE are nil, false, true respectively. They are singletons for the data type. The equivalent C constants are: Qnil, Qfalse, Qtrue. -Note that Qfalse is false in C also (i.e. 0), but not Qnil. +RTEST() will return true if a VALUE is neither Qfalse nor Qnil. +If you need to differentiate Qfalse from Qnil, +specifically test against Qfalse. The T_FIXNUM data is a 31bit or 63bit length fixed integer. This size depends on the size of long: if long is 32bit then @@ -141,7 +143,7 @@ Notice: Do not change the value of the structure directly, unless you are responsible for the result. This ends up being the cause of interesting bugs. -=== Convert C Data into VALUE +=== Convert C data into VALUE To convert C data to Ruby values: @@ -167,14 +169,14 @@ INT2NUM() :: for arbitrary sized integers. INT2NUM() converts an integer into a Bignum if it is out of the FIXNUM range, but is a bit slower. -=== Manipulating Ruby Data +=== Manipulating Ruby object As I already mentioned, it is not recommended to modify an object's internal structure. To manipulate objects, use the functions supplied by the Ruby interpreter. Some (not all) of the useful functions are listed below: -==== String Functions +==== String functions rb_str_new(const char *ptr, long len) :: @@ -277,7 +279,7 @@ rb_str_modify(VALUE str) :: you MUST call this function before modifying the contents using RSTRING_PTR and/or rb_str_set_len. -==== Array Functions +==== Array functions rb_ary_new() :: @@ -336,13 +338,13 @@ rb_ary_cat(VALUE ary, const VALUE *ptr, long len) :: == Extending Ruby with C -=== Adding New Features to Ruby +=== Adding new features to Ruby You can add new features (classes, methods, etc.) to the Ruby interpreter. Ruby provides APIs for defining the following things: - Classes, Modules -- Methods, Singleton Methods +- Methods, singleton methods - Constants ==== Class and Module Definition @@ -360,7 +362,7 @@ To define nested classes or modules, use the functions below: VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super) VALUE rb_define_module_under(VALUE outer, const char *name) -==== Method and Singleton Method Definition +==== Method and singleton method definition To define methods or singleton methods, use these functions: @@ -465,7 +467,7 @@ available), you can use: VALUE rb_current_receiver(void) -==== Constant Definition +==== Constant definition We have 2 functions to define constants: @@ -475,11 +477,11 @@ We have 2 functions to define constants: The former is to define a constant under specified class/module. The latter is to define a global constant. -=== Use Ruby Features from C +=== Use Ruby features from C There are several ways to invoke Ruby's features from C code. -==== Evaluate Ruby Programs in a String +==== Evaluate Ruby programs in a string The easiest way to use Ruby's functionality from a C program is to evaluate the string as Ruby program. This function will do the job: @@ -548,7 +550,7 @@ and to convert Ruby Symbol object to ID, use ID SYM2ID(VALUE symbol) -==== Invoke Ruby Method from C +==== Invoke Ruby method from C To invoke methods directly, you can use the function below @@ -557,7 +559,7 @@ To invoke methods directly, you can use the function below This function invokes a method on the recv, with the method name specified by the symbol mid. -==== Accessing the Variables and Constants +==== Accessing the variables and constants You can access class variables and instance variables using access functions. Also, global variables can be shared between both @@ -576,9 +578,9 @@ To access the constants of the class/module: See also Constant Definition above. -== Information Sharing Between Ruby and C +== Information sharing between Ruby and C -=== Ruby Constants That Can Be Accessed From C +=== Ruby constants that can be accessed from C As stated in section 1.3, the following Ruby constants can be referred from C. @@ -592,7 +594,7 @@ Qnil :: Ruby nil in C scope. -=== Global Variables Shared Between C and Ruby +=== Global variables shared between C and Ruby Information can be shared between the two environments using shared global variables. To define them, you can use functions listed below: @@ -634,7 +636,7 @@ The prototypes of the getter and setter functions are as follows: VALUE (*getter)(ID id); void (*setter)(VALUE val, ID id); -=== Encapsulate C Data into a Ruby Object +=== Encapsulate C data into a Ruby object Sometimes you need to expose your struct in the C world as a Ruby object. @@ -745,33 +747,100 @@ RUBY_TYPED_WB_PROTECTED :: barriers in all implementations of methods of that object as appropriate. Otherwise Ruby might crash while running. - More about write barriers can be found in "Generational GC" in - Appendix D. + More about write barriers can be found in {Generational + GC}[rdoc-ref:@Appendix+D.+Generational+GC]. RUBY_TYPED_FROZEN_SHAREABLE :: - This flag indicates that the object is shareable object - if the object is frozen. See Appendix F more details. + This flag indicates that the object is shareable object if the object + is frozen. See {Ractor support}[rdoc-ref:@Appendix+F.+Ractor+support] + more details. If this flag is not set, the object can not become a shareable object by Ractor.make_shareable() method. -You can allocate and wrap the structure in one step. +Note that this macro can raise an exception. If sval to be wrapped +holds a resource needs to be released (e.g., allocated memory, handle +from an external library, and etc), you will have to use rb_protect. + +You can allocate and wrap the structure in one step, in more +preferable manner. TypedData_Make_Struct(klass, type, data_type, sval) -This macro returns an allocated Data object, wrapping the pointer to +This macro returns an allocated T_DATA object, wrapping the pointer to the structure, which is also allocated. This macro works like: (sval = ZALLOC(type), TypedData_Wrap_Struct(klass, data_type, sval)) +However, you should use this macro instead of "allocation then wrap" +like the above code if it is simply allocated, because the latter can +raise a NoMemoryError and sval will be memory leaked in that case. + Arguments klass and data_type work like their counterparts in TypedData_Wrap_Struct(). A pointer to the allocated structure will be assigned to sval, which should be a pointer of the type specified. +==== Declaratively marking/compacting struct references + +In the case where your struct refers to Ruby objects that are simple values, +not wrapped in conditional logic or complex data structures an alternative +approach to marking and reference updating is provided, by declaring offset +references to the VALUES in your struct. + +Doing this allows the Ruby GC to support marking these references and GC +compaction without the need to define the +dmark+ and +dcompact+ callbacks. + +You must define a static list of VALUE pointers to the offsets within your +struct where the references are located, and set the "data" member to point to +this reference list. The reference list must end with +RUBY_END_REFS+. + +Some Macros have been provided to make edge referencing easier: + +* <code>RUBY_TYPED_DECL_MARKING</code> =A flag that can be set on the +ruby_data_type_t+ to indicate that references are being declared as edges. + +* <code>RUBY_REFERENCES(ref_list_name)</code> - Define _ref_list_name_ as a list of references + +* <code>RUBY_REF_END</code> - The end mark of the references list. + +* <code>RUBY_REF_EDGE(struct, member)</code> - Declare _member_ as a VALUE edge from _struct_. Use this after +RUBY_REFERENCES_START+ + +* +RUBY_REFS_LIST_PTR+ - Coerce the reference list into a format that can be + accepted by the existing +dmark+ interface. + +The example below is from Dir (defined in +dir.c+) + + // The struct being wrapped. Notice this contains 3 members of which the second + // is a VALUE reference to another ruby object. + struct dir_data { + DIR *dir; + const VALUE path; + rb_encoding *enc; + } + + // Define a reference list `dir_refs` containing a single entry to `path`. + // Needs terminating with RUBY_REF_END + RUBY_REFERENCES(dir_refs) = { + RUBY_REF_EDGE(dir_data, path), + RUBY_REF_END + }; + + // Override the "dmark" field with the defined reference list now that we + // no longer need a marking callback and add RUBY_TYPED_DECL_MARKING to the + // flags field + static const rb_data_type_t dir_data_type = { + "dir", + {RUBY_REFS_LIST_PTR(dir_refs), dir_free, dir_memsize,}, + 0, NULL, RUBY_TYPED_WB_PROTECTED | RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_DECL_MARKING + }; + +Declaring simple references declaratively in this manner allows the GC to both +mark, and move the underlying object, and automatically update the reference to +it during compaction. + ==== Ruby object to C struct -To retrieve the C pointer from the Data object, use the macro +To retrieve the C pointer from the T_DATA object, use the macro TypedData_Get_Struct(). TypedData_Get_Struct(obj, type, &data_type, sval) @@ -786,7 +855,7 @@ OK, here's the example of making an extension library. This is the extension to access DBMs. The full source is included in the ext/ directory in the Ruby's source tree. -=== Make the Directory +=== Make the directory % mkdir ext/dbm @@ -813,6 +882,7 @@ the library. Here's the example of an initializing function. + #include <ruby.h> void Init_dbm(void) { @@ -953,6 +1023,9 @@ need to put at the top of the file. You can use the functions below to check various conditions. + append_cppflags(array-of-flags[, opt]): append each flag to $CPPFLAGS if usable + append_cflags(array-of-flags[, opt]): append each flag to $CFLAGS if usable + append_ldflags(array-of-flags[, opt]): append each flag to $LDFLAGS if usable have_macro(macro[, headers[, opt]]): check whether macro is defined have_library(lib[, func[, headers[, opt]]]): check whether library containing function exists find_library(lib[, func, *paths]): find library from paths @@ -981,6 +1054,10 @@ The value of the variables below will affect the Makefile. $LDFLAGS: included in LDFLAGS make variable (such as -L) $objs: list of object file names +Compiler/linker flags are not portable usually, you should use ++append_cppflags+, +append_cpflags+ and +append_ldflags+ respectively +instead of appending the above variables directly. + Normally, the object files list is automatically generated by searching source files, but you must define them explicitly if any sources will be generated while building. @@ -989,7 +1066,7 @@ If a compilation condition is not fulfilled, you should not call ``create_makefile''. The Makefile will not be generated, compilation will not be done. -=== Prepare Depend (Optional) +=== Prepare depend (Optional) If the file named depend exists, Makefile will include that file to check dependencies. You can make this file by invoking @@ -1028,15 +1105,32 @@ You may need to rb_debug the extension. Extensions can be linked statically by adding the directory name in the ext/Setup file so that you can inspect the extension with the debugger. -=== Done! Now You Have the Extension Library +=== Done! Now you have the extension library You can do anything you want with your library. The author of Ruby will not claim any restrictions on your code depending on the Ruby API. Feel free to use, modify, distribute or sell your program. -== Appendix A. Ruby Source Files Overview +== Appendix A. Ruby header and source files overview + +=== Ruby header files + +Everything under <tt>$repo_root/include/ruby</tt> is installed with +<tt>make install</tt>. +It should be included per <tt>#include <ruby.h></tt> from C extensions. +All symbols are public API with the exception of symbols prefixed with ++rbimpl_+ or +RBIMPL_+. They are implementation details and shouldn't +be used by C extensions. -=== Ruby Language Core +Only <tt>$repo_root/include/ruby/*.h</tt> whose corresponding macros +are defined in the <tt>$repo_root/include/ruby.h</tt> header are +allowed to be <tt>#include</tt>-d by C extensions. + +Header files under <tt>$repo_root/internal/</tt> or directly under the +root <tt>$repo_root/*.h</tt> are not make-installed. +They are internal headers with only internal APIs. + +=== Ruby language core class.c :: classes and modules error.c :: exception classes and exception mechanism @@ -1045,14 +1139,14 @@ load.c :: library loading object.c :: objects variable.c :: variables and constants -=== Ruby Syntax Parser +=== Ruby syntax parser parse.y :: grammar definition parse.c :: automatically generated from parse.y defs/keywords :: reserved keywords lex.c :: automatically generated from keywords -=== Ruby Evaluator (a.k.a. YARV) +=== Ruby evaluator (a.k.a. YARV) compile.c eval.c @@ -1078,7 +1172,7 @@ lex.c :: automatically generated from keywords -> opt*.inc : automatically generated -> vm.inc : automatically generated -=== Regular Expression Engine (Onigumo) +=== Regular expression engine (Onigumo) regcomp.c regenc.c @@ -1087,7 +1181,7 @@ lex.c :: automatically generated from keywords regparse.c regsyntax.c -=== Utility Functions +=== Utility functions debug.c :: debug symbols for C debugger dln.c :: dynamic loading @@ -1095,7 +1189,7 @@ st.c :: general purpose hash table strftime.c :: formatting times util.c :: misc utilities -=== Ruby Interpreter Implementation +=== Ruby interpreter implementation dmyext.c dmydln.c @@ -1109,7 +1203,7 @@ util.c :: misc utilities gem_prelude.rb prelude.rb -=== Class Library +=== Class library array.c :: Array bignum.c :: Bignum @@ -1148,13 +1242,13 @@ transcode.c :: Encoding::Converter enc/*.c :: encoding classes enc/trans/* :: codepoint mapping tables -=== goruby Interpreter Implementation +=== goruby interpreter implementation goruby.c golf_prelude.rb : goruby specific libraries. -> golf_prelude.c : automatically generated -== Appendix B. Ruby Extension API Reference +== Appendix B. Ruby extension API reference === Types @@ -1164,7 +1258,7 @@ VALUE :: such as struct RString, etc. To refer the values in structures, use casting macros like RSTRING(obj). -=== Variables and Constants +=== Variables and constants Qnil :: @@ -1178,7 +1272,7 @@ Qfalse :: false object -=== C Pointer Wrapping +=== C pointer wrapping Data_Wrap_Struct(VALUE klass, void (*mark)(), void (*free)(), void *sval) :: @@ -1198,7 +1292,7 @@ Data_Get_Struct(data, type, sval) :: This macro retrieves the pointer value from DATA, and assigns it to the variable sval. -=== Checking Data Types +=== Checking VALUE types RB_TYPE_P(value, type) :: @@ -1228,7 +1322,7 @@ void Check_Type(VALUE value, int type) :: Ensures +value+ is of the given internal +type+ or raises a TypeError -=== Data Type Conversion +=== VALUE type conversion FIX2INT(value), INT2FIX(i) :: @@ -1312,7 +1406,7 @@ rb_str_new2(s) :: char * -> String -=== Defining Classes and Modules +=== Defining classes and modules VALUE rb_define_class(const char *name, VALUE super) :: @@ -1339,7 +1433,7 @@ void rb_extend_object(VALUE object, VALUE module) :: Extend the object with the module's attributes. -=== Defining Global Variables +=== Defining global variables void rb_define_variable(const char *name, VALUE *var) :: @@ -1383,7 +1477,7 @@ void rb_gc_register_mark_object(VALUE object) :: Tells GC to protect the +object+, which may not be referenced anywhere. -=== Constant Definition +=== Constant definition void rb_define_const(VALUE klass, const char *name, VALUE val) :: @@ -1395,7 +1489,7 @@ void rb_define_global_const(const char *name, VALUE val) :: rb_define_const(rb_cObject, name, val) -=== Method Definition +=== Method definition rb_define_method(VALUE klass, const char *name, VALUE (*func)(ANYARGS), int argc) :: @@ -1571,7 +1665,7 @@ int rb_respond_to(VALUE obj, ID id) :: Returns true if the object responds to the message specified by id. -=== Instance Variables +=== Instance variables VALUE rb_iv_get(VALUE obj, const char *name) :: @@ -1582,7 +1676,7 @@ VALUE rb_iv_set(VALUE obj, const char *name, VALUE val) :: Sets the value of the instance variable. -=== Control Structure +=== Control structure VALUE rb_block_call(VALUE recv, ID mid, int argc, VALUE * argv, VALUE (*func) (ANYARGS), VALUE data2) :: @@ -1678,7 +1772,7 @@ void rb_iter_break_value(VALUE value) :: return the given argument value. This function never return to the caller. -=== Exceptions and Errors +=== Exceptions and errors void rb_warn(const char *fmt, ...) :: @@ -1751,7 +1845,7 @@ int rb_wait_for_single_fd(int fd, int events, struct timeval *timeout) :: Use a NULL +timeout+ to wait indefinitely. -=== I/O Multiplexing +=== I/O multiplexing Ruby supports I/O multiplexing based on the select(2) system call. The Linux select_tut(2) manpage @@ -1803,7 +1897,7 @@ int rb_thread_fd_select(int nfds, rb_fdset_t *readfds, rb_fdset_t *writefds, rb_ rb_io_wait_writable, or rb_wait_for_single_fd functions since they can be optimized for specific platforms (currently, only Linux). -=== Initialize and Start the Interpreter +=== Initialize and start the interpreter The embedding API functions are below (not needed for extension libraries): @@ -1828,7 +1922,7 @@ void ruby_script(char *name) :: Specifies the name of the script ($0). -=== Hooks for the Interpreter Events +=== Hooks for the interpreter events void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data) :: @@ -1870,7 +1964,7 @@ void rb_gc_adjust_memory_usage(ssize_t diff) :: is decreased; a memory block is freed or a block is reallocated as smaller size. This function may trigger the GC. -=== Macros for Compatibility +=== Macros for compatibility Some macros to check API compatibilities are available by default. @@ -1905,6 +1999,9 @@ HAVE_RUBY_*_H :: instance, when HAVE_RUBY_ST_H is defined you should use ruby/st.h not mere st.h. + Header files corresponding to these macros may be <tt>#include</tt> + directly from extension libraries. + RB_EVENT_HOOKS_HAVE_CALLBACK_DATA :: Means that rb_add_event_hook() takes the third argument `data', to be @@ -2107,87 +2204,87 @@ keyword in C. RB_GC_GUARD has the following advantages: == Appendix F. Ractor support -Ractor is parallel execution mechanism introduced from Ruby 3.0. All -ractrors can run in parallel by different OS thread (underlying system -provided thread), so the C extension should be thread-safe. Now we call -the property that C extension can run in multiple ractors "Ractor-safe". +Ractor(s) are the parallel execution mechanism introduced in Ruby 3.0. All +ractors can run in parallel on a different OS thread (using an underlying system +provided thread), so the C extension should be thread-safe. A C extension that +can run in multiple ractors is called "Ractor-safe". -By default, all C extensions are recognized as Ractor-unsafe. If C -extension becomes Ractor-safe, the extension should call -rb_ext_ractor_safe(true) at the Init_ function and all defined method -marked as Ractor-safe. Ractor-unsafe C-methods only been called from -main-ractor. If non-main ractor calls it, then Ractor::UnsafeError is -raised. +Ractor safety around C extensions has the following properties: +1. By default, all C extensions are recognized as Ractor-unsafe. +2. Ractor-unsafe C-methods may only be called from the main Ractor. If invoked + by a non-main Ractor, then a Ractor::UnsafeError is raised. +3. If an extension desires to be marked as Ractor-safe the extension should + call rb_ext_ractor_safe(true) at the Init_ function for the extension, and + all defined methods will be marked as Ractor-safe. -BTW non-"Ractor-safe" extensions raises an error on non-main ractors, so -that it is "safe" because unsafe operations are not allowed. -"Ractor-safe" property means "multi-Ractor-ready" or "safe on -multi-ractors execution". "Ractor-safe" term comes from "Thread-safe". +To make a "Ractor-safe" C extension, we need to check the following points: -To make "Ractor-safe" C extension, we need to check the following points: +1. Do not share unshareable objects between ractors -(1) Do not share unshareable objects between ractors + For example, C's global variable can lead sharing an unshareable objects + between ractors. -For example, C's global variable can lead sharing an unshareable objects -between ractors. + VALUE g_var; + VALUE set(VALUE self, VALUE v){ return g_var = v; } + VALUE get(VALUE self){ return g_var; } - VALUE g_var; - VALUE set(VALUE self, VALUE v){ return g_var = v; } - VALUE get(VALUE self){ return g_var; } + set() and get() pair can share an unshareable objects using g_var, and + it is Ractor-unsafe. -set() and get() pair can share an unshareable objects using g_var, and -it is Ractor-unsafe. + Not only using global variables directly, some indirect data structure + such as global st_table can share the objects, so please take care. -Not only using global variables directly, some indirect data structure -such as global st_table can share the objects, so please take care. + Note that class and module objects are shareable objects, so you can + keep the code "cFoo = rb_define_class(...)" with C's global variables. -Note that class and module objects are shareable objects, so you can -keep the code "cFoo = rb_define_class(...)" with C's global variables. +2. Check the thread-safety of the extension -(2) Check the thread-safety of the extension + An extension should be thread-safe. For example, the following code is + not thread-safe: -An extension should be thread-safe. For example, the following code is -not thread-safe: + bool g_called = false; + VALUE call(VALUE self) { + if (g_called) rb_raise("recursive call is not allowed."); + g_called = true; + VALUE ret = do_something(); + g_called = false; + return ret; + } - bool g_called = false; - VALUE call(VALUE self) { - if (g_called) rb_raise("recursive call is not allowed."); - g_called = true; - VALUE ret = do_something(); - g_called = false; - return ret; - } + because g_called global variable should be synchronized by other + ractor's threads. To avoid such data-race, some synchronization should + be used. Check include/ruby/thread_native.h and include/ruby/atomic.h. -because g_called global variable should be synchronized by other -ractor's threads. To avoid such data-race, some synchronization should -be used. Check include/ruby/thread_native.h and include/ruby/atomic.h. + With Ractors, all objects given as method parameters and the receiver (self) + are guaranteed to be from the current Ractor or to be shareable. As a + consequence, it is easier to make code ractor-safe than to make code generally + thread-safe. For example, we don't need to lock an array object to access the + element of it. -On the Ractor mechanism, most of objects given by the method parameters -or the receiver are isolated by Ractor's boundary, it is easy to make -thread-safe code than usual thread-programming in general. For example, -we don't need to lock an array object to access the element of it. +3. Check the thread-safety of any used library -(3) Check the thread-safety of using library + If the extension relies on an external library, such as a function foo() from + a library libfoo, the function libfoo foo() should be thread safe. -If an extension relies on the external library libfoo and the function -foo(), the function foo() should be thread safe. +4. Make an object shareable -(4) Make an object shareable + This is not required to make an extension Ractor-safe. -This is not required to make an extension Ractor-safe. + If an extension provides special objects defined by rb_data_type_t, + consider these objects can become shareable or not. -If an extension provides special objects defined by rb_data_type_t, -consider these objects can become shareable or not. + RUBY_TYPED_FROZEN_SHAREABLE flag indicates that these objects can be + shareable objects if the object is frozen. This means that if the object + is frozen, the mutation of wrapped data is not allowed. -RUBY_TYPED_FROZEN_SHAREABLE flag indicates that these objects can be -shareable objects if the object is frozen. This means that if the object -is frozen, the mutation of wrapped data is not allowed. +5. Others -(5) Others + There are possibly other points or requirements which must be considered in the + making of a Ractor-safe extension. This document will be extended as they are + discovered. -Maybe there are more points which should be considered to make -Ractor-safe extension, so this document will be extended. - -:enddoc: Local variables: -:enddoc: fill-column: 70 -:enddoc: end: +-- +Local variables: +fill-column: 70 +end: +++ diff --git a/doc/format_specifications.rdoc b/doc/format_specifications.rdoc new file mode 100644 index 0000000000..1111575e74 --- /dev/null +++ b/doc/format_specifications.rdoc @@ -0,0 +1,348 @@ += Format Specifications + +Several Ruby core classes have instance method +printf+ or +sprintf+: + +- ARGF#printf +- IO#printf +- Kernel#printf +- Kernel#sprintf + +Each of these methods takes: + +- Argument +format_string+, which has zero or more + embedded _format_ _specifications_ (see below). +- Arguments <tt>*arguments</tt>, which are zero or more objects to be formatted. + +Each of these methods prints or returns the string +resulting from replacing each +format specification embedded in +format_string+ with a string form +of the corresponding argument among +arguments+. + +A simple example: + + sprintf('Name: %s; value: %d', 'Foo', 0) # => "Name: Foo; value: 0" + +A format specification has the form: + + %[flags][width][.precision]type + +It consists of: + +- A leading percent character. +- Zero or more _flags_ (each is a character). +- An optional _width_ _specifier_ (an integer). +- An optional _precision_ _specifier_ (a period followed by a non-negative integer). +- A _type_ _specifier_ (a character). + +Except for the leading percent character, +the only required part is the type specifier, so we begin with that. + +== Type Specifiers + +This section provides a brief explanation of each type specifier. +The links lead to the details and examples. + +=== \Integer Type Specifiers + +- +b+ or +B+: Format +argument+ as a binary integer. + See {Specifiers b and B}[rdoc-ref:format_specifications.rdoc@Specifiers+b+and+B]. +- +d+, +i+, or +u+ (all are identical): + Format +argument+ as a decimal integer. + See {Specifier d}[rdoc-ref:format_specifications.rdoc@Specifier+d]. +- +o+: Format +argument+ as an octal integer. + See {Specifier o}[rdoc-ref:format_specifications.rdoc@Specifier+o]. +- +x+ or +X+: Format +argument+ as a hexadecimal integer. + See {Specifiers x and X}[rdoc-ref:format_specifications.rdoc@Specifiers+x+and+X]. + +=== Floating-Point Type Specifiers + +- +a+ or +A+: Format +argument+ as hexadecimal floating-point number. + See {Specifiers a and A}[rdoc-ref:format_specifications.rdoc@Specifiers+a+and+A]. +- +e+ or +E+: Format +argument+ in scientific notation. + See {Specifiers e and E}[rdoc-ref:format_specifications.rdoc@Specifiers+e+and+E]. +- +f+: Format +argument+ as a decimal floating-point number. + See {Specifier f}[rdoc-ref:format_specifications.rdoc@Specifier+f]. +- +g+ or +G+: Format +argument+ in a "general" format. + See {Specifiers g and G}[rdoc-ref:format_specifications.rdoc@Specifiers+g+and+G]. + +=== Other Type Specifiers + +- +c+: Format +argument+ as a character. + See {Specifier c}[rdoc-ref:format_specifications.rdoc@Specifier+c]. +- +p+: Format +argument+ as a string via <tt>argument.inspect</tt>. + See {Specifier p}[rdoc-ref:format_specifications.rdoc@Specifier+p]. +- +s+: Format +argument+ as a string via <tt>argument.to_s</tt>. + See {Specifier s}[rdoc-ref:format_specifications.rdoc@Specifier+s]. +- <tt>%</tt>: Format +argument+ (<tt>'%'</tt>) as a single percent character. + See {Specifier %}[rdoc-ref:format_specifications.rdoc@Specifier+-25]. + +== Flags + +The effect of a flag may vary greatly among type specifiers. +These remarks are general in nature. +See {type-specific details}[rdoc-ref:format_specifications.rdoc@Type+Specifier+Details+and+Examples]. + +Multiple flags may be given with single type specifier; +order does not matter. + +=== <tt>' '</tt> Flag + +Insert a space before a non-negative number: + + sprintf('%d', 10) # => "10" + sprintf('% d', 10) # => " 10" + +Insert a minus sign for negative value: + + sprintf('%d', -10) # => "-10" + sprintf('% d', -10) # => "-10" + +=== <tt>'#'</tt> Flag + +Use an alternate format; varies among types: + + sprintf('%x', 100) # => "64" + sprintf('%#x', 100) # => "0x64" + +=== <tt>'+'</tt> Flag + +Add a leading plus sign for a non-negative number: + + sprintf('%x', 100) # => "64" + sprintf('%+x', 100) # => "+64" + +=== <tt>'-'</tt> Flag + +Left justify the value in its field: + + sprintf('%6d', 100) # => " 100" + sprintf('%-6d', 100) # => "100 " + +=== <tt>'0'</tt> Flag + +Left-pad with zeros instead of spaces: + + sprintf('%6d', 100) # => " 100" + sprintf('%06d', 100) # => "000100" + +=== <tt>'*'</tt> Flag + +Use the next argument as the field width: + + sprintf('%d', 20, 14) # => "20" + sprintf('%*d', 20, 14) # => " 14" + +=== <tt>'n$'</tt> Flag + +Format the (1-based) <tt>n</tt>th argument into this field: + + sprintf("%s %s", 'world', 'hello') # => "world hello" + sprintf("%2$s %1$s", 'world', 'hello') # => "hello world" + +== Width Specifier + +In general, a width specifier determines the minimum width (in characters) +of the formatted field: + + sprintf('%10d', 100) # => " 100" + + # Left-justify if negative. + sprintf('%-10d', 100) # => "100 " + + # Ignore if too small. + sprintf('%1d', 100) # => "100" + +== Precision Specifier + +A precision specifier is a decimal point followed by zero or more +decimal digits. + +For integer type specifiers, the precision specifies the minimum number of +digits to be written. If the precision is shorter than the integer, the result is +padded with leading zeros. There is no modification or truncation of the result +if the integer is longer than the precision: + + sprintf('%.3d', 1) # => "001" + sprintf('%.3d', 1000) # => "1000" + + # If the precision is 0 and the value is 0, nothing is written + sprintf('%.d', 0) # => "" + sprintf('%.0d', 0) # => "" + +For the +a+/+A+, +e+/+E+, +f+/+F+ specifiers, the precision specifies +the number of digits after the decimal point to be written: + + sprintf('%.2f', 3.14159) # => "3.14" + sprintf('%.10f', 3.14159) # => "3.1415900000" + + # With no precision specifier, defaults to 6-digit precision. + sprintf('%f', 3.14159) # => "3.141590" + +For the +g+/+G+ specifiers, the precision specifies +the number of significant digits to be written: + + sprintf('%.2g', 123.45) # => "1.2e+02" + sprintf('%.3g', 123.45) # => "123" + sprintf('%.10g', 123.45) # => "123.45" + + # With no precision specifier, defaults to 6 significant digits. + sprintf('%g', 123.456789) # => "123.457" + +For the +s+, +p+ specifiers, the precision specifies +the number of characters to write: + + sprintf('%s', Time.now) # => "2022-05-04 11:59:16 -0400" + sprintf('%.10s', Time.now) # => "2022-05-04" + +== Type Specifier Details and Examples + +=== Specifiers +a+ and +A+ + +Format +argument+ as hexadecimal floating-point number: + + sprintf('%a', 3.14159) # => "0x1.921f9f01b866ep+1" + sprintf('%a', -3.14159) # => "-0x1.921f9f01b866ep+1" + sprintf('%a', 4096) # => "0x1p+12" + sprintf('%a', -4096) # => "-0x1p+12" + + # Capital 'A' means that alphabetical characters are printed in upper case. + sprintf('%A', 4096) # => "0X1P+12" + sprintf('%A', -4096) # => "-0X1P+12" + +=== Specifiers +b+ and +B+ + +The two specifiers +b+ and +B+ behave identically +except when flag <tt>'#'</tt>+ is used. + +Format +argument+ as a binary integer: + + sprintf('%b', 1) # => "1" + sprintf('%b', 4) # => "100" + + # Prefix '..' for negative value. + sprintf('%b', -4) # => "..100" + + # Alternate format. + sprintf('%#b', 4) # => "0b100" + sprintf('%#B', 4) # => "0B100" + +=== Specifier +c+ + +Format +argument+ as a single character: + + sprintf('%c', 'A') # => "A" + sprintf('%c', 65) # => "A" + +=== Specifier +d+ + +Format +argument+ as a decimal integer: + + sprintf('%d', 100) # => "100" + sprintf('%d', -100) # => "-100" + +Flag <tt>'#'</tt> does not apply. + +=== Specifiers +e+ and +E+ + +Format +argument+ in +{scientific notation}[https://en.wikipedia.org/wiki/Scientific_notation]: + + sprintf('%e', 3.14159) # => "3.141590e+00" + sprintf('%E', -3.14159) # => "-3.141590E+00" + +=== Specifier +f+ + +Format +argument+ as a floating-point number: + + sprintf('%f', 3.14159) # => "3.141590" + sprintf('%f', -3.14159) # => "-3.141590" + +Flag <tt>'#'</tt> does not apply. + +=== Specifiers +g+ and +G+ + +Format +argument+ using exponential form (+e+/+E+ specifier) +if the exponent is less than -4 or greater than or equal to the precision. +Otherwise format +argument+ using floating-point form (+f+ specifier): + + sprintf('%g', 100) # => "100" + sprintf('%g', 100.0) # => "100" + sprintf('%g', 3.14159) # => "3.14159" + sprintf('%g', 100000000000) # => "1e+11" + sprintf('%g', 0.000000000001) # => "1e-12" + + # Capital 'G' means use capital 'E'. + sprintf('%G', 100000000000) # => "1E+11" + sprintf('%G', 0.000000000001) # => "1E-12" + + # Alternate format. + sprintf('%#g', 100000000000) # => "1.00000e+11" + sprintf('%#g', 0.000000000001) # => "1.00000e-12" + sprintf('%#G', 100000000000) # => "1.00000E+11" + sprintf('%#G', 0.000000000001) # => "1.00000E-12" + +=== Specifier +o+ + +Format +argument+ as an octal integer. +If +argument+ is negative, it will be formatted as a two's complement +prefixed with +..7+: + + sprintf('%o', 16) # => "20" + + # Prefix '..7' for negative value. + sprintf('%o', -16) # => "..760" + + # Prefix zero for alternate format if positive. + sprintf('%#o', 16) # => "020" + sprintf('%#o', -16) # => "..760" + +=== Specifier +p+ + +Format +argument+ as a string via <tt>argument.inspect</tt>: + + t = Time.now + sprintf('%p', t) # => "2022-05-01 13:42:07.1645683 -0500" + +=== Specifier +s+ + +Format +argument+ as a string via <tt>argument.to_s</tt>: + + t = Time.now + sprintf('%s', t) # => "2022-05-01 13:42:07 -0500" + +Flag <tt>'#'</tt> does not apply. + +=== Specifiers +x+ and +X+ + +Format +argument+ as a hexadecimal integer. +If +argument+ is negative, it will be formatted as a two's complement +prefixed with +..f+: + + sprintf('%x', 100) # => "64" + + # Prefix '..f' for negative value. + sprintf('%x', -100) # => "..f9c" + + # Use alternate format. + sprintf('%#x', 100) # => "0x64" + + # Alternate format for negative value. + sprintf('%#x', -100) # => "0x..f9c" + +=== Specifier <tt>%</tt> + +Format +argument+ (<tt>'%'</tt>) as a single percent character: + + sprintf('%d %%', 100) # => "100 %" + +Flags do not apply. + +== Reference by Name + +For more complex formatting, Ruby supports a reference by name. +%<name>s style uses format style, but %{name} style doesn't. + +Examples: + + sprintf("%<foo>d : %<bar>f", { :foo => 1, :bar => 2 }) # => 1 : 2.000000 + sprintf("%{foo}f", { :foo => 1 }) # => "1f" diff --git a/doc/globals.rdoc b/doc/globals.rdoc index 1d7cda69f9..1b51bb1b36 100644 --- a/doc/globals.rdoc +++ b/doc/globals.rdoc @@ -1,69 +1,422 @@ -# -*- mode: rdoc; coding: utf-8; fill-column: 74; -*- - -== Pre-defined global variables - -$!:: The Exception object set by Kernel#raise. -$@:: The same as <code>$!.backtrace</code>. -$~:: The information about the last match in the current scope (thread-local and frame-local). -$&:: The string matched by the last successful match. -$`:: The string to the left of the last successful match. -$':: The string to the right of the last successful match. -$+:: The highest group matched by the last successful match. -$1:: The Nth group of the last successful match. May be > 1. -$=:: This variable is no longer effective. Deprecated. -$/:: The input record separator, newline by default. Aliased to $-0. -$\:: The output record separator for Kernel#print and IO#write. Default is +nil+. -$,:: The output field separator for Kernel#print and Array#join. Non-nil $, will be deprecated. -$;:: The default separator for String#split. Non-nil $; will be deprecated. Aliased to $-F. -$.:: The current input line number of the last file that was read. -$<:: The same as ARGF. -$>:: The default output stream for Kernel#print and Kernel#printf. $stdout by default. -$_:: The last input line of string by gets or readline. -$0:: Contains the name of the script being executed. May be assignable. -$*:: The same as ARGV. -$$:: The process number of the Ruby running this script. Same as Process.pid. -$?:: The status of the last executed child process (thread-local). -$LOAD_PATH:: Load path for searching Ruby scripts and extension libraries used - by Kernel#load and Kernel#require. Aliased to $: and $-I. - Has a singleton method <code>$LOAD_PATH.resolve_feature_path(feature)</code> - that returns [+:rb+ or +:so+, path], which resolves the feature to - the path the original Kernel#require method would load. -$LOADED_FEATURES:: The array contains the module names loaded by require. - Aliased to $". -$DEBUG:: The debug flag, which is set by the <tt>-d</tt> switch. Enabling debug - output prints each exception raised to $stderr (but not its - backtrace). Setting this to a true value enables debug output as - if <tt>-d</tt> were given on the command line. Setting this to a false - value disables debug output. Aliased to $-d. -$FILENAME:: Current input filename from ARGF. Same as ARGF.filename. -$stderr:: The current standard error output. -$stdin:: The current standard input. -$stdout:: The current standard output. -$VERBOSE:: The verbose flag, which is set by the <tt>-w</tt> or <tt>-v</tt> switch. - Setting this to a true value enables warnings as if <tt>-w</tt> or <tt>-v</tt> were given - on the command line. Setting this to +nil+ disables warnings, - including from Kernel#warn. Aliased to $-v and $-w. -$-a:: True if option <tt>-a</tt> is set. Read-only variable. -$-i:: In in-place-edit mode, this variable holds the extension, otherwise +nil+. -$-l:: True if option <tt>-l</tt> is set. Read-only variable. -$-p:: True if option <tt>-p</tt> is set. Read-only variable. - -== Pre-defined global constants - -STDIN:: The standard input. The default value for $stdin. -STDOUT:: The standard output. The default value for $stdout. -STDERR:: The standard error output. The default value for $stderr. -ENV:: The hash contains current environment variables. -ARGF:: The virtual concatenation of the files given on command line (or from $stdin if no files were given). -ARGV:: An Array of command line arguments given for the script. -DATA:: The file object of the script, pointing just after <code>__END__</code>. -TOPLEVEL_BINDING:: The Binding of the top level scope. -RUBY_VERSION:: The Ruby language version. -RUBY_RELEASE_DATE:: The release date string. -RUBY_PLATFORM:: The platform identifier. -RUBY_PATCHLEVEL:: The patchlevel for this Ruby. If this is a development build of Ruby the patchlevel will be -1. -RUBY_REVISION:: The GIT commit hash for this Ruby. -RUBY_COPYRIGHT:: The copyright string for Ruby. -RUBY_ENGINE:: The name of the Ruby implementation. -RUBY_ENGINE_VERSION:: The version of the Ruby implementation. -RUBY_DESCRIPTION:: The same as <tt>ruby --version</tt>, a String describing various aspects of the Ruby implementation. += Pre-Defined Global Variables + +Some of the pre-defined global variables have synonyms +that are available via module English. +For each of those, the \English synonym is given. + +To use the module: + + require 'English' + +== Exceptions + +=== <tt>$!</tt> (\Exception) + +Contains the Exception object set by Kernel#raise: + + begin + raise RuntimeError.new('Boo!') + rescue RuntimeError + p $! + end + +Output: + + #<RuntimeError: Boo!> + +English - <tt>$ERROR_INFO</tt> + +=== <tt>$@</tt> (Backtrace) + +Same as <tt>$!.backtrace</tt>; +returns an array of backtrace positions: + + begin + raise RuntimeError.new('Boo!') + rescue RuntimeError + pp $@.take(4) + end + +Output: + + ["(irb):338:in `<top (required)>'", + "/snap/ruby/317/lib/ruby/3.2.0/irb/workspace.rb:119:in `eval'", + "/snap/ruby/317/lib/ruby/3.2.0/irb/workspace.rb:119:in `evaluate'", + "/snap/ruby/317/lib/ruby/3.2.0/irb/context.rb:502:in `evaluate'"] + +English - <tt>$ERROR_POSITION</tt>. + +== Pattern Matching + +These global variables store information about the most recent +successful match in the current scope. + +For details and examples, +see {Regexp Global Variables}[rdoc-ref:Regexp@Global+Variables]. + +=== <tt>$~</tt> (\MatchData) + +MatchData object created from the match; +thread-local and frame-local. + +English - <tt>$LAST_MATCH_INFO</tt>. + +=== <tt>$&</tt> (Matched Substring) + +The matched string. + +English - <tt>$MATCH</tt>. + +=== <tt>$`</tt> (Pre-Match Substring) + +The string to the left of the match. + +English - <tt>$PREMATCH</tt>. + +=== <tt>$'</tt> (Post-Match Substring) + +The string to the right of the match. + +English - <tt>$POSTMATCH</tt>. + +=== <tt>$+</tt> (Last Matched Group) + +The last group matched. + +English - <tt>$LAST_PAREN_MATCH</tt>. + +=== <tt>$1</tt>, <tt>$2</tt>, \Etc. (Matched Group) + +For <tt>$_n_</tt> the _nth_ group of the match. + +No \English. + +== Separators + +=== <tt>$/</tt> (Input Record Separator) + +An input record separator, initially newline. + +English - <tt>$INPUT_RECORD_SEPARATOR</tt>, <tt>$RS</tt>. + +Aliased as <tt>$-0</tt>. + +=== <tt>$;</tt> (Input Field Separator) + +An input field separator, initially +nil+. + +English - <tt>$FIELD_SEPARATOR</tt>, <tt>$FS</tt>. + +Aliased as <tt>$-F</tt>. + +=== <tt>$\\</tt> (Output Record Separator) + +An output record separator, initially +nil+. + +English - <tt>$OUTPUT_RECORD_SEPARATOR</tt>, <tt>$ORS</tt>. + +== Streams + +=== <tt>$stdin</tt> (Standard Input) + +The current standard input stream; initially: + + $stdin # => #<IO:<STDIN>> + +=== <tt>$stdout</tt> (Standard Output) + +The current standard output stream; initially: + + $stdout # => #<IO:<STDOUT>> + +=== <tt>$stderr</tt> (Standard Error) + +The current standard error stream; initially: + + $stderr # => #<IO:<STDERR>> + +=== <tt>$<</tt> (\ARGF or $stdin) + +Points to stream ARGF if not empty, else to stream $stdin; read-only. + +English - <tt>$DEFAULT_INPUT</tt>. + +=== <tt>$></tt> (Default Standard Output) + +An output stream, initially <tt>$stdout</tt>. + +English - <tt>$DEFAULT_OUTPUT + +=== <tt>$.</tt> (Input Position) + +The input position (line number) in the most recently read stream. + +English - <tt>$INPUT_LINE_NUMBER</tt>, <tt>$NR</tt> + +=== <tt>$_</tt> (Last Read Line) + +The line (string) from the most recently read stream. + +English - <tt>$LAST_READ_LINE</tt>. + +== Processes + +=== <tt>$0</tt> + +Initially, contains the name of the script being executed; +may be reassigned. + +=== <tt>$*</tt> (\ARGV) + +Points to ARGV. + +English - <tt>$ARGV</tt>. + +=== <tt>$$</tt> (Process ID) + +The process ID of the current process. Same as Process.pid. + +English - <tt>$PROCESS_ID</tt>, <tt>$PID</tt>. + +=== <tt>$?</tt> (Child Status) + +Initially +nil+, otherwise the Process::Status object +created for the most-recently exited child process; +thread-local. + +English - <tt>$CHILD_STATUS</tt>. + +=== <tt>$LOAD_PATH</tt> (Load Path) + +Contains the array of paths to be searched +by Kernel#load and Kernel#require. + +Singleton method <tt>$LOAD_PATH.resolve_feature_path(feature)</tt> +returns: + +- <tt>[:rb, _path_]</tt>, where +path+ is the path to the Ruby file + to be loaded for the given +feature+. +- <tt>[:so+ _path_]</tt>, where +path+ is the path to the shared object file + to be loaded for the given +feature+. +- +nil+ if there is no such +feature+ and +path+. + +Examples: + + $LOAD_PATH.resolve_feature_path('timeout') + # => [:rb, "/snap/ruby/317/lib/ruby/3.2.0/timeout.rb"] + $LOAD_PATH.resolve_feature_path('date_core') + # => [:so, "/snap/ruby/317/lib/ruby/3.2.0/x86_64-linux/date_core.so"] + $LOAD_PATH.resolve_feature_path('foo') + # => nil + +Aliased as <tt>$:</tt> and <tt>$-I</tt>. + +=== <tt>$LOADED_FEATURES</tt> + +Contains an array of the paths to the loaded files: + + $LOADED_FEATURES.take(10) + # => + ["enumerator.so", + "thread.rb", + "fiber.so", + "rational.so", + "complex.so", + "ruby2_keywords.rb", + "/snap/ruby/317/lib/ruby/3.2.0/x86_64-linux/enc/encdb.so", + "/snap/ruby/317/lib/ruby/3.2.0/x86_64-linux/enc/trans/transdb.so", + "/snap/ruby/317/lib/ruby/3.2.0/x86_64-linux/rbconfig.rb", + "/snap/ruby/317/lib/ruby/3.2.0/rubygems/compatibility.rb"] + +Aliased as <tt>$"</tt>. + +== Debugging + +=== <tt>$FILENAME</tt> + +The value returned by method ARGF.filename. + +=== <tt>$DEBUG</tt> + +Initially +true+ if command-line option <tt>-d</tt> or <tt>--debug</tt> is given, +otherwise initially +false+; +may be set to either value in the running program. + +When +true+, prints each raised exception to <tt>$stderr</tt>. + +Aliased as <tt>$-d</tt>. + +=== <tt>$VERBOSE</tt> + +Initially +true+ if command-line option <tt>-v</tt> or <tt>-w</tt> is given, +otherwise initially +false+; +may be set to either value, or to +nil+, in the running program. + +When +true+, enables Ruby warnings. + +When +nil+, disables warnings, including those from Kernel#warn. + +Aliased as <tt>$-v</tt> and <tt>$-w</tt>. + +== Other Variables + +=== <tt>$-a</tt> + +Whether command-line option <tt>-a</tt> was given; read-only. + +=== <tt>$-i</tt> + +Contains the extension given with command-line option <tt>-i</tt>, +or +nil+ if none. + +An alias of ARGF.inplace_mode. + +=== <tt>$-l</tt> + +Whether command-line option <tt>-l</tt> was set; read-only. + +=== <tt>$-p</tt> + +Whether command-line option <tt>-p</tt> was given; read-only. + +== Deprecated + +=== <tt>$=</tt> + +=== <tt>$,</tt> + += Pre-Defined Global Constants + += Streams + +=== <tt>STDIN</tt> + +The standard input stream (the default value for <tt>$stdin</tt>): + + STDIN # => #<IO:<STDIN>> + +=== <tt>STDOUT</tt> + +The standard output stream (the default value for <tt>$stdout</tt>): + + STDOUT # => #<IO:<STDOUT>> + +=== <tt>STDERR</tt> + +The standard error stream (the default value for <tt>$stderr</tt>): + + STDERR # => #<IO:<STDERR>> + +== Environment + +=== ENV + +A hash of the contains current environment variables names and values: + + ENV.take(5) + # => + [["COLORTERM", "truecolor"], + ["DBUS_SESSION_BUS_ADDRESS", "unix:path=/run/user/1000/bus"], + ["DESKTOP_SESSION", "ubuntu"], + ["DISPLAY", ":0"], + ["GDMSESSION", "ubuntu"]] + +=== ARGF + +The virtual concatenation of the files given on the command line, or from +<tt>$stdin</tt> if no files were given, <tt>"-"</tt> is given, or after +all files have been read. + +=== <tt>ARGV</tt> + +An array of the given command-line arguments. + +=== <tt>TOPLEVEL_BINDING</tt> + +The Binding of the top level scope: + + TOPLEVEL_BINDING # => #<Binding:0x00007f58da0da7c0> + +=== <tt>RUBY_VERSION</tt> + +The Ruby version: + + RUBY_VERSION # => "3.2.2" + +=== <tt>RUBY_RELEASE_DATE</tt> + +The release date string: + + RUBY_RELEASE_DATE # => "2023-03-30" + +=== <tt>RUBY_PLATFORM</tt> + +The platform identifier: + + RUBY_PLATFORM # => "x86_64-linux" + +=== <tt>RUBY_PATCHLEVEL</tt> + +The integer patch level for this Ruby: + + RUBY_PATCHLEVEL # => 53 + +For a development build the patch level will be -1. + +=== <tt>RUBY_REVISION</tt> + +The git commit hash for this Ruby: + + RUBY_REVISION # => "e51014f9c05aa65cbf203442d37fef7c12390015" + +=== <tt>RUBY_COPYRIGHT</tt> + +The copyright string: + + RUBY_COPYRIGHT + # => "ruby - Copyright (C) 1993-2023 Yukihiro Matsumoto" + +=== <tt>RUBY_ENGINE</tt> + +The name of the Ruby implementation: + + RUBY_ENGINE # => "ruby" + +=== <tt>RUBY_ENGINE_VERSION</tt> + +The version of the Ruby implementation: + + RUBY_ENGINE_VERSION # => "3.2.2" + +=== <tt>RUBY_DESCRIPTION</tt> + +The description of the Ruby implementation: + + RUBY_DESCRIPTION + # => "ruby 3.2.2 (2023-03-30 revision e51014f9c0) [x86_64-linux]" + +== Embedded \Data + +=== <tt>DATA</tt> + +Defined if and only if the program has this line: + + __END__ + +When defined, <tt>DATA</tt> is a File object +containing the lines following the <tt>__END__</tt>, +positioned at the first of those lines: + + p DATA + DATA.each_line { |line| p line } + __END__ + Foo + Bar + Baz + +Output: + + #<File:t.rb> + "Foo\n" + "Bar\n" + "Baz\n" diff --git a/doc/implicit_conversion.rdoc b/doc/implicit_conversion.rdoc index 0c2a1d4971..e244096125 100644 --- a/doc/implicit_conversion.rdoc +++ b/doc/implicit_conversion.rdoc @@ -1,7 +1,8 @@ -== Implicit Conversions += Implicit Conversions Some Ruby methods accept one or more objects that can be either: + * <i>Of a given class</i>, and so accepted as is. * <i>Implicitly convertible to that class</i>, in which case the called method converts the object. @@ -14,13 +15,18 @@ a specific conversion method: * Integer: +to_int+ * String: +to_str+ -=== Array-Convertible Objects +== Array-Convertible Objects An <i>Array-convertible object</i> is an object that: + * Has instance method +to_ary+. * The method accepts no arguments. * The method returns an object +obj+ for which <tt>obj.kind_of?(Array)</tt> returns +true+. +The Ruby core class that satisfies these requirements is: + +* Array + The examples in this section use method <tt>Array#replace</tt>, which accepts an Array-convertible argument. @@ -63,13 +69,18 @@ This class is not Array-convertible (method +to_ary+ returns non-Array): # Raises TypeError (can't convert NotArrayConvertible to Array (NotArrayConvertible#to_ary gives Symbol)) a.replace(NotArrayConvertible.new) -=== Hash-Convertible Objects +== Hash-Convertible Objects A <i>Hash-convertible object</i> is an object that: + * Has instance method +to_hash+. * The method accepts no arguments. * The method returns an object +obj+ for which <tt>obj.kind_of?(Hash)</tt> returns +true+. +The Ruby core class that satisfies these requirements is: + +* Hash + The examples in this section use method <tt>Hash#merge</tt>, which accepts a Hash-convertible argument. @@ -112,13 +123,21 @@ This class is not Hash-convertible (method +to_hash+ returns non-Hash): # Raises TypeError (can't convert NotHashConvertible to Hash (ToHashReturnsNonHash#to_hash gives Symbol)) h.merge(NotHashConvertible.new) -=== Integer-Convertible Objects +== Integer-Convertible Objects An <i>Integer-convertible object</i> is an object that: + * Has instance method +to_int+. * The method accepts no arguments. * The method returns an object +obj+ for which <tt>obj.kind_of?(Integer)</tt> returns +true+. +The Ruby core classes that satisfy these requirements are: + +* Integer +* Float +* Complex +* Rational + The examples in this section use method <tt>Array.new</tt>, which accepts an Integer-convertible argument. @@ -152,13 +171,17 @@ This class is not Integer-convertible (method +to_int+ returns non-Integer): # Raises TypeError (can't convert NotIntegerConvertible to Integer (NotIntegerConvertible#to_int gives Symbol)) Array.new(NotIntegerConvertible.new) -=== String-Convertible Objects +== String-Convertible Objects A <i>String-convertible object</i> is an object that: * Has instance method +to_str+. * The method accepts no arguments. * The method returns an object +obj+ for which <tt>obj.kind_of?(String)</tt> returns +true+. +The Ruby core class that satisfies these requirements is: + +* String + The examples in this section use method <tt>String::new</tt>, which accepts a String-convertible argument. diff --git a/doc/irb/indexes.md b/doc/irb/indexes.md new file mode 100644 index 0000000000..24a67b9698 --- /dev/null +++ b/doc/irb/indexes.md @@ -0,0 +1,189 @@ +## Indexes + +### Index of Command-Line Options + +These are the \IRB command-line options, with links to explanatory text: + +- `-d`: Set `$DEBUG` and {$VERBOSE}[rdoc-ref:IRB@Verbosity] + to `true`. +- `-E _ex_[:_in_]`: Set initial external (ex) and internal (in) + {encodings}[rdoc-ref:IRB@Encodings] (same as `ruby -E>`). +- `-f`: Don't initialize from {configuration file}[rdoc-ref:IRB@Configuration+File]. +- `-I _dirpath_`: Specify {$LOAD_PATH directory}[rdoc-ref:IRB@Load+Modules] + (same as `ruby -I`). +- `-r _load-module_`: Require {load-module}[rdoc-ref:IRB@Load+Modules] + (same as `ruby -r`). +- `-U`: Set external and internal {encodings}[rdoc-ref:IRB@Encodings] to UTF-8. +- `-w`: Suppress {warnings}[rdoc-ref:IRB@Warnings] (same as `ruby -w`). +- `-W[_level_]`: Set {warning level}[rdoc-ref:IRB@Warnings]; + 0=silence, 1=medium, 2=verbose (same as `ruby -W`). +- `--autocomplete`: Use {auto-completion}[rdoc-ref:IRB@Automatic+Completion]. +- `--back-trace-limit _n_`: Set a {backtrace limit}[rdoc-ref:IRB@Tracer]; + display at most the top `n` and bottom `n` entries. +- `--colorize`: Use {color-highlighting}[rdoc-ref:IRB@Color+Highlighting] + for input and output. +- `--context-mode _n_`: Select method to create Binding object + for new {workspace}[rdoc-ref:IRB@Commands]; `n` in range `0..4`. +- `--echo`: Print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29]) + return values. +- `--extra-doc-dir _dirpath_`: + Add a {documentation directory}[rdoc-ref:IRB@RI+Documentation+Directories] + for the documentation dialog. +- `--inf-ruby-mode`: Set prompt mode to {:INF_RUBY}[rdoc-ref:IRB@Pre-Defined+Prompts] + (appropriate for `inf-ruby-mode` on Emacs); + suppresses --multiline and --singleline. +- `--inspect`: Use method `inspect` for printing ({echoing}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29]) + return values. +- `--multiline`: Use the multiline editor as the {input method}[rdoc-ref:IRB@Input+Method]. +- `--noautocomplete`: Don't use {auto-completion}[rdoc-ref:IRB@Automatic+Completion]. +- `--nocolorize`: Don't use {color-highlighting}[rdoc-ref:IRB@Color+Highlighting] + for input and output. +- `--noecho`: Don't print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29]) + return values. +- `--noecho-on-assignment`: Don't print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29]) + result on assignment. +- `--noinspect`: Don't se method `inspect` for printing ({echoing}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29]) + return values. +- `--nomultiline`: Don't use the multiline editor as the {input method}[rdoc-ref:IRB@Input+Method]. +- `--noprompt`: Don't print {prompts}[rdoc-ref:IRB@Prompt+and+Return+Formats]. +- `--noscript`: Treat the first command-line argument as a normal + {command-line argument}[rdoc-ref:IRB@Initialization+Script], + and include it in `ARGV`. +- `--nosingleline`: Don't use the singleline editor as the {input method}[rdoc-ref:IRB@Input+Method]. +- `--noverbose`Don't print {verbose}[rdoc-ref:IRB@Verbosity] details. +- `--prompt _mode_`, `--prompt-mode _mode_`: + Set {prompt and return formats}[rdoc-ref:IRB@Prompt+and+Return+Formats]; + `mode` may be a {pre-defined prompt}[rdoc-ref:IRB@Pre-Defined+Prompts] + or the name of a {custom prompt}[rdoc-ref:IRB@Custom+Prompts]. +- `--script`: Treat the first command-line argument as the path to an + {initialization script}[rdoc-ref:IRB@Initialization+Script], + and omit it from `ARGV`. +- `--simple-prompt`, `--sample-book-mode`: + Set prompt mode to {:SIMPLE}[rdoc-ref:IRB@Pre-Defined+Prompts]. +- `--singleline`: Use the singleline editor as the {input method}[rdoc-ref:IRB@Input+Method]. +- `--tracer`: Use {Tracer}[rdoc-ref:IRB@Tracer] to print a stack trace for each input command. +- `--truncate-echo-on-assignment`: Print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29]) + truncated result on assignment. +- `--verbose`Print {verbose}[rdoc-ref:IRB@Verbosity] details. +- `-v`, `--version`: Print the {IRB version}[rdoc-ref:IRB@Version]. +- `-h`, `--help`: Print the {IRB help text}[rdoc-ref:IRB@Help]. +- `--`: Separate options from {arguments}[rdoc-ref:IRB@Command-Line+Arguments] + on the command-line. + +### Index of \IRB.conf Entries + +These are the keys for hash \IRB.conf entries, with links to explanatory text; +for each entry that is pre-defined, the initial value is given: + +- `:AP_NAME`: \IRB {application name}[rdoc-ref:IRB@Application+Name]; + initial value: `'irb'`. +- `:AT_EXIT`: Array of hooks to call + {at exit}[rdoc-ref:IRB@IRB]; + initial value: `[]`. +- `:AUTO_INDENT`: Whether {automatic indentation}[rdoc-ref:IRB@Automatic+Indentation] + is enabled; initial value: `true`. +- `:BACK_TRACE_LIMIT`: Sets the {back trace limit}[rdoc-ref:IRB@Tracer]; + initial value: `16`. +- `:COMMAND_ALIASES`: Defines input {command aliases}[rdoc-ref:IRB@Command+Aliases]; + initial value: + + { + "$": :show_source, + "@": :whereami, + } + +- `:CONTEXT_MODE`: Sets the {context mode}[rdoc-ref:IRB@Context+Mode], + the type of binding to be used when evaluating statements; + initial value: `4`. +- `:ECHO`: Whether to print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29]) + return values; + initial value: `nil`, which would set `conf.echo` to `true`. +- `:ECHO_ON_ASSIGNMENT`: Whether to print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29]) + return values on assignment; + initial value: `nil`, which would set `conf.echo_on_assignment` to `:truncate`. +- `:EVAL_HISTORY`: How much {evaluation history}[rdoc-ref:IRB@Evaluation+History] + is to be stored; initial value: `nil`. +- `:EXTRA_DOC_DIRS`: \Array of + {RI documentation directories}[rdoc-ref:IRB@RI+Documentation+Directories] + to be parsed for the documentation dialog; + initial value: `[]`. +- `:IGNORE_EOF`: Whether to ignore {end-of-file}[rdoc-ref:IRB@End-of-File]; + initial value: `false`. +- `:IGNORE_SIGINT`: Whether to ignore {SIGINT}[rdoc-ref:IRB@SIGINT]; + initial value: `true`. +- `:INSPECT_MODE`: Whether to use method `inspect` for printing + ({echoing}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29]) return values; + initial value: `true`. +- `:IRB_LIB_PATH`: The path to the {IRB library directory}[rdoc-ref:IRB@IRB+Library+Directory]; initial value: + + - `"<i>RUBY_DIR</i>/lib/ruby/gems/<i>RUBY_VER_NUM</i>/gems/irb-<i>IRB_VER_NUM</i>/lib/irb"`, + + where: + + - <i>RUBY_DIR</i> is the Ruby installation dirpath. + - <i>RUBY_VER_NUM</i> is the Ruby version number. + - <i>IRB_VER_NUM</i> is the \IRB version number. + +- `:IRB_NAME`: {IRB name}[rdoc-ref:IRB@IRB+Name]; + initial value: `'irb'`. +- `:IRB_RC`: {Configuration monitor}[rdoc-ref:IRB@Configuration+Monitor]; + initial value: `nil`. +- `:LC_MESSAGES`: {Locale}[rdoc-ref:IRB@Locale]; + initial value: IRB::Locale object. +- `:LOAD_MODULES`: deprecated. +- `:MAIN_CONTEXT`: The {context}[rdoc-ref:IRB@Session+Context] for the main \IRB session; + initial value: IRB::Context object. +- `:MEASURE`: Whether to + {measure performance}[rdoc-ref:IRB@Performance+Measurement]; + initial value: `false`. +- `:MEASURE_CALLBACKS`: Callback methods for + {performance measurement}[rdoc-ref:IRB@Performance+Measurement]; + initial value: `[]`. +- `:MEASURE_PROC`: Procs for + {performance measurement}[rdoc-ref:IRB@Performance+Measurement]; + initial value: + + { + :TIME=>#<Proc:0x0000556e271c6598 /var/lib/gems/3.0.0/gems/irb-1.8.3/lib/irb/init.rb:106>, + :STACKPROF=>#<Proc:0x0000556e271c6548 /var/lib/gems/3.0.0/gems/irb-1.8.3/lib/irb/init.rb:116> + } + +- `:PROMPT`: \Hash of {defined prompts}[rdoc-ref:IRB@Prompt+and+Return+Formats]; + initial value: + + { + :NULL=>{:PROMPT_I=>nil, :PROMPT_S=>nil, :PROMPT_C=>nil, :RETURN=>"%s\n"}, + :DEFAULT=>{:PROMPT_I=>"%N(%m):%03n> ", :PROMPT_S=>"%N(%m):%03n%l ", :PROMPT_C=>"%N(%m):%03n* ", :RETURN=>"=> %s\n"}, + :CLASSIC=>{:PROMPT_I=>"%N(%m):%03n:%i> ", :PROMPT_S=>"%N(%m):%03n:%i%l ", :PROMPT_C=>"%N(%m):%03n:%i* ", :RETURN=>"%s\n"}, + :SIMPLE=>{:PROMPT_I=>">> ", :PROMPT_S=>"%l> ", :PROMPT_C=>"?> ", :RETURN=>"=> %s\n"}, + :INF_RUBY=>{:PROMPT_I=>"%N(%m):%03n> ", :PROMPT_S=>nil, :PROMPT_C=>nil, :RETURN=>"%s\n", :AUTO_INDENT=>true}, + :XMP=>{:PROMPT_I=>nil, :PROMPT_S=>nil, :PROMPT_C=>nil, :RETURN=>" ==>%s\n"} + } + +- `:PROMPT_MODE`: Name of {current prompt}[rdoc-ref:IRB@Prompt+and+Return+Formats]; + initial value: `:DEFAULT`. +- `:RC`: Whether a {configuration file}[rdoc-ref:IRB@Configuration+File] + was found and interpreted; + initial value: `true` if a configuration file was found, `false` otherwise. +- `:SAVE_HISTORY`: Number of commands to save in + {input command history}[rdoc-ref:IRB@Input+Command+History]; + initial value: `1000`. +- `:SINGLE_IRB`: Whether command-line option `--single-irb` was given; + initial value: `true` if the option was given, `false` otherwise. + See {Single-IRB Mode}[rdoc-ref:IRB@Single-IRB+Mode]. +- `:USE_AUTOCOMPLETE`: Whether to use + {automatic completion}[rdoc-ref:IRB@Automatic+Completion]; + initial value: `true`. +- `:USE_COLORIZE`: Whether to use + {color highlighting}[rdoc-ref:IRB@Color+Highlighting]; + initial value: `true`. +- `:USE_LOADER`: Whether to use the + {IRB loader}[rdoc-ref:IRB@IRB+Loader] for `require` and `load`; + initial value: `false`. +- `:USE_TRACER`: Whether to use the + {IRB tracer}[rdoc-ref:IRB@Tracer]; + initial value: `false`. +- `:VERBOSE`: Whether to print {verbose output}[rdoc-ref:IRB@Verbosity]; + initial value: `nil`. +- `:__MAIN__`: The main \IRB object; + initial value: `main`. diff --git a/doc/irb/irb.rd.ja b/doc/irb/irb.rd.ja index 633c08cbd4..c51e0bd60d 100644 --- a/doc/irb/irb.rd.ja +++ b/doc/irb/irb.rd.ja @@ -125,7 +125,6 @@ irb起動時に``~/.irbrc''を読み込みます. もし存在しない場合は IRB.conf[:PROMPT][:MY_PROMPT] = { # プロンプトモードの名前 :PROMPT_I => nil, # 通常のプロンプト - :PROMPT_N => nil, # 継続行のプロンプト :PROMPT_S => nil, # 文字列などの継続行のプロンプト :PROMPT_C => nil, # 式が継続している時のプロンプト :RETURN => " ==>%s\n" # リターン時のプロンプト @@ -140,7 +139,7 @@ OKです. IRB.conf[:PROMPT_MODE] = :MY_PROMPT -PROMPT_I, PROMPT_N, PROMPT_S, PROMPT_Cは, フォーマットを指定します. +PROMPT_I, PROMPT_S, PROMPT_Cは, フォーマットを指定します. %N 起動しているコマンド名が出力される. %m mainオブジェクト(self)がto_sで出力される. @@ -155,7 +154,6 @@ PROMPT_I, PROMPT_N, PROMPT_S, PROMPT_Cは, フォーマットを指定します. IRB.conf[:PROMPT][:DEFAULT] = { :PROMPT_I => "%N(%m):%03n:%i> ", - :PROMPT_N => "%N(%m):%03n:%i> ", :PROMPT_S => "%N(%m):%03n:%i%l ", :PROMPT_C => "%N(%m):%03n:%i* ", :RETURN => "=> %s\n" diff --git a/doc/keywords.rdoc b/doc/keywords.rdoc index cb1cff33f0..7c368205ef 100644 --- a/doc/keywords.rdoc +++ b/doc/keywords.rdoc @@ -1,4 +1,4 @@ -== Keywords += Keywords The following keywords are used by Ruby. diff --git a/doc/maintainers.md b/doc/maintainers.md new file mode 100644 index 0000000000..dabbdc0cb6 --- /dev/null +++ b/doc/maintainers.md @@ -0,0 +1,504 @@ +# Maintainers +This page describes the current branch, module, library, and extension maintainers of Ruby. + +## Branch Maintainers + +A branch maintainer is responsible for backporting commits into stable branches +and publishing Ruby patch releases. + +[The list of current branch maintainers is available in the wiki](https://github.com/ruby/ruby/wiki/Release-Engineering). + +## Module Maintainers +A module maintainer is responsible for a certain part of Ruby. + +* The maintainer fixes bugs of the part. Particularly, they should fix + security vulnerabilities as soon as possible. +* They handle issues related the module on the Redmine or ML. +* They may be discharged by the 3 months rule [[ruby-core:25764]](https://blade.ruby-lang.org/ruby-core/25764). +* They have commit right to Ruby's repository to modify their part in the + repository. +* They have "developer" role on the Redmine to modify issues. +* They have authority to decide the feature of their part. But they should + always respect discussions on ruby-core/ruby-dev. + +A submaintainer of a module is like a maintainer. But the submaintainer does +not have authority to change/add a feature on his/her part. They need +consensus on ruby-core/ruby-dev before changing/adding. Some of submaintainers +have commit right, others don't. + +### Language core features including security +* Yukihiro Matsumoto (matz) + +### Evaluator +* Koichi Sasada (ko1) + +### Core classes +* Yukihiro Matsumoto (matz) + +## Standard Library Maintainers +### Libraries +#### lib/mkmf.rb +* *unmaintained* + +#### lib/rubygems.rb, lib/rubygems/* +* Eric Hodel (drbrain) +* Hiroshi SHIBATA (hsbt) +* https://github.com/rubygems/rubygems + +#### lib/unicode_normalize.rb, lib/unicode_normalize/* +* Martin J. Dürst + +### Extensions +#### ext/continuation +* Koichi Sasada (ko1) + +#### ext/coverage +* Yusuke Endoh (mame) + +#### ext/fiber +* Koichi Sasada (ko1) + +#### ext/monitor +* Koichi Sasada (ko1) + +#### ext/objspace +* *unmaintained* + +#### ext/pty +* *unmaintained* + +#### ext/ripper +* *unmaintained* + +#### ext/socket +* Tanaka Akira (akr) +* API change needs matz's approval + +#### ext/win32 +* NAKAMURA Usaku (usa) + +## Default gems Maintainers +### Libraries + +#### lib/benchmark.rb +* *unmaintained* +* https://github.com/ruby/benchmark +* https://rubygems.org/gems/benchmark + +#### lib/bundler.rb, lib/bundler/* +* Hiroshi SHIBATA (hsbt) +* https://github.com/rubygems/rubygems +* https://rubygems.org/gems/bundler + +#### lib/cgi.rb, lib/cgi/* +* *unmaintained* +* https://github.com/ruby/cgi +* https://rubygems.org/gems/cgi + +#### lib/English.rb +* *unmaintained* +* https://github.com/ruby/English +* https://rubygems.org/gems/English + +#### lib/delegate.rb +* *unmaintained* +* https://github.com/ruby/delegate +* https://rubygems.org/gems/delegate + +#### lib/did_you_mean.rb +* Yuki Nishijima (yuki24) +* https://github.com/ruby/did_you_mean +* https://rubygems.org/gems/did_you_mean + +#### ext/digest, ext/digest/* +* Akinori MUSHA (knu) +* https://github.com/ruby/digest +* https://rubygems.org/gems/digest + +#### lib/erb.rb +* Masatoshi SEKI (seki) +* Takashi Kokubun (k0kubun) +* https://github.com/ruby/erb +* https://rubygems.org/gems/erb + +#### lib/error_highlight.rb, lib/error_highlight/* +* Yusuke Endoh (mame) +* https://github.com/ruby/error_highlight +* https://rubygems.org/gems/error_highlight + +#### lib/fileutils.rb +* *unmaintained* +* https://github.com/ruby/fileutils +* https://rubygems.org/gems/fileutils + +#### lib/find.rb +* Kazuki Tsujimoto (ktsj) +* https://github.com/ruby/find +* https://rubygems.org/gems/find + +#### lib/forwardable.rb +* Keiju ISHITSUKA (keiju) +* https://github.com/ruby/forwardable +* https://rubygems.org/gems/forwardable + +#### lib/ipaddr.rb +* Akinori MUSHA (knu) +* https://github.com/ruby/ipaddr +* https://rubygems.org/gems/ipaddr + +#### lib/irb.rb, lib/irb/* +* Stan Lo (st0012) +* Tomoya Ishida (tompng) +* Mari Imaizumi (ima1zumi) +* Hitoshi Hasumi (hasumikin) +* https://github.com/ruby/irb +* https://rubygems.org/gems/irb + +#### lib/optparse.rb, lib/optparse/* +* Nobuyuki Nakada (nobu) +* https://github.com/ruby/optparse + +#### lib/logger.rb +* Naotoshi Seo (sonots) +* https://github.com/ruby/logger +* https://rubygems.org/gems/logger + +#### lib/net/http.rb, lib/net/https.rb +* NARUSE, Yui (naruse) +* https://github.com/ruby/net-http +* https://rubygems.org/gems/net-http + +#### lib/net/protocol.rb +* *unmaintained* +* https://github.com/ruby/net-protocol +* https://rubygems.org/gems/net-protocol + +#### lib/open3.rb +* *unmaintained* +* https://github.com/ruby/open3 +* https://rubygems.org/gems/open3 + +#### lib/open-uri.rb +* Tanaka Akira (akr) +* https://github.com/ruby/open-uri + +#### lib/ostruct.rb +* Marc-André Lafortune (marcandre) +* https://github.com/ruby/ostruct +* https://rubygems.org/gems/ostruct + +#### lib/pp.rb +* Tanaka Akira (akr) +* https://github.com/ruby/pp +* https://rubygems.org/gems/pp + +#### lib/prettyprint.rb +* Tanaka Akira (akr) +* https://github.com/ruby/prettyprint +* https://rubygems.org/gems/prettyprint + +#### lib/prism.rb +* Kevin Newton (kddnewton) +* Jemma Issroff (jemmaissroff) +* https://github.com/ruby/prism +* https://rubygems.org/gems/prism + +#### lib/pstore.rb +* *unmaintained* +* https://github.com/ruby/pstore +* https://rubygems.org/gems/pstore + +#### lib/readline.rb +* aycabta +* https://github.com/ruby/readline +* https://rubygems.org/gems/readline + +#### lib/resolv.rb +* Tanaka Akira (akr) +* https://github.com/ruby/resolv +* https://rubygems.org/gems/resolv + +#### lib/rdoc.rb, lib/rdoc/* +* Eric Hodel (drbrain) +* Hiroshi SHIBATA (hsbt) +* https://github.com/ruby/rdoc +* https://rubygems.org/gems/rdoc + +#### lib/reline.rb, lib/reline/* +* Tomoya Ishida (tompng) +* Mari Imaizumi (ima1zumi) +* Stan Lo (st0012) +* Hitoshi Hasumi (hasumikin) +* https://github.com/ruby/reline +* https://rubygems.org/gems/reline + +#### lib/securerandom.rb +* Tanaka Akira (akr) +* https://github.com/ruby/securerandom +* https://rubygems.org/gems/securerandom + +#### lib/set.rb +* Akinori MUSHA (knu) +* https://github.com/ruby/set +* https://rubygems.org/gems/set + +#### lib/shellwords.rb +* Akinori MUSHA (knu) +* https://github.com/ruby/shellwords +* https://rubygems.org/gems/shellwords + +#### lib/singleton.rb +* Yukihiro Matsumoto (matz) +* https://github.com/ruby/singleton +* https://rubygems.org/gems/singleton + +#### lib/tempfile.rb +* *unmaintained* +* https://github.com/ruby/tempfile +* https://rubygems.org/gems/tempfile + +#### lib/time.rb +* Tanaka Akira (akr) +* https://github.com/ruby/time +* https://rubygems.org/gems/time + +#### lib/timeout.rb +* Yukihiro Matsumoto (matz) +* https://github.com/ruby/timeout +* https://rubygems.org/gems/timeout + +#### lib/thwait.rb +* Keiju ISHITSUKA (keiju) +* https://github.com/ruby/thwait +* https://rubygems.org/gems/thwait + +#### lib/tmpdir.rb +* *unmaintained* +* https://github.com/ruby/tmpdir +* https://rubygems.org/gems/tmpdir + +#### lib/tsort.rb +* Tanaka Akira (akr) +* https://github.com/ruby/tsort +* https://rubygems.org/gems/tsort + +#### lib/un.rb +* WATANABE Hirofumi (eban) +* https://github.com/ruby/un +* https://rubygems.org/gems/un + +#### lib/uri.rb, lib/uri/* +* NARUSE, Yui (naruse) +* https://github.com/ruby/uri +* https://rubygems.org/gems/uri + +#### lib/yaml.rb, lib/yaml/* +* Aaron Patterson (tenderlove) +* Hiroshi SHIBATA (hsbt) +* https://github.com/ruby/yaml +* https://rubygems.org/gems/yaml + +#### lib/weakref.rb +* *unmaintained* +* https://github.com/ruby/weakref +* https://rubygems.org/gems/weakref + +### Extensions + +#### ext/cgi +* Nobuyoshi Nakada (nobu) +* https://github.com/ruby/cgi +* https://rubygems.org/gems/cgi + +#### ext/date +* *unmaintained* +* https://github.com/ruby/date +* https://rubygems.org/gems/date + +#### ext/etc +* *unmaintained* +* https://github.com/ruby/etc +* https://rubygems.org/gems/etc + +#### ext/fcntl +* *unmaintained* +* https://github.com/ruby/fcntl +* https://rubygems.org/gems/fcntl + +#### ext/fiddle +* Aaron Patterson (tenderlove) +* https://github.com/ruby/fiddle +* https://rubygems.org/gems/fiddle + +#### ext/io/console +* Nobuyuki Nakada (nobu) +* https://github.com/ruby/io-console +* https://rubygems.org/gems/io-console + +#### ext/io/nonblock +* Nobuyuki Nakada (nobu) +* https://github.com/ruby/io-nonblock +* https://rubygems.org/gems/io-nonblock + +#### ext/io/wait +* Nobuyuki Nakada (nobu) +* https://github.com/ruby/io-wait +* https://rubygems.org/gems/io-wait + +#### ext/json +* NARUSE, Yui (naruse) +* Hiroshi SHIBATA (hsbt) +* https://github.com/flori/json +* https://rubygems.org/gems/json + +#### ext/openssl +* Kazuki Yamaguchi (rhe) +* https://github.com/ruby/openssl +* https://rubygems.org/gems/openssl + +#### ext/pathname +* Tanaka Akira (akr) +* https://github.com/ruby/pathname +* https://rubygems.org/gems/pathname + +#### ext/psych +* Aaron Patterson (tenderlove) +* Hiroshi SHIBATA (hsbt) +* https://github.com/ruby/psych +* https://rubygems.org/gems/psych + +#### ext/stringio +* Nobuyuki Nakada (nobu) +* https://github.com/ruby/stringio +* https://rubygems.org/gems/stringio + +#### ext/strscan +* Kouhei Sutou (kou) +* https://github.com/ruby/strscan +* https://rubygems.org/gems/strscan + +#### ext/win32ole +* Masaki Suketa (suke) +* https://github.com/ruby/win32ole +* https://rubygems.org/gems/win32ole + +#### ext/zlib +* NARUSE, Yui (naruse) +* https://github.com/ruby/zlib +* https://rubygems.org/gems/zlib + +## Bundled gems upstream repositories +### minitest +* https://github.com/minitest/minitest + +### power_assert +* https://github.com/ruby/power_assert + +### rake +* https://github.com/ruby/rake + +### test-unit +* https://github.com/test-unit/test-unit + +### rexml +* https://github.com/ruby/rexml + +### rss +* https://github.com/ruby/rss + +### net-ftp +* https://github.com/ruby/net-ftp + +### net-imap +* https://github.com/ruby/net-imap + +### net-pop +* https://github.com/ruby/net-pop + +### net-smtp +* https://github.com/ruby/net-smtp + +### matrix +* https://github.com/ruby/matrix + +### prime +* https://github.com/ruby/prime + +### rbs +* https://github.com/ruby/rbs + +### typeprof +* https://github.com/ruby/typeprof + +### debug +* https://github.com/ruby/debug + +### racc +* https://github.com/ruby/racc + +#### mutex_m +* https://github.com/ruby/mutex_m + +#### getoptlong +* https://github.com/ruby/getoptlong + +#### base64 +* https://github.com/ruby/base64 + +#### bigdecimal +* https://github.com/ruby/bigdecimal + +#### observer +* https://github.com/ruby/observer + +#### abbrev +* https://github.com/ruby/abbrev + +#### resolv-replace +* https://github.com/ruby/resolv-replace + +#### rinda +* https://github.com/ruby/rinda + +#### drb +* https://github.com/ruby/drb + +#### nkf +* https://github.com/ruby/nkf + +#### syslog +* https://github.com/ruby/syslog + +#### csv +* https://github.com/ruby/csv + +## Platform Maintainers +### mswin64 (Microsoft Windows) +* NAKAMURA Usaku (usa) + +### mingw32 (Minimalist GNU for Windows) +* Nobuyoshi Nakada (nobu) + +### AIX +* Yutaka Kanemoto (kanemoto) + +### FreeBSD +* Akinori MUSHA (knu) + +### Solaris +* Naohisa Goto (ngoto) + +### RHEL, CentOS +* KOSAKI Motohiro (kosaki) + +### macOS +* Kenta Murata (mrkn) + +### OpenBSD +* Jeremy Evans (jeremyevans0) + +### cygwin, ... +* none. (Maintainer WANTED) + +### WebAssembly/WASI +* Yuta Saito (katei) diff --git a/doc/maintainers.rdoc b/doc/maintainers.rdoc deleted file mode 100644 index b56a3d887f..0000000000 --- a/doc/maintainers.rdoc +++ /dev/null @@ -1,414 +0,0 @@ -= Maintainers - -This page describes the current module, library, and extension maintainers of Ruby. - -== Module Maintainers - -A module maintainer is responsible for a certain part of Ruby. - -* The maintainer fixes bugs of the part. Particularly, they should fix security vulnerabilities as soon as possible. -* They handle issues related the module on the Redmine or ML. -* They may be discharged by the 3 months rule [ruby-core:25764]. -* They have commit right to Ruby's repository to modify their part in the repository. -* They have "developer" role on the Redmine to modify issues. -* They have authority to decide the feature of their part. But they should always respect discussions on ruby-core/ruby-dev. - -A submaintainer of a module is like a maintainer. But the submaintainer does -not have authority to change/add a feature on his/her part. They need consensus -on ruby-core/ruby-dev before changing/adding. Some of submaintainers have -commit right, others don't. - -=== Language core features including security - -Yukihiro Matsumoto (matz) - -=== Evaluator - -Koichi Sasada (ko1) - -=== Core classes - -Yukihiro Matsumoto (matz) - -== Standard Library Maintainers - -=== Libraries - -[lib/mkmf.rb] - _unmaintained_ -[lib/rubygems.rb, lib/rubygems/*] - Eric Hodel (drbrain), Hiroshi SHIBATA (hsbt) - https://github.com/rubygems/rubygems -[lib/unicode_normalize.rb, lib/unicode_normalize/*] - Martin J. Dürst - -=== Extensions - -[ext/continuation] - Koichi Sasada (ko1) -[ext/coverage] - Yusuke Endoh (mame) -[ext/fiber] - Koichi Sasada (ko1) -[ext/monitor] - Koichi Sasada (ko1) -[ext/objspace] - _unmaintained_ -[ext/pty] - _unmaintained_ -[ext/ripper] - _unmaintained_ -[ext/socket] - * Tanaka Akira (akr) - * API change needs matz's approval -[ext/win32] - NAKAMURA Usaku (usa) - -== Default gems Maintainers - -=== Libraries - -[lib/abbrev.rb] - Akinori MUSHA (knu) - https://github.com/ruby/abbrev - https://rubygems.org/gems/abbrev -[lib/base64.rb] - Yusuke Endoh (mame) - https://github.com/ruby/base64 - https://rubygems.org/gems/base64 -[lib/benchmark.rb] - _unmaintained_ - https://github.com/ruby/benchmark - https://rubygems.org/gems/benchmark -[lib/bundler.rb, lib/bundler/*] - Hiroshi SHIBATA (hsbt) - https://github.com/rubygems/rubygems - https://rubygems.org/gems/bundler -[lib/cgi.rb, lib/cgi/*] - _unmaintained_ - https://github.com/ruby/cgi - https://rubygems.org/gems/cgi -[lib/csv.rb] - Kenta Murata (mrkn), Kouhei Sutou (kou) - https://github.com/ruby/csv - https://rubygems.org/gems/csv -[lib/English.rb] - _unmaintained_ - https://github.com/ruby/English - https://rubygems.org/gems/English -[lib/debug.rb] - _unmaintained_ - https://github.com/ruby/debug -[lib/delegate.rb] - _unmaintained_ - https://github.com/ruby/delegate - https://rubygems.org/gems/delegate -[lib/did_you_mean.rb] - Yuki Nishijima (yuki24) - https://github.com/ruby/did_you_mean - https://rubygems.org/gems/did_you_mean -[ext/digest, ext/digest/*] - Akinori MUSHA (knu) - https://github.com/ruby/digest - https://rubygems.org/gems/digest -[lib/drb.rb, lib/drb/*] - Masatoshi SEKI (seki) - https://github.com/ruby/drb - https://rubygems.org/gems/drb -[lib/erb.rb] - Masatoshi SEKI (seki), Takashi Kokubun (k0kubun) - https://github.com/ruby/erb - https://rubygems.org/gems/erb -[lib/fileutils.rb] - _unmaintained_ - https://github.com/ruby/fileutils - https://rubygems.org/gems/fileutils -[lib/find.rb] - Kazuki Tsujimoto (ktsj) - https://github.com/ruby/find - https://rubygems.org/gems/find -[lib/forwardable.rb] - Keiju ISHITSUKA (keiju) - https://github.com/ruby/forwardable - https://rubygems.org/gems/forwardable -[lib/getoptlong.rb] - _unmaintained_ - https://github.com/ruby/getoptlong - https://rubygems.org/gems/getoptlong -[lib/ipaddr.rb] - Akinori MUSHA (knu) - https://github.com/ruby/ipaddr - https://rubygems.org/gems/ipaddr -[lib/irb.rb, lib/irb/*] - aycabta - https://github.com/ruby/irb - https://rubygems.org/gems/irb -[lib/optparse.rb, lib/optparse/*] - Nobuyuki Nakada (nobu) - https://github.com/ruby/optparse -[lib/logger.rb] - Naotoshi Seo (sonots) - https://github.com/ruby/logger - https://rubygems.org/gems/logger -[lib/mutex_m.rb] - Keiju ISHITSUKA (keiju) - https://github.com/ruby/mutex_m - https://rubygems.org/gems/mutex_m -[lib/net/http.rb, lib/net/https.rb] - NARUSE, Yui (naruse) - https://github.com/ruby/net-http - https://rubygems.org/gems/net-http -[lib/net/protocol.rb] - _unmaintained_ - https://github.com/ruby/net-protocol - https://rubygems.org/gems/net-protocol -[lib/observer.rb] - _unmaintained_ - https://github.com/ruby/observer - https://rubygems.org/gems/observer -[lib/open3.rb] - _unmaintained_ - https://github.com/ruby/open3 - https://rubygems.org/gems/open3 -[lib/open-uri.rb] - Tanaka Akira (akr) - https://github.com/ruby/open-uri -[lib/ostruct.rb] - Marc-André Lafortune (marcandre) - https://github.com/ruby/ostruct - https://rubygems.org/gems/ostruct -[lib/pp.rb] - Tanaka Akira (akr) - https://github.com/ruby/pp - https://rubygems.org/gems/pp -[lib/prettyprint.rb] - Tanaka Akira (akr) - https://github.com/ruby/prettyprint - https://rubygems.org/gems/prettyprint -[lib/pstore.rb] - _unmaintained_ - https://github.com/ruby/pstore - https://rubygems.org/gems/pstore -[lib/racc.rb, lib/racc/*] - Aaron Patterson (tenderlove), Hiroshi SHIBATA (hsbt) - https://github.com/ruby/racc - https://rubygems.org/gems/racc -[lib/readline.rb] - aycabta - https://github.com/ruby/readline - https://rubygems.org/gems/readline -[lib/resolv.rb] - Tanaka Akira (akr) - https://github.com/ruby/resolv - https://rubygems.org/gems/resolv -[lib/resolv-replace.rb] - Tanaka Akira (akr) - https://github.com/ruby/resolv-replace - https://rubygems.org/gems/resolv-replace -[lib/rdoc.rb, lib/rdoc/*] - Eric Hodel (drbrain), Hiroshi SHIBATA (hsbt) - https://github.com/ruby/rdoc - https://rubygems.org/gems/rdoc -[lib/reline.rb, lib/reline/*] - aycabta - https://github.com/ruby/reline - https://rubygems.org/gems/reline -[lib/rinda/*] - Masatoshi SEKI (seki) - https://github.com/ruby/rinda - https://rubygems.org/gems/rinda -[lib/securerandom.rb] - Tanaka Akira (akr) - https://github.com/ruby/securerandom - https://rubygems.org/gems/securerandom -[lib/set.rb] - Akinori MUSHA (knu) - https://github.com/ruby/set - https://rubygems.org/gems/set -[lib/shellwords.rb] - Akinori MUSHA (knu) - https://github.com/ruby/shellwords - https://rubygems.org/gems/shellwords -[lib/singleton.rb] - Yukihiro Matsumoto (matz) - https://github.com/ruby/singleton - https://rubygems.org/gems/singleton -[lib/tempfile.rb] - _unmaintained_ - https://github.com/ruby/tempfile - https://rubygems.org/gems/tempfile -[lib/time.rb] - Tanaka Akira (akr) - https://github.com/ruby/time - https://rubygems.org/gems/time -[lib/timeout.rb] - Yukihiro Matsumoto (matz) - https://github.com/ruby/timeout - https://rubygems.org/gems/timeout -[lib/thwait.rb] - Keiju ISHITSUKA (keiju) - https://github.com/ruby/thwait - https://rubygems.org/gems/thwait -[lib/tmpdir.rb] - _unmaintained_ - https://github.com/ruby/tmpdir - https://rubygems.org/gems/tmpdir -[lib/tsort.rb] - Tanaka Akira (akr) - https://github.com/ruby/tsort - https://rubygems.org/gems/tsort -[lib/un.rb] - WATANABE Hirofumi (eban) - https://github.com/ruby/un - https://rubygems.org/gems/un -[lib/uri.rb, lib/uri/*] - YAMADA, Akira (akira) - https://github.com/ruby/uri - https://rubygems.org/gems/uri -[lib/yaml.rb, lib/yaml/*] - Aaron Patterson (tenderlove), Hiroshi SHIBATA (hsbt) - https://github.com/ruby/yaml - https://rubygems.org/gems/yaml -[lib/weakref.rb] - _unmaintained_ - https://github.com/ruby/weakref - https://rubygems.org/gems/weakref - -=== Extensions - -[ext/bigdecimal] - Kenta Murata (mrkn) - https://github.com/ruby/bigdecimal - https://rubygems.org/gems/bigdecimal -[ext/cgi] - Nobuyoshi Nakada (nobu) - https://github.com/ruby/cgi - https://rubygems.org/gems/cgi -[ext/date] - _unmaintained_ - https://github.com/ruby/date - https://rubygems.org/gems/date -[ext/etc] - Ruby core team - https://github.com/ruby/etc - https://rubygems.org/gems/etc -[ext/fcntl] - Ruby core team - https://github.com/ruby/fcntl - https://rubygems.org/gems/fcntl -[ext/fiddle] - Aaron Patterson (tenderlove) - https://github.com/ruby/fiddle - https://rubygems.org/gems/fiddle -[ext/io/console] - Nobuyuki Nakada (nobu) - https://github.com/ruby/io-console - https://rubygems.org/gems/io-console -[ext/io/nonblock] - Nobuyuki Nakada (nobu) - https://github.com/ruby/io-nonblock - https://rubygems.org/gems/io-nonblock -[ext/io/wait] - Nobuyuki Nakada (nobu) - https://github.com/ruby/io-wait - https://rubygems.org/gems/io-wait -[ext/json] - NARUSE, Yui (naruse), Hiroshi SHIBATA (hsbt) - https://github.com/flori/json - https://rubygems.org/gems/json -[ext/nkf] - NARUSE, Yui (naruse) - https://github.com/ruby/nkf - https://rubygems.org/gems/nkf -[ext/openssl] - Kazuki Yamaguchi (rhe) - https://github.com/ruby/openssl - https://rubygems.org/gems/openssl -[ext/pathname] - Tanaka Akira (akr) - https://github.com/ruby/pathname - https://rubygems.org/gems/pathname -[ext/psych] - Aaron Patterson (tenderlove), Hiroshi SHIBATA (hsbt) - https://github.com/ruby/psych - https://rubygems.org/gems/psych -[ext/racc] - Aaron Patterson (tenderlove), Hiroshi SHIBATA (hsbt) - https://github.com/ruby/racc - https://rubygems.org/gems/racc -[ext/readline] - TAKAO Kouji (kouji) - https://github.com/ruby/readline-ext - https://rubygems.org/gems/readline-ext -[ext/stringio] - Nobuyuki Nakada (nobu) - https://github.com/ruby/stringio - https://rubygems.org/gems/stringio -[ext/strscan] - Kouhei Sutou (kou) - https://github.com/ruby/strscan - https://rubygems.org/gems/strscan -[ext/syslog] - Akinori MUSHA (knu) - https://github.com/ruby/syslog - https://rubygems.org/gems/syslog -[ext/win32ole] - Masaki Suketa (suke) - https://github.com/ruby/win32ole - https://rubygems.org/gems/win32ole -[ext/zlib] - NARUSE, Yui (naruse) - https://github.com/ruby/zlib - https://rubygems.org/gems/zlib - -== Bundled gems upstream repositories - -[minitest] - https://github.com/seattlerb/minitest -[power_assert] - https://github.com/ruby/power_assert -[rake] - https://github.com/ruby/rake -[test-unit] - https://github.com/test-unit/test-unit -[rexml] - https://github.com/ruby/rexml -[rss] - https://github.com/ruby/rss -[net-ftp] - https://github.com/ruby/net-ftp -[net-imap] - https://github.com/ruby/net-imap -[net-pop] - https://github.com/ruby/net-pop -[net-smtp] - https://github.com/ruby/net-smtp -[matrix] - https://github.com/ruby/matrix -[prime] - https://github.com/ruby/prime -[rbs] - https://github.com/ruby/rbs -[typeprof] - https://github.com/ruby/typeprof - -=== Platform Maintainers - -[mswin64 (Microsoft Windows)] - NAKAMURA Usaku (usa) -[mingw32 (Minimalist GNU for Windows)] - Nobuyoshi Nakada (nobu) -[AIX] - Yutaka Kanemoto (kanemoto) -[FreeBSD] - Akinori MUSHA (knu) -[Solaris] - Naohisa Goto (ngoto) -[RHEL, CentOS] - KOSAKI Motohiro (kosaki) -[macOS] - Kenta Murata (mrkn) -[OpenBSD] - Jeremy Evans (jeremyevans0) -[cygwin, ...] - none. (Maintainer WANTED) diff --git a/doc/make_cheatsheet.md b/doc/make_cheatsheet.md deleted file mode 100644 index 6b056a4f0b..0000000000 --- a/doc/make_cheatsheet.md +++ /dev/null @@ -1,124 +0,0 @@ -# How to use "configure" and "make" commands for Ruby - -This is for developers of Ruby. -If you are a user of Ruby, please see README.md. - -## In-place build - -``` -$ ./autogen.sh -$ ./configure --prefix=$PWD/local -$ make -$ make install -$ ./local/bin/ruby -e 'puts "Hello"' -Hello -``` - -## Out-of-place build - -``` -$ ./autogen.sh -$ mkdir ../ruby-build -$ cd ../ruby-build -$ ../ruby-src/configure --prefix=$PWD/local -$ make -$ make install -$ ./local/bin/ruby -e 'puts "Hello"' -Hello -``` - -## How to run the whole test suite - -``` -$ make check -``` - -It runs (about) three test suites: - -* `make test` (a test suite for the interpreter core) -* `make test-all` (for all builtin classes and libraries) -* `make test-spec` (a conformance test suite for Ruby implementations) -* `make test-bundler` (a test suite for the bundler examples) - -## How to run the test suite with log - -``` -$ make test OPTS=-v - -$ make test-all TESTS=-v - -$ make test-spec MSPECOPT=-Vfs -``` - -## How to run a part of the test suite - -### Runs a directory -``` -$ make test-all TESTS=test/rubygems -$ make test-all TESTS=rubygems -``` - -### Runs a file -``` -$ make test-all TESTS=test/ruby/test_foo.rb -$ make test-all TESTS=ruby/foo -``` - -### Runs a test whose name includes test_bar -``` -$ make test-all TESTS="test/ruby/test_foo.rb -n /test_bar/" -``` - -### Runs a file or directory with GNU make -``` -$ make test/ruby/test_foo.rb -$ make test/ruby/test_foo.rb TESTOPTS="-n /test_bar/" -``` - -### Runs a ruby-spec directory -``` -$ make test-spec MSPECOPT=spec/ruby/core/foo -``` - -### Runs a ruby-spec file -``` -$ make test-spec MSPECOPT=spec/ruby/core/foo/bar_spec.rb -``` - -### Runs a ruby-spec file or directory with GNU make -``` -$ make spec/ruby/core/foo/bar_spec.rb -``` - -### Runs a bundler spec file -``` -$ make test-bundler BUNDLER_SPECS=commands/exec_spec.rb:58 -``` - -## How to measure coverage of C and Ruby code - -You need to be able to use gcc (gcov) and lcov visualizer. - -``` -$ ./autogen.sh -$ ./configure --enable-gcov -$ make -$ make update-coverage -$ rm -f test-coverage.dat -$ make test-all COVERAGE=true -$ make lcov -$ open lcov-out/index.html -``` - -If you need only C code coverage, you can remove `COVERAGE=true` from the above process. -You can also use `gcov` command directly to get per-file coverage. - -If you need only Ruby code coverage, you can remove `--enable-gcov`. -Note that `test-coverage.dat` accumulates all runs of `make test-all`. -Make sure that you remove the file if you want to measure one test run. - -You can see the coverage result of CI: https://rubyci.org/coverage - -## How to benchmark - -see https://github.com/ruby/ruby/tree/master/benchmark#make-benchmark diff --git a/doc/matchdata/begin.rdoc b/doc/matchdata/begin.rdoc new file mode 100644 index 0000000000..8046dd9d55 --- /dev/null +++ b/doc/matchdata/begin.rdoc @@ -0,0 +1,30 @@ +Returns the offset (in characters) of the beginning of the specified match. + +When non-negative integer argument +n+ is given, +returns the offset of the beginning of the <tt>n</tt>th match: + + m = /(.)(.)(\d+)(\d)/.match("THX1138.") + # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8"> + m[0] # => "HX1138" + m.begin(0) # => 1 + m[3] # => "113" + m.begin(3) # => 3 + + m = /(т)(е)(с)/.match('тест') + # => #<MatchData "тес" 1:"т" 2:"е" 3:"с"> + m[0] # => "тес" + m.begin(0) # => 0 + m[3] # => "с" + m.begin(3) # => 2 + +When string or symbol argument +name+ is given, +returns the offset of the beginning for the named match: + + m = /(?<foo>.)(.)(?<bar>.)/.match("hoge") + # => #<MatchData "hog" foo:"h" bar:"g"> + m[:foo] # => "h" + m.begin('foo') # => 0 + m[:bar] # => "g" + m.begin(:bar) # => 2 + +Related: MatchData#end, MatchData#offset, MatchData#byteoffset. diff --git a/doc/matchdata/end.rdoc b/doc/matchdata/end.rdoc new file mode 100644 index 0000000000..0209b2d2fc --- /dev/null +++ b/doc/matchdata/end.rdoc @@ -0,0 +1,30 @@ +Returns the offset (in characters) of the end of the specified match. + +When non-negative integer argument +n+ is given, +returns the offset of the end of the <tt>n</tt>th match: + + m = /(.)(.)(\d+)(\d)/.match("THX1138.") + # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8"> + m[0] # => "HX1138" + m.end(0) # => 7 + m[3] # => "113" + m.end(3) # => 6 + + m = /(т)(е)(с)/.match('тест') + # => #<MatchData "тес" 1:"т" 2:"е" 3:"с"> + m[0] # => "тес" + m.end(0) # => 3 + m[3] # => "с" + m.end(3) # => 3 + +When string or symbol argument +name+ is given, +returns the offset of the end for the named match: + + m = /(?<foo>.)(.)(?<bar>.)/.match("hoge") + # => #<MatchData "hog" foo:"h" bar:"g"> + m[:foo] # => "h" + m.end('foo') # => 1 + m[:bar] # => "g" + m.end(:bar) # => 3 + +Related: MatchData#begin, MatchData#offset, MatchData#byteoffset. diff --git a/doc/matchdata/offset.rdoc b/doc/matchdata/offset.rdoc new file mode 100644 index 0000000000..0985316d76 --- /dev/null +++ b/doc/matchdata/offset.rdoc @@ -0,0 +1,31 @@ +Returns a 2-element array containing the beginning and ending +offsets (in characters) of the specified match. + +When non-negative integer argument +n+ is given, +returns the starting and ending offsets of the <tt>n</tt>th match: + + m = /(.)(.)(\d+)(\d)/.match("THX1138.") + # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8"> + m[0] # => "HX1138" + m.offset(0) # => [1, 7] + m[3] # => "113" + m.offset(3) # => [3, 6] + + m = /(т)(е)(с)/.match('тест') + # => #<MatchData "тес" 1:"т" 2:"е" 3:"с"> + m[0] # => "тес" + m.offset(0) # => [0, 3] + m[3] # => "с" + m.offset(3) # => [2, 3] + +When string or symbol argument +name+ is given, +returns the starting and ending offsets for the named match: + + m = /(?<foo>.)(.)(?<bar>.)/.match("hoge") + # => #<MatchData "hog" foo:"h" bar:"g"> + m[:foo] # => "h" + m.offset('foo') # => [0, 1] + m[:bar] # => "g" + m.offset(:bar) # => [2, 3] + +Related: MatchData#byteoffset, MatchData#begin, MatchData#end. diff --git a/doc/math/math.rdoc b/doc/math/math.rdoc new file mode 100644 index 0000000000..7a89df951c --- /dev/null +++ b/doc/math/math.rdoc @@ -0,0 +1,117 @@ +\Module \Math provides methods for basic trigonometric, +logarithmic, and transcendental functions, and for extracting roots. + +You can write its constants and method calls thus: + + Math::PI # => 3.141592653589793 + Math::E # => 2.718281828459045 + Math.sin(0.0) # => 0.0 + Math.cos(0.0) # => 1.0 + +If you include module \Math, you can write simpler forms: + + include Math + PI # => 3.141592653589793 + E # => 2.718281828459045 + sin(0.0) # => 0.0 + cos(0.0) # => 1.0 + +For simplicity, the examples here assume: + + include Math + INFINITY = Float::INFINITY + +The domains and ranges for the methods +are denoted by open or closed intervals, +using, respectively, parentheses or square brackets: + +- An open interval does not include the endpoints: + + (-INFINITY, INFINITY) + +- A closed interval includes the endpoints: + + [-1.0, 1.0] + +- A half-open interval includes one endpoint, but not the other: + + [1.0, INFINITY) + +Many values returned by \Math methods are numerical approximations. +This is because many such values are, in mathematics, +of infinite precision, while in numerical computation +the precision is finite. + +Thus, in mathematics, <i>cos(π/2)</i> is exactly zero, +but in our computation <tt>cos(PI/2)</tt> is a number very close to zero: + + cos(PI/2) # => 6.123031769111886e-17 + +For very large and very small returned values, +we have added formatted numbers for clarity: + + tan(PI/2) # => 1.633123935319537e+16 # 16331239353195370.0 + tan(PI) # => -1.2246467991473532e-16 # -0.0000000000000001 + +See class Float for the constants +that affect Ruby's floating-point arithmetic. + +=== What's Here + +==== Trigonometric Functions + +- ::cos: Returns the cosine of the given argument. +- ::sin: Returns the sine of the given argument. +- ::tan: Returns the tangent of the given argument. + +==== Inverse Trigonometric Functions + +- ::acos: Returns the arc cosine of the given argument. +- ::asin: Returns the arc sine of the given argument. +- ::atan: Returns the arc tangent of the given argument. +- ::atan2: Returns the arg tangent of two given arguments. + +==== Hyperbolic Trigonometric Functions + +- ::cosh: Returns the hyperbolic cosine of the given argument. +- ::sinh: Returns the hyperbolic sine of the given argument. +- ::tanh: Returns the hyperbolic tangent of the given argument. + +==== Inverse Hyperbolic Trigonometric Functions + +- ::acosh: Returns the inverse hyperbolic cosine of the given argument. +- ::asinh: Returns the inverse hyperbolic sine of the given argument. +- ::atanh: Returns the inverse hyperbolic tangent of the given argument. + +==== Exponentiation and Logarithmic Functions + +- ::exp: Returns the value of a given value raised to a given power. +- ::log: Returns the logarithm of a given value in a given base. +- ::log10: Returns the base 10 logarithm of the given argument. +- ::log2: Returns the base 2 logarithm of the given argument. + +==== Fraction and Exponent Functions + +- ::frexp: Returns the fraction and exponent of the given argument. +- ::ldexp: Returns the value for a given fraction and exponent. + +==== Root Functions + +- ::cbrt: Returns the cube root of the given argument. +- ::sqrt: Returns the square root of the given argument. + +==== Error Functions + +- ::erf: Returns the value of the Gauss error function for the given argument. +- ::erfc: Returns the value of the complementary error function + for the given argument. + +==== Gamma Functions + +- ::gamma: Returns the value of the gamma function for the given argument. +- ::lgamma: Returns the value of the logarithmic gamma function + for the given argument. + +==== Hypotenuse Function + +- ::hypot: Returns <tt>sqrt(a**2 + b**2)</tt> for the given +a+ and +b+. diff --git a/doc/memory_view.md b/doc/memory_view.md index a24700d0b1..0b1369163d 100644 --- a/doc/memory_view.md +++ b/doc/memory_view.md @@ -48,7 +48,7 @@ The MemoryView structure consists of the following members. - `ssize_t byte_size` - The numbero f bytes in the memory pointed by `data`. + The number of bytes in the memory pointed by `data`. - `bool readonly` @@ -56,7 +56,7 @@ The MemoryView structure consists of the following members. - `const char *format` - A string to describeth e format of an element, or NULL for unsigned byte. + A string to describe the format of an element, or NULL for unsigned byte. - `ssize_t item_size` diff --git a/doc/net-http/examples.rdoc b/doc/net-http/examples.rdoc new file mode 100644 index 0000000000..c1366e7ad1 --- /dev/null +++ b/doc/net-http/examples.rdoc @@ -0,0 +1,31 @@ +Examples here assume that <tt>net/http</tt> has been required +(which also requires +uri+): + + require 'net/http' + +Many code examples here use these example websites: + +- https://jsonplaceholder.typicode.com. +- http://example.com. + +Some examples also assume these variables: + + uri = URI('https://jsonplaceholder.typicode.com/') + uri.freeze # Examples may not modify. + hostname = uri.hostname # => "jsonplaceholder.typicode.com" + path = uri.path # => "/" + port = uri.port # => 443 + +So that example requests may be written as: + + Net::HTTP.get(uri) + Net::HTTP.get(hostname, '/index.html') + Net::HTTP.start(hostname) do |http| + http.get('/todos/1') + http.get('/todos/2') + end + +An example that needs a modified URI first duplicates +uri+, then modifies the duplicate: + + _uri = uri.dup + _uri.path = '/todos/1' diff --git a/doc/net-http/included_getters.rdoc b/doc/net-http/included_getters.rdoc new file mode 100644 index 0000000000..7ac327f4b4 --- /dev/null +++ b/doc/net-http/included_getters.rdoc @@ -0,0 +1,3 @@ +This class also includes (indirectly) module Net::HTTPHeader, +which gives access to its +{methods for getting headers}[rdoc-ref:Net::HTTPHeader@Getters]. diff --git a/doc/optparse/.document b/doc/optparse/.document new file mode 100644 index 0000000000..96dfc7779f --- /dev/null +++ b/doc/optparse/.document @@ -0,0 +1 @@ +*.rdoc diff --git a/doc/optparse/argument_converters.rdoc b/doc/optparse/argument_converters.rdoc index ac659da8c5..4b4b30e8de 100644 --- a/doc/optparse/argument_converters.rdoc +++ b/doc/optparse/argument_converters.rdoc @@ -1,7 +1,7 @@ == Argument Converters An option can specify that its argument is to be converted -from the default \String to an instance of another class. +from the default +String+ to an instance of another class. === Contents @@ -27,13 +27,13 @@ from the default \String to an instance of another class. === Built-In Argument Converters -\OptionParser has a number of built-in argument converters, ++OptionParser+ has a number of built-in argument converters, which are demonstrated below. -==== \Date +==== +Date+ File +date.rb+ -defines an option whose argument is to be converted to a \Date object. +defines an option whose argument is to be converted to a +Date+ object. The argument is converted by method Date#parse. :include: ruby/date.rb @@ -47,10 +47,10 @@ Executions: $ ruby date.rb --date "3rd Feb 2001" [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date] -==== \DateTime +==== +DateTime+ File +datetime.rb+ -defines an option whose argument is to be converted to a \DateTime object. +defines an option whose argument is to be converted to a +DateTime+ object. The argument is converted by method DateTime#parse. :include: ruby/datetime.rb @@ -64,10 +64,10 @@ Executions: $ ruby datetime.rb --datetime "3rd Feb 2001 04:05:06 PM" [#<DateTime: 2001-02-03T16:05:06+00:00 ((2451944j,57906s,0n),+0s,2299161j)>, DateTime] -==== \Time +==== +Time+ File +time.rb+ -defines an option whose argument is to be converted to a \Time object. +defines an option whose argument is to be converted to a +Time+ object. The argument is converted by method Time#httpdate or Time#parse. :include: ruby/time.rb @@ -79,10 +79,10 @@ Executions: $ ruby time.rb --time 2010-10-31 [2010-10-31 00:00:00 -0500, Time] -==== \URI +==== +URI+ File +uri.rb+ -defines an option whose argument is to be converted to a \URI object. +defines an option whose argument is to be converted to a +URI+ object. The argument is converted by method URI#parse. :include: ruby/uri.rb @@ -96,10 +96,10 @@ Executions: $ ruby uri.rb --uri file://~/var [#<URI::File file://~/var>, URI::File] -==== \Shellwords +==== +Shellwords+ File +shellwords.rb+ -defines an option whose argument is to be converted to an \Array object by method +defines an option whose argument is to be converted to an +Array+ object by method Shellwords#shellwords. :include: ruby/shellwords.rb @@ -111,10 +111,10 @@ Executions: $ ruby shellwords.rb --shellwords "here are 'two words'" [["here", "are", "two words"], Array] -==== \Integer +==== +Integer+ File +integer.rb+ -defines an option whose argument is to be converted to an \Integer object. +defines an option whose argument is to be converted to an +Integer+ object. The argument is converted by method Kernel#Integer. :include: ruby/integer.rb @@ -132,10 +132,10 @@ Executions: $ ruby integer.rb --integer 0b100 [4, Integer] -==== \Float +==== +Float+ File +float.rb+ -defines an option whose argument is to be converted to a \Float object. +defines an option whose argument is to be converted to a +Float+ object. The argument is converted by method Kernel#Float. :include: ruby/float.rb @@ -151,11 +151,11 @@ Executions: $ ruby float.rb --float 1.234E-2 [0.01234, Float] -==== \Numeric +==== +Numeric+ File +numeric.rb+ defines an option whose argument is to be converted to an instance -of \Rational, \Float, or \Integer. +of +Rational+, +Float+, or +Integer+. The argument is converted by method Kernel#Rational, Kernel#Float, or Kernel#Integer. @@ -170,10 +170,10 @@ Executions: $ ruby numeric.rb --numeric 3 [3, Integer] -==== \DecimalInteger +==== +DecimalInteger+ File +decimal_integer.rb+ -defines an option whose argument is to be converted to an \Integer object. +defines an option whose argument is to be converted to an +Integer+ object. The argument is converted by method Kernel#Integer. :include: ruby/decimal_integer.rb @@ -192,10 +192,10 @@ Executions: $ ruby decimal_integer.rb --decimal_integer -0100 [-100, Integer] -==== \OctalInteger +==== +OctalInteger+ File +octal_integer.rb+ -defines an option whose argument is to be converted to an \Integer object. +defines an option whose argument is to be converted to an +Integer+ object. The argument is converted by method Kernel#Integer. :include: ruby/octal_integer.rb @@ -212,10 +212,10 @@ Executions: $ ruby octal_integer.rb --octal_integer 0100 [64, Integer] -==== \DecimalNumeric +==== +DecimalNumeric+ File +decimal_numeric.rb+ -defines an option whose argument is to be converted to an \Integer object. +defines an option whose argument is to be converted to an +Integer+ object. The argument is converted by method Kernel#Integer :include: ruby/decimal_numeric.rb @@ -232,7 +232,7 @@ Executions: $ ruby decimal_numeric.rb --decimal_numeric 0100 [64, Integer] -==== \TrueClass +==== +TrueClass+ File +true_class.rb+ defines an option whose argument is to be converted to +true+ or +false+. @@ -259,7 +259,7 @@ Executions: $ ruby true_class.rb --true_class nil [false, FalseClass] -==== \FalseClass +==== +FalseClass+ File +false_class.rb+ defines an option whose argument is to be converted to +true+ or +false+. @@ -286,10 +286,10 @@ Executions: $ ruby false_class.rb --false_class + [true, TrueClass] -==== \Object +==== +Object+ File +object.rb+ -defines an option whose argument is not to be converted from \String. +defines an option whose argument is not to be converted from +String+. :include: ruby/object.rb @@ -300,10 +300,10 @@ Executions: $ ruby object.rb --object nil ["nil", String] -==== \String +==== +String+ File +string.rb+ -defines an option whose argument is not to be converted from \String. +defines an option whose argument is not to be converted from +String+. :include: ruby/string.rb @@ -314,10 +314,10 @@ Executions: $ ruby string.rb --string nil ["nil", String] -==== \Array +==== +Array+ File +array.rb+ -defines an option whose argument is to be converted from \String +defines an option whose argument is to be converted from +String+ to an array of strings, based on comma-separated substrings. :include: ruby/array.rb @@ -331,10 +331,10 @@ Executions: $ ruby array.rb --array "foo, bar, baz" [["foo", " bar", " baz"], Array] -==== \Regexp +==== +Regexp+ File +regexp.rb+ -defines an option whose argument is to be converted to a \Regexp object. +defines an option whose argument is to be converted to a +Regexp+ object. :include: ruby/regexp.rb @@ -352,7 +352,7 @@ To create a custom converter, call OptionParser#accept with: - A block that accepts the argument and returns the converted value. This custom converter accepts any argument and converts it, -if possible, to a \Complex object. +if possible, to a +Complex+ object. :include: ruby/custom_converter.rb diff --git a/doc/optparse/creates_option.rdoc b/doc/optparse/creates_option.rdoc index 131c877971..ab672d5124 100644 --- a/doc/optparse/creates_option.rdoc +++ b/doc/optparse/creates_option.rdoc @@ -1,7 +1,7 @@ Creates an option from the given parameters +params+. -See {Parameters for New Options}[./doc/optparse/option_params_rdoc.html]. +See {Parameters for New Options}[optparse/option_params.rdoc]. The block, if given, is the handler for the created option. When the option is encountered during command-line parsing, the block is called with the argument given for the option, if any. -See {Option Handlers}[./option_params_rdoc.html#label-Option+Handlers]. +See {Option Handlers}[optparse/option_params.rdoc#label-Option+Handlers]. diff --git a/doc/optparse/option_params.rdoc b/doc/optparse/option_params.rdoc index 3e6cb1be41..35db8b5a55 100644 --- a/doc/optparse/option_params.rdoc +++ b/doc/optparse/option_params.rdoc @@ -1,6 +1,6 @@ == Parameters for New Options -Option-creating methods in \OptionParser +Option-creating methods in +OptionParser+ accept arguments that determine the behavior of a new option: - OptionParser#on @@ -31,7 +31,7 @@ Contents: - {Long Names with Optional Arguments}[#label-Long+Names+with+Optional+Arguments] - {Long Names with Negation}[#label-Long+Names+with+Negation] - {Mixed Names}[#label-Mixed+Names] -- {Argument Styles}[#label-Argument+Styles] +- {Argument Strings}[#label-Argument+Strings] - {Argument Values}[#label-Argument+Values] - {Explicit Argument Values}[#label-Explicit+Argument+Values] - {Explicit Values in Array}[#label-Explicit+Values+in+Array] @@ -405,12 +405,12 @@ Executions: === Argument Converters An option can specify that its argument is to be converted -from the default \String to an instance of another class. +from the default +String+ to an instance of another class. There are a number of built-in converters. You can also define custom converters. -See {Argument Converters}[./argument_converters_rdoc.html]. +See {Argument Converters}[./argument_converters.rdoc]. === Descriptions @@ -418,7 +418,7 @@ A description parameter is any string parameter that is not recognized as an {option name}[#label-Option+Names] or a {terminator}[#label-Terminators]; -in other words, it does not begin with a hypnen. +in other words, it does not begin with a hyphen. You may give any number of description parameters; each becomes a line in the text generated by option <tt>--help</tt>. @@ -453,7 +453,7 @@ when the option is encountered. The handler may be: ==== Handler Blocks -An option hadler may be a block. +An option handler may be a block. File +block.rb+ defines an option that has a handler block. diff --git a/doc/optparse/ruby/argument_abbreviation.rb b/doc/optparse/ruby/argument_abbreviation.rb new file mode 100644 index 0000000000..49007ebe69 --- /dev/null +++ b/doc/optparse/ruby/argument_abbreviation.rb @@ -0,0 +1,9 @@ +require 'optparse' +parser = OptionParser.new +parser.on('-x', '--xxx=VALUE', %w[ABC def], 'Argument abbreviations') do |value| + p ['--xxx', value] +end +parser.on('-y', '--yyy=VALUE', {"abc"=>"XYZ", def: "FOO"}, 'Argument abbreviations') do |value| + p ['--yyy', value] +end +parser.parse! diff --git a/doc/optparse/tutorial.rdoc b/doc/optparse/tutorial.rdoc index 1d7c52b19e..6f56bbf92d 100644 --- a/doc/optparse/tutorial.rdoc +++ b/doc/optparse/tutorial.rdoc @@ -1,10 +1,10 @@ == Tutorial -=== Why \OptionParser? +=== Why +OptionParser+? When a Ruby program executes, it captures its command-line arguments and options into variable ARGV. -This simple program just prints its \ARGV: +This simple program just prints its +ARGV+: :include: ruby/argv.rb @@ -18,7 +18,7 @@ the command-line options. OptionParser offers methods for parsing and handling those options. -With \OptionParser, you can define options so that for each option: +With +OptionParser+, you can define options so that for each option: - The code that defines the option and code that handles that option are in the same place. @@ -55,7 +55,7 @@ The class also has method #help, which displays automatically-generated help tex - {Argument Converters}[#label-Argument+Converters] - {Help}[#label-Help] - {Top List and Base List}[#label-Top+List+and+Base+List] -- {Defining Options}[#label-Defining+Options] +- {Methods for Defining Options}[#label-Methods+for+Defining+Options] - {Parsing}[#label-Parsing] - {Method parse!}[#label-Method+parse-21] - {Method parse}[#label-Method+parse] @@ -66,10 +66,10 @@ The class also has method #help, which displays automatically-generated help tex === To Begin With -To use \OptionParser: +To use +OptionParser+: -1. Require the \OptionParser code. -2. Create an \OptionParser object. +1. Require the +OptionParser+ code. +2. Create an +OptionParser+ object. 3. Define one or more options. 4. Parse the command line. @@ -92,9 +92,9 @@ the block defined for the option is called with the argument value. An invalid option raises an exception. Method #parse!, which is used most often in this tutorial, -removes from \ARGV the options and arguments it finds, +removes from +ARGV+ the options and arguments it finds, leaving other non-option arguments for the program to handle on its own. -The method returns the possibly-reduced \ARGV array. +The method returns the possibly-reduced +ARGV+ array. Executions: @@ -115,7 +115,7 @@ Executions: === Defining Options -A common way to define an option in \OptionParser +A common way to define an option in +OptionParser+ is with instance method OptionParser#on. The method may be called with any number of arguments @@ -351,6 +351,29 @@ Executions: Omitting an optional argument does not raise an error. +==== Argument Abbreviations + +Specify an argument list as an Array or a Hash. + + :include: ruby/argument_abbreviation.rb + +When an argument is abbreviated, the expanded argument yielded. + +Executions: + + $ ruby argument_abbreviation.rb --help + Usage: argument_abbreviation [options] + Usage: argument_abbreviation [options] + -x, --xxx=VALUE Argument abbreviations + -y, --yyy=VALUE Argument abbreviations + $ ruby argument_abbreviation.rb --xxx A + ["--xxx", "ABC"] + $ ruby argument_abbreviation.rb --xxx c + argument_abbreviation.rb:9:in `<main>': invalid argument: --xxx c (OptionParser::InvalidArgument) + $ ruby argument_abbreviation.rb --yyy a --yyy d + ["--yyy", "XYZ"] + ["--yyy", "FOO"] + === Argument Values Permissible argument values may be restricted @@ -522,11 +545,11 @@ Executions: === Argument Converters An option can specify that its argument is to be converted -from the default \String to an instance of another class. +from the default +String+ to an instance of another class. There are a number of built-in converters. Example: File +date.rb+ -defines an option whose argument is to be converted to a \Date object. +defines an option whose argument is to be converted to a +Date+ object. The argument is converted by method Date#parse. :include: ruby/date.rb @@ -541,12 +564,12 @@ Executions: [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date] You can also define custom converters. -See {Argument Converters}[./argument_converters_rdoc.html] +See {Argument Converters}[./argument_converters.rdoc] for both built-in and custom converters. === Help -\OptionParser makes automatically generated help text available. ++OptionParser+ makes automatically generated help text available. The help text consists of: @@ -614,50 +637,50 @@ Execution: === Top List and Base List -An \OptionParser object maintains a stack of \OptionParser::List objects, +An +OptionParser+ object maintains a stack of OptionParser::List objects, each of which has a collection of zero or more options. It is unlikely that you'll need to add or take away from that stack. The stack includes: -- The <em>top list</em>, given by \OptionParser#top. -- The <em>base list</em>, given by \OptionParser#base. +- The <em>top list</em>, given by OptionParser#top. +- The <em>base list</em>, given by OptionParser#base. -When \OptionParser builds its help text, the options in the top list +When +OptionParser+ builds its help text, the options in the top list precede those in the base list. -=== Defining Options +=== Methods for Defining Options Option-defining methods allow you to create an option, and also append/prepend it to the top list or append it to the base list. Each of these next three methods accepts a sequence of parameter arguments and a block, -creates an option object using method \Option#make_switch (see below), +creates an option object using method OptionParser#make_switch (see below), and returns the created option: -- \Method \OptionParser#define appends the created option to the top list. +- \Method OptionParser#define appends the created option to the top list. -- \Method \OptionParser#define_head prepends the created option to the top list. +- \Method OptionParser#define_head prepends the created option to the top list. -- \Method \OptionParser#define_tail appends the created option to the base list. +- \Method OptionParser#define_tail appends the created option to the base list. These next three methods are identical to the three above, except for their return values: -- \Method \OptionParser#on is identical to method \OptionParser#define, +- \Method OptionParser#on is identical to method OptionParser#define, except that it returns the parser object +self+. -- \Method \OptionParser#on_head is identical to method \OptionParser#define_head, +- \Method OptionParser#on_head is identical to method OptionParser#define_head, except that it returns the parser object +self+. -- \Method \OptionParser#on_tail is identical to method \OptionParser#define_tail, +- \Method OptionParser#on_tail is identical to method OptionParser#define_tail, except that it returns the parser object +self+. Though you may never need to call it directly, here's the core method for defining an option: -- \Method \OptionParser#make_switch accepts an array of parameters and a block. - See {Parameters for New Options}[./option_params_rdoc.html]. +- \Method OptionParser#make_switch accepts an array of parameters and a block. + See {Parameters for New Options}[optparse/option_params.rdoc]. This method is unlike others here in that it: - Accepts an <em>array of parameters</em>; others accept a <em>sequence of parameter arguments</em>. @@ -668,7 +691,7 @@ here's the core method for defining an option: === Parsing -\OptionParser has six instance methods for parsing. ++OptionParser+ has six instance methods for parsing. Three have names ending with a "bang" (<tt>!</tt>): @@ -699,9 +722,9 @@ Each of these methods: (see {Keyword Argument into}[#label-Keyword+Argument+into]). - Returns +argv+, possibly with some elements removed. -==== \Method parse! +==== \Method +parse!+ -\Method parse!: +\Method +parse!+: - Accepts an optional array of string arguments +argv+; if not given, +argv+ defaults to the value of OptionParser#default_argv, @@ -756,9 +779,9 @@ Processing ended by non-option found when +POSIXLY_CORRECT+ is defined: ["--xxx", true] Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array) -==== \Method parse +==== \Method +parse+ -\Method parse: +\Method +parse+: - Accepts an array of string arguments _or_ zero or more string arguments. @@ -810,25 +833,25 @@ Processing ended by non-option found when +POSIXLY_CORRECT+ is defined: ["--xxx", true] Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array) -==== \Method order! +==== \Method +order!+ Calling method OptionParser#order! gives exactly the same result as calling method OptionParser#parse! with environment variable +POSIXLY_CORRECT+ defined. -==== \Method order +==== \Method +order+ Calling method OptionParser#order gives exactly the same result as calling method OptionParser#parse with environment variable +POSIXLY_CORRECT+ defined. -==== \Method permute! +==== \Method +permute!+ Calling method OptionParser#permute! gives exactly the same result as calling method OptionParser#parse! with environment variable +POSIXLY_CORRECT+ _not_ defined. -==== \Method permute +==== \Method +permute+ Calling method OptionParser#permute gives exactly the same result as calling method OptionParser#parse with environment variable diff --git a/doc/packed_data.rdoc b/doc/packed_data.rdoc new file mode 100644 index 0000000000..17bbf92023 --- /dev/null +++ b/doc/packed_data.rdoc @@ -0,0 +1,589 @@ += Packed \Data + +Certain Ruby core methods deal with packing and unpacking data: + +- \Method Array#pack: + Formats each element in array +self+ into a binary string; + returns that string. +- \Method String#unpack: + Extracts data from string +self+, + forming objects that become the elements of a new array; + returns that array. +- \Method String#unpack1: + Does the same, but unpacks and returns only the first extracted object. + +Each of these methods accepts a string +template+, +consisting of zero or more _directive_ characters, +each followed by zero or more _modifier_ characters. + +Examples (directive <tt>'C'</tt> specifies 'unsigned character'): + + [65].pack('C') # => "A" # One element, one directive. + [65, 66].pack('CC') # => "AB" # Two elements, two directives. + [65, 66].pack('C') # => "A" # Extra element is ignored. + [65].pack('') # => "" # No directives. + [65].pack('CC') # Extra directive raises ArgumentError. + + 'A'.unpack('C') # => [65] # One character, one directive. + 'AB'.unpack('CC') # => [65, 66] # Two characters, two directives. + 'AB'.unpack('C') # => [65] # Extra character is ignored. + 'A'.unpack('CC') # => [65, nil] # Extra directive generates nil. + 'AB'.unpack('') # => [] # No directives. + +The string +template+ may contain any mixture of valid directives +(directive <tt>'c'</tt> specifies 'signed character'): + + [65, -1].pack('cC') # => "A\xFF" + "A\xFF".unpack('cC') # => [65, 255] + +The string +template+ may contain whitespace (which is ignored) +and comments, each of which begins with character <tt>'#'</tt> +and continues up to and including the next following newline: + + [0,1].pack(" C #foo \n C ") # => "\x00\x01" + "\0\1".unpack(" C #foo \n C ") # => [0, 1] + +Any directive may be followed by either of these modifiers: + +- <tt>'*'</tt> - The directive is to be applied as many times as needed: + + [65, 66].pack('C*') # => "AB" + 'AB'.unpack('C*') # => [65, 66] + +- Integer +count+ - The directive is to be applied +count+ times: + + [65, 66].pack('C2') # => "AB" + [65, 66].pack('C3') # Raises ArgumentError. + 'AB'.unpack('C2') # => [65, 66] + 'AB'.unpack('C3') # => [65, 66, nil] + + Note: Directives in <tt>%w[A a Z m]</tt> use +count+ differently; + see {String Directives}[rdoc-ref:packed_data.rdoc@String+Directives]. + +If elements don't fit the provided directive, only least significant bits are encoded: + + [257].pack("C").unpack("C") # => [1] + +== Packing \Method + +\Method Array#pack accepts optional keyword argument ++buffer+ that specifies the target string (instead of a new string): + + [65, 66].pack('C*', buffer: 'foo') # => "fooAB" + +The method can accept a block: + + # Packed string is passed to the block. + [65, 66].pack('C*') {|s| p s } # => "AB" + +== Unpacking Methods + +Methods String#unpack and String#unpack1 each accept +an optional keyword argument +offset+ that specifies an offset +into the string: + + 'ABC'.unpack('C*', offset: 1) # => [66, 67] + 'ABC'.unpack1('C*', offset: 1) # => 66 + +Both methods can accept a block: + + # Each unpacked object is passed to the block. + ret = [] + "ABCD".unpack("C*") {|c| ret << c } + ret # => [65, 66, 67, 68] + + # The single unpacked object is passed to the block. + 'AB'.unpack1('C*') {|ele| p ele } # => 65 + +== \Integer Directives + +Each integer directive specifies the packing or unpacking +for one element in the input or output array. + +=== 8-Bit \Integer Directives + +- <tt>'c'</tt> - 8-bit signed integer + (like C <tt>signed char</tt>): + + [0, 1, 255].pack('c*') # => "\x00\x01\xFF" + s = [0, 1, -1].pack('c*') # => "\x00\x01\xFF" + s.unpack('c*') # => [0, 1, -1] + +- <tt>'C'</tt> - 8-bit unsigned integer + (like C <tt>unsigned char</tt>): + + [0, 1, 255].pack('C*') # => "\x00\x01\xFF" + s = [0, 1, -1].pack('C*') # => "\x00\x01\xFF" + s.unpack('C*') # => [0, 1, 255] + +=== 16-Bit \Integer Directives + +- <tt>'s'</tt> - 16-bit signed integer, native-endian + (like C <tt>int16_t</tt>): + + [513, -514].pack('s*') # => "\x01\x02\xFE\xFD" + s = [513, 65022].pack('s*') # => "\x01\x02\xFE\xFD" + s.unpack('s*') # => [513, -514] + +- <tt>'S'</tt> - 16-bit unsigned integer, native-endian + (like C <tt>uint16_t</tt>): + + [513, -514].pack('S*') # => "\x01\x02\xFE\xFD" + s = [513, 65022].pack('S*') # => "\x01\x02\xFE\xFD" + s.unpack('S*') # => [513, 65022] + +- <tt>'n'</tt> - 16-bit network integer, big-endian: + + s = [0, 1, -1, 32767, -32768, 65535].pack('n*') + # => "\x00\x00\x00\x01\xFF\xFF\x7F\xFF\x80\x00\xFF\xFF" + s.unpack('n*') + # => [0, 1, 65535, 32767, 32768, 65535] + +- <tt>'v'</tt> - 16-bit VAX integer, little-endian: + + s = [0, 1, -1, 32767, -32768, 65535].pack('v*') + # => "\x00\x00\x01\x00\xFF\xFF\xFF\x7F\x00\x80\xFF\xFF" + s.unpack('v*') + # => [0, 1, 65535, 32767, 32768, 65535] + +=== 32-Bit \Integer Directives + +- <tt>'l'</tt> - 32-bit signed integer, native-endian + (like C <tt>int32_t</tt>): + + s = [67305985, -50462977].pack('l*') + # => "\x01\x02\x03\x04\xFF\xFE\xFD\xFC" + s.unpack('l*') + # => [67305985, -50462977] + +- <tt>'L'</tt> - 32-bit unsigned integer, native-endian + (like C <tt>uint32_t</tt>): + + s = [67305985, 4244504319].pack('L*') + # => "\x01\x02\x03\x04\xFF\xFE\xFD\xFC" + s.unpack('L*') + # => [67305985, 4244504319] + +- <tt>'N'</tt> - 32-bit network integer, big-endian: + + s = [0,1,-1].pack('N*') + # => "\x00\x00\x00\x00\x00\x00\x00\x01\xFF\xFF\xFF\xFF" + s.unpack('N*') + # => [0, 1, 4294967295] + +- <tt>'V'</tt> - 32-bit VAX integer, little-endian: + + s = [0,1,-1].pack('V*') + # => "\x00\x00\x00\x00\x01\x00\x00\x00\xFF\xFF\xFF\xFF" + s.unpack('v*') + # => [0, 0, 1, 0, 65535, 65535] + +=== 64-Bit \Integer Directives + +- <tt>'q'</tt> - 64-bit signed integer, native-endian + (like C <tt>int64_t</tt>): + + s = [578437695752307201, -506097522914230529].pack('q*') + # => "\x01\x02\x03\x04\x05\x06\a\b\xFF\xFE\xFD\xFC\xFB\xFA\xF9\xF8" + s.unpack('q*') + # => [578437695752307201, -506097522914230529] + +- <tt>'Q'</tt> - 64-bit unsigned integer, native-endian + (like C <tt>uint64_t</tt>): + + s = [578437695752307201, 17940646550795321087].pack('Q*') + # => "\x01\x02\x03\x04\x05\x06\a\b\xFF\xFE\xFD\xFC\xFB\xFA\xF9\xF8" + s.unpack('Q*') + # => [578437695752307201, 17940646550795321087] + +=== Platform-Dependent \Integer Directives + +- <tt>'i'</tt> - Platform-dependent width signed integer, + native-endian (like C <tt>int</tt>): + + s = [67305985, -50462977].pack('i*') + # => "\x01\x02\x03\x04\xFF\xFE\xFD\xFC" + s.unpack('i*') + # => [67305985, -50462977] + +- <tt>'I'</tt> - Platform-dependent width unsigned integer, + native-endian (like C <tt>unsigned int</tt>): + + s = [67305985, -50462977].pack('I*') + # => "\x01\x02\x03\x04\xFF\xFE\xFD\xFC" + s.unpack('I*') + # => [67305985, 4244504319] + +- <tt>'j'</tt> - Pointer-width signed integer, native-endian + (like C <tt>intptr_t</tt>): + + s = [67305985, -50462977].pack('j*') + # => "\x01\x02\x03\x04\x00\x00\x00\x00\xFF\xFE\xFD\xFC\xFF\xFF\xFF\xFF" + s.unpack('j*') + # => [67305985, -50462977] + +- <tt>'J'</tt> - Pointer-width unsigned integer, native-endian + (like C <tt>uintptr_t</tt>): + + s = [67305985, 4244504319].pack('J*') + # => "\x01\x02\x03\x04\x00\x00\x00\x00\xFF\xFE\xFD\xFC\x00\x00\x00\x00" + s.unpack('J*') + # => [67305985, 4244504319] + +=== Other \Integer Directives + +- <tt>'U'</tt> - UTF-8 character: + + s = [4194304].pack('U*') + # => "\xF8\x90\x80\x80\x80" + s.unpack('U*') + # => [4194304] + +- <tt>'w'</tt> - BER-encoded integer + (see {BER encoding}[https://en.wikipedia.org/wiki/X.690#BER_encoding]): + + s = [1073741823].pack('w*') + # => "\x83\xFF\xFF\xFF\x7F" + s.unpack('w*') + # => [1073741823] + +=== Modifiers for \Integer Directives + +For the following directives, <tt>'!'</tt> or <tt>'_'</tt> modifiers may be +suffixed as underlying platform’s native size. + +- <tt>'i'</tt>, <tt>'I'</tt> - C <tt>int</tt>, always native size. +- <tt>'s'</tt>, <tt>'S'</tt> - C <tt>short</tt>. +- <tt>'l'</tt>, <tt>'L'</tt> - C <tt>long</tt>. +- <tt>'q'</tt>, <tt>'Q'</tt> - C <tt>long long</tt>, if available. +- <tt>'j'</tt>, <tt>'J'</tt> - C <tt>intptr_t</tt>, always native size. + +Native size modifiers are silently ignored for always native size directives. + +The endian modifiers also may be suffixed in the directives above: + +- <tt>'>'</tt> - Big-endian. +- <tt>'<'</tt> - Little-endian. + +== \Float Directives + +Each float directive specifies the packing or unpacking +for one element in the input or output array. + +=== Single-Precision \Float Directives + +- <tt>'F'</tt> or <tt>'f'</tt> - Native format: + + s = [3.0].pack('F') # => "\x00\x00@@" + s.unpack('F') # => [3.0] + +- <tt>'e'</tt> - Little-endian: + + s = [3.0].pack('e') # => "\x00\x00@@" + s.unpack('e') # => [3.0] + +- <tt>'g'</tt> - Big-endian: + + s = [3.0].pack('g') # => "@@\x00\x00" + s.unpack('g') # => [3.0] + +=== Double-Precision \Float Directives + +- <tt>'D'</tt> or <tt>'d'</tt> - Native format: + + s = [3.0].pack('D') # => "\x00\x00\x00\x00\x00\x00\b@" + s.unpack('D') # => [3.0] + +- <tt>'E'</tt> - Little-endian: + + s = [3.0].pack('E') # => "\x00\x00\x00\x00\x00\x00\b@" + s.unpack('E') # => [3.0] + +- <tt>'G'</tt> - Big-endian: + + s = [3.0].pack('G') # => "@\b\x00\x00\x00\x00\x00\x00" + s.unpack('G') # => [3.0] + +A float directive may be infinity or not-a-number: + + inf = 1.0/0.0 # => Infinity + [inf].pack('f') # => "\x00\x00\x80\x7F" + "\x00\x00\x80\x7F".unpack('f') # => [Infinity] + + nan = inf/inf # => NaN + [nan].pack('f') # => "\x00\x00\xC0\x7F" + "\x00\x00\xC0\x7F".unpack('f') # => [NaN] + +== \String Directives + +Each string directive specifies the packing or unpacking +for one byte in the input or output string. + +=== Binary \String Directives + +- <tt>'A'</tt> - Arbitrary binary string (space padded; count is width); + +nil+ is treated as the empty string: + + ['foo'].pack('A') # => "f" + ['foo'].pack('A*') # => "foo" + ['foo'].pack('A2') # => "fo" + ['foo'].pack('A4') # => "foo " + [nil].pack('A') # => " " + [nil].pack('A*') # => "" + [nil].pack('A2') # => " " + [nil].pack('A4') # => " " + + "foo\0".unpack('A') # => ["f"] + "foo\0".unpack('A4') # => ["foo"] + "foo\0bar".unpack('A10') # => ["foo\x00bar"] # Reads past "\0". + "foo ".unpack('A') # => ["f"] + "foo ".unpack('A4') # => ["foo"] + "foo".unpack('A4') # => ["foo"] + + russian = "\u{442 435 441 442}" # => "тест" + russian.size # => 4 + russian.bytesize # => 8 + [russian].pack('A') # => "\xD1" + [russian].pack('A*') # => "\xD1\x82\xD0\xB5\xD1\x81\xD1\x82" + russian.unpack('A') # => ["\xD1"] + russian.unpack('A2') # => ["\xD1\x82"] + russian.unpack('A4') # => ["\xD1\x82\xD0\xB5"] + russian.unpack('A*') # => ["\xD1\x82\xD0\xB5\xD1\x81\xD1\x82"] + +- <tt>'a'</tt> - Arbitrary binary string (null padded; count is width): + + ["foo"].pack('a') # => "f" + ["foo"].pack('a*') # => "foo" + ["foo"].pack('a2') # => "fo" + ["foo\0"].pack('a4') # => "foo\x00" + [nil].pack('a') # => "\x00" + [nil].pack('a*') # => "" + [nil].pack('a2') # => "\x00\x00" + [nil].pack('a4') # => "\x00\x00\x00\x00" + + "foo\0".unpack('a') # => ["f"] + "foo\0".unpack('a4') # => ["foo\x00"] + "foo ".unpack('a4') # => ["foo "] + "foo".unpack('a4') # => ["foo"] + "foo\0bar".unpack('a4') # => ["foo\x00"] # Reads past "\0". + +- <tt>'Z'</tt> - Same as <tt>'a'</tt>, + except that null is added or ignored with <tt>'*'</tt>: + + ["foo"].pack('Z*') # => "foo\x00" + [nil].pack('Z*') # => "\x00" + + "foo\0".unpack('Z*') # => ["foo"] + "foo".unpack('Z*') # => ["foo"] + "foo\0bar".unpack('Z*') # => ["foo"] # Does not read past "\0". + +=== Bit \String Directives + +- <tt>'B'</tt> - Bit string (high byte first): + + ['11111111' + '00000000'].pack('B*') # => "\xFF\x00" + ['10000000' + '01000000'].pack('B*') # => "\x80@" + + ['1'].pack('B0') # => "" + ['1'].pack('B1') # => "\x80" + ['1'].pack('B2') # => "\x80\x00" + ['1'].pack('B3') # => "\x80\x00" + ['1'].pack('B4') # => "\x80\x00\x00" + ['1'].pack('B5') # => "\x80\x00\x00" + ['1'].pack('B6') # => "\x80\x00\x00\x00" + + "\xff\x00".unpack("B*") # => ["1111111100000000"] + "\x01\x02".unpack("B*") # => ["0000000100000010"] + + "".unpack("B0") # => [""] + "\x80".unpack("B1") # => ["1"] + "\x80".unpack("B2") # => ["10"] + "\x80".unpack("B3") # => ["100"] + +- <tt>'b'</tt> - Bit string (low byte first): + + ['11111111' + '00000000'].pack('b*') # => "\xFF\x00" + ['10000000' + '01000000'].pack('b*') # => "\x01\x02" + + ['1'].pack('b0') # => "" + ['1'].pack('b1') # => "\x01" + ['1'].pack('b2') # => "\x01\x00" + ['1'].pack('b3') # => "\x01\x00" + ['1'].pack('b4') # => "\x01\x00\x00" + ['1'].pack('b5') # => "\x01\x00\x00" + ['1'].pack('b6') # => "\x01\x00\x00\x00" + + "\xff\x00".unpack("b*") # => ["1111111100000000"] + "\x01\x02".unpack("b*") # => ["1000000001000000"] + + "".unpack("b0") # => [""] + "\x01".unpack("b1") # => ["1"] + "\x01".unpack("b2") # => ["10"] + "\x01".unpack("b3") # => ["100"] + +=== Hex \String Directives + +- <tt>'H'</tt> - Hex string (high nibble first): + + ['10ef'].pack('H*') # => "\x10\xEF" + ['10ef'].pack('H0') # => "" + ['10ef'].pack('H3') # => "\x10\xE0" + ['10ef'].pack('H5') # => "\x10\xEF\x00" + + ['fff'].pack('H3') # => "\xFF\xF0" + ['fff'].pack('H4') # => "\xFF\xF0" + ['fff'].pack('H5') # => "\xFF\xF0\x00" + ['fff'].pack('H6') # => "\xFF\xF0\x00" + ['fff'].pack('H7') # => "\xFF\xF0\x00\x00" + ['fff'].pack('H8') # => "\xFF\xF0\x00\x00" + + "\x10\xef".unpack('H*') # => ["10ef"] + "\x10\xef".unpack('H0') # => [""] + "\x10\xef".unpack('H1') # => ["1"] + "\x10\xef".unpack('H2') # => ["10"] + "\x10\xef".unpack('H3') # => ["10e"] + "\x10\xef".unpack('H4') # => ["10ef"] + "\x10\xef".unpack('H5') # => ["10ef"] + +- <tt>'h'</tt> - Hex string (low nibble first): + + ['10ef'].pack('h*') # => "\x01\xFE" + ['10ef'].pack('h0') # => "" + ['10ef'].pack('h3') # => "\x01\x0E" + ['10ef'].pack('h5') # => "\x01\xFE\x00" + + ['fff'].pack('h3') # => "\xFF\x0F" + ['fff'].pack('h4') # => "\xFF\x0F" + ['fff'].pack('h5') # => "\xFF\x0F\x00" + ['fff'].pack('h6') # => "\xFF\x0F\x00" + ['fff'].pack('h7') # => "\xFF\x0F\x00\x00" + ['fff'].pack('h8') # => "\xFF\x0F\x00\x00" + + "\x01\xfe".unpack('h*') # => ["10ef"] + "\x01\xfe".unpack('h0') # => [""] + "\x01\xfe".unpack('h1') # => ["1"] + "\x01\xfe".unpack('h2') # => ["10"] + "\x01\xfe".unpack('h3') # => ["10e"] + "\x01\xfe".unpack('h4') # => ["10ef"] + "\x01\xfe".unpack('h5') # => ["10ef"] + +=== Pointer \String Directives + +- <tt>'P'</tt> - Pointer to a structure (fixed-length string): + + s = ['abc'].pack('P') # => "\xE0O\x7F\xE5\xA1\x01\x00\x00" + s.unpack('P*') # => ["abc"] + ".".unpack("P") # => [] + ("\0" * 8).unpack("P") # => [nil] + [nil].pack("P") # => "\x00\x00\x00\x00\x00\x00\x00\x00" + +- <tt>'p'</tt> - Pointer to a null-terminated string: + + s = ['abc'].pack('p') # => "(\xE4u\xE5\xA1\x01\x00\x00" + s.unpack('p*') # => ["abc"] + ".".unpack("p") # => [] + ("\0" * 8).unpack("p") # => [nil] + [nil].pack("p") # => "\x00\x00\x00\x00\x00\x00\x00\x00" + +=== Other \String Directives + +- <tt>'M'</tt> - Quoted printable, MIME encoding; + text mode, but input must use LF and output LF; + (see {RFC 2045}[https://www.ietf.org/rfc/rfc2045.txt]): + + ["a b c\td \ne"].pack('M') # => "a b c\td =\n\ne=\n" + ["\0"].pack('M') # => "=00=\n" + + ["a"*1023].pack('M') == ("a"*73+"=\n")*14+"a=\n" # => true + ("a"*73+"=\na=\n").unpack('M') == ["a"*74] # => true + (("a"*73+"=\n")*14+"a=\n").unpack('M') == ["a"*1023] # => true + + "a b c\td =\n\ne=\n".unpack('M') # => ["a b c\td \ne"] + "=00=\n".unpack('M') # => ["\x00"] + + "pre=31=32=33after".unpack('M') # => ["pre123after"] + "pre=\nafter".unpack('M') # => ["preafter"] + "pre=\r\nafter".unpack('M') # => ["preafter"] + "pre=".unpack('M') # => ["pre="] + "pre=\r".unpack('M') # => ["pre=\r"] + "pre=hoge".unpack('M') # => ["pre=hoge"] + "pre==31after".unpack('M') # => ["pre==31after"] + "pre===31after".unpack('M') # => ["pre===31after"] + +- <tt>'m'</tt> - Base64 encoded string; + count specifies input bytes between each newline, + rounded down to nearest multiple of 3; + if count is zero, no newlines are added; + (see {RFC 4648}[https://www.ietf.org/rfc/rfc4648.txt]): + + [""].pack('m') # => "" + ["\0"].pack('m') # => "AA==\n" + ["\0\0"].pack('m') # => "AAA=\n" + ["\0\0\0"].pack('m') # => "AAAA\n" + ["\377"].pack('m') # => "/w==\n" + ["\377\377"].pack('m') # => "//8=\n" + ["\377\377\377"].pack('m') # => "////\n" + + "".unpack('m') # => [""] + "AA==\n".unpack('m') # => ["\x00"] + "AAA=\n".unpack('m') # => ["\x00\x00"] + "AAAA\n".unpack('m') # => ["\x00\x00\x00"] + "/w==\n".unpack('m') # => ["\xFF"] + "//8=\n".unpack('m') # => ["\xFF\xFF"] + "////\n".unpack('m') # => ["\xFF\xFF\xFF"] + "A\n".unpack('m') # => [""] + "AA\n".unpack('m') # => ["\x00"] + "AA=\n".unpack('m') # => ["\x00"] + "AAA\n".unpack('m') # => ["\x00\x00"] + + [""].pack('m0') # => "" + ["\0"].pack('m0') # => "AA==" + ["\0\0"].pack('m0') # => "AAA=" + ["\0\0\0"].pack('m0') # => "AAAA" + ["\377"].pack('m0') # => "/w==" + ["\377\377"].pack('m0') # => "//8=" + ["\377\377\377"].pack('m0') # => "////" + + "".unpack('m0') # => [""] + "AA==".unpack('m0') # => ["\x00"] + "AAA=".unpack('m0') # => ["\x00\x00"] + "AAAA".unpack('m0') # => ["\x00\x00\x00"] + "/w==".unpack('m0') # => ["\xFF"] + "//8=".unpack('m0') # => ["\xFF\xFF"] + "////".unpack('m0') # => ["\xFF\xFF\xFF"] + +- <tt>'u'</tt> - UU-encoded string: + + [""].pack("u") # => "" + ["a"].pack("u") # => "!80``\n" + ["aaa"].pack("u") # => "#86%A\n" + + "".unpack("u") # => [""] + "#86)C\n".unpack("u") # => ["abc"] + +== Offset Directives + +- <tt>'@'</tt> - Begin packing at the given byte offset; + for packing, null fill if necessary: + + [1, 2].pack("C@0C") # => "\x02" + [1, 2].pack("C@1C") # => "\x01\x02" + [1, 2].pack("C@5C") # => "\x01\x00\x00\x00\x00\x02" + + "\x01\x00\x00\x02".unpack("C@3C") # => [1, 2] + "\x00".unpack("@1C") # => [nil] + +- <tt>'X'</tt> - Back up a byte: + + [0, 1, 2].pack("CCXC") # => "\x00\x02" + [0, 1, 2].pack("CCX2C") # => "\x02" + "\x00\x02".unpack("CCXC") # => [0, 2, 2] + +== Null Byte Directive + +- <tt>'x'</tt> - Null byte: + + [].pack("x0") # => "" + [].pack("x") # => "\x00" + [].pack("x8") # => "\x00\x00\x00\x00\x00\x00\x00\x00" + "\x00\x00\x02".unpack("CxC") # => [0, 2] diff --git a/doc/pty/README.expect.ja b/doc/pty/README.expect.ja index 7c0456f24f..a4eb6b01df 100644 --- a/doc/pty/README.expect.ja +++ b/doc/pty/README.expect.ja @@ -1,21 +1,23 @@ - README for expect += README for expect by A. Ito, 28 October, 1998 - Expectライブラリは，tcl の expect パッケージと似たような機能を +Expectライブラリは，tcl の expect パッケージと似たような機能を IOクラスに追加します． - 追加されるメソッドの使い方は次の通りです． +追加されるメソッドの使い方は次の通りです． - IO#expect(pattern,timeout=9999999) +[IO#expect(pattern,timeout=9999999)] -pattern は String か Regexp のインスタンス，timeout は Fixnum -のインスタンスです．timeout は省略できます． - このメソッドがブロックなしで呼ばれた場合，まずレシーバである -IOオブジェクトから pattern にマッチするパターンが読みこまれる -まで待ちます．パターンが得られたら，そのパターンに関する配列を -返します．配列の最初の要素は，pattern にマッチするまでに読みこ -まれた内容の文字列です．2番目以降の要素は，pattern の正規表現 -の中にアンカーがあった場合に，そのアンカーにマッチする部分です． -もしタイムアウトが起きた場合は，このメソッドはnilを返します． - このメソッドがブロック付きで呼ばれた場合には，マッチした要素の -配列がブロック引数として渡され，ブロックが評価されます． + _pattern_ は String か Regexp のインスタンス，_timeout_ は Fixnum + のインスタンスです．_timeout_ は省略できます． + + このメソッドがブロックなしで呼ばれた場合，まずレシーバである + IOオブジェクトから _pattern_ にマッチするパターンが読みこまれる + まで待ちます．パターンが得られたら，そのパターンに関する配列を + 返します．配列の最初の要素は，_pattern_ にマッチするまでに読みこ + まれた内容の文字列です．2番目以降の要素は，_pattern_ の正規表現 + の中にアンカーがあった場合に，そのアンカーにマッチする部分です． + もしタイムアウトが起きた場合は，このメソッドは +nil+ を返します． + + このメソッドがブロック付きで呼ばれた場合には，マッチした要素の + 配列がブロック引数として渡され，ブロックが評価されます． diff --git a/doc/pty/README.ja b/doc/pty/README.ja index 2d83ffa033..a26b4932ff 100644 --- a/doc/pty/README.ja +++ b/doc/pty/README.ja @@ -1,27 +1,26 @@ -pty 拡張モジュール version 0.3 by A.ito += pty 拡張モジュール version 0.3 by A.ito 1. はじめに -この拡張モジュールは，仮想tty (pty) を通して適当なコマンドを -実行する機能を ruby に提供します． + この拡張モジュールは，仮想tty (pty) を通して適当なコマンドを + 実行する機能を ruby に提供します． 2. インストール -次のようにしてインストールしてください． + 次のようにしてインストールしてください． -(1) ruby extconf.rb + 1. <tt>ruby extconf.rb</tt> + を実行すると Makefile が生成されます． - を実行すると Makefile が生成されます． - -(2) make; make install を実行してください． + 2. <tt>make; make install</tt> を実行してください． 3. 何ができるか -この拡張モジュールは，PTY というモジュールを定義します．その中 -には，次のようなモジュール関数が含まれています． + この拡張モジュールは，PTY というモジュールを定義します．その中 + には，次のようなモジュール関数が含まれています． - getpty(command) - spawn(command) + [PTY.getpty(command)] + [PTY.spawn(command)] この関数は，仮想ttyを確保し，指定されたコマンドをその仮想tty の向こうで実行し，配列を返します．戻り値は3つの要素からなる @@ -35,12 +34,7 @@ pty 拡張モジュール version 0.3 by A.ito のみ例外が発生します．子プロセスをモニターしているスレッドはブロッ クを抜けるときに終了します． - protect_signal - reset_signal - - 廃止予定です． - - PTY.open + [PTY.open] 仮想ttyを確保し，マスター側に対応するIOオブジェクトとスレーブ側に 対応するFileオブジェクトの配列を返します．ブロック付きで呼び出さ @@ -48,7 +42,7 @@ pty 拡張モジュール version 0.3 by A.ito クから返された結果を返します．また、このマスターIOとスレーブFile は、ブロックを抜けるときにクローズ済みでなければクローズされます． - PTY.check(pid[, raise=false]) + [PTY.check(pid[, raise=false])] pidで指定された子プロセスの状態をチェックし，実行中であればnilを 返します．終了しているか停止している場合、第二引数が偽であれば、 @@ -57,20 +51,20 @@ pty 拡張モジュール version 0.3 by A.ito 4. 利用について -伊藤彰則が著作権を保有します． + 伊藤彰則が著作権を保有します． -ソースプログラムまたはドキュメントに元の著作権表示が改変されずに -表示されている場合に限り，誰でも，このソフトウェアを無償かつ著作 -権者に無断で利用・配布・改変できます．利用目的は限定されていませ -ん． + ソースプログラムまたはドキュメントに元の著作権表示が改変されずに + 表示されている場合に限り，誰でも，このソフトウェアを無償かつ著作 + 権者に無断で利用・配布・改変できます．利用目的は限定されていませ + ん． -このプログラムの利用・配布その他このプログラムに関係する行為によ -って生じたいかなる損害に対しても，作者は一切責任を負いません． + このプログラムの利用・配布その他このプログラムに関係する行為によ + って生じたいかなる損害に対しても，作者は一切責任を負いません． 5. バグ報告等 -バグレポートは歓迎します． + バグレポートは歓迎します． aito@ei5sun.yz.yamagata-u.ac.jp -まで電子メールでバグレポートをお送りください． + まで電子メールでバグレポートをお送りください． diff --git a/doc/ractor.md b/doc/ractor.md index f5b1fb5403..7a69e839de 100644 --- a/doc/ractor.md +++ b/doc/ractor.md @@ -179,7 +179,7 @@ end Communication between Ractors is achieved by sending and receiving messages. There are two ways to communicate with each other. * (1) Message sending/receiving - * (1-1) push type send/receive (sender knows receiver). similar to the Actor model. + * (1-1) push type send/receive (sender knows receiver). Similar to the Actor model. * (1-2) pull type yield/take (receiver knows sender). * (2) Using shareable container objects * Ractor::TVar gem ([ko1/ractor-tvar](https://github.com/ko1/ractor-tvar)) @@ -204,8 +204,8 @@ For message sending and receiving, there are two types of APIs: push type and pu * When a Ractor is terminated, the Ractor's ports are closed. * There are 3 ways to send an object as a message * (1) Send a reference: Sending a shareable object, send only a reference to the object (fast) - * (2) Copy an object: Sending an unshareable object by copying an object deeply (slow). Note that you can not send an object which does not support deep copy. Some `T_DATA` objects are not supported. - * (3) Move an object: Sending an unshareable object reference with a membership. Sender Ractor can not access moved objects anymore (raise an exception) after moving it. Current implementation makes new object as a moved object for receiver Ractor and copies references of sending object to moved object. + * (2) Copy an object: Sending an unshareable object by copying an object deeply (slow). Note that you can not send an object which does not support deep copy. Some `T_DATA` objects (objects whose class is defined in a C extension, such as `StringIO`) are not supported. + * (3) Move an object: Sending an unshareable object reference with a membership. Sender Ractor can not access moved objects anymore (raise an exception) after moving it. Current implementation makes new object as a moved object for receiver Ractor and copies references of sending object to moved object. `T_DATA` objects are not supported. * You can choose "Copy" and "Move" by the `move:` keyword, `Ractor#send(obj, move: true/false)` and `Ractor.yield(obj, move: true/false)` (default is `false` (COPY)). ### Sending/Receiving ports @@ -393,7 +393,7 @@ TODO: `select` syntax of go-language uses round-robin technique to make fair sch * `Ractor#close_incoming/outgoing` close incoming/outgoing ports (similar to `Queue#close`). * `Ractor#close_incoming` - * `r.send(obj) ` where `r`'s incoming port is closed, will raise an exception. + * `r.send(obj)` where `r`'s incoming port is closed, will raise an exception. * When the incoming queue is empty and incoming port is closed, `Ractor.receive` raises an exception. If the incoming queue is not empty, it dequeues an object without exceptions. * `Ractor#close_outgoing` * `Ractor.yield` on a Ractor which closed the outgoing port, it will raise an exception. @@ -536,7 +536,7 @@ The following objects are shareable. Implementation: Now shareable objects (`RVALUE`) have `FL_SHAREABLE` flag. This flag can be added lazily. -To make shareable objects, `Ractor.make_shareable(obj)` method is provided. In this case, try to make sharaeble by freezing `obj` and recursively travasible objects. This method accepts `copy:` keyword (default value is false).`Ractor.make_shareable(obj, copy: true)` tries to make a deep copy of `obj` and make the copied object shareable. +To make shareable objects, `Ractor.make_shareable(obj)` method is provided. In this case, try to make sharaeble by freezing `obj` and recursively traversable objects. This method accepts `copy:` keyword (default value is false).`Ractor.make_shareable(obj, copy: true)` tries to make a deep copy of `obj` and make the copied object shareable. ## Language changes to isolate unshareable objects between Ractors @@ -705,8 +705,8 @@ TABLE = {a: 'ko1', b: 'ko2', c: 'ko3'} * none: Do nothing. Same as: `CONST = expr` * literal: - * if `expr` is consites of literals, replaced to `CONST = Ractor.make_shareable(expr)`. - * otherwise: replaced to `CONST = expr.tap{|o| raise unless Ractor.shareable?}`. + * if `expr` consists of literals, replaced to `CONST = Ractor.make_shareable(expr)`. + * otherwise: replaced to `CONST = expr.tap{|o| raise unless Ractor.shareable?(o)}`. * experimental_everything: replaced to `CONST = Ractor.make_shareable(expr)`. * experimental_copy: replaced to `CONST = Ractor.make_shareable(expr, copy: true)`. diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb new file mode 100644 index 0000000000..bfc84abd5a --- /dev/null +++ b/doc/rdoc/markup_reference.rb @@ -0,0 +1,1287 @@ +require 'rdoc' + +# \Class \RDoc::MarkupReference exists only to provide a suitable home +# for a reference document for \RDoc markup. +# +# All objects defined in this class -- classes, modules, methods, aliases, +# attributes, and constants -- are solely for illustrating \RDoc markup, +# and have no other legitimate use. +# +# == About the Examples +# +# - Examples in this reference are Ruby code and comments; +# certain differences from other sources +# (such as C code and comments) are noted. +# - Almost all examples on this page are all RDoc-like; +# that is, they have no explicit comment markers like Ruby <tt>#</tt> +# or C <tt>/* ... */</tt>. +# - An example that shows rendered HTML output +# displays that output in a blockquote: +# +# >>> +# Some stuff +# +# == \RDoc Sources +# +# The sources of \RDoc documentation vary according to the type of file: +# +# - <tt>.rb</tt> (Ruby code file): +# +# - Markup may be found in Ruby comments: +# A comment that immediately precedes the definition +# of a Ruby class, module, method, alias, constant, or attribute +# becomes the documentation for that defined object. +# - An \RDoc directive may be found in: +# +# - A trailing comment (on the same line as code); +# see <tt>:nodoc:</tt>, <tt>:doc:</tt>, and <tt>:notnew:</tt>. +# - A single-line comment; +# see other {Directives}[rdoc-ref:RDoc::MarkupReference@Directives]. +# +# - Documentation may be derived from the Ruby code itself; +# see {Documentation Derived from Ruby Code}[rdoc-ref:RDoc::MarkupReference@Documentation+Derived+from+Ruby+Code]. +# +# - <tt>.c</tt> (C code file): markup is parsed from C comments. +# A comment that immediately precedes +# a function that implements a Ruby method, +# or otherwise immediately precedes the definition of a Ruby object, +# becomes the documentation for that object. +# - <tt>.rdoc</tt> (\RDoc markup text file) or <tt>.md</tt> (\RDoc markdown text file): +# markup is parsed from the entire file. +# The text is not associated with any code object, +# but may (depending on how the documentation is built) +# become a separate page. +# +# An <i>RDoc document</i>: +# +# - A (possibly multi-line) comment in a Ruby or C file +# that generates \RDoc documentation (as above). +# - The entire markup (<tt>.rdoc</tt>) file or markdown (<tt>.md</tt>) file +# (which is usually multi-line). +# +# === Blocks +# +# It's convenient to think of an \RDoc document as a sequence of _blocks_ +# of various types (details at the links): +# +# - {Paragraph}[rdoc-ref:RDoc::MarkupReference@Paragraphs]: +# an ordinary paragraph. +# - {Verbatim text block}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks]: +# a block of text to be rendered literally. +# - {Code block}[rdoc-ref:RDoc::MarkupReference@Code+Blocks]: +# a verbatim text block containing Ruby code, +# to be rendered with code highlighting. +# - {Block quote}[rdoc-ref:RDoc::MarkupReference@Block+Quotes]: +# a longish quoted passage, to be rendered with indentation +# instead of quote marks. +# - {List}[rdoc-ref:RDoc::MarkupReference@Lists]: items for +# a bullet list, numbered list, lettered list, or labeled list. +# - {Heading}[rdoc-ref:RDoc::MarkupReference@Headings]: +# a heading. +# - {Horizontal rule}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules]: +# a line across the rendered page. +# - {Directive}[rdoc-ref:RDoc::MarkupReference@Directives]: +# various special directions for the rendering. +# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup]: +# text to be rendered in a special way. +# +# About the blocks: +# +# - Except for a paragraph, a block is distinguished by its indentation, +# or by unusual initial or embedded characters. +# - Any block may appear independently +# (that is, not nested in another block); +# some blocks may be nested, as detailed below. +# - In a multi-line block, +# \RDoc looks for the block's natural left margin, +# which becomes the <em>base margin</em> for the block +# and is the initial <em>current margin</em> for the block. +# +# ==== Paragraphs +# +# A paragraph consists of one or more non-empty lines of ordinary text, +# each beginning at the current margin. +# +# Note: Here, <em>ordinary text</em> means text that is <em>not identified</em> +# by indentation, or by unusual initial or embedded characters. +# See below. +# +# Paragraphs are separated by one or more empty lines. +# +# Example input: +# +# \RDoc produces HTML and command-line documentation for Ruby projects. +# \RDoc includes the rdoc and ri tools for generating and displaying +# documentation from the command-line. +# +# You'll love it. +# +# Rendered HTML: +# >>> +# \RDoc produces HTML and command-line documentation for Ruby projects. +# \RDoc includes the rdoc and ri tools for generating and displaying +# documentation from the command-line. +# +# You'll love it. +# +# A paragraph may contain nested blocks, including: +# +# - {Verbatim text blocks}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks]. +# - {Code blocks}[rdoc-ref:RDoc::MarkupReference@Code+Blocks]. +# - {Block quotes}[rdoc-ref:RDoc::MarkupReference@Block+Quotes]. +# - {Lists}[rdoc-ref:RDoc::MarkupReference@Lists]. +# - {Headings}[rdoc-ref:RDoc::MarkupReference@Headings]. +# - {Horizontal rules}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules]. +# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup]. +# +# ==== Verbatim Text Blocks +# +# Text indented farther than the current margin becomes a <em>verbatim text block</em> +# (or a code block, described next). +# In the rendered HTML, such text: +# +# - Is indented. +# - Has a contrasting background color. +# +# The verbatim text block ends at the first line beginning at the current margin. +# +# Example input: +# +# This is not verbatim text. +# +# This is verbatim text. +# Whitespace is honored. # See? +# Whitespace is honored. # See? +# +# This is still the same verbatim text block. +# +# This is not verbatim text. +# +# Rendered HTML: +# >>> +# This is not verbatim text. +# +# This is verbatim text. +# Whitespace is honored. # See? +# Whitespace is honored. # See? +# +# This is still the same verbatim text block. +# +# This is not verbatim text. +# +# A verbatim text block may not contain nested blocks of any kind +# -- it's verbatim. +# +# ==== Code Blocks +# +# A special case of verbatim text is the <em>code block</em>, +# which is merely verbatim text that \RDoc recognizes as Ruby code: +# +# In the rendered HTML, the code block: +# +# - Is indented. +# - Has a contrasting background color. +# - Has syntax highlighting. +# +# Example input: +# +# Consider this method: +# +# def foo(name = '', value = 0) +# @name = name # Whitespace is still honored. +# @value = value +# end +# +# +# Rendered HTML: +# >>> +# Consider this method: +# +# def foo(name = '', value = 0) +# @name = name # Whitespace is still honored. +# @value = value +# end +# +# Pro tip: If your indented Ruby code does not get highlighted, +# it may contain a syntax error. +# +# A code block may not contain nested blocks of any kind +# -- it's verbatim. +# +# ==== Block Quotes +# +# You can use the characters <tt>>>></tt> (unindented), +# followed by indented text, to treat the text +# as a {block quote}[https://en.wikipedia.org/wiki/Block_quotation]: +# +# Example input: +# +# Here's a block quote: +# >>> +# Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer +# commodo quam iaculis massa posuere, dictum fringilla justo pulvinar. +# Quisque turpis erat, pharetra eu dui at, sollicitudin accumsan nulla. +# +# Aenean congue ligula eu ligula molestie, eu pellentesque purus +# faucibus. In id leo non ligula condimentum lobortis. Duis vestibulum, +# diam in pellentesque aliquet, mi tellus placerat sapien, id euismod +# purus magna ut tortor. +# +# Rendered HTML: +# +# >>> +# Here's a block quote: +# >>> +# Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer +# commodo quam iaculis massa posuere, dictum fringilla justo pulvinar. +# Quisque turpis erat, pharetra eu dui at, sollicitudin accumsan nulla. +# +# Aenean congue ligula eu ligula molestie, eu pellentesque purus +# faucibus. In id leo non ligula condimentum lobortis. Duis vestibulum, +# diam in pellentesque aliquet, mi tellus placerat sapien, id euismod +# purus magna ut tortor. +# +# Note that, unlike verbatim text, single newlines are not honored, +# but that a double newline begins a new paragraph in the block quote. +# +# A block quote may contain nested blocks, including: +# +# - Other block quotes. +# - {Paragraphs}[rdoc-ref:RDoc::MarkupReference@Paragraphs]. +# - {Verbatim text blocks}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks]. +# - {Code blocks}[rdoc-ref:RDoc::MarkupReference@Code+Blocks]. +# - {Lists}[rdoc-ref:RDoc::MarkupReference@Lists]. +# - {Headings}[rdoc-ref:RDoc::MarkupReference@Headings]. +# - {Horizontal rules}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules]. +# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup]. +# +# ==== Lists +# +# Each type of list item is marked by a special beginning: +# +# - Bullet list item: Begins with a hyphen or asterisk. +# - Numbered list item: Begins with digits and a period. +# - Lettered list item: Begins with an alphabetic character and a period. +# - Labeled list item: Begins with one of: +# - Square-bracketed text. +# - A word followed by two colons. +# +# A list begins with a list item and continues, even across blank lines, +# as long as list items of the same type are found at the same indentation level. +# +# A new list resets the current margin inward. +# Additional lines of text aligned at that margin +# are part of the continuing list item. +# +# A list item may be continued on additional lines that are aligned +# with the first line. See examples below. +# +# A list item may contain nested blocks, including: +# +# - Other lists of any type. +# - {Paragraphs}[rdoc-ref:RDoc::MarkupReference@Paragraphs]. +# - {Verbatim text blocks}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks]. +# - {Code blocks}[rdoc-ref:RDoc::MarkupReference@Code+Blocks]. +# - {Block quotes}[rdoc-ref:RDoc::MarkupReference@Block+Quotes]. +# - {Headings}[rdoc-ref:RDoc::MarkupReference@Headings]. +# - {Horizontal rules}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules]. +# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup]. +# +# ===== Bullet Lists +# +# A bullet list item begins with a hyphen or asterisk. +# +# Example input: +# +# - An item. +# - Another. +# - An item spanning +# multiple lines. +# +# * Yet another. +# - Last one. +# +# Rendered HTML: +# >>> +# - An item. +# - Another. +# - An item spanning +# multiple lines. +# +# * Yet another. +# - Last one. +# +# ===== Numbered Lists +# +# A numbered list item begins with digits and a period. +# +# The items are automatically re-numbered. +# +# Example input: +# +# 100. An item. +# 10. Another. +# 1. An item spanning +# multiple lines. +# +# 1. Yet another. +# 1000. Last one. +# +# Rendered HTML: +# >>> +# 100. An item. +# 10. Another. +# 1. An item spanning +# multiple lines. +# +# 1. Yet another. +# 1000. Last one. +# +# ===== Lettered Lists +# +# A lettered list item begins with letters and a period. +# +# The items are automatically "re-lettered." +# +# Example input: +# +# z. An item. +# y. Another. +# x. An item spanning +# multiple lines. +# +# x. Yet another. +# a. Last one. +# +# Rendered HTML: +# >>> +# z. An item. +# y. Another. +# +# x. Yet another. +# a. Last one. +# +# ===== Labeled Lists +# +# A labeled list item begins with one of: +# +# - Square-bracketed text: the label and text are on two lines. +# - A word followed by two colons: the label and text are on the same line. +# +# Example input: +# +# [foo] An item. +# bat:: Another. +# [bag] An item spanning +# multiple lines. +# +# [bar baz] Yet another. +# bam:: Last one. +# +# Rendered HTML: +# >>> +# [foo] An item. +# bat:: Another. +# [bag] An item spanning +# multiple lines. +# +# [bar baz] Yet another. +# bam:: Last one. +# +# ==== Headings +# +# A heading begins with up to six equal-signs, followed by heading text. +# Whitespace between those and the heading text is optional. +# +# Examples: +# +# = Section 1 +# == Section 1.1 +# === Section 1.1.1 +# === Section 1.1.2 +# == Section 1.2 +# = Section 2 +# = Foo +# == Bar +# === Baz +# ==== Bam +# ===== Bat +# ====== Bad +# ============Still a Heading (Level 6) +# \== Not a Heading +# +# A heading may contain only one type of nested block: +# +# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup]. +# +# ==== Horizontal Rules +# +# A horizontal rule consists of a line with three or more hyphens +# and nothing more. +# +# Example input: +# +# --- +# --- Not a horizontal rule. +# +# -- Also not a horizontal rule. +# --- +# +# Rendered HTML: +# >>> +# --- +# --- Not a horizontal rule. +# +# -- Also not a horizontal rule. +# --- +# +# ==== Directives +# +# ===== Directives for Allowing or Suppressing Documentation +# +# - <tt># :stopdoc:</tt>: +# +# - Appears on a line by itself. +# - Specifies that \RDoc should ignore markup +# until next <tt>:startdoc:</tt> directive or end-of-file. +# +# - <tt># :startdoc:</tt>: +# +# - Appears on a line by itself. +# - Specifies that \RDoc should resume parsing markup. +# +# - <tt># :enddoc:</tt>: +# +# - Appears on a line by itself. +# - Specifies that \RDoc should ignore markup to end-of-file +# regardless of other directives. +# +# - <tt># :nodoc:</tt>: +# +# - Appended to a line of code +# that defines a class, module, method, alias, constant, or attribute. +# +# - Specifies that the defined object should not be documented. +# +# - For a method definition in C code, it the directive must be in the comment line +# immediately preceding the definition: +# +# /* :nodoc: */ +# static VALUE +# some_method(VALUE self) +# { +# return self; +# } +# +# Note that this directive has <em>no effect at all</em> +# when placed at the method declaration: +# +# /* :nodoc: */ +# rb_define_method(cMyClass, "do_something", something_func, 0); +# +# The above comment is just a comment and has nothing to do with \RDoc. +# Therefore, +do_something+ method will be reported as "undocumented" +# unless that method or function is documented elsewhere. +# +# - For a constant definition in C code, this directive <em>can not work</em> +# because there is no "implementation" place for a constant. +# +# - <tt># :nodoc: all</tt>: +# +# - Appended to a line of code +# that defines a class or module. +# - Specifies that the class or module should not be documented. +# By default, however, a nested class or module _will_ be documented. +# +# - <tt># :doc:</tt>: +# +# - Appended to a line of code +# that defines a class, module, method, alias, constant, or attribute. +# - Specifies the defined object should be documented, even if it otherwise +# would not be documented. +# +# - <tt># :notnew:</tt> (aliased as <tt>:not_new:</tt> and <tt>:not-new:</tt>): +# +# - Appended to a line of code +# that defines instance method +initialize+. +# - Specifies that singleton method +new+ should not be documented. +# By default, Ruby fakes a corresponding singleton method +new+, +# which \RDoc includes in the documentation. +# Note that instance method +initialize+ is private, and so by default +# is not documented. +# +# For Ruby code, but not for other \RDoc sources, +# there is a shorthand for <tt>:stopdoc:</tt> and <tt>:startdoc:</tt>: +# +# # Documented. +# #-- +# # Not documented. +# #++ +# # Documented. +# +# For C code, any of directives <tt>:startdoc:</tt>, <tt>:stopdoc:</tt>, +# and <tt>:enddoc:</tt> may appear in a stand-alone comment: +# +# /* :startdoc: */ +# /* :stopdoc: */ +# /* :enddoc: */ +# +# ===== Directive for Specifying \RDoc Source Format +# +# - <tt># :markup: _type_</tt>: +# +# - Appears on a line by itself. +# - Specifies the format for the \RDoc input; +# parameter +type+ is one of +markdown+, +rd+, +rdoc+, +tomdoc+. +# +# ===== Directives for HTML Output +# +# - <tt># :title: _text_</tt>: +# +# - Appears on a line by itself. +# - Specifies the title for the HTML output. +# +# - <tt># :main: _filename_</tt>: +# - Appears on a line by itself. +# - Specifies the HTML file to be displayed first. +# +# ===== Directives for Method Documentation +# +# - <tt># :call-seq:</tt>: +# +# - Appears on a line by itself. +# - Specifies the calling sequence to be reported in the HTML, +# overriding the actual calling sequence in the code. +# See method #call_seq_directive. +# +# Note that \RDoc can build the calling sequence for a Ruby-coded method, +# but not for other languages. +# You may want to override that by explicitly giving a <tt>:call-seq:</tt> +# directive if you want to include: +# +# - A return type, which is not automatically inferred. +# - Multiple calling sequences. +# +# For C code, the directive may appear in a stand-alone comment. +# +# - <tt># :args: _arg_names_</tt> (aliased as <tt>:arg:</tt>): +# +# - Appears on a line by itself. +# - Specifies the arguments to be reported in the HTML, +# overriding the actual arguments in the code. +# See method #args_directive. +# +# - <tt># :yields: _arg_names_</tt> (aliased as <tt>:yield:</tt>): +# +# - Appears on a line by itself. +# - Specifies the yield arguments to be reported in the HTML, +# overriding the actual yield in the code. +# See method #yields_directive. +# +# ===== Directives for Organizing Documentation +# +# By default, \RDoc groups: +# +# - Singleton methods together in alphabetical order. +# - Instance methods and their aliases together in alphabetical order. +# - Attributes and their aliases together in alphabetical order. +# +# You can use directives to modify those behaviors. +# +# - <tt># :section: _section_title_</tt>: +# +# - Appears on a line by itself. +# - Specifies that following methods are to be grouped into the section +# with the given <em>section_title</em>, +# or into the default section if no title is given. +# The directive remains in effect until another such directive is given, +# but may be temporarily overridden by directive <tt>:category:</tt>. +# See below. +# +# The comment block containing this directive: +# +# - Must be separated by a blank line from the documentation for the next item. +# - May have one or more lines preceding the directive. +# These will be removed, along with any trailing lines that match them. +# Such lines may be visually helpful. +# - Lines of text that are not so removed become the descriptive text +# for the section. +# +# Example: +# +# # ---------------------------------------- +# # :section: My Section +# # This is the section that I wrote. +# # See it glisten in the noon-day sun. +# # ---------------------------------------- +# +# ## +# # Comment for some_method +# def some_method +# # ... +# end +# +# You can use directive <tt>:category:</tt> to temporarily +# override the current section. +# +# - <tt># :category: _section_title_</tt>: +# +# - Appears on a line by itself. +# - Specifies that just one following method is to be included +# in the given section, or in the default section if no title is given. +# Subsequent methods are to be grouped into the current section. +# +# ===== Directive for Including a File +# +# - <tt># :include: _filepath_</tt>: +# +# - Appears on a line by itself. +# - Specifies that the contents of the given file +# are to be included at this point. +# The file content is shifted to have the same indentation as the colon +# at the start of the directive. +# +# The file is searched for in the directory containing the current file, +# and then in each of the directories given with the <tt>--include</tt> +# command-line option. +# +# For C code, the directive may appear in a stand-alone comment +# +# ==== Text Markup +# +# Text markup is metatext that affects HTML rendering: +# +# - Typeface: italic, bold, monofont. +# - Character conversions: copyright, trademark, certain punctuation. +# - Links. +# - Escapes: marking text as "not markup." +# +# ===== Typeface Markup +# +# Typeface markup can specify that text is to be rendered +# as italic, bold, or monofont. +# +# Typeface markup may contain only one type of nested block: +# +# - More typeface markup: +# italic, bold, monofont. +# +# ====== Italic +# +# Text may be marked as italic via HTML tag <tt><i></tt> or <tt><em></tt>. +# +# Example input: +# +# <i>Italicized words</i> in a paragraph. +# +# >>> +# <i>Italicized words in a block quote</i>. +# +# - <i>Italicized words</i> in a list item. +# +# ====== <i>Italicized words</i> in a Heading +# +# <i>Italicized passage containing *bold* and +monofont+.</i> +# +# Rendered HTML: +# >>> +# <i>Italicized words</i> in a paragraph. +# +# >>> +# <i>Italicized words in a block quote</i>. +# +# - <i>Italicized words</i> in a list item. +# +# ====== <i>Italicized words</i> in a Heading +# +# <i>Italicized passage containing *bold* and +monofont+.</i> +# +# A single word may be italicized via a shorthand: +# prefixed and suffixed underscores. +# +# Example input: +# +# _Italic_ in a paragraph. +# +# >>> +# _Italic_ in a block quote. +# +# - _Italic_ in a list item. +# +# ====== _Italic_ in a Heading +# +# Rendered HTML: +# >>> +# _Italic_ in a paragraph. +# +# >>> +# _Italic_ in a block quote. +# +# - _Italic_ in a list item. +# +# ====== _Italic_ in a Heading +# +# ====== Bold +# +# Text may be marked as bold via HTML tag <tt><b></tt>. +# +# Example input: +# +# <b>Bold words</b> in a paragraph. +# +# >>> +# <b>Bold words</b> in a block quote. +# +# - <b>Bold words</b> in a list item. +# +# ====== <b>Bold words</b> in a Heading +# +# <b>Bold passage containing _italics_ and +monofont+.</b> +# +# Rendered HTML: +# +# >>> +# <b>Bold words</b> in a paragraph. +# +# >>> +# <b>Bold words</b> in a block quote. +# +# - <b>Bold words</b> in a list item. +# +# ====== <b>Bold words</b> in a Heading +# +# <b>Bold passage containing _italics_ and +monofont+.</b> +# +# A single word may be made bold via a shorthand: +# prefixed and suffixed asterisks. +# +# Example input: +# +# *Bold* in a paragraph. +# +# >>> +# *Bold* in a block quote. +# +# - *Bold* in a list item. +# +# ===== *Bold* in a Heading +# +# Rendered HTML: +# +# >>> +# *Bold* in a paragraph. +# +# >>> +# *Bold* in a block quote. +# +# - *Bold* in a list item. +# +# ===== *Bold* in a Heading +# +# ====== Monofont +# +# Text may be marked as monofont +# -- sometimes called 'typewriter font' -- +# via HTML tag <tt><tt></tt> or <tt><code></tt>. +# +# Example input: +# +# <tt>Monofont words</tt> in a paragraph. +# +# >>> +# <tt>Monofont words</tt> in a block quote. +# +# - <tt>Monofont words</tt> in a list item. +# +# ====== <tt>Monofont words</tt> in heading +# +# <tt>Monofont passage containing _italics_ and *bold*.</tt> +# +# Rendered HTML: +# +# >>> +# <tt>Monofont words</tt> in a paragraph. +# +# >>> +# <tt>Monofont words</tt> in a block quote. +# +# - <tt>Monofont words</tt> in a list item. +# +# ====== <tt>Monofont words</tt> in heading +# +# <tt>Monofont passage containing _italics_ and *bold*.</tt> +# +# A single word may be made monofont by a shorthand: +# prefixed and suffixed plus-signs. +# +# Example input: +# +# +Monofont+ in a paragraph. +# +# >>> +# +Monofont+ in a block quote. +# +# - +Monofont+ in a list item. +# +# ====== +Monofont+ in a Heading +# +# Rendered HTML: +# +# >>> +# +Monofont+ in a paragraph. +# +# >>> +# +Monofont+ in a block quote. +# +# - +Monofont+ in a list item. +# +# ====== +Monofont+ in a Heading +# +# ==== Character Conversions +# +# Certain combinations of characters may be converted to special characters; +# whether the conversion occurs depends on whether the special character +# is available in the current encoding. +# +# - <tt>(c)</tt> converts to (c) (copyright character); must be lowercase. +# +# - <tt>(r)</tt> converts to (r) (registered trademark character); must be lowercase. +# +# - <tt>'foo'</tt> converts to 'foo' (smart single-quotes). +# +# - <tt>"foo"</tt> converts to "foo" (smart double-quotes). +# +# - <tt>foo ... bar</tt> converts to foo ... bar (1-character ellipsis). +# +# - <tt>foo -- bar</tt> converts to foo -- bar (1-character en-dash). +# +# - <tt>foo --- bar</tt> converts to foo --- bar (1-character em-dash). +# +# ==== Links +# +# Certain strings in \RDoc text are converted to links. +# Any such link may be suppressed by prefixing a backslash. +# This section shows how to link to various +# targets. +# +# [Class] +# +# - On-page: <tt>DummyClass</tt> links to DummyClass. +# - Off-page: <tt>RDoc::Alias</tt> links to RDoc::Alias. +# +# [Module] +# +# - On-page: <tt>DummyModule</tt> links to DummyModule. +# - Off-page: <tt>RDoc</tt> links to RDoc. +# +# [Constant] +# +# - On-page: <tt>DUMMY_CONSTANT</tt> links to DUMMY_CONSTANT. +# - Off-page: <tt>RDoc::Text::MARKUP_FORMAT</tt> links to RDoc::Text::MARKUP_FORMAT. +# +# [Singleton Method] +# +# - On-page: <tt>::dummy_singleton_method</tt> links to ::dummy_singleton_method. +# - Off-page<tt>RDoc::TokenStream::to_html</tt> links to RDoc::TokenStream::to_html. +# +# Note: Occasionally \RDoc is not linked to a method whose name +# has only special characters. Check whether the links you were expecting +# are actually there. If not, you'll need to put in an explicit link; +# see below. +# +# Pro tip: The link to any method is available in the alphabetical table of contents +# at the top left of the page for the class or module. +# +# [Instance Method] +# +# - On-page: <tt>#dummy_instance_method</tt> links to #dummy_instance_method. +# - Off-page: <tt>RDoc::Alias#html_name</tt> links to RDoc::Alias#html_name. +# +# See the Note and Pro Tip immediately above. +# +# [Attribute] +# +# - On-page: <tt>#dummy_attribute</tt> links to #dummy_attribute. +# - Off-page: <tt>RDoc::Alias#name</tt> links to RDoc::Alias#name. +# +# [Alias] +# +# - On-page: <tt>#dummy_instance_alias</tt> links to #dummy_instance_alias. +# - Off-page: <tt>RDoc::Alias#new_name</tt> links to RDoc::Alias#new_name. +# +# [Protocol +http+] +# +# - Linked: <tt>http://yahoo.com</tt> links to http://yahoo.com. +# +# [Protocol +https+] +# +# - Linked: <tt>https://github.com</tt> links to https://github.com. +# +# [Protocol +www+] +# +# - Linked: <tt>www.yahoo.com</tt> links to www.yahoo.com. +# +# [Protocol +ftp+] +# +# - Linked: <tt>ftp://nosuch.site</tt> links to ftp://nosuch.site. +# +# [Protocol +mailto+] +# +# - Linked: <tt>mailto:/foo@bar.com</tt> links to mailto://foo@bar.com. +# +# [Protocol +irc+] +# +# - link: <tt>irc://irc.freenode.net/ruby</tt> links to irc://irc.freenode.net/ruby. +# +# [Image Filename Extensions] +# +# - Link: <tt>https://www.ruby-lang.org/images/header-ruby-logo@2x.png</tt> is +# converted to an in-line HTML +img+ tag, which displays the image in the HTML: +# +# https://www.ruby-lang.org/images/header-ruby-logo@2x.png +# +# Also works for +bmp+, +gif+, +jpeg+, and +jpg+ files. +# +# Note: Works only for a fully qualified URL. +# +# [Heading] +# +# - Link: <tt>RDoc::RD@LICENSE</tt> links to RDoc::RDoc::RD@LICENSE. +# +# Note that spaces in the actual heading are represented by <tt>+</tt> characters +# in the linkable text. +# +# - Link: <tt>RDoc::Options@Saved+Options</tt> +# links to RDoc::Options@Saved+Options. +# +# Punctuation and other special characters must be escaped like CGI.escape. +# +# Pro tip: The link to any heading is available in the alphabetical table of contents +# at the top left of the page for the class or module. +# +# [Section] +# +# See {Directives for Organizing Documentation}[#class-RDoc::MarkupReference-label-Directives+for+Organizing+Documentation]. +# +# - Link: <tt>RDoc::Markup::ToHtml@Visitor</tt> links to RDoc::Markup::ToHtml@Visitor. +# +# If a section and a heading share the same name, the link target is the section. +# +# [Single-Word Text Link] +# +# Use square brackets to create single-word text link: +# +# - <tt>GitHub[https://github.com]</tt> links to GitHub[https://github.com]. +# +# [Multi-Word Text Link] +# +# Use square brackets and curly braces to create a multi-word text link. +# +# - <tt>{GitHub home page}[https://github.com]</tt> links to +# {GitHub home page}[https://github.com]. +# +# [<tt>rdoc-ref</tt> Scheme] +# +# A link with the <tt>rdoc-ref:</tt> scheme links to the referenced item, +# if that item exists. +# The referenced item may be a class, module, method, file, etc. +# +# - Class: <tt>Alias[rdoc-ref:RDoc::Alias]</tt> links to Alias[rdoc-ref:RDoc::Alias]. +# - Module: <tt>RDoc[rdoc-ref:RDoc]</tt> links to RDoc[rdoc-ref:RDoc]. +# - Method: <tt>foo[rdoc-ref:RDoc::Markup::ToHtml#handle_regexp_RDOCLINK]</tt> +# links to foo[rdoc-ref:RDoc::Markup::ToHtml#handle_regexp_RDOCLINK]. +# - Constant: <tt>bar[rdoc-ref:RDoc::Markup::ToHtml::LIST_TYPE_TO_HTML]</tt> +# links to bar[rdoc-ref:RDoc::Markup::ToHtml::LIST_TYPE_TO_HTML]. +# - Attribute: <tt>baz[rdoc-ref:RDoc::Markup::ToHtml#code_object]</tt> +# links to baz[rdoc-ref:RDoc::Markup::ToHtml#code_object]. +# - Alias: <tt>bad[rdoc-ref:RDoc::MarkupReference#dummy_instance_alias]</tt> links to +# bad[rdoc-ref:RDoc::MarkupReference#dummy_instance_alias]. +# +# If the referenced item does not exist, no link is generated +# and entire <tt>rdoc-ref:</tt> square-bracketed clause is removed +# from the resulting text. +# +# - <tt>Nosuch[rdoc-ref:RDoc::Nosuch]</tt> is rendered as +# Nosuch[rdoc-ref:RDoc::Nosuch]. +# +# +# [<tt>rdoc-label</tt> Scheme] +# +# [Simple] +# +# You can specify a link target using this form, +# where the second part cites the id of an HTML element. +# +# This link refers to the constant +DUMMY_CONSTANT+ on this page: +# +# - <tt>{DUMMY_CONSTANT}[rdoc-label:DUMMY_CONSTANT]</tt> +# +# Thus: +# +# {DUMMY_CONSTANT}[rdoc-label:DUMMY_CONSTANT] +# +# [With Return] +# +# You can specify both a link target and a local label +# that can be used as the target for a return link. +# These two links refer to each other: +# +# - <tt>{go to addressee}[rdoc-label:addressee:sender]</tt> +# - <tt>{return to sender}[rdoc-label:sender:addressee]</tt> +# +# Thus: +# +# {go to addressee}[rdoc-label:addressee:sender] +# +# Some text. +# +# {return to sender}[rdoc-label:sender:addressee] +# +# [<tt>link:</tt> Scheme] +# +# - <tt>link:README_rdoc.html</tt> links to link:README_rdoc.html. +# +# [<tt>rdoc-image</tt> Scheme] +# +# Use the <tt>rdoc-image</tt> scheme to display an image that is also a link: +# +# # {rdoc-image:path/to/image}[link_target] +# +# - Link: <tt>{rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[https://www.ruby-lang.org]</tt> +# displays image <tt>https://www.ruby-lang.org/images/header-ruby-logo@2x.png</tt> +# as a link to <tt>https://www.ruby-lang.org</tt>. +# +# {rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[https://www.ruby-lang.org] +# +# A relative path as the target also works: +# +# - Link: <tt>{rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[./Alias.html]</tt> links to <tt>./Alias.html</tt> +# +# {rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[./Alias.html] +# +# === Escaping Text +# +# Text that would otherwise be interpreted as markup +# can be "escaped," so that it is not interpreted as markup; +# the escape character is the backslash (<tt>'\\'</tt>). +# +# In a verbatim text block or a code block, +# the escape character is always preserved: +# +# Example input: +# +# This is not verbatim text. +# +# This is verbatim text, with an escape character \. +# +# This is not a code block. +# +# def foo +# 'String with an escape character.' +# end +# +# Rendered HTML: +# +# >>> +# This is not verbatim text. +# +# This is verbatim text, with an escape character \. +# +# This is not a code block. +# +# def foo +# 'This is a code block with an escape character \.' +# end +# +# In typeface markup (italic, bold, or monofont), +# an escape character is preserved unless it is immediately +# followed by nested typeface markup. +# +# Example input: +# +# This list is about escapes; it contains: +# +# - <tt>Monofont text with unescaped nested _italic_</tt>. +# - <tt>Monofont text with escaped nested \_italic_</tt>. +# - <tt>Monofont text with an escape character \</tt>. +# +# Rendered HTML: +# +# >>> +# This list is about escapes; it contains: +# +# - <tt>Monofont text with unescaped nested _italic_</tt>. +# - <tt>Monofont text with escaped nested \_italic_</tt>. +# - <tt>Monofont text with an escape character \ </tt>. +# +# In other text-bearing blocks +# (paragraphs, block quotes, list items, headings): +# +# - A single escape character immediately followed by markup +# escapes the markup. +# - A single escape character followed by whitespace is preserved. +# - A single escape character anywhere else is ignored. +# - A double escape character is rendered as a single backslash. +# +# Example input: +# +# This list is about escapes; it contains: +# +# - An unescaped class name, RDoc, that will become a link. +# - An escaped class name, \RDoc, that will not become a link. +# - An escape character followed by whitespace \ . +# - An escape character \that is ignored. +# - A double escape character \\ that is rendered +# as a single backslash. +# +# Rendered HTML: +# +# >>> +# This list is about escapes; it contains: +# +# - An unescaped class name, RDoc, that will become a link. +# - An escaped class name, \RDoc, that will not become a link. +# - An escape character followed by whitespace \ . +# - An escape character \that is ignored. +# - A double escape character \\ that is rendered +# as a single backslash. +# +# == Documentation Derived from Ruby Code +# +# [Class] +# +# By default, \RDoc documents: +# +# - \Class name. +# - Parent class. +# - Singleton methods. +# - Instance methods. +# - Aliases. +# - Constants. +# - Attributes. +# +# [Module] +# +# By default, \RDoc documents: +# +# - \Module name. +# - \Singleton methods. +# - Instance methods. +# - Aliases. +# - Constants. +# - Attributes. +# +# [Method] +# +# By default, \RDoc documents: +# +# - \Method name. +# - Arguments. +# - Yielded values. +# +# See #method. +# +# [Alias] +# +# By default, \RDoc documents: +# +# - Alias name. +# - Aliased name. +# +# See #dummy_instance_alias and #dummy_instance_method. +# +# [Constant] +# +# By default, \RDoc documents: +# +# - \Constant name. +# +# See DUMMY_CONSTANT. +# +# [Attribute] +# +# By default, \RDoc documents: +# +# - Attribute name. +# - Attribute type (<tt>[R]</tt>, <tt>[W]</tt>, or <tt>[RW]</tt>) +# +# See #dummy_attribute. +# +class RDoc::MarkupReference + + # Example class. + class DummyClass; end + + # Example module. + module DummyModule; end + + # Example singleton method. + def self.dummy_singleton_method(foo, bar); end + + # Example instance method. + def dummy_instance_method(foo, bar); end; + + alias dummy_instance_alias dummy_instance_method + + # Example attribute. + attr_accessor :dummy_attribute + + alias dummy_attribute_alias dummy_attribute + + # Example constant. + DUMMY_CONSTANT = '' + + # :call-seq: + # call_seq_directive(foo, bar) + # Can be anything -> bar + # Also anything more -> baz or bat + # + # The <tt>:call-seq:</tt> directive overrides the actual calling sequence + # found in the Ruby code. + # + # - It can specify anything at all. + # - It can have multiple calling sequences. + # + # This one includes <tt>Can be anything -> foo</tt>, which is nonsense. + # + # Note that the "arrow" is two characters, hyphen and right angle-bracket, + # which is made into a single character in the HTML. + # + # Click on the calling sequence to see the code. + # + # Here is the <tt>:call-seq:</tt> directive given for the method: + # + # :call-seq: + # call_seq_directive(foo, bar) + # Can be anything -> bar + # Also anything more -> baz or bat + # + def call_seq_directive + nil + end + + # The <tt>:args:</tt> directive overrides the actual arguments found in the Ruby code. + # + # Click on the calling sequence to see the code. + # + def args_directive(foo, bar) # :args: baz + nil + end + + # The <tt>:yields:</tt> directive overrides the actual yield found in the Ruby code. + # + # Click on the calling sequence to see the code. + # + def yields_directive(foo, bar) # :yields: 'bat' + yield 'baz' + end + + # This method is documented only by \RDoc, except for these comments. + # + # Click on the calling sequence to see the code. + # + def method(foo, bar) + yield 'baz' + end + +end diff --git a/doc/regexp.rdoc b/doc/regexp.rdoc deleted file mode 100644 index 23fe7113b9..0000000000 --- a/doc/regexp.rdoc +++ /dev/null @@ -1,760 +0,0 @@ -# -*- mode: rdoc; coding: utf-8; fill-column: 74; -*- - -Regular expressions (<i>regexp</i>s) are patterns which describe the -contents of a string. They're used for testing whether a string contains a -given pattern, or extracting the portions that match. They are created -with the <tt>/</tt><i>pat</i><tt>/</tt> and -<tt>%r{</tt><i>pat</i><tt>}</tt> literals or the <tt>Regexp.new</tt> -constructor. - -A regexp is usually delimited with forward slashes (<tt>/</tt>). For -example: - - /hay/ =~ 'haystack' #=> 0 - /y/.match('haystack') #=> #<MatchData "y"> - -If a string contains the pattern it is said to <i>match</i>. A literal -string matches itself. - -Here 'haystack' does not contain the pattern 'needle', so it doesn't match: - - /needle/.match('haystack') #=> nil - -Here 'haystack' contains the pattern 'hay', so it matches: - - /hay/.match('haystack') #=> #<MatchData "hay"> - -Specifically, <tt>/st/</tt> requires that the string contains the letter -_s_ followed by the letter _t_, so it matches _haystack_, also. - -== <tt>=~</tt> and Regexp#match - -Pattern matching may be achieved by using <tt>=~</tt> operator or Regexp#match -method. - -=== <tt>=~</tt> operator - -<tt>=~</tt> is Ruby's basic pattern-matching operator. When one operand is a -regular expression and the other is a string then the regular expression is -used as a pattern to match against the string. (This operator is equivalently -defined by Regexp and String so the order of String and Regexp do not matter. -Other classes may have different implementations of <tt>=~</tt>.) If a match -is found, the operator returns index of first match in string, otherwise it -returns +nil+. - - /hay/ =~ 'haystack' #=> 0 - 'haystack' =~ /hay/ #=> 0 - /a/ =~ 'haystack' #=> 1 - /u/ =~ 'haystack' #=> nil - -Using <tt>=~</tt> operator with a String and Regexp the <tt>$~</tt> global -variable is set after a successful match. <tt>$~</tt> holds a MatchData -object. Regexp.last_match is equivalent to <tt>$~</tt>. - -=== Regexp#match method - -The #match method returns a MatchData object: - - /st/.match('haystack') #=> #<MatchData "st"> - -== Metacharacters and Escapes - -The following are <i>metacharacters</i> <tt>(</tt>, <tt>)</tt>, -<tt>[</tt>, <tt>]</tt>, <tt>{</tt>, <tt>}</tt>, <tt>.</tt>, <tt>?</tt>, -<tt>+</tt>, <tt>*</tt>. They have a specific meaning when appearing in a -pattern. To match them literally they must be backslash-escaped. To match -a backslash literally, backslash-escape it: <tt>\\\\</tt>. - - /1 \+ 2 = 3\?/.match('Does 1 + 2 = 3?') #=> #<MatchData "1 + 2 = 3?"> - /a\\\\b/.match('a\\\\b') #=> #<MatchData "a\\b"> - -Patterns behave like double-quoted strings and can contain the same -backslash escapes (the meaning of <tt>\s</tt> is different, however, -see below[#label-Character+Classes]). - - /\s\u{6771 4eac 90fd}/.match("Go to 東京都") - #=> #<MatchData " 東京都"> - -Arbitrary Ruby expressions can be embedded into patterns with the -<tt>#{...}</tt> construct. - - place = "東京都" - /#{place}/.match("Go to 東京都") - #=> #<MatchData "東京都"> - -== Character Classes - -A <i>character class</i> is delimited with square brackets (<tt>[</tt>, -<tt>]</tt>) and lists characters that may appear at that point in the -match. <tt>/[ab]/</tt> means _a_ or _b_, as opposed to <tt>/ab/</tt> which -means _a_ followed by _b_. - - /W[aeiou]rd/.match("Word") #=> #<MatchData "Word"> - -Within a character class the hyphen (<tt>-</tt>) is a metacharacter -denoting an inclusive range of characters. <tt>[abcd]</tt> is equivalent -to <tt>[a-d]</tt>. A range can be followed by another range, so -<tt>[abcdwxyz]</tt> is equivalent to <tt>[a-dw-z]</tt>. The order in which -ranges or individual characters appear inside a character class is -irrelevant. - - /[0-9a-f]/.match('9f') #=> #<MatchData "9"> - /[9f]/.match('9f') #=> #<MatchData "9"> - -If the first character of a character class is a caret (<tt>^</tt>) the -class is inverted: it matches any character _except_ those named. - - /[^a-eg-z]/.match('f') #=> #<MatchData "f"> - -A character class may contain another character class. By itself this -isn't useful because <tt>[a-z[0-9]]</tt> describes the same set as -<tt>[a-z0-9]</tt>. However, character classes also support the <tt>&&</tt> -operator which performs set intersection on its arguments. The two can be -combined as follows: - - /[a-w&&[^c-g]z]/ # ([a-w] AND ([^c-g] OR z)) - -This is equivalent to: - - /[abh-w]/ - -The following metacharacters also behave like character classes: - -* <tt>/./</tt> - Any character except a newline. -* <tt>/./m</tt> - Any character (the +m+ modifier enables multiline mode) -* <tt>/\w/</tt> - A word character (<tt>[a-zA-Z0-9_]</tt>) -* <tt>/\W/</tt> - A non-word character (<tt>[^a-zA-Z0-9_]</tt>). - Please take a look at {Bug #4044}[https://bugs.ruby-lang.org/issues/4044] if - using <tt>/\W/</tt> with the <tt>/i</tt> modifier. -* <tt>/\d/</tt> - A digit character (<tt>[0-9]</tt>) -* <tt>/\D/</tt> - A non-digit character (<tt>[^0-9]</tt>) -* <tt>/\h/</tt> - A hexdigit character (<tt>[0-9a-fA-F]</tt>) -* <tt>/\H/</tt> - A non-hexdigit character (<tt>[^0-9a-fA-F]</tt>) -* <tt>/\s/</tt> - A whitespace character: <tt>/[ \t\r\n\f\v]/</tt> -* <tt>/\S/</tt> - A non-whitespace character: <tt>/[^ \t\r\n\f\v]/</tt> -* <tt>/\R/</tt> - A linebreak: <tt>\n</tt>, <tt>\v</tt>, <tt>\f</tt>, <tt>\r</tt> - <tt>\u0085</tt> (NEXT LINE), <tt>\u2028</tt> (LINE SEPARATOR), <tt>\u2029</tt> (PARAGRAPH SEPARATOR) - or <tt>\r\n</tt>. - -POSIX <i>bracket expressions</i> are also similar to character classes. -They provide a portable alternative to the above, with the added benefit -that they encompass non-ASCII characters. For instance, <tt>/\d/</tt> -matches only the ASCII decimal digits (0-9); whereas <tt>/[[:digit:]]/</tt> -matches any character in the Unicode _Nd_ category. - -* <tt>/[[:alnum:]]/</tt> - Alphabetic and numeric character -* <tt>/[[:alpha:]]/</tt> - Alphabetic character -* <tt>/[[:blank:]]/</tt> - Space or tab -* <tt>/[[:cntrl:]]/</tt> - Control character -* <tt>/[[:digit:]]/</tt> - Digit -* <tt>/[[:graph:]]/</tt> - Non-blank character (excludes spaces, control - characters, and similar) -* <tt>/[[:lower:]]/</tt> - Lowercase alphabetical character -* <tt>/[[:print:]]/</tt> - Like [:graph:], but includes the space character -* <tt>/[[:punct:]]/</tt> - Punctuation character -* <tt>/[[:space:]]/</tt> - Whitespace character (<tt>[:blank:]</tt>, newline, - carriage return, etc.) -* <tt>/[[:upper:]]/</tt> - Uppercase alphabetical -* <tt>/[[:xdigit:]]/</tt> - Digit allowed in a hexadecimal number (i.e., - 0-9a-fA-F) - -Ruby also supports the following non-POSIX character classes: - -* <tt>/[[:word:]]/</tt> - A character in one of the following Unicode - general categories _Letter_, _Mark_, _Number_, - <i>Connector_Punctuation</i> -* <tt>/[[:ascii:]]/</tt> - A character in the ASCII character set - - # U+06F2 is "EXTENDED ARABIC-INDIC DIGIT TWO" - /[[:digit:]]/.match("\u06F2") #=> #<MatchData "\u{06F2}"> - /[[:upper:]][[:lower:]]/.match("Hello") #=> #<MatchData "He"> - /[[:xdigit:]][[:xdigit:]]/.match("A6") #=> #<MatchData "A6"> - -== Repetition - -The constructs described so far match a single character. They can be -followed by a repetition metacharacter to specify how many times they need -to occur. Such metacharacters are called <i>quantifiers</i>. - -* <tt>*</tt> - Zero or more times -* <tt>+</tt> - One or more times -* <tt>?</tt> - Zero or one times (optional) -* <tt>{</tt><i>n</i><tt>}</tt> - Exactly <i>n</i> times -* <tt>{</tt><i>n</i><tt>,}</tt> - <i>n</i> or more times -* <tt>{,</tt><i>m</i><tt>}</tt> - <i>m</i> or less times -* <tt>{</tt><i>n</i><tt>,</tt><i>m</i><tt>}</tt> - At least <i>n</i> and - at most <i>m</i> times - -At least one uppercase character ('H'), at least one lowercase character -('e'), two 'l' characters, then one 'o': - - "Hello".match(/[[:upper:]]+[[:lower:]]+l{2}o/) #=> #<MatchData "Hello"> - -=== Greedy match - -Repetition is <i>greedy</i> by default: as many occurrences as possible -are matched while still allowing the overall match to succeed. By -contrast, <i>lazy</i> matching makes the minimal amount of matches -necessary for overall success. Most greedy metacharacters can be made lazy -by following them with <tt>?</tt>. For the <tt>{n}</tt> pattern, because -it specifies an exact number of characters to match and not a variable -number of characters, the <tt>?</tt> metacharacter instead makes the -repeated pattern optional. - -Both patterns below match the string. The first uses a greedy quantifier so -'.+' matches '<a><b>'; the second uses a lazy quantifier so '.+?' matches -'<a>': - - /<.+>/.match("<a><b>") #=> #<MatchData "<a><b>"> - /<.+?>/.match("<a><b>") #=> #<MatchData "<a>"> - -=== Possessive match - -A quantifier followed by <tt>+</tt> matches <i>possessively</i>: once it -has matched it does not backtrack. They behave like greedy quantifiers, -but having matched they refuse to "give up" their match even if this -jeopardises the overall match. - - /<.*><.+>/.match("<a><b>") #=> #<MatchData "<a><b>"> - /<.*+><.+>/.match("<a><b>") #=> nil - /<.*><.++>/.match("<a><b>") #=> nil - -== Capturing - -Parentheses can be used for <i>capturing</i>. The text enclosed by the -<i>n</i>th group of parentheses can be subsequently referred to -with <i>n</i>. Within a pattern use the <i>backreference</i> -<tt>\n</tt> (e.g. <tt>\1</tt>); outside of the pattern use -<tt>MatchData[n]</tt> (e.g. <tt>MatchData[1]</tt>). - -In this example, <tt>'at'</tt> is captured by the first group of -parentheses, then referred to later with <tt>\1</tt>: - - /[csh](..) [csh]\1 in/.match("The cat sat in the hat") - #=> #<MatchData "cat sat in" 1:"at"> - -Regexp#match returns a MatchData object which makes the captured text -available with its #[] method: - - /[csh](..) [csh]\1 in/.match("The cat sat in the hat")[1] #=> 'at' - -While Ruby supports an arbitrary number of numbered captured groups, -only groups 1-9 are supported using the <tt>\n</tt> backreference -syntax. - -Ruby also supports <tt>\0</tt> as a special backreference, which -references the entire matched string. This is also available at -<tt>MatchData[0]</tt>. Note that the <tt>\0</tt> backreference cannot -be used inside the regexp, as backreferences can only be used after the -end of the capture group, and the <tt>\0</tt> backreference uses the -implicit capture group of the entire match. However, you can use -this backreference when doing substitution: - - "The cat sat in the hat".gsub(/[csh]at/, '\0s') - # => "The cats sats in the hats" - -=== Named captures - -Capture groups can be referred to by name when defined with the -<tt>(?<</tt><i>name</i><tt>>)</tt> or <tt>(?'</tt><i>name</i><tt>')</tt> -constructs. - - /\$(?<dollars>\d+)\.(?<cents>\d+)/.match("$3.67") - #=> #<MatchData "$3.67" dollars:"3" cents:"67"> - /\$(?<dollars>\d+)\.(?<cents>\d+)/.match("$3.67")[:dollars] #=> "3" - -Named groups can be backreferenced with <tt>\k<</tt><i>name</i><tt>></tt>, -where _name_ is the group name. - - /(?<vowel>[aeiou]).\k<vowel>.\k<vowel>/.match('ototomy') - #=> #<MatchData "ototo" vowel:"o"> - -*Note*: A regexp can't use named backreferences and numbered -backreferences simultaneously. Also, if a named capture is used in a -regexp, then parentheses used for grouping which would otherwise result -in a unnamed capture are treated as non-capturing. - - /(\w)(\w)/.match("ab").captures # => ["a", "b"] - /(\w)(\w)/.match("ab").named_captures # => {} - - /(?<c>\w)(\w)/.match("ab").captures # => ["a"] - /(?<c>\w)(\w)/.match("ab").named_captures # => {"c"=>"a"} - -When named capture groups are used with a literal regexp on the left-hand -side of an expression and the <tt>=~</tt> operator, the captured text is -also assigned to local variables with corresponding names. - - /\$(?<dollars>\d+)\.(?<cents>\d+)/ =~ "$3.67" #=> 0 - dollars #=> "3" - -== Grouping - -Parentheses also <i>group</i> the terms they enclose, allowing them to be -quantified as one <i>atomic</i> whole. - -The pattern below matches a vowel followed by 2 word characters: - - /[aeiou]\w{2}/.match("Caenorhabditis elegans") #=> #<MatchData "aen"> - -Whereas the following pattern matches a vowel followed by a word character, -twice, i.e. <tt>[aeiou]\w[aeiou]\w</tt>: 'enor'. - - /([aeiou]\w){2}/.match("Caenorhabditis elegans") - #=> #<MatchData "enor" 1:"or"> - -The <tt>(?:</tt>...<tt>)</tt> construct provides grouping without -capturing. That is, it combines the terms it contains into an atomic whole -without creating a backreference. This benefits performance at the slight -expense of readability. - -The first group of parentheses captures 'n' and the second 'ti'. The second -group is referred to later with the backreference <tt>\2</tt>: - - /I(n)ves(ti)ga\2ons/.match("Investigations") - #=> #<MatchData "Investigations" 1:"n" 2:"ti"> - -The first group of parentheses is now made non-capturing with '?:', so it -still matches 'n', but doesn't create the backreference. Thus, the -backreference <tt>\1</tt> now refers to 'ti'. - - /I(?:n)ves(ti)ga\1ons/.match("Investigations") - #=> #<MatchData "Investigations" 1:"ti"> - -=== Atomic Grouping - -Grouping can be made <i>atomic</i> with -<tt>(?></tt><i>pat</i><tt>)</tt>. This causes the subexpression <i>pat</i> -to be matched independently of the rest of the expression such that what -it matches becomes fixed for the remainder of the match, unless the entire -subexpression must be abandoned and subsequently revisited. In this -way <i>pat</i> is treated as a non-divisible whole. Atomic grouping is -typically used to optimise patterns so as to prevent the regular -expression engine from backtracking needlessly. - -The <tt>"</tt> in the pattern below matches the first character of the string, -then <tt>.*</tt> matches <i>Quote"</i>. This causes the overall match to fail, -so the text matched by <tt>.*</tt> is backtracked by one position, which -leaves the final character of the string available to match <tt>"</tt> - - /".*"/.match('"Quote"') #=> #<MatchData "\"Quote\""> - -If <tt>.*</tt> is grouped atomically, it refuses to backtrack <i>Quote"</i>, -even though this means that the overall match fails - - /"(?>.*)"/.match('"Quote"') #=> nil - -== Subexpression Calls - -The <tt>\g<</tt><i>name</i><tt>></tt> syntax matches the previous -subexpression named _name_, which can be a group name or number, again. -This differs from backreferences in that it re-executes the group rather -than simply trying to re-match the same text. - -This pattern matches a <i>(</i> character and assigns it to the <tt>paren</tt> -group, tries to call that the <tt>paren</tt> sub-expression again but fails, -then matches a literal <i>)</i>: - - /\A(?<paren>\(\g<paren>*\))*\z/ =~ '()' - - - /\A(?<paren>\(\g<paren>*\))*\z/ =~ '(())' #=> 0 - # ^1 - # ^2 - # ^3 - # ^4 - # ^5 - # ^6 - # ^7 - # ^8 - # ^9 - # ^10 - -1. Matches at the beginning of the string, i.e. before the first - character. -2. Enters a named capture group called <tt>paren</tt> -3. Matches a literal <i>(</i>, the first character in the string -4. Calls the <tt>paren</tt> group again, i.e. recurses back to the - second step -5. Re-enters the <tt>paren</tt> group -6. Matches a literal <i>(</i>, the second character in the - string -7. Try to call <tt>paren</tt> a third time, but fail because - doing so would prevent an overall successful match -8. Match a literal <i>)</i>, the third character in the string. - Marks the end of the second recursive call -9. Match a literal <i>)</i>, the fourth character in the string -10. Match the end of the string - -== Alternation - -The vertical bar metacharacter (<tt>|</tt>) combines several expressions into -a single one that matches any of the expressions. Each expression is an -<i>alternative</i>. - - /\w(and|or)\w/.match("Feliformia") #=> #<MatchData "form" 1:"or"> - /\w(and|or)\w/.match("furandi") #=> #<MatchData "randi" 1:"and"> - /\w(and|or)\w/.match("dissemblance") #=> nil - -== Character Properties - -The <tt>\p{}</tt> construct matches characters with the named property, -much like POSIX bracket classes. - -* <tt>/\p{Alnum}/</tt> - Alphabetic and numeric character -* <tt>/\p{Alpha}/</tt> - Alphabetic character -* <tt>/\p{Blank}/</tt> - Space or tab -* <tt>/\p{Cntrl}/</tt> - Control character -* <tt>/\p{Digit}/</tt> - Digit -* <tt>/\p{Graph}/</tt> - Non-blank character (excludes spaces, control - characters, and similar) -* <tt>/\p{Lower}/</tt> - Lowercase alphabetical character -* <tt>/\p{Print}/</tt> - Like <tt>\p{Graph}</tt>, but includes the space character -* <tt>/\p{Punct}/</tt> - Punctuation character -* <tt>/\p{Space}/</tt> - Whitespace character (<tt>[:blank:]</tt>, newline, - carriage return, etc.) -* <tt>/\p{Upper}/</tt> - Uppercase alphabetical -* <tt>/\p{XDigit}/</tt> - Digit allowed in a hexadecimal number (i.e., 0-9a-fA-F) -* <tt>/\p{Word}/</tt> - A member of one of the following Unicode general - category <i>Letter</i>, <i>Mark</i>, <i>Number</i>, - <i>Connector\_Punctuation</i> -* <tt>/\p{ASCII}/</tt> - A character in the ASCII character set -* <tt>/\p{Any}/</tt> - Any Unicode character (including unassigned - characters) -* <tt>/\p{Assigned}/</tt> - An assigned character - -A Unicode character's <i>General Category</i> value can also be matched -with <tt>\p{</tt><i>Ab</i><tt>}</tt> where <i>Ab</i> is the category's -abbreviation as described below: - -* <tt>/\p{L}/</tt> - 'Letter' -* <tt>/\p{Ll}/</tt> - 'Letter: Lowercase' -* <tt>/\p{Lm}/</tt> - 'Letter: Mark' -* <tt>/\p{Lo}/</tt> - 'Letter: Other' -* <tt>/\p{Lt}/</tt> - 'Letter: Titlecase' -* <tt>/\p{Lu}/</tt> - 'Letter: Uppercase -* <tt>/\p{Lo}/</tt> - 'Letter: Other' -* <tt>/\p{M}/</tt> - 'Mark' -* <tt>/\p{Mn}/</tt> - 'Mark: Nonspacing' -* <tt>/\p{Mc}/</tt> - 'Mark: Spacing Combining' -* <tt>/\p{Me}/</tt> - 'Mark: Enclosing' -* <tt>/\p{N}/</tt> - 'Number' -* <tt>/\p{Nd}/</tt> - 'Number: Decimal Digit' -* <tt>/\p{Nl}/</tt> - 'Number: Letter' -* <tt>/\p{No}/</tt> - 'Number: Other' -* <tt>/\p{P}/</tt> - 'Punctuation' -* <tt>/\p{Pc}/</tt> - 'Punctuation: Connector' -* <tt>/\p{Pd}/</tt> - 'Punctuation: Dash' -* <tt>/\p{Ps}/</tt> - 'Punctuation: Open' -* <tt>/\p{Pe}/</tt> - 'Punctuation: Close' -* <tt>/\p{Pi}/</tt> - 'Punctuation: Initial Quote' -* <tt>/\p{Pf}/</tt> - 'Punctuation: Final Quote' -* <tt>/\p{Po}/</tt> - 'Punctuation: Other' -* <tt>/\p{S}/</tt> - 'Symbol' -* <tt>/\p{Sm}/</tt> - 'Symbol: Math' -* <tt>/\p{Sc}/</tt> - 'Symbol: Currency' -* <tt>/\p{Sc}/</tt> - 'Symbol: Currency' -* <tt>/\p{Sk}/</tt> - 'Symbol: Modifier' -* <tt>/\p{So}/</tt> - 'Symbol: Other' -* <tt>/\p{Z}/</tt> - 'Separator' -* <tt>/\p{Zs}/</tt> - 'Separator: Space' -* <tt>/\p{Zl}/</tt> - 'Separator: Line' -* <tt>/\p{Zp}/</tt> - 'Separator: Paragraph' -* <tt>/\p{C}/</tt> - 'Other' -* <tt>/\p{Cc}/</tt> - 'Other: Control' -* <tt>/\p{Cf}/</tt> - 'Other: Format' -* <tt>/\p{Cn}/</tt> - 'Other: Not Assigned' -* <tt>/\p{Co}/</tt> - 'Other: Private Use' -* <tt>/\p{Cs}/</tt> - 'Other: Surrogate' - -Lastly, <tt>\p{}</tt> matches a character's Unicode <i>script</i>. The -following scripts are supported: <i>Arabic</i>, <i>Armenian</i>, -<i>Balinese</i>, <i>Bengali</i>, <i>Bopomofo</i>, <i>Braille</i>, -<i>Buginese</i>, <i>Buhid</i>, <i>Canadian_Aboriginal</i>, <i>Carian</i>, -<i>Cham</i>, <i>Cherokee</i>, <i>Common</i>, <i>Coptic</i>, -<i>Cuneiform</i>, <i>Cypriot</i>, <i>Cyrillic</i>, <i>Deseret</i>, -<i>Devanagari</i>, <i>Ethiopic</i>, <i>Georgian</i>, <i>Glagolitic</i>, -<i>Gothic</i>, <i>Greek</i>, <i>Gujarati</i>, <i>Gurmukhi</i>, <i>Han</i>, -<i>Hangul</i>, <i>Hanunoo</i>, <i>Hebrew</i>, <i>Hiragana</i>, -<i>Inherited</i>, <i>Kannada</i>, <i>Katakana</i>, <i>Kayah_Li</i>, -<i>Kharoshthi</i>, <i>Khmer</i>, <i>Lao</i>, <i>Latin</i>, <i>Lepcha</i>, -<i>Limbu</i>, <i>Linear_B</i>, <i>Lycian</i>, <i>Lydian</i>, -<i>Malayalam</i>, <i>Mongolian</i>, <i>Myanmar</i>, <i>New_Tai_Lue</i>, -<i>Nko</i>, <i>Ogham</i>, <i>Ol_Chiki</i>, <i>Old_Italic</i>, -<i>Old_Persian</i>, <i>Oriya</i>, <i>Osmanya</i>, <i>Phags_Pa</i>, -<i>Phoenician</i>, <i>Rejang</i>, <i>Runic</i>, <i>Saurashtra</i>, -<i>Shavian</i>, <i>Sinhala</i>, <i>Sundanese</i>, <i>Syloti_Nagri</i>, -<i>Syriac</i>, <i>Tagalog</i>, <i>Tagbanwa</i>, <i>Tai_Le</i>, -<i>Tamil</i>, <i>Telugu</i>, <i>Thaana</i>, <i>Thai</i>, <i>Tibetan</i>, -<i>Tifinagh</i>, <i>Ugaritic</i>, <i>Vai</i>, and <i>Yi</i>. - -Unicode codepoint U+06E9 is named "ARABIC PLACE OF SAJDAH" and belongs to the -Arabic script: - - /\p{Arabic}/.match("\u06E9") #=> #<MatchData "\u06E9"> - -All character properties can be inverted by prefixing their name with a -caret (<tt>^</tt>). - -Letter 'A' is not in the Unicode Ll (Letter; Lowercase) category, so this -match succeeds: - - /\p{^Ll}/.match("A") #=> #<MatchData "A"> - -== Anchors - -Anchors are metacharacter that match the zero-width positions between -characters, <i>anchoring</i> the match to a specific position. - -* <tt>^</tt> - Matches beginning of line -* <tt>$</tt> - Matches end of line -* <tt>\A</tt> - Matches beginning of string. -* <tt>\Z</tt> - Matches end of string. If string ends with a newline, - it matches just before newline -* <tt>\z</tt> - Matches end of string -* <tt>\G</tt> - Matches first matching position: - - In methods like <tt>String#gsub</tt> and <tt>String#scan</tt>, it changes on each iteration. - It initially matches the beginning of subject, and in each following iteration it matches where the last match finished. - - " a b c".gsub(/ /, '_') #=> "____a_b_c" - " a b c".gsub(/\G /, '_') #=> "____a b c" - - In methods like <tt>Regexp#match</tt> and <tt>String#match</tt> that take an (optional) offset, it matches where the search begins. - - "hello, world".match(/,/, 3) #=> #<MatchData ","> - "hello, world".match(/\G,/, 3) #=> nil - -* <tt>\b</tt> - Matches word boundaries when outside brackets; - backspace (0x08) when inside brackets -* <tt>\B</tt> - Matches non-word boundaries -* <tt>(?=</tt><i>pat</i><tt>)</tt> - <i>Positive lookahead</i> assertion: - ensures that the following characters match <i>pat</i>, but doesn't - include those characters in the matched text -* <tt>(?!</tt><i>pat</i><tt>)</tt> - <i>Negative lookahead</i> assertion: - ensures that the following characters do not match <i>pat</i>, but - doesn't include those characters in the matched text -* <tt>(?<=</tt><i>pat</i><tt>)</tt> - <i>Positive lookbehind</i> - assertion: ensures that the preceding characters match <i>pat</i>, but - doesn't include those characters in the matched text -* <tt>(?<!</tt><i>pat</i><tt>)</tt> - <i>Negative lookbehind</i> - assertion: ensures that the preceding characters do not match - <i>pat</i>, but doesn't include those characters in the matched text -* <tt>\K</tt> - Uses an positive lookbehind of the content preceding - <tt>\K</tt> in the regexp. For example, the following two regexps are - almost equivalent: - - /ab\Kc/ - /(?<=ab)c/ - - As are the following two regexps: - - /(a)\K(b)\Kc/ - /(?<=(?<=(a))(b))c/ - -If a pattern isn't anchored it can begin at any point in the string: - - /real/.match("surrealist") #=> #<MatchData "real"> - -Anchoring the pattern to the beginning of the string forces the match to start -there. 'real' doesn't occur at the beginning of the string, so now the match -fails: - - /\Areal/.match("surrealist") #=> nil - -The match below fails because although 'Demand' contains 'and', the pattern -does not occur at a word boundary. - - /\band/.match("Demand") - -Whereas in the following example 'and' has been anchored to a non-word -boundary so instead of matching the first 'and' it matches from the fourth -letter of 'demand' instead: - - /\Band.+/.match("Supply and demand curve") #=> #<MatchData "and curve"> - -The pattern below uses positive lookahead and positive lookbehind to match -text appearing in <b></b> tags without including the tags in the match: - - /(?<=<b>)\w+(?=<\/b>)/.match("Fortune favours the <b>bold</b>") - #=> #<MatchData "bold"> - -== Options - -The end delimiter for a regexp can be followed by one or more single-letter -options which control how the pattern can match. - -* <tt>/pat/i</tt> - Ignore case -* <tt>/pat/m</tt> - Treat a newline as a character matched by <tt>.</tt> -* <tt>/pat/x</tt> - Ignore whitespace and comments in the pattern -* <tt>/pat/o</tt> - Perform <tt>#{}</tt> interpolation only once - -<tt>i</tt>, <tt>m</tt>, and <tt>x</tt> can also be applied on the -subexpression level with the -<tt>(?</tt><i>on</i><tt>-</tt><i>off</i><tt>)</tt> construct, which -enables options <i>on</i>, and disables options <i>off</i> for the -expression enclosed by the parentheses: - - /a(?i:b)c/.match('aBc') #=> #<MatchData "aBc"> - /a(?-i:b)c/i.match('ABC') #=> nil - -Additionally, these options can also be toggled for the remainder of the -pattern: - - /a(?i)bc/.match('abC') #=> #<MatchData "abC"> - -Options may also be used with <tt>Regexp.new</tt>: - - Regexp.new("abc", Regexp::IGNORECASE) #=> /abc/i - Regexp.new("abc", Regexp::MULTILINE) #=> /abc/m - Regexp.new("abc # Comment", Regexp::EXTENDED) #=> /abc # Comment/x - Regexp.new("abc", Regexp::IGNORECASE | Regexp::MULTILINE) #=> /abc/mi - -== Free-Spacing Mode and Comments - -As mentioned above, the <tt>x</tt> option enables <i>free-spacing</i> -mode. Literal white space inside the pattern is ignored, and the -octothorpe (<tt>#</tt>) character introduces a comment until the end of -the line. This allows the components of the pattern to be organized in a -potentially more readable fashion. - -A contrived pattern to match a number with optional decimal places: - - float_pat = /\A - [[:digit:]]+ # 1 or more digits before the decimal point - (\. # Decimal point - [[:digit:]]+ # 1 or more digits after the decimal point - )? # The decimal point and following digits are optional - \Z/x - float_pat.match('3.14') #=> #<MatchData "3.14" 1:".14"> - -There are a number of strategies for matching whitespace: - -* Use a pattern such as <tt>\s</tt> or <tt>\p{Space}</tt>. -* Use escaped whitespace such as <tt>\ </tt>, i.e. a space preceded by a backslash. -* Use a character class such as <tt>[ ]</tt>. - -Comments can be included in a non-<tt>x</tt> pattern with the -<tt>(?#</tt><i>comment</i><tt>)</tt> construct, where <i>comment</i> is -arbitrary text ignored by the regexp engine. - -Comments in regexp literals cannot include unescaped terminator -characters. - -== Encoding - -Regular expressions are assumed to use the source encoding. This can be -overridden with one of the following modifiers. - -* <tt>/</tt><i>pat</i><tt>/u</tt> - UTF-8 -* <tt>/</tt><i>pat</i><tt>/e</tt> - EUC-JP -* <tt>/</tt><i>pat</i><tt>/s</tt> - Windows-31J -* <tt>/</tt><i>pat</i><tt>/n</tt> - ASCII-8BIT - -A regexp can be matched against a string when they either share an -encoding, or the regexp's encoding is _US-ASCII_ and the string's encoding -is ASCII-compatible. - -If a match between incompatible encodings is attempted an -<tt>Encoding::CompatibilityError</tt> exception is raised. - -The <tt>Regexp#fixed_encoding?</tt> predicate indicates whether the regexp -has a <i>fixed</i> encoding, that is one incompatible with ASCII. A -regexp's encoding can be explicitly fixed by supplying -<tt>Regexp::FIXEDENCODING</tt> as the second argument of -<tt>Regexp.new</tt>: - - r = Regexp.new("a".force_encoding("iso-8859-1"),Regexp::FIXEDENCODING) - r =~ "a\u3042" - # raises Encoding::CompatibilityError: incompatible encoding regexp match - # (ISO-8859-1 regexp with UTF-8 string) - -== Special global variables - -Pattern matching sets some global variables : -* <tt>$~</tt> is equivalent to Regexp.last_match; -* <tt>$&</tt> contains the complete matched text; -* <tt>$`</tt> contains string before match; -* <tt>$'</tt> contains string after match; -* <tt>$1</tt>, <tt>$2</tt> and so on contain text matching first, second, etc - capture group; -* <tt>$+</tt> contains last capture group. - -Example: - - m = /s(\w{2}).*(c)/.match('haystack') #=> #<MatchData "stac" 1:"ta" 2:"c"> - $~ #=> #<MatchData "stac" 1:"ta" 2:"c"> - Regexp.last_match #=> #<MatchData "stac" 1:"ta" 2:"c"> - - $& #=> "stac" - # same as m[0] - $` #=> "hay" - # same as m.pre_match - $' #=> "k" - # same as m.post_match - $1 #=> "ta" - # same as m[1] - $2 #=> "c" - # same as m[2] - $3 #=> nil - # no third group in pattern - $+ #=> "c" - # same as m[-1] - -These global variables are thread-local and method-local variables. - -== Performance - -Certain pathological combinations of constructs can lead to abysmally bad -performance. - -Consider a string of 25 <i>a</i>s, a <i>d</i>, 4 <i>a</i>s, and a -<i>c</i>. - - s = 'a' * 25 + 'd' + 'a' * 4 + 'c' - #=> "aaaaaaaaaaaaaaaaaaaaaaaaadaaaac" - -The following patterns match instantly as you would expect: - - /(b|a)/ =~ s #=> 0 - /(b|a+)/ =~ s #=> 0 - /(b|a+)*/ =~ s #=> 0 - -However, the following pattern takes appreciably longer: - - /(b|a+)*c/ =~ s #=> 26 - -This happens because an atom in the regexp is quantified by both an -immediate <tt>+</tt> and an enclosing <tt>*</tt> with nothing to -differentiate which is in control of any particular character. The -nondeterminism that results produces super-linear performance. (Consult -<i>Mastering Regular Expressions</i> (3rd ed.), pp 222, by -<i>Jeffery Friedl</i>, for an in-depth analysis). This particular case -can be fixed by use of atomic grouping, which prevents the unnecessary -backtracking: - - (start = Time.now) && /(b|a+)*c/ =~ s && (Time.now - start) - #=> 24.702736882 - (start = Time.now) && /(?>b|a+)*c/ =~ s && (Time.now - start) - #=> 0.000166571 - -A similar case is typified by the following example, which takes -approximately 60 seconds to execute for me: - -Match a string of 29 <i>a</i>s against a pattern of 29 optional <i>a</i>s -followed by 29 mandatory <i>a</i>s: - - Regexp.new('a?' * 29 + 'a' * 29) =~ 'a' * 29 - -The 29 optional <i>a</i>s match the string, but this prevents the 29 -mandatory <i>a</i>s that follow from matching. Ruby must then backtrack -repeatedly so as to satisfy as many of the optional matches as it can -while still matching the mandatory 29. It is plain to us that none of the -optional matches can succeed, but this fact unfortunately eludes Ruby. - -The best way to improve performance is to significantly reduce the amount of -backtracking needed. For this case, instead of individually matching 29 -optional <i>a</i>s, a range of optional <i>a</i>s can be matched all at once -with <i>a{0,29}</i>: - - Regexp.new('a{0,29}' + 'a' * 29) =~ 'a' * 29 - diff --git a/doc/regexp/methods.rdoc b/doc/regexp/methods.rdoc new file mode 100644 index 0000000000..356156ac9a --- /dev/null +++ b/doc/regexp/methods.rdoc @@ -0,0 +1,41 @@ +== \Regexp Methods + +Each of these Ruby core methods can accept a regexp as an argument: + +- Enumerable#all? +- Enumerable#any? +- Enumerable#grep +- Enumerable#grep_v +- Enumerable#none? +- Enumerable#one? +- Enumerable#slice_after +- Enumerable#slice_before +- Regexp#=~ +- Regexp#match +- Regexp#match? +- Regexp.new +- Regexp.union +- String#=~ +- String#[]= +- String#byteindex +- String#byterindex +- String#gsub +- String#gsub! +- String#index +- String#match +- String#match? +- String#partition +- String#rindex +- String#rpartition +- String#scan +- String#slice +- String#slice! +- String#split +- String#start_with? +- String#sub +- String#sub! +- Symbol#=~ +- Symbol#match +- Symbol#match? +- Symbol#slice +- Symbol#start_with? diff --git a/doc/regexp/unicode_properties.rdoc b/doc/regexp/unicode_properties.rdoc new file mode 100644 index 0000000000..a1d7ecc380 --- /dev/null +++ b/doc/regexp/unicode_properties.rdoc @@ -0,0 +1,678 @@ +== \Regexps Based on Unicode Properties + +The properties shown here are those currently supported in Ruby. +Older versions may not support all of these. + +=== POSIX brackets + +- <tt>\p{ASCII}</tt> +- <tt>\p{Alnum}</tt> +- <tt>\p{Alphabetic}</tt>, <tt>\p{Alpha}</tt> +- <tt>\p{Blank}</tt> +- <tt>\p{Cntrl}</tt> +- <tt>\p{Digit}</tt> +- <tt>\p{Graph}</tt> +- <tt>\p{Lowercase}</tt>, <tt>\p{Lower}</tt> +- <tt>\p{Print}</tt> +- <tt>\p{Punct}</tt> +- <tt>\p{Space}</tt> +- <tt>\p{Uppercase}</tt>, <tt>\p{Upper}</tt> +- <tt>\p{Word}</tt> +- <tt>\p{XDigit}</tt> +- <tt>\p{XPosixPunct}</tt> + +=== Special + +- <tt>\p{Any}</tt> +- <tt>\p{Assigned}</tt> + +=== Major and General Categories + +- <tt>\p{Cased_Letter}</tt>, <tt>\p{LC}</tt> +- <tt>\p{Close_Punctuation}</tt>, <tt>\p{Pe}</tt> +- <tt>\p{Connector_Punctuation}</tt>, <tt>\p{Pc}</tt> +- <tt>\p{Control}</tt>, <tt>\p{Cc}</tt> +- <tt>\p{Currency_Symbol}</tt>, <tt>\p{Sc}</tt> +- <tt>\p{Dash_Punctuation}</tt>, <tt>\p{Pd}</tt> +- <tt>\p{Decimal_Number}</tt>, <tt>\p{Nd}</tt> +- <tt>\p{Enclosing_Mark}</tt>, <tt>\p{Me}</tt> +- <tt>\p{Final_Punctuation}</tt>, <tt>\p{Pf}</tt> +- <tt>\p{Format}</tt>, <tt>\p{Cf}</tt> +- <tt>\p{Initial_Punctuation}</tt>, <tt>\p{Pi}</tt> +- <tt>\p{Letter}</tt>, <tt>\p{L}</tt> +- <tt>\p{Letter_Number}</tt>, <tt>\p{Nl}</tt> +- <tt>\p{Line_Separator}</tt>, <tt>\p{Zl}</tt> +- <tt>\p{Lowercase_Letter}</tt>, <tt>\p{Ll}</tt> +- <tt>\p{Mark}</tt>, <tt>\p{M}</tt> +- <tt>\p{Math_Symbol}</tt>, <tt>\p{Sm}</tt> +- <tt>\p{Modifier_Letter}</tt>, <tt>\p{Lm}</tt> +- <tt>\p{Modifier_Symbol}</tt>, <tt>\p{Sk}</tt> +- <tt>\p{Nonspacing_Mark}</tt>, <tt>\p{Mn}</tt> +- <tt>\p{Number}</tt>, <tt>\p{N}</tt> +- <tt>\p{Open_Punctuation}</tt>, <tt>\p{Ps}</tt> +- <tt>\p{Other}</tt>, <tt>\p{C}</tt> +- <tt>\p{Other_Letter}</tt>, <tt>\p{Lo}</tt> +- <tt>\p{Other_Number}</tt>, <tt>\p{No}</tt> +- <tt>\p{Other_Punctuation}</tt>, <tt>\p{Po}</tt> +- <tt>\p{Other_Symbol}</tt>, <tt>\p{So}</tt> +- <tt>\p{Paragraph_Separator}</tt>, <tt>\p{Zp}</tt> +- <tt>\p{Private_Use}</tt>, <tt>\p{Co}</tt> +- <tt>\p{Punctuation}</tt>, <tt>\p{P}</tt> +- <tt>\p{Separator}</tt>, <tt>\p{Z}</tt> +- <tt>\p{Space_Separator}</tt>, <tt>\p{Zs}</tt> +- <tt>\p{Spacing_Mark}</tt>, <tt>\p{Mc}</tt> +- <tt>\p{Surrogate}</tt>, <tt>\p{Cs}</tt> +- <tt>\p{Symbol}</tt>, <tt>\p{S}</tt> +- <tt>\p{Titlecase_Letter}</tt>, <tt>\p{Lt}</tt> +- <tt>\p{Unassigned}</tt>, <tt>\p{Cn}</tt> +- <tt>\p{Uppercase_Letter}</tt>, <tt>\p{Lu}</tt> + +=== Prop List + +- <tt>\p{ASCII_Hex_Digit}</tt>, <tt>\p{AHex}</tt> +- <tt>\p{Bidi_Control}</tt>, <tt>\p{Bidi_C}</tt> +- <tt>\p{Dash}</tt> +- <tt>\p{Deprecated}</tt>, <tt>\p{Dep}</tt> +- <tt>\p{Diacritic}</tt>, <tt>\p{Dia}</tt> +- <tt>\p{Extender}</tt>, <tt>\p{Ext}</tt> +- <tt>\p{Hex_Digit}</tt>, <tt>\p{Hex}</tt> +- <tt>\p{Hyphen}</tt> +- <tt>\p{IDS_Binary_Operator}</tt>, <tt>\p{IDSB}</tt> +- <tt>\p{IDS_Trinary_Operator}</tt>, <tt>\p{IDST}</tt> +- <tt>\p{Ideographic}</tt>, <tt>\p{Ideo}</tt> +- <tt>\p{Join_Control}</tt>, <tt>\p{Join_C}</tt> +- <tt>\p{Logical_Order_Exception}</tt>, <tt>\p{LOE}</tt> +- <tt>\p{Noncharacter_Code_Point}</tt>, <tt>\p{NChar}</tt> +- <tt>\p{Other_Alphabetic}</tt>, <tt>\p{OAlpha}</tt> +- <tt>\p{Other_Default_Ignorable_Code_Point}</tt>, <tt>\p{ODI}</tt> +- <tt>\p{Other_Grapheme_Extend}</tt>, <tt>\p{OGr_Ext}</tt> +- <tt>\p{Other_ID_Continue}</tt>, <tt>\p{OIDC}</tt> +- <tt>\p{Other_ID_Start}</tt>, <tt>\p{OIDS}</tt> +- <tt>\p{Other_Lowercase}</tt>, <tt>\p{OLower}</tt> +- <tt>\p{Other_Math}</tt>, <tt>\p{OMath}</tt> +- <tt>\p{Other_Uppercase}</tt>, <tt>\p{OUpper}</tt> +- <tt>\p{Pattern_Syntax}</tt>, <tt>\p{Pat_Syn}</tt> +- <tt>\p{Pattern_White_Space}</tt>, <tt>\p{Pat_WS}</tt> +- <tt>\p{Prepended_Concatenation_Mark}</tt>, <tt>\p{PCM}</tt> +- <tt>\p{Quotation_Mark}</tt>, <tt>\p{QMark}</tt> +- <tt>\p{Radical}</tt> +- <tt>\p{Regional_Indicator}</tt>, <tt>\p{RI}</tt> +- <tt>\p{Sentence_Terminal}</tt>, <tt>\p{STerm}</tt> +- <tt>\p{Soft_Dotted}</tt>, <tt>\p{SD}</tt> +- <tt>\p{Terminal_Punctuation}</tt>, <tt>\p{Term}</tt> +- <tt>\p{Unified_Ideograph}</tt>, <tt>\p{UIdeo}</tt> +- <tt>\p{Variation_Selector}</tt>, <tt>\p{VS}</tt> +- <tt>\p{White_Space}</tt>, <tt>\p{WSpace}</tt> + +=== Derived Core Properties + +- <tt>\p{Alphabetic}</tt>, <tt>\p{Alpha}</tt> +- <tt>\p{Case_Ignorable}</tt>, <tt>\p{CI}</tt> +- <tt>\p{Cased}</tt> +- <tt>\p{Changes_When_Casefolded}</tt>, <tt>\p{CWCF}</tt> +- <tt>\p{Changes_When_Casemapped}</tt>, <tt>\p{CWCM}</tt> +- <tt>\p{Changes_When_Lowercased}</tt>, <tt>\p{CWL}</tt> +- <tt>\p{Changes_When_Titlecased}</tt>, <tt>\p{CWT}</tt> +- <tt>\p{Changes_When_Uppercased}</tt>, <tt>\p{CWU}</tt> +- <tt>\p{Default_Ignorable_Code_Point}</tt>, <tt>\p{DI}</tt> +- <tt>\p{Grapheme_Base}</tt>, <tt>\p{Gr_Base}</tt> +- <tt>\p{Grapheme_Extend}</tt>, <tt>\p{Gr_Ext}</tt> +- <tt>\p{Grapheme_Link}</tt>, <tt>\p{Gr_Link}</tt> +- <tt>\p{ID_Continue}</tt>, <tt>\p{IDC}</tt> +- <tt>\p{ID_Start}</tt>, <tt>\p{IDS}</tt> +- <tt>\p{Lowercase}</tt>, <tt>\p{Lower}</tt> +- <tt>\p{Math}</tt> +- <tt>\p{Uppercase}</tt>, <tt>\p{Upper}</tt> +- <tt>\p{XID_Continue}</tt>, <tt>\p{XIDC}</tt> +- <tt>\p{XID_Start}</tt>, <tt>\p{XIDS}</tt> + +=== Scripts + +- <tt>\p{Adlam}</tt>, <tt>\p{Adlm}</tt> +- <tt>\p{Ahom}</tt> +- <tt>\p{Anatolian_Hieroglyphs}</tt>, <tt>\p{Hluw}</tt> +- <tt>\p{Arabic}</tt>, <tt>\p{Arab}</tt> +- <tt>\p{Armenian}</tt>, <tt>\p{Armn}</tt> +- <tt>\p{Avestan}</tt>, <tt>\p{Avst}</tt> +- <tt>\p{Balinese}</tt>, <tt>\p{Bali}</tt> +- <tt>\p{Bamum}</tt>, <tt>\p{Bamu}</tt> +- <tt>\p{Bassa_Vah}</tt>, <tt>\p{Bass}</tt> +- <tt>\p{Batak}</tt>, <tt>\p{Batk}</tt> +- <tt>\p{Bengali}</tt>, <tt>\p{Beng}</tt> +- <tt>\p{Bhaiksuki}</tt>, <tt>\p{Bhks}</tt> +- <tt>\p{Bopomofo}</tt>, <tt>\p{Bopo}</tt> +- <tt>\p{Brahmi}</tt>, <tt>\p{Brah}</tt> +- <tt>\p{Braille}</tt>, <tt>\p{Brai}</tt> +- <tt>\p{Buginese}</tt>, <tt>\p{Bugi}</tt> +- <tt>\p{Buhid}</tt>, <tt>\p{Buhd}</tt> +- <tt>\p{Canadian_Aboriginal}</tt>, <tt>\p{Cans}</tt> +- <tt>\p{Carian}</tt>, <tt>\p{Cari}</tt> +- <tt>\p{Caucasian_Albanian}</tt>, <tt>\p{Aghb}</tt> +- <tt>\p{Chakma}</tt>, <tt>\p{Cakm}</tt> +- <tt>\p{Cham}</tt> +- <tt>\p{Cherokee}</tt>, <tt>\p{Cher}</tt> +- <tt>\p{Chorasmian}</tt>, <tt>\p{Chrs}</tt> +- <tt>\p{Common}</tt>, <tt>\p{Zyyy}</tt> +- <tt>\p{Coptic}</tt>, <tt>\p{Copt}</tt> +- <tt>\p{Cuneiform}</tt>, <tt>\p{Xsux}</tt> +- <tt>\p{Cypriot}</tt>, <tt>\p{Cprt}</tt> +- <tt>\p{Cypro_Minoan}</tt>, <tt>\p{Cpmn}</tt> +- <tt>\p{Cyrillic}</tt>, <tt>\p{Cyrl}</tt> +- <tt>\p{Deseret}</tt>, <tt>\p{Dsrt}</tt> +- <tt>\p{Devanagari}</tt>, <tt>\p{Deva}</tt> +- <tt>\p{Dives_Akuru}</tt>, <tt>\p{Diak}</tt> +- <tt>\p{Dogra}</tt>, <tt>\p{Dogr}</tt> +- <tt>\p{Duployan}</tt>, <tt>\p{Dupl}</tt> +- <tt>\p{Egyptian_Hieroglyphs}</tt>, <tt>\p{Egyp}</tt> +- <tt>\p{Elbasan}</tt>, <tt>\p{Elba}</tt> +- <tt>\p{Elymaic}</tt>, <tt>\p{Elym}</tt> +- <tt>\p{Ethiopic}</tt>, <tt>\p{Ethi}</tt> +- <tt>\p{Georgian}</tt>, <tt>\p{Geor}</tt> +- <tt>\p{Glagolitic}</tt>, <tt>\p{Glag}</tt> +- <tt>\p{Gothic}</tt>, <tt>\p{Goth}</tt> +- <tt>\p{Grantha}</tt>, <tt>\p{Gran}</tt> +- <tt>\p{Greek}</tt>, <tt>\p{Grek}</tt> +- <tt>\p{Gujarati}</tt>, <tt>\p{Gujr}</tt> +- <tt>\p{Gunjala_Gondi}</tt>, <tt>\p{Gong}</tt> +- <tt>\p{Gurmukhi}</tt>, <tt>\p{Guru}</tt> +- <tt>\p{Han}</tt>, <tt>\p{Hani}</tt> +- <tt>\p{Hangul}</tt>, <tt>\p{Hang}</tt> +- <tt>\p{Hanifi_Rohingya}</tt>, <tt>\p{Rohg}</tt> +- <tt>\p{Hanunoo}</tt>, <tt>\p{Hano}</tt> +- <tt>\p{Hatran}</tt>, <tt>\p{Hatr}</tt> +- <tt>\p{Hebrew}</tt>, <tt>\p{Hebr}</tt> +- <tt>\p{Hiragana}</tt>, <tt>\p{Hira}</tt> +- <tt>\p{Imperial_Aramaic}</tt>, <tt>\p{Armi}</tt> +- <tt>\p{Inherited}</tt>, <tt>\p{Zinh}</tt> +- <tt>\p{Inscriptional_Pahlavi}</tt>, <tt>\p{Phli}</tt> +- <tt>\p{Inscriptional_Parthian}</tt>, <tt>\p{Prti}</tt> +- <tt>\p{Javanese}</tt>, <tt>\p{Java}</tt> +- <tt>\p{Kaithi}</tt>, <tt>\p{Kthi}</tt> +- <tt>\p{Kannada}</tt>, <tt>\p{Knda}</tt> +- <tt>\p{Katakana}</tt>, <tt>\p{Kana}</tt> +- <tt>\p{Kawi}</tt> +- <tt>\p{Kayah_Li}</tt>, <tt>\p{Kali}</tt> +- <tt>\p{Kharoshthi}</tt>, <tt>\p{Khar}</tt> +- <tt>\p{Khitan_Small_Script}</tt>, <tt>\p{Kits}</tt> +- <tt>\p{Khmer}</tt>, <tt>\p{Khmr}</tt> +- <tt>\p{Khojki}</tt>, <tt>\p{Khoj}</tt> +- <tt>\p{Khudawadi}</tt>, <tt>\p{Sind}</tt> +- <tt>\p{Lao}</tt>, <tt>\p{Laoo}</tt> +- <tt>\p{Latin}</tt>, <tt>\p{Latn}</tt> +- <tt>\p{Lepcha}</tt>, <tt>\p{Lepc}</tt> +- <tt>\p{Limbu}</tt>, <tt>\p{Limb}</tt> +- <tt>\p{Linear_A}</tt>, <tt>\p{Lina}</tt> +- <tt>\p{Linear_B}</tt>, <tt>\p{Linb}</tt> +- <tt>\p{Lisu}</tt> +- <tt>\p{Lycian}</tt>, <tt>\p{Lyci}</tt> +- <tt>\p{Lydian}</tt>, <tt>\p{Lydi}</tt> +- <tt>\p{Mahajani}</tt>, <tt>\p{Mahj}</tt> +- <tt>\p{Makasar}</tt>, <tt>\p{Maka}</tt> +- <tt>\p{Malayalam}</tt>, <tt>\p{Mlym}</tt> +- <tt>\p{Mandaic}</tt>, <tt>\p{Mand}</tt> +- <tt>\p{Manichaean}</tt>, <tt>\p{Mani}</tt> +- <tt>\p{Marchen}</tt>, <tt>\p{Marc}</tt> +- <tt>\p{Masaram_Gondi}</tt>, <tt>\p{Gonm}</tt> +- <tt>\p{Medefaidrin}</tt>, <tt>\p{Medf}</tt> +- <tt>\p{Meetei_Mayek}</tt>, <tt>\p{Mtei}</tt> +- <tt>\p{Mende_Kikakui}</tt>, <tt>\p{Mend}</tt> +- <tt>\p{Meroitic_Cursive}</tt>, <tt>\p{Merc}</tt> +- <tt>\p{Meroitic_Hieroglyphs}</tt>, <tt>\p{Mero}</tt> +- <tt>\p{Miao}</tt>, <tt>\p{Plrd}</tt> +- <tt>\p{Modi}</tt> +- <tt>\p{Mongolian}</tt>, <tt>\p{Mong}</tt> +- <tt>\p{Mro}</tt>, <tt>\p{Mroo}</tt> +- <tt>\p{Multani}</tt>, <tt>\p{Mult}</tt> +- <tt>\p{Myanmar}</tt>, <tt>\p{Mymr}</tt> +- <tt>\p{Nabataean}</tt>, <tt>\p{Nbat}</tt> +- <tt>\p{Nag_Mundari}</tt>, <tt>\p{Nagm}</tt> +- <tt>\p{Nandinagari}</tt>, <tt>\p{Nand}</tt> +- <tt>\p{New_Tai_Lue}</tt>, <tt>\p{Talu}</tt> +- <tt>\p{Newa}</tt> +- <tt>\p{Nko}</tt>, <tt>\p{Nkoo}</tt> +- <tt>\p{Nushu}</tt>, <tt>\p{Nshu}</tt> +- <tt>\p{Nyiakeng_Puachue_Hmong}</tt>, <tt>\p{Hmnp}</tt> +- <tt>\p{Ogham}</tt>, <tt>\p{Ogam}</tt> +- <tt>\p{Ol_Chiki}</tt>, <tt>\p{Olck}</tt> +- <tt>\p{Old_Hungarian}</tt>, <tt>\p{Hung}</tt> +- <tt>\p{Old_Italic}</tt>, <tt>\p{Ital}</tt> +- <tt>\p{Old_North_Arabian}</tt>, <tt>\p{Narb}</tt> +- <tt>\p{Old_Permic}</tt>, <tt>\p{Perm}</tt> +- <tt>\p{Old_Persian}</tt>, <tt>\p{Xpeo}</tt> +- <tt>\p{Old_Sogdian}</tt>, <tt>\p{Sogo}</tt> +- <tt>\p{Old_South_Arabian}</tt>, <tt>\p{Sarb}</tt> +- <tt>\p{Old_Turkic}</tt>, <tt>\p{Orkh}</tt> +- <tt>\p{Old_Uyghur}</tt>, <tt>\p{Ougr}</tt> +- <tt>\p{Oriya}</tt>, <tt>\p{Orya}</tt> +- <tt>\p{Osage}</tt>, <tt>\p{Osge}</tt> +- <tt>\p{Osmanya}</tt>, <tt>\p{Osma}</tt> +- <tt>\p{Pahawh_Hmong}</tt>, <tt>\p{Hmng}</tt> +- <tt>\p{Palmyrene}</tt>, <tt>\p{Palm}</tt> +- <tt>\p{Pau_Cin_Hau}</tt>, <tt>\p{Pauc}</tt> +- <tt>\p{Phags_Pa}</tt>, <tt>\p{Phag}</tt> +- <tt>\p{Phoenician}</tt>, <tt>\p{Phnx}</tt> +- <tt>\p{Psalter_Pahlavi}</tt>, <tt>\p{Phlp}</tt> +- <tt>\p{Rejang}</tt>, <tt>\p{Rjng}</tt> +- <tt>\p{Runic}</tt>, <tt>\p{Runr}</tt> +- <tt>\p{Samaritan}</tt>, <tt>\p{Samr}</tt> +- <tt>\p{Saurashtra}</tt>, <tt>\p{Saur}</tt> +- <tt>\p{Sharada}</tt>, <tt>\p{Shrd}</tt> +- <tt>\p{Shavian}</tt>, <tt>\p{Shaw}</tt> +- <tt>\p{Siddham}</tt>, <tt>\p{Sidd}</tt> +- <tt>\p{SignWriting}</tt>, <tt>\p{Sgnw}</tt> +- <tt>\p{Sinhala}</tt>, <tt>\p{Sinh}</tt> +- <tt>\p{Sogdian}</tt>, <tt>\p{Sogd}</tt> +- <tt>\p{Sora_Sompeng}</tt>, <tt>\p{Sora}</tt> +- <tt>\p{Soyombo}</tt>, <tt>\p{Soyo}</tt> +- <tt>\p{Sundanese}</tt>, <tt>\p{Sund}</tt> +- <tt>\p{Syloti_Nagri}</tt>, <tt>\p{Sylo}</tt> +- <tt>\p{Syriac}</tt>, <tt>\p{Syrc}</tt> +- <tt>\p{Tagalog}</tt>, <tt>\p{Tglg}</tt> +- <tt>\p{Tagbanwa}</tt>, <tt>\p{Tagb}</tt> +- <tt>\p{Tai_Le}</tt>, <tt>\p{Tale}</tt> +- <tt>\p{Tai_Tham}</tt>, <tt>\p{Lana}</tt> +- <tt>\p{Tai_Viet}</tt>, <tt>\p{Tavt}</tt> +- <tt>\p{Takri}</tt>, <tt>\p{Takr}</tt> +- <tt>\p{Tamil}</tt>, <tt>\p{Taml}</tt> +- <tt>\p{Tangsa}</tt>, <tt>\p{Tnsa}</tt> +- <tt>\p{Tangut}</tt>, <tt>\p{Tang}</tt> +- <tt>\p{Telugu}</tt>, <tt>\p{Telu}</tt> +- <tt>\p{Thaana}</tt>, <tt>\p{Thaa}</tt> +- <tt>\p{Thai}</tt> +- <tt>\p{Tibetan}</tt>, <tt>\p{Tibt}</tt> +- <tt>\p{Tifinagh}</tt>, <tt>\p{Tfng}</tt> +- <tt>\p{Tirhuta}</tt>, <tt>\p{Tirh}</tt> +- <tt>\p{Toto}</tt> +- <tt>\p{Ugaritic}</tt>, <tt>\p{Ugar}</tt> +- <tt>\p{Unknown}</tt>, <tt>\p{Zzzz}</tt> +- <tt>\p{Vai}</tt>, <tt>\p{Vaii}</tt> +- <tt>\p{Vithkuqi}</tt>, <tt>\p{Vith}</tt> +- <tt>\p{Wancho}</tt>, <tt>\p{Wcho}</tt> +- <tt>\p{Warang_Citi}</tt>, <tt>\p{Wara}</tt> +- <tt>\p{Yezidi}</tt>, <tt>\p{Yezi}</tt> +- <tt>\p{Yi}</tt>, <tt>\p{Yiii}</tt> +- <tt>\p{Zanabazar_Square}</tt>, <tt>\p{Zanb}</tt> + +=== Blocks + +- <tt>\p{In_Adlam}</tt> +- <tt>\p{In_Aegean_Numbers}</tt> +- <tt>\p{In_Ahom}</tt> +- <tt>\p{In_Alchemical_Symbols}</tt> +- <tt>\p{In_Alphabetic_Presentation_Forms}</tt> +- <tt>\p{In_Anatolian_Hieroglyphs}</tt> +- <tt>\p{In_Ancient_Greek_Musical_Notation}</tt> +- <tt>\p{In_Ancient_Greek_Numbers}</tt> +- <tt>\p{In_Ancient_Symbols}</tt> +- <tt>\p{In_Arabic}</tt> +- <tt>\p{In_Arabic_Extended_A}</tt> +- <tt>\p{In_Arabic_Extended_B}</tt> +- <tt>\p{In_Arabic_Extended_C}</tt> +- <tt>\p{In_Arabic_Mathematical_Alphabetic_Symbols}</tt> +- <tt>\p{In_Arabic_Presentation_Forms_A}</tt> +- <tt>\p{In_Arabic_Presentation_Forms_B}</tt> +- <tt>\p{In_Arabic_Supplement}</tt> +- <tt>\p{In_Armenian}</tt> +- <tt>\p{In_Arrows}</tt> +- <tt>\p{In_Avestan}</tt> +- <tt>\p{In_Balinese}</tt> +- <tt>\p{In_Bamum}</tt> +- <tt>\p{In_Bamum_Supplement}</tt> +- <tt>\p{In_Basic_Latin}</tt> +- <tt>\p{In_Bassa_Vah}</tt> +- <tt>\p{In_Batak}</tt> +- <tt>\p{In_Bengali}</tt> +- <tt>\p{In_Bhaiksuki}</tt> +- <tt>\p{In_Block_Elements}</tt> +- <tt>\p{In_Bopomofo}</tt> +- <tt>\p{In_Bopomofo_Extended}</tt> +- <tt>\p{In_Box_Drawing}</tt> +- <tt>\p{In_Brahmi}</tt> +- <tt>\p{In_Braille_Patterns}</tt> +- <tt>\p{In_Buginese}</tt> +- <tt>\p{In_Buhid}</tt> +- <tt>\p{In_Byzantine_Musical_Symbols}</tt> +- <tt>\p{In_CJK_Compatibility}</tt> +- <tt>\p{In_CJK_Compatibility_Forms}</tt> +- <tt>\p{In_CJK_Compatibility_Ideographs}</tt> +- <tt>\p{In_CJK_Compatibility_Ideographs_Supplement}</tt> +- <tt>\p{In_CJK_Radicals_Supplement}</tt> +- <tt>\p{In_CJK_Strokes}</tt> +- <tt>\p{In_CJK_Symbols_and_Punctuation}</tt> +- <tt>\p{In_CJK_Unified_Ideographs}</tt> +- <tt>\p{In_CJK_Unified_Ideographs_Extension_A}</tt> +- <tt>\p{In_CJK_Unified_Ideographs_Extension_B}</tt> +- <tt>\p{In_CJK_Unified_Ideographs_Extension_C}</tt> +- <tt>\p{In_CJK_Unified_Ideographs_Extension_D}</tt> +- <tt>\p{In_CJK_Unified_Ideographs_Extension_E}</tt> +- <tt>\p{In_CJK_Unified_Ideographs_Extension_F}</tt> +- <tt>\p{In_CJK_Unified_Ideographs_Extension_G}</tt> +- <tt>\p{In_CJK_Unified_Ideographs_Extension_H}</tt> +- <tt>\p{In_Carian}</tt> +- <tt>\p{In_Caucasian_Albanian}</tt> +- <tt>\p{In_Chakma}</tt> +- <tt>\p{In_Cham}</tt> +- <tt>\p{In_Cherokee}</tt> +- <tt>\p{In_Cherokee_Supplement}</tt> +- <tt>\p{In_Chess_Symbols}</tt> +- <tt>\p{In_Chorasmian}</tt> +- <tt>\p{In_Combining_Diacritical_Marks}</tt> +- <tt>\p{In_Combining_Diacritical_Marks_Extended}</tt> +- <tt>\p{In_Combining_Diacritical_Marks_Supplement}</tt> +- <tt>\p{In_Combining_Diacritical_Marks_for_Symbols}</tt> +- <tt>\p{In_Combining_Half_Marks}</tt> +- <tt>\p{In_Common_Indic_Number_Forms}</tt> +- <tt>\p{In_Control_Pictures}</tt> +- <tt>\p{In_Coptic}</tt> +- <tt>\p{In_Coptic_Epact_Numbers}</tt> +- <tt>\p{In_Counting_Rod_Numerals}</tt> +- <tt>\p{In_Cuneiform}</tt> +- <tt>\p{In_Cuneiform_Numbers_and_Punctuation}</tt> +- <tt>\p{In_Currency_Symbols}</tt> +- <tt>\p{In_Cypriot_Syllabary}</tt> +- <tt>\p{In_Cypro_Minoan}</tt> +- <tt>\p{In_Cyrillic}</tt> +- <tt>\p{In_Cyrillic_Extended_A}</tt> +- <tt>\p{In_Cyrillic_Extended_B}</tt> +- <tt>\p{In_Cyrillic_Extended_C}</tt> +- <tt>\p{In_Cyrillic_Extended_D}</tt> +- <tt>\p{In_Cyrillic_Supplement}</tt> +- <tt>\p{In_Deseret}</tt> +- <tt>\p{In_Devanagari}</tt> +- <tt>\p{In_Devanagari_Extended}</tt> +- <tt>\p{In_Devanagari_Extended_A}</tt> +- <tt>\p{In_Dingbats}</tt> +- <tt>\p{In_Dives_Akuru}</tt> +- <tt>\p{In_Dogra}</tt> +- <tt>\p{In_Domino_Tiles}</tt> +- <tt>\p{In_Duployan}</tt> +- <tt>\p{In_Early_Dynastic_Cuneiform}</tt> +- <tt>\p{In_Egyptian_Hieroglyph_Format_Controls}</tt> +- <tt>\p{In_Egyptian_Hieroglyphs}</tt> +- <tt>\p{In_Elbasan}</tt> +- <tt>\p{In_Elymaic}</tt> +- <tt>\p{In_Emoticons}</tt> +- <tt>\p{In_Enclosed_Alphanumeric_Supplement}</tt> +- <tt>\p{In_Enclosed_Alphanumerics}</tt> +- <tt>\p{In_Enclosed_CJK_Letters_and_Months}</tt> +- <tt>\p{In_Enclosed_Ideographic_Supplement}</tt> +- <tt>\p{In_Ethiopic}</tt> +- <tt>\p{In_Ethiopic_Extended}</tt> +- <tt>\p{In_Ethiopic_Extended_A}</tt> +- <tt>\p{In_Ethiopic_Extended_B}</tt> +- <tt>\p{In_Ethiopic_Supplement}</tt> +- <tt>\p{In_General_Punctuation}</tt> +- <tt>\p{In_Geometric_Shapes}</tt> +- <tt>\p{In_Geometric_Shapes_Extended}</tt> +- <tt>\p{In_Georgian}</tt> +- <tt>\p{In_Georgian_Extended}</tt> +- <tt>\p{In_Georgian_Supplement}</tt> +- <tt>\p{In_Glagolitic}</tt> +- <tt>\p{In_Glagolitic_Supplement}</tt> +- <tt>\p{In_Gothic}</tt> +- <tt>\p{In_Grantha}</tt> +- <tt>\p{In_Greek_Extended}</tt> +- <tt>\p{In_Greek_and_Coptic}</tt> +- <tt>\p{In_Gujarati}</tt> +- <tt>\p{In_Gunjala_Gondi}</tt> +- <tt>\p{In_Gurmukhi}</tt> +- <tt>\p{In_Halfwidth_and_Fullwidth_Forms}</tt> +- <tt>\p{In_Hangul_Compatibility_Jamo}</tt> +- <tt>\p{In_Hangul_Jamo}</tt> +- <tt>\p{In_Hangul_Jamo_Extended_A}</tt> +- <tt>\p{In_Hangul_Jamo_Extended_B}</tt> +- <tt>\p{In_Hangul_Syllables}</tt> +- <tt>\p{In_Hanifi_Rohingya}</tt> +- <tt>\p{In_Hanunoo}</tt> +- <tt>\p{In_Hatran}</tt> +- <tt>\p{In_Hebrew}</tt> +- <tt>\p{In_High_Private_Use_Surrogates}</tt> +- <tt>\p{In_High_Surrogates}</tt> +- <tt>\p{In_Hiragana}</tt> +- <tt>\p{In_IPA_Extensions}</tt> +- <tt>\p{In_Ideographic_Description_Characters}</tt> +- <tt>\p{In_Ideographic_Symbols_and_Punctuation}</tt> +- <tt>\p{In_Imperial_Aramaic}</tt> +- <tt>\p{In_Indic_Siyaq_Numbers}</tt> +- <tt>\p{In_Inscriptional_Pahlavi}</tt> +- <tt>\p{In_Inscriptional_Parthian}</tt> +- <tt>\p{In_Javanese}</tt> +- <tt>\p{In_Kaithi}</tt> +- <tt>\p{In_Kaktovik_Numerals}</tt> +- <tt>\p{In_Kana_Extended_A}</tt> +- <tt>\p{In_Kana_Extended_B}</tt> +- <tt>\p{In_Kana_Supplement}</tt> +- <tt>\p{In_Kanbun}</tt> +- <tt>\p{In_Kangxi_Radicals}</tt> +- <tt>\p{In_Kannada}</tt> +- <tt>\p{In_Katakana}</tt> +- <tt>\p{In_Katakana_Phonetic_Extensions}</tt> +- <tt>\p{In_Kawi}</tt> +- <tt>\p{In_Kayah_Li}</tt> +- <tt>\p{In_Kharoshthi}</tt> +- <tt>\p{In_Khitan_Small_Script}</tt> +- <tt>\p{In_Khmer}</tt> +- <tt>\p{In_Khmer_Symbols}</tt> +- <tt>\p{In_Khojki}</tt> +- <tt>\p{In_Khudawadi}</tt> +- <tt>\p{In_Lao}</tt> +- <tt>\p{In_Latin_1_Supplement}</tt> +- <tt>\p{In_Latin_Extended_A}</tt> +- <tt>\p{In_Latin_Extended_Additional}</tt> +- <tt>\p{In_Latin_Extended_B}</tt> +- <tt>\p{In_Latin_Extended_C}</tt> +- <tt>\p{In_Latin_Extended_D}</tt> +- <tt>\p{In_Latin_Extended_E}</tt> +- <tt>\p{In_Latin_Extended_F}</tt> +- <tt>\p{In_Latin_Extended_G}</tt> +- <tt>\p{In_Lepcha}</tt> +- <tt>\p{In_Letterlike_Symbols}</tt> +- <tt>\p{In_Limbu}</tt> +- <tt>\p{In_Linear_A}</tt> +- <tt>\p{In_Linear_B_Ideograms}</tt> +- <tt>\p{In_Linear_B_Syllabary}</tt> +- <tt>\p{In_Lisu}</tt> +- <tt>\p{In_Lisu_Supplement}</tt> +- <tt>\p{In_Low_Surrogates}</tt> +- <tt>\p{In_Lycian}</tt> +- <tt>\p{In_Lydian}</tt> +- <tt>\p{In_Mahajani}</tt> +- <tt>\p{In_Mahjong_Tiles}</tt> +- <tt>\p{In_Makasar}</tt> +- <tt>\p{In_Malayalam}</tt> +- <tt>\p{In_Mandaic}</tt> +- <tt>\p{In_Manichaean}</tt> +- <tt>\p{In_Marchen}</tt> +- <tt>\p{In_Masaram_Gondi}</tt> +- <tt>\p{In_Mathematical_Alphanumeric_Symbols}</tt> +- <tt>\p{In_Mathematical_Operators}</tt> +- <tt>\p{In_Mayan_Numerals}</tt> +- <tt>\p{In_Medefaidrin}</tt> +- <tt>\p{In_Meetei_Mayek}</tt> +- <tt>\p{In_Meetei_Mayek_Extensions}</tt> +- <tt>\p{In_Mende_Kikakui}</tt> +- <tt>\p{In_Meroitic_Cursive}</tt> +- <tt>\p{In_Meroitic_Hieroglyphs}</tt> +- <tt>\p{In_Miao}</tt> +- <tt>\p{In_Miscellaneous_Mathematical_Symbols_A}</tt> +- <tt>\p{In_Miscellaneous_Mathematical_Symbols_B}</tt> +- <tt>\p{In_Miscellaneous_Symbols}</tt> +- <tt>\p{In_Miscellaneous_Symbols_and_Arrows}</tt> +- <tt>\p{In_Miscellaneous_Symbols_and_Pictographs}</tt> +- <tt>\p{In_Miscellaneous_Technical}</tt> +- <tt>\p{In_Modi}</tt> +- <tt>\p{In_Modifier_Tone_Letters}</tt> +- <tt>\p{In_Mongolian}</tt> +- <tt>\p{In_Mongolian_Supplement}</tt> +- <tt>\p{In_Mro}</tt> +- <tt>\p{In_Multani}</tt> +- <tt>\p{In_Musical_Symbols}</tt> +- <tt>\p{In_Myanmar}</tt> +- <tt>\p{In_Myanmar_Extended_A}</tt> +- <tt>\p{In_Myanmar_Extended_B}</tt> +- <tt>\p{In_NKo}</tt> +- <tt>\p{In_Nabataean}</tt> +- <tt>\p{In_Nag_Mundari}</tt> +- <tt>\p{In_Nandinagari}</tt> +- <tt>\p{In_New_Tai_Lue}</tt> +- <tt>\p{In_Newa}</tt> +- <tt>\p{In_No_Block}</tt> +- <tt>\p{In_Number_Forms}</tt> +- <tt>\p{In_Nushu}</tt> +- <tt>\p{In_Nyiakeng_Puachue_Hmong}</tt> +- <tt>\p{In_Ogham}</tt> +- <tt>\p{In_Ol_Chiki}</tt> +- <tt>\p{In_Old_Hungarian}</tt> +- <tt>\p{In_Old_Italic}</tt> +- <tt>\p{In_Old_North_Arabian}</tt> +- <tt>\p{In_Old_Permic}</tt> +- <tt>\p{In_Old_Persian}</tt> +- <tt>\p{In_Old_Sogdian}</tt> +- <tt>\p{In_Old_South_Arabian}</tt> +- <tt>\p{In_Old_Turkic}</tt> +- <tt>\p{In_Old_Uyghur}</tt> +- <tt>\p{In_Optical_Character_Recognition}</tt> +- <tt>\p{In_Oriya}</tt> +- <tt>\p{In_Ornamental_Dingbats}</tt> +- <tt>\p{In_Osage}</tt> +- <tt>\p{In_Osmanya}</tt> +- <tt>\p{In_Ottoman_Siyaq_Numbers}</tt> +- <tt>\p{In_Pahawh_Hmong}</tt> +- <tt>\p{In_Palmyrene}</tt> +- <tt>\p{In_Pau_Cin_Hau}</tt> +- <tt>\p{In_Phags_pa}</tt> +- <tt>\p{In_Phaistos_Disc}</tt> +- <tt>\p{In_Phoenician}</tt> +- <tt>\p{In_Phonetic_Extensions}</tt> +- <tt>\p{In_Phonetic_Extensions_Supplement}</tt> +- <tt>\p{In_Playing_Cards}</tt> +- <tt>\p{In_Private_Use_Area}</tt> +- <tt>\p{In_Psalter_Pahlavi}</tt> +- <tt>\p{In_Rejang}</tt> +- <tt>\p{In_Rumi_Numeral_Symbols}</tt> +- <tt>\p{In_Runic}</tt> +- <tt>\p{In_Samaritan}</tt> +- <tt>\p{In_Saurashtra}</tt> +- <tt>\p{In_Sharada}</tt> +- <tt>\p{In_Shavian}</tt> +- <tt>\p{In_Shorthand_Format_Controls}</tt> +- <tt>\p{In_Siddham}</tt> +- <tt>\p{In_Sinhala}</tt> +- <tt>\p{In_Sinhala_Archaic_Numbers}</tt> +- <tt>\p{In_Small_Form_Variants}</tt> +- <tt>\p{In_Small_Kana_Extension}</tt> +- <tt>\p{In_Sogdian}</tt> +- <tt>\p{In_Sora_Sompeng}</tt> +- <tt>\p{In_Soyombo}</tt> +- <tt>\p{In_Spacing_Modifier_Letters}</tt> +- <tt>\p{In_Specials}</tt> +- <tt>\p{In_Sundanese}</tt> +- <tt>\p{In_Sundanese_Supplement}</tt> +- <tt>\p{In_Superscripts_and_Subscripts}</tt> +- <tt>\p{In_Supplemental_Arrows_A}</tt> +- <tt>\p{In_Supplemental_Arrows_B}</tt> +- <tt>\p{In_Supplemental_Arrows_C}</tt> +- <tt>\p{In_Supplemental_Mathematical_Operators}</tt> +- <tt>\p{In_Supplemental_Punctuation}</tt> +- <tt>\p{In_Supplemental_Symbols_and_Pictographs}</tt> +- <tt>\p{In_Supplementary_Private_Use_Area_A}</tt> +- <tt>\p{In_Supplementary_Private_Use_Area_B}</tt> +- <tt>\p{In_Sutton_SignWriting}</tt> +- <tt>\p{In_Syloti_Nagri}</tt> +- <tt>\p{In_Symbols_and_Pictographs_Extended_A}</tt> +- <tt>\p{In_Symbols_for_Legacy_Computing}</tt> +- <tt>\p{In_Syriac}</tt> +- <tt>\p{In_Syriac_Supplement}</tt> +- <tt>\p{In_Tagalog}</tt> +- <tt>\p{In_Tagbanwa}</tt> +- <tt>\p{In_Tags}</tt> +- <tt>\p{In_Tai_Le}</tt> +- <tt>\p{In_Tai_Tham}</tt> +- <tt>\p{In_Tai_Viet}</tt> +- <tt>\p{In_Tai_Xuan_Jing_Symbols}</tt> +- <tt>\p{In_Takri}</tt> +- <tt>\p{In_Tamil}</tt> +- <tt>\p{In_Tamil_Supplement}</tt> +- <tt>\p{In_Tangsa}</tt> +- <tt>\p{In_Tangut}</tt> +- <tt>\p{In_Tangut_Components}</tt> +- <tt>\p{In_Tangut_Supplement}</tt> +- <tt>\p{In_Telugu}</tt> +- <tt>\p{In_Thaana}</tt> +- <tt>\p{In_Thai}</tt> +- <tt>\p{In_Tibetan}</tt> +- <tt>\p{In_Tifinagh}</tt> +- <tt>\p{In_Tirhuta}</tt> +- <tt>\p{In_Toto}</tt> +- <tt>\p{In_Transport_and_Map_Symbols}</tt> +- <tt>\p{In_Ugaritic}</tt> +- <tt>\p{In_Unified_Canadian_Aboriginal_Syllabics}</tt> +- <tt>\p{In_Unified_Canadian_Aboriginal_Syllabics_Extended}</tt> +- <tt>\p{In_Unified_Canadian_Aboriginal_Syllabics_Extended_A}</tt> +- <tt>\p{In_Vai}</tt> +- <tt>\p{In_Variation_Selectors}</tt> +- <tt>\p{In_Variation_Selectors_Supplement}</tt> +- <tt>\p{In_Vedic_Extensions}</tt> +- <tt>\p{In_Vertical_Forms}</tt> +- <tt>\p{In_Vithkuqi}</tt> +- <tt>\p{In_Wancho}</tt> +- <tt>\p{In_Warang_Citi}</tt> +- <tt>\p{In_Yezidi}</tt> +- <tt>\p{In_Yi_Radicals}</tt> +- <tt>\p{In_Yi_Syllables}</tt> +- <tt>\p{In_Yijing_Hexagram_Symbols}</tt> +- <tt>\p{In_Zanabazar_Square}</tt> +- <tt>\p{In_Znamenny_Musical_Notation}</tt> + +=== Emoji + +- <tt>\p{Emoji}</tt> +- <tt>\p{Emoji_Component}</tt>, <tt>\p{EComp}</tt> +- <tt>\p{Emoji_Modifier}</tt>, <tt>\p{EMod}</tt> +- <tt>\p{Emoji_Modifier_Base}</tt>, <tt>\p{EBase}</tt> +- <tt>\p{Emoji_Presentation}</tt>, <tt>\p{EPres}</tt> +- <tt>\p{Extended_Pictographic}</tt>, <tt>\p{ExtPict}</tt> + +=== Graphemes + +- <tt>\p{Grapheme_Cluster_Break_CR}</tt> +- <tt>\p{Grapheme_Cluster_Break_Control}</tt> +- <tt>\p{Grapheme_Cluster_Break_Extend}</tt> +- <tt>\p{Grapheme_Cluster_Break_L}</tt> +- <tt>\p{Grapheme_Cluster_Break_LF}</tt> +- <tt>\p{Grapheme_Cluster_Break_LV}</tt> +- <tt>\p{Grapheme_Cluster_Break_LVT}</tt> +- <tt>\p{Grapheme_Cluster_Break_Prepend}</tt> +- <tt>\p{Grapheme_Cluster_Break_Regional_Indicator}</tt> +- <tt>\p{Grapheme_Cluster_Break_SpacingMark}</tt> +- <tt>\p{Grapheme_Cluster_Break_T}</tt> +- <tt>\p{Grapheme_Cluster_Break_V}</tt> +- <tt>\p{Grapheme_Cluster_Break_ZWJ}</tt> + +=== Derived Ages + +- <tt>\p{Age_10_0}</tt> +- <tt>\p{Age_11_0}</tt> +- <tt>\p{Age_12_0}</tt> +- <tt>\p{Age_12_1}</tt> +- <tt>\p{Age_13_0}</tt> +- <tt>\p{Age_14_0}</tt> +- <tt>\p{Age_15_0}</tt> +- <tt>\p{Age_1_1}</tt> +- <tt>\p{Age_2_0}</tt> +- <tt>\p{Age_2_1}</tt> +- <tt>\p{Age_3_0}</tt> +- <tt>\p{Age_3_1}</tt> +- <tt>\p{Age_3_2}</tt> +- <tt>\p{Age_4_0}</tt> +- <tt>\p{Age_4_1}</tt> +- <tt>\p{Age_5_0}</tt> +- <tt>\p{Age_5_1}</tt> +- <tt>\p{Age_5_2}</tt> +- <tt>\p{Age_6_0}</tt> +- <tt>\p{Age_6_1}</tt> +- <tt>\p{Age_6_2}</tt> +- <tt>\p{Age_6_3}</tt> +- <tt>\p{Age_7_0}</tt> +- <tt>\p{Age_8_0}</tt> +- <tt>\p{Age_9_0}</tt> diff --git a/doc/reline/face.md b/doc/reline/face.md new file mode 100644 index 0000000000..1fa916123b --- /dev/null +++ b/doc/reline/face.md @@ -0,0 +1,111 @@ +# Face + +With the `Reline::Face` class, you can modify the text color and text decorations in your terminal emulator. +This is primarily used to customize the appearance of the method completion dialog in IRB. + +## Usage + +### ex: Change the background color of the completion dialog cyan to blue + +```ruby +Reline::Face.config(:completion_dialog) do |conf| + conf.define :default, foreground: :white, background: :blue + # ^^^^^ `:cyan` by default + conf.define :enhanced, foreground: :white, background: :magenta + conf.define :scrollbar, foreground: :white, background: :blue +end +``` + +If you provide the above code to an IRB session in some way, you can apply the configuration. +It's generally done by writing it in `.irbrc`. + +Regarding `.irbrc`, please refer to the following link: [https://docs.ruby-lang.org/en/master/IRB.html](https://docs.ruby-lang.org/en/master/IRB.html) + +## Available parameters + +`Reline::Face` internally creates SGR (Select Graphic Rendition) code according to the block parameter of `Reline::Face.config` method. + +| Key | Value | SGR Code (numeric part following "\e[")| +|:------------|:------------------|-----:| +| :foreground | :black | 30 | +| | :red | 31 | +| | :green | 32 | +| | :yellow | 33 | +| | :blue | 34 | +| | :magenta | 35 | +| | :cyan | 36 | +| | :white | 37 | +| | :bright_black | 90 | +| | :gray | 90 | +| | :bright_red | 91 | +| | :bright_green | 92 | +| | :bright_yellow | 93 | +| | :bright_blue | 94 | +| | :bright_magenta | 95 | +| | :bright_cyan | 96 | +| | :bright_white | 97 | +| :background | :black | 40 | +| | :red | 41 | +| | :green | 42 | +| | :yellow | 43 | +| | :blue | 44 | +| | :magenta | 45 | +| | :cyan | 46 | +| | :white | 47 | +| | :bright_black | 100 | +| | :gray | 100 | +| | :bright_red | 101 | +| | :bright_green | 102 | +| | :bright_yellow | 103 | +| | :bright_blue | 104 | +| | :bright_magenta | 105 | +| | :bright_cyan | 106 | +| | :bright_white | 107 | +| :style | :reset | 0 | +| | :bold | 1 | +| | :faint | 2 | +| | :italicized | 3 | +| | :underlined | 4 | +| | :slowly_blinking | 5 | +| | :blinking | 5 | +| | :rapidly_blinking | 6 | +| | :negative | 7 | +| | :concealed | 8 | +| | :crossed_out | 9 | + +- The value for `:style` can be both a Symbol and an Array + ```ruby + # Single symbol + conf.define :default, style: :bold + # Array + conf.define :default, style: [:bold, :negative] + ``` +- The availability of specific SGR codes depends on your terminal emulator +- You can specify a hex color code to `:foreground` and `:background` color like `foreground: "#FF1020"`. Its availability also depends on your terminal emulator + +## Debugging + +You can see the current Face configuration by `Reline::Face.configs` method + +Example: + +```ruby +irb(main):001:0> Reline::Face.configs +=> +{:default=> + {:default=>{:style=>:reset, :escape_sequence=>"\e[0m"}, + :enhanced=>{:style=>:reset, :escape_sequence=>"\e[0m"}, + :scrollbar=>{:style=>:reset, :escape_sequence=>"\e[0m"}}, + :completion_dialog=> + {:default=>{:foreground=>:white, :background=>:cyan, :escape_sequence=>"\e[0m\e[37;46m"}, + :enhanced=>{:foreground=>:white, :background=>:magenta, :escape_sequence=>"\e[0m\e[37;45m"}, + :scrollbar=>{:foreground=>:white, :background=>:cyan, :escape_sequence=>"\e[0m\e[37;46m"}}} +``` + +## 256-Color and TrueColor + +Reline will automatically detect if your terminal emulator supports truecolor with `ENV['COLORTERM] in 'truecolor' | '24bit'`. When this env is not set, Reline will fallback to 256-color. +If your terminal emulator supports truecolor but does not set COLORTERM env, add this line to `.irbrc`. +```ruby +Reline::Face.force_truecolor +``` diff --git a/doc/rjit/rjit.md b/doc/rjit/rjit.md new file mode 100644 index 0000000000..9e60e43ce3 --- /dev/null +++ b/doc/rjit/rjit.md @@ -0,0 +1,45 @@ +# RJIT: Ruby JIT + +This document has some tips that might be useful when you work on RJIT. + +## Project purpose + +This project is for experimental purposes. +For production deployment, consider using YJIT instead. + +## Supported platforms + +The following platforms are assumed to work. `linux-x86_64` is tested on CI. + +* OS: Linux, macOS, BSD +* Arch: x86\_64 + +## configure +### --enable-rjit + +On supported platforms, `--enable-rjit` is set by default. You usually don't need to specify this. +You may still manually pass `--enable-rjit` to try RJIT on unsupported platforms. + +### --enable-rjit=dev + +It enables `--rjit-dump-disasm` if libcapstone is available. + +## make +### rjit-bindgen + +If you see an "RJIT bindgen" GitHub Actions failure, please commit the `git diff` shown on the failed job. + +For doing the same thing locally, run `make rjit-bindgen` after installing libclang. +macOS seems to have libclang by default. On Ubuntu, you can install it with `apt install libclang1`. + +## ruby +### --rjit-stats + +This prints RJIT stats at exit. + +### --rjit-dump-disasm + +This dumps all JIT code. You need to install libcapstone before configure and use `--enable-rjit=dev` on configure. + +* Ubuntu: `sudo apt-get install -y libcapstone-dev` +* macOS: `brew install capstone` diff --git a/doc/ruby/option_dump.md b/doc/ruby/option_dump.md new file mode 100644 index 0000000000..00d0ec77d5 --- /dev/null +++ b/doc/ruby/option_dump.md @@ -0,0 +1,297 @@ +# Option `--dump` + +For other argument values, +see {Option --dump}[options_md.html#label--dump-3A+Dump+Items]. + +For the examples here, we use this program: + +```sh +$ cat t.rb +puts 'Foo' +``` + +The supported dump items: + +- `insns`: Instruction sequences: + + ```sh + $ ruby --dump=insns t.rb + == disasm: #<ISeq:<main>@t.rb:1 (1,0)-(1,10)> (catch: FALSE) + 0000 putself ( 1)[Li] + 0001 putstring "Foo" + 0003 opt_send_without_block <calldata!mid:puts, argc:1, FCALL|ARGS_SIMPLE> + 0005 leave + ``` + +- `parsetree`: {Abstract syntax tree}[https://en.wikipedia.org/wiki/Abstract_syntax_tree] + (AST): + + ```sh + $ ruby --dump=parsetree t.rb + ########################################################### + ## Do NOT use this node dump for any purpose other than ## + ## debug and research. Compatibility is not guaranteed. ## + ########################################################### + + # @ NODE_SCOPE (line: 1, location: (1,0)-(1,10)) + # +- nd_tbl: (empty) + # +- nd_args: + # | (null node) + # +- nd_body: + # @ NODE_FCALL (line: 1, location: (1,0)-(1,10))* + # +- nd_mid: :puts + # +- nd_args: + # @ NODE_LIST (line: 1, location: (1,5)-(1,10)) + # +- nd_alen: 1 + # +- nd_head: + # | @ NODE_STR (line: 1, location: (1,5)-(1,10)) + # | +- nd_lit: "Foo" + # +- nd_next: + # (null node) + ``` + +- `parsetree_with_comment`: AST with comments: + + ```sh + $ ruby --dump=parsetree_with_comment t.rb + ########################################################### + ## Do NOT use this node dump for any purpose other than ## + ## debug and research. Compatibility is not guaranteed. ## + ########################################################### + + # @ NODE_SCOPE (line: 1, location: (1,0)-(1,10)) + # | # new scope + # | # format: [nd_tbl]: local table, [nd_args]: arguments, [nd_body]: body + # +- nd_tbl (local table): (empty) + # +- nd_args (arguments): + # | (null node) + # +- nd_body (body): + # @ NODE_FCALL (line: 1, location: (1,0)-(1,10))* + # | # function call + # | # format: [nd_mid]([nd_args]) + # | # example: foo(1) + # +- nd_mid (method id): :puts + # +- nd_args (arguments): + # @ NODE_LIST (line: 1, location: (1,5)-(1,10)) + # | # list constructor + # | # format: [ [nd_head], [nd_next].. ] (length: [nd_alen]) + # | # example: [1, 2, 3] + # +- nd_alen (length): 1 + # +- nd_head (element): + # | @ NODE_STR (line: 1, location: (1,5)-(1,10)) + # | | # string literal + # | | # format: [nd_lit] + # | | # example: 'foo' + # | +- nd_lit (literal): "Foo" + # +- nd_next (next element): + # (null node) + ``` + +- `yydebug`: Debugging information from yacc parser generator: + + ```sh + $ ruby --dump=yydebug t.rb + Starting parse + Entering state 0 + Reducing stack by rule 1 (line 1295): + lex_state: NONE -> BEG at line 1296 + vtable_alloc:12392: 0x0000558453df1a00 + vtable_alloc:12393: 0x0000558453df1a60 + cmdarg_stack(push): 0 at line 12406 + cond_stack(push): 0 at line 12407 + -> $$ = nterm $@1 (1.0-1.0: ) + Stack now 0 + Entering state 2 + Reading a token: + lex_state: BEG -> CMDARG at line 9049 + Next token is token "local variable or method" (1.0-1.4: puts) + Shifting token "local variable or method" (1.0-1.4: puts) + Entering state 35 + Reading a token: Next token is token "string literal" (1.5-1.6: ) + Reducing stack by rule 742 (line 5567): + $1 = token "local variable or method" (1.0-1.4: puts) + -> $$ = nterm operation (1.0-1.4: ) + Stack now 0 2 + Entering state 126 + Reducing stack by rule 78 (line 1794): + $1 = nterm operation (1.0-1.4: ) + -> $$ = nterm fcall (1.0-1.4: ) + Stack now 0 2 + Entering state 80 + Next token is token "string literal" (1.5-1.6: ) + Reducing stack by rule 292 (line 2723): + cmdarg_stack(push): 1 at line 2737 + -> $$ = nterm $@16 (1.4-1.4: ) + Stack now 0 2 80 + Entering state 235 + Next token is token "string literal" (1.5-1.6: ) + Shifting token "string literal" (1.5-1.6: ) + Entering state 216 + Reducing stack by rule 607 (line 4706): + -> $$ = nterm string_contents (1.6-1.6: ) + Stack now 0 2 80 235 216 + Entering state 437 + Reading a token: Next token is token "literal content" (1.6-1.9: "Foo") + Shifting token "literal content" (1.6-1.9: "Foo") + Entering state 503 + Reducing stack by rule 613 (line 4802): + $1 = token "literal content" (1.6-1.9: "Foo") + -> $$ = nterm string_content (1.6-1.9: ) + Stack now 0 2 80 235 216 437 + Entering state 507 + Reducing stack by rule 608 (line 4716): + $1 = nterm string_contents (1.6-1.6: ) + $2 = nterm string_content (1.6-1.9: ) + -> $$ = nterm string_contents (1.6-1.9: ) + Stack now 0 2 80 235 216 + Entering state 437 + Reading a token: + lex_state: CMDARG -> END at line 7276 + Next token is token "terminator" (1.9-1.10: ) + Shifting token "terminator" (1.9-1.10: ) + Entering state 508 + Reducing stack by rule 590 (line 4569): + $1 = token "string literal" (1.5-1.6: ) + $2 = nterm string_contents (1.6-1.9: ) + $3 = token "terminator" (1.9-1.10: ) + -> $$ = nterm string1 (1.5-1.10: ) + Stack now 0 2 80 235 + Entering state 109 + Reducing stack by rule 588 (line 4559): + $1 = nterm string1 (1.5-1.10: ) + -> $$ = nterm string (1.5-1.10: ) + Stack now 0 2 80 235 + Entering state 108 + Reading a token: + lex_state: END -> BEG at line 9200 + Next token is token '\n' (1.10-1.10: ) + Reducing stack by rule 586 (line 4541): + $1 = nterm string (1.5-1.10: ) + -> $$ = nterm strings (1.5-1.10: ) + Stack now 0 2 80 235 + Entering state 107 + Reducing stack by rule 307 (line 2837): + $1 = nterm strings (1.5-1.10: ) + -> $$ = nterm primary (1.5-1.10: ) + Stack now 0 2 80 235 + Entering state 90 + Next token is token '\n' (1.10-1.10: ) + Reducing stack by rule 261 (line 2553): + $1 = nterm primary (1.5-1.10: ) + -> $$ = nterm arg (1.5-1.10: ) + Stack now 0 2 80 235 + Entering state 220 + Next token is token '\n' (1.10-1.10: ) + Reducing stack by rule 270 (line 2586): + $1 = nterm arg (1.5-1.10: ) + -> $$ = nterm arg_value (1.5-1.10: ) + Stack now 0 2 80 235 + Entering state 221 + Next token is token '\n' (1.10-1.10: ) + Reducing stack by rule 297 (line 2779): + $1 = nterm arg_value (1.5-1.10: ) + -> $$ = nterm args (1.5-1.10: ) + Stack now 0 2 80 235 + Entering state 224 + Next token is token '\n' (1.10-1.10: ) + Reducing stack by rule 772 (line 5626): + -> $$ = nterm none (1.10-1.10: ) + Stack now 0 2 80 235 224 + Entering state 442 + Reducing stack by rule 296 (line 2773): + $1 = nterm none (1.10-1.10: ) + + -> $$ = nterm opt_block_arg (1.10-1.10: ) + Stack now 0 2 80 235 224 + Entering state 441 + Reducing stack by rule 288 (line 2696): + $1 = nterm args (1.5-1.10: ) + $2 = nterm opt_block_arg (1.10-1.10: ) + -> $$ = nterm call_args (1.5-1.10: ) + Stack now 0 2 80 235 + Entering state 453 + Reducing stack by rule 293 (line 2723): + $1 = nterm $@16 (1.4-1.4: ) + $2 = nterm call_args (1.5-1.10: ) + cmdarg_stack(pop): 0 at line 2754 + -> $$ = nterm command_args (1.4-1.10: ) + Stack now 0 2 80 + Entering state 333 + Next token is token '\n' (1.10-1.10: ) + Reducing stack by rule 79 (line 1804): + $1 = nterm fcall (1.0-1.4: ) + $2 = nterm command_args (1.4-1.10: ) + -> $$ = nterm command (1.0-1.10: ) + Stack now 0 2 + Entering state 81 + Next token is token '\n' (1.10-1.10: ) + Reducing stack by rule 73 (line 1770): + $1 = nterm command (1.0-1.10: ) + -> $$ = nterm command_call (1.0-1.10: ) + Stack now 0 2 + Entering state 78 + Reducing stack by rule 51 (line 1659): + $1 = nterm command_call (1.0-1.10: ) + -> $$ = nterm expr (1.0-1.10: ) + Stack now 0 2 + Entering state 75 + Next token is token '\n' (1.10-1.10: ) + Reducing stack by rule 39 (line 1578): + $1 = nterm expr (1.0-1.10: ) + -> $$ = nterm stmt (1.0-1.10: ) + Stack now 0 2 + Entering state 73 + Next token is token '\n' (1.10-1.10: ) + Reducing stack by rule 8 (line 1354): + $1 = nterm stmt (1.0-1.10: ) + -> $$ = nterm top_stmt (1.0-1.10: ) + Stack now 0 2 + Entering state 72 + Reducing stack by rule 5 (line 1334): + $1 = nterm top_stmt (1.0-1.10: ) + -> $$ = nterm top_stmts (1.0-1.10: ) + Stack now 0 2 + Entering state 71 + Next token is token '\n' (1.10-1.10: ) + Shifting token '\n' (1.10-1.10: ) + Entering state 311 + Reducing stack by rule 769 (line 5618): + $1 = token '\n' (1.10-1.10: ) + -> $$ = nterm term (1.10-1.10: ) + Stack now 0 2 71 + Entering state 313 + Reducing stack by rule 770 (line 5621): + $1 = nterm term (1.10-1.10: ) + -> $$ = nterm terms (1.10-1.10: ) + Stack now 0 2 71 + Entering state 314 + Reading a token: Now at end of input. + Reducing stack by rule 759 (line 5596): + $1 = nterm terms (1.10-1.10: ) + -> $$ = nterm opt_terms (1.10-1.10: ) + Stack now 0 2 71 + Entering state 312 + Reducing stack by rule 3 (line 1321): + $1 = nterm top_stmts (1.0-1.10: ) + $2 = nterm opt_terms (1.10-1.10: ) + -> $$ = nterm top_compstmt (1.0-1.10: ) + Stack now 0 2 + Entering state 70 + Reducing stack by rule 2 (line 1295): + $1 = nterm $@1 (1.0-1.0: ) + $2 = nterm top_compstmt (1.0-1.10: ) + vtable_free:12426: p->lvtbl->args(0x0000558453df1a00) + vtable_free:12427: p->lvtbl->vars(0x0000558453df1a60) + cmdarg_stack(pop): 0 at line 12428 + cond_stack(pop): 0 at line 12429 + -> $$ = nterm program (1.0-1.10: ) + Stack now 0 + Entering state 1 + Now at end of input. + Shifting token "end-of-input" (1.10-1.10: ) + Entering state 3 + Stack now 0 1 3 + Cleanup: popping token "end-of-input" (1.10-1.10: ) + Cleanup: popping nterm program (1.0-1.10: ) + ``` + diff --git a/doc/ruby/options.md b/doc/ruby/options.md new file mode 100644 index 0000000000..143c8925f1 --- /dev/null +++ b/doc/ruby/options.md @@ -0,0 +1,723 @@ +# Ruby Command-Line Options + +## About the Examples + +Some examples here use command-line option `-e`, +which passes the Ruby code to be executed on the command line itself: + +```sh +$ ruby -e 'puts "Hello, World."' +``` + +Some examples here assume that file `desiderata.txt` exists: + +``` +$ cat desiderata.txt +Go placidly amid the noise and the haste, +and remember what peace there may be in silence. +As far as possible, without surrender, +be on good terms with all persons. +``` + +## Options + +### `-0`: \Set `$/` (Input Record Separator) + +Option `-0` defines the input record separator `$/` +for the invoked Ruby program. + +The optional argument to the option must be octal digits, +each in the range `0..7`; +these digits are prefixed with digit `0` to form an octal value. + +If no argument is given, the input record separator is `0x00`. + +If an argument is given, it must immediately follow the option +(no intervening whitespace or equal-sign character `'='`); +argument values: + +- `0`: the input record separator is `''`; + see {Special Line Separator Values}[rdoc-ref:IO@Special+Line+Separator+Values]. +- In range `(1..0377)`: + the input record separator `$/` is set to the character value of the argument. +- Any other octal value: the input record separator is `nil`. + +Examples: + +```sh +$ ruby -0 -e 'p $/' +"\x00" +ruby -00 -e 'p $/' +"" +$ ruby -012 -e 'p $/' +"\n" +$ ruby -015 -e 'p $/' +"\r" +$ ruby -0377 -e 'p $/' +"\xFF" +$ ruby -0400 -e 'p $/' +nil +``` + +See also: + +- {Option -a}[rdoc-ref:ruby/options.md@a-3A+Split+Input+Lines+into+Fields]: + Split input lines into fields. +- {Option -F}[rdoc-ref:ruby/options.md@F-3A+Set+Input+Field+Separator]: + \Set input field separator. +- {Option -l}[rdoc-ref:ruby/options.md@l-3A+Set+Output+Record+Separator-3B+Chop+Lines]: + \Set output record separator; chop lines. +- {Option -n}[rdoc-ref:ruby/options.md@n-3A+Run+Program+in+gets+Loop]: + Run program in `gets` loop. +- {Option -p}[rdoc-ref:ruby/options.md@p-3A+-n-2C+with+Printing]: + `-n`, with printing. + +### `-a`: Split Input Lines into Fields + +Option `-a`, when given with either of options `-n` or `-p`, +splits the string at `$_` into an array of strings at `$F`: + +```sh +$ ruby -an -e 'p $F' desiderata.txt +["Go", "placidly", "amid", "the", "noise", "and", "the", "haste,"] +["and", "remember", "what", "peace", "there", "may", "be", "in", "silence."] +["As", "far", "as", "possible,", "without", "surrender,"] +["be", "on", "good", "terms", "with", "all", "persons."] +``` + +For the splitting, +the default record separator is `$/`, +and the default field separator is `$;`. + +See also: + +- {Option -0}[rdoc-ref:ruby/options.md@0-3A+Set+-24-2F+-28Input+Record+Separator-29]: + \Set `$/` (input record separator). +- {Option -F}[rdoc-ref:ruby/options.md@F-3A+Set+Input+Field+Separator]: + \Set input field separator. +- {Option -l}[rdoc-ref:ruby/options.md@l-3A+Set+Output+Record+Separator-3B+Chop+Lines]: + \Set output record separator; chop lines. +- {Option -n}[rdoc-ref:ruby/options.md@n-3A+Run+Program+in+gets+Loop]: + Run program in `gets` loop. +- {Option -p}[rdoc-ref:ruby/options.md@p-3A+-n-2C+with+Printing]: + `-n`, with printing. + +### `-c`: Check Syntax + +Option `-c` specifies that the specified Ruby program +should be checked for syntax, but not actually executed: + +``` +$ ruby -e 'puts "Foo"' +Foo +$ ruby -c -e 'puts "Foo"' +Syntax OK +``` + +### `-C`: \Set Working Directory + +The argument to option `-C` specifies a working directory +for the invoked Ruby program; +does not change the working directory for the current process: + +```sh +$ basename `pwd` +ruby +$ ruby -C lib -e 'puts File.basename(Dir.pwd)' +lib +$ basename `pwd` +ruby +``` + +Whitespace between the option and its argument may be omitted. + +### `-d`: \Set `$DEBUG` to `true` + +Some code in (or called by) the Ruby program may include statements or blocks +conditioned by the global variable `$DEBUG` (e.g., `if $DEBUG`); +these commonly write to `$stdout` or `$stderr`. + +The default value for `$DEBUG` is `false`; +option `-d` sets it to `true`: + +```sh +$ ruby -e 'p $DEBUG' +false +$ ruby -d -e 'p $DEBUG' +true +``` + +Option `--debug` is an alias for option `-d`. + +### `-e`: Execute Given Ruby Code + +Option `-e` requires an argument, which is Ruby code to be executed; +the option may be given more than once: + +``` +$ ruby -e 'puts "Foo"' -e 'puts "Bar"' +Foo +Bar +``` + +Whitespace between the option and its argument may be omitted. + +The command may include other options, +but should not include arguments (which, if given, are ignored). + +### `-E`: \Set Default Encodings + +Option `-E` requires an argument, which specifies either the default external encoding, +or both the default external and internal encodings for the invoked Ruby program: + +``` +# No option -E. +$ ruby -e 'p [Encoding::default_external, Encoding::default_internal]' +[#<Encoding:UTF-8>, nil] +# Option -E with default external encoding. +$ ruby -E cesu-8 -e 'p [Encoding::default_external, Encoding::default_internal]' +[#<Encoding:CESU-8>, nil] +# Option -E with default external and internal encodings. +$ ruby -E utf-8:cesu-8 -e 'p [Encoding::default_external, Encoding::default_internal]' +[#<Encoding:UTF-8>, #<Encoding:CESU-8>] +``` + +Whitespace between the option and its argument may be omitted. + +See also: + +- {Option --external-encoding}[options_md.html#label--external-encoding-3A+Set+Default+External+Encoding]: + \Set default external encoding. +- {Option --internal-encoding}[options_md.html#label--internal-encoding-3A+Set+Default+Internal+Encoding]: + \Set default internal encoding. + +Option `--encoding` is an alias for option `-E`. + +### `-F`: \Set Input Field Separator + +Option `-F`, when given with option `-a`, +specifies that its argument is to be the input field separator to be used for splitting: + +```sh +$ ruby -an -Fs -e 'p $F' desiderata.txt +["Go placidly amid the noi", "e and the ha", "te,\n"] +["and remember what peace there may be in ", "ilence.\n"] +["A", " far a", " po", "", "ible, without ", "urrender,\n"] +["be on good term", " with all per", "on", ".\n"] +``` + +The argument may be a regular expression: + +``` +$ ruby -an -F'[.,]\s*' -e 'p $F' desiderata.txt +["Go placidly amid the noise and the haste"] +["and remember what peace there may be in silence"] +["As far as possible", "without surrender"] +["be on good terms with all persons"] +``` + +The argument must immediately follow the option +(no intervening whitespace or equal-sign character `'='`). + +See also: + +- {Option -0}[rdoc-ref:ruby/options.md@0-3A+Set+-24-2F+-28Input+Record+Separator-29]: + \Set `$/` (input record separator). +- {Option -a}[rdoc-ref:ruby/options.md@a-3A+Split+Input+Lines+into+Fields]: + Split input lines into fields. +- {Option -l}[rdoc-ref:ruby/options.md@l-3A+Set+Output+Record+Separator-3B+Chop+Lines]: + \Set output record separator; chop lines. +- {Option -n}[rdoc-ref:ruby/options.md@n-3A+Run+Program+in+gets+Loop]: + Run program in `gets` loop. +- {Option -p}[rdoc-ref:ruby/options.md@p-3A+-n-2C+with+Printing]: + `-n`, with printing. + +### `-h`: Print Short Help Message + +Option `-h` prints a short help message +that includes single-hyphen options (e.g. `-I`), +and largely omits double-hyphen options (e.g., `--version`). + +Arguments and additional options are ignored. + +For a longer help message, use option `--help`. + +### `-i`: \Set \ARGF In-Place Mode + +Option `-i` sets the \ARGF in-place mode for the invoked Ruby program; +see ARGF#inplace_mode=: + +``` +$ ruby -e 'p ARGF.inplace_mode' +nil +$ ruby -i -e 'p ARGF.inplace_mode' +"" +$ ruby -i.bak -e 'p ARGF.inplace_mode' +".bak" +``` + +### `-I`: Add to `$LOAD_PATH` + +The argument to option `-I` specifies a directory +to be added to the array in global variable `$LOAD_PATH`; +the option may be given more than once: + +```sh +$ pushd /tmp +$ ruby -e 'p $LOAD_PATH.size' +8 +$ ruby -I my_lib -I some_lib -e 'p $LOAD_PATH.size' +10 +$ ruby -I my_lib -I some_lib -e 'p $LOAD_PATH.take(2)' +["/tmp/my_lib", "/tmp/some_lib"] +$ popd +``` + +Whitespace between the option and its argument may be omitted. + +### `-l`: \Set Output Record Separator; Chop Lines + +Option `-l`, when given with option `-n` or `-p`, +modifies line-ending processing by: + +- Setting global variable output record separator `$\` + to the current value of input record separator `$/`; + this affects line-oriented output (such a the output from Kernel#puts). +- Calling String#chop! on each line read. + +Without option `-l` (unchopped): + +```sh +$ ruby -n -e 'p $_' desiderata.txt +"Go placidly amid the noise and the haste,\n" +"and remember what peace there may be in silence.\n" +"As far as possible, without surrender,\n" +"be on good terms with all persons.\n" +``` + +With option `-l' (chopped): + +```sh +$ ruby -ln -e 'p $_' desiderata.txt +"Go placidly amid the noise and the haste," +"and remember what peace there may be in silence." +"As far as possible, without surrender," +"be on good terms with all persons." +``` + +See also: + +- {Option -0}[rdoc-ref:ruby/options.md@0-3A+Set+-24-2F+-28Input+Record+Separator-29]: + \Set `$/` (input record separator). +- {Option -a}[rdoc-ref:ruby/options.md@a-3A+Split+Input+Lines+into+Fields]: + Split input lines into fields. +- {Option -F}[rdoc-ref:ruby/options.md@F-3A+Set+Input+Field+Separator]: + \Set input field separator. +- {Option -n}[rdoc-ref:ruby/options.md@n-3A+Run+Program+in+gets+Loop]: + Run program in `gets` loop. +- {Option -p}[rdoc-ref:ruby/options.md@p-3A+-n-2C+with+Printing]: + `-n`, with printing. + +### `-n`: Run Program in `gets` Loop + +Option `-n` runs your program in a Kernel#gets loop: + +``` +while gets + # Your Ruby code. +end +``` + +Note that `gets` reads the next line and sets global variable `$_` +to the last read line: + +```sh +$ ruby -n -e 'puts $_' desiderata.txt +Go placidly amid the noise and the haste, +and remember what peace there may be in silence. +As far as possible, without surrender, +be on good terms with all persons. +``` + +See also: + +- {Option -0}[rdoc-ref:ruby/options.md@0-3A+Set+-24-2F+-28Input+Record+Separator-29]: + \Set `$/` (input record separator). +- {Option -a}[rdoc-ref:ruby/options.md@a-3A+Split+Input+Lines+into+Fields]: + Split input lines into fields. +- {Option -F}[rdoc-ref:ruby/options.md@F-3A+Set+Input+Field+Separator]: + \Set input field separator. +- {Option -l}[rdoc-ref:ruby/options.md@l-3A+Set+Output+Record+Separator-3B+Chop+Lines]: + \Set output record separator; chop lines. +- {Option -p}[rdoc-ref:ruby/options.md@p-3A+-n-2C+with+Printing]: + `-n`, with printing. + +### `-p`: `-n`, with Printing + +Option `-p` is like option `-n`, but also prints each line: + +```sh +$ ruby -p -e 'puts $_.size' desiderata.txt +42 +Go placidly amid the noise and the haste, +49 +and remember what peace there may be in silence. +39 +As far as possible, without surrender, +35 +be on good terms with all persons. +``` + +See also: + +- {Option -0}[rdoc-ref:ruby/options.md@0-3A+Set+-24-2F+-28Input+Record+Separator-29]: + \Set `$/` (input record separator). +- {Option -a}[rdoc-ref:ruby/options.md@a-3A+Split+Input+Lines+into+Fields]: + Split input lines into fields. +- {Option -F}[rdoc-ref:ruby/options.md@F-3A+Set+Input+Field+Separator]: + \Set input field separator. +- {Option -l}[rdoc-ref:ruby/options.md@l-3A+Set+Output+Record+Separator-3B+Chop+Lines]: + \Set output record separator; chop lines. +- {Option -n}[rdoc-ref:ruby/options.md@n-3A+Run+Program+in+gets+Loop]: + Run program in `gets` loop. + +### `-r`: Require Library + +The argument to option `-r` specifies a library to be required +before executing the Ruby program; +the option may be given more than once: + +```sh +$ ruby -e 'p defined?(JSON); p defined?(CSV)' +nil +nil +$ ruby -r CSV -r JSON -e 'p defined?(JSON); p defined?(CSV)' +"constant" +"constant" +``` + +Whitespace between the option and its argument may be omitted. + +### `-s`: Define Global Variable + +Option `-s` specifies that a "custom option" is to define a global variable +in the invoked Ruby program: + +- The custom option must appear _after_ the program name. +- The custom option must begin with single hyphen (e.g., `-foo`), + not two hyphens (e.g., `--foo`). +- The name of the global variable is based on the option name: + global variable `$foo` for custom option`-foo`. +- The value of the global variable is the string option argument if given, + `true` otherwise. + +More than one custom option may be given: + +``` +$ cat t.rb +p [$foo, $bar] +$ ruby t.rb +[nil, nil] +$ ruby -s t.rb -foo=baz +["baz", nil] +$ ruby -s t.rb -foo +[true, nil] +$ ruby -s t.rb -foo=baz -bar=bat +["baz", "bat"] +``` + +The option may not be used with +{option -e}[rdoc-ref:ruby/options.md@e-3A+Execute+Given+Ruby+Code] + +### `-S`: Search Directories in `ENV['PATH']` + +Option `-S` specifies that the Ruby interpreter +is to search (if necessary) the directories whose paths are in the program's +`PATH` environment variable; +the program is executed in the shell's current working directory +(not necessarily in the directory where the program is found). + +This example uses adds path `'tmp/'` to the `PATH` environment variable: + +```sh +$ export PATH=/tmp:$PATH +$ echo "puts File.basename(Dir.pwd)" > /tmp/t.rb +$ ruby -S t.rb +ruby +``` + +### `-v`: Print Version; \Set `$VERBOSE` + +Options `-v` prints the Ruby version and sets global variable `$VERBOSE`: + +``` +$ ruby -e 'p $VERBOSE' +false +$ ruby -v -e 'p $VERBOSE' +ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [x64-mingw-ucrt] +true +``` + +### `-w`: Synonym for `-W1` + +Option `-w` (lowercase letter) is equivalent to option `-W1` (uppercase letter). + +### `-W`: \Set \Warning Policy + +Any Ruby code can create a <i>warning message</i> by calling method Kernel#warn; +methods in the Ruby core and standard libraries can also create warning messages. +Such a message may be printed on `$stderr` +(or not, depending on certain settings). + +Option `-W` helps determine whether a particular warning message +will be written, +by setting the initial value of global variable `$-W`: + +- `-W0`: Sets `$-W` to `0` (silent; no warnings). +- `-W1`: Sets `$-W` to `1` (moderate verbosity). +- `-W2`: Sets `$-W` to `2` (high verbosity). +- `-W`: Same as `-W2` (high verbosity). +- Option not given: Same as `-W1` (moderate verbosity). + +The value of `$-W`, in turn, determines which warning messages (if any) +are to be printed to `$stdout` (see Kernel#warn): + +```sh +$ ruby -W1 -e 'p $foo' +nil +$ ruby -W2 -e 'p $foo' +-e:1: warning: global variable '$foo' not initialized +nil +``` + +Ruby code may also define warnings for certain categories; +these are the default settings for the defined categories: + +``` +Warning[:experimental] # => true +Warning[:deprecated] # => false +Warning[:performance] # => false +``` + +They may also be set: +``` +Warning[:experimental] = false +Warning[:deprecated] = true +Warning[:performance] = true +``` + +You can suppress a category by prefixing `no-` to the category name: + +``` +$ ruby -W:no-experimental -e 'p IO::Buffer.new' +#<IO::Buffer> +``` + +### `-x`: Execute Ruby Code Found in Text + +Option `-x` executes a Ruby program whose code is embedded +in other, non-code, text: + +The ruby code: + +- Begins after the first line beginning with `'#!` and containing string `'ruby'`. +- Ends before any one of: + + - End-of-file. + - A line consisting of `'__END__'`, + - Character `Ctrl-D` or `Ctrl-Z`. + +Example: + +```sh +$ cat t.txt +Leading garbage. +#!ruby +puts File.basename(Dir.pwd) +__END__ +Trailing garbage. + +$ ruby -x t.txt +ruby +``` + +The optional argument specifies the directory where the text file +is to be found; +the Ruby code is executed in that directory: + +```sh +$ cp t.txt /tmp/ +$ ruby -x/tmp t.txt +tmp +$ + +``` + +If an argument is given, it must immediately follow the option +(no intervening whitespace or equal-sign character `'='`). + +### `--backtrace-limit`: \Set Backtrace Limit + +Option `--backtrace-limit` sets a limit on the number of entries +to be displayed in a backtrace. + +See Thread::Backtrace.limit. + +### `--copyright`: Print Ruby Copyright + +Option `--copyright` prints a copyright message: + +```sh +$ ruby --copyright +ruby - Copyright (C) 1993-2024 Yukihiro Matsumoto +``` + +### `--debug`: Alias for `-d` + +Option `--debug` is an alias for +{option -d}[rdoc-ref:ruby/options.md@d-3A+Set+-24DEBUG+to+true]. + +### `--disable`: Disable Features + +Option `--disable` specifies features to be disabled; +the argument is a comma-separated list of the features to be disabled: + +```sh +ruby --disable=gems,rubyopt t.rb +``` + +The supported features: + +- `gems`: Rubygems (default: enabled). +- `did_you_mean`: [`did_you_mean`](https://github.com/ruby/did_you_mean) (default: enabled). +- `rubyopt`: `RUBYOPT` environment variable (default: enabled). +- `frozen-string-literal`: Freeze all string literals (default: disabled). +- `jit`: JIT compiler (default: disabled). + +See also {option --enable}[options_md.html#label--enable-3A+Enable+Features]. + +### `--dump`: Dump Items + +Option `--dump` specifies items to be dumped; +the argument is a comma-separated list of the items. + +Some of the argument values cause the command to behave as if a different +option was given: + +- `--dump=copyright`: + Same as {option \-\-copyright}[options_md.html#label--copyright-3A+Print+Ruby+Copyright]. +- `--dump=help`: + Same as {option \-\-help}[options_md.html#label--help-3A+Print+Help+Message]. +- `--dump=syntax`: + Same as {option -c}[rdoc-ref:ruby/options.md@c-3A+Check+Syntax]. +- `--dump=usage`: + Same as {option -h}[rdoc-ref:ruby/options.md@h-3A+Print+Short+Help+Message]. +- `--dump=version`: + Same as {option \-\-version}[options_md.html#label--version-3A+Print+Ruby+Version]. + +For other argument values and examples, +see {Option --dump}[option_dump_md.html]. + +### `--enable`: Enable Features + +Option `--enable` specifies features to be enabled; +the argument is a comma-separated list of the features to be enabled. + +```sh +ruby --enable=gems,rubyopt t.rb +``` + +For the features, +see {option --disable}[options_md.html#label--disable-3A+Disable+Features]. + +### `--encoding`: Alias for `-E`. + +Option `--encoding` is an alias for +{option -E}[rdoc-ref:ruby/options.md@E-3A+Set+Default+Encodings]. + +### `--external-encoding`: \Set Default External \Encoding + +Option `--external-encoding` +sets the default external encoding for the invoked Ruby program; +for values of +encoding+, +see {Encoding: Names and Aliases}[rdoc-ref:encodings.rdoc@Names+and+Aliases]. + +```sh +$ ruby -e 'puts Encoding::default_external' +UTF-8 +$ ruby --external-encoding=cesu-8 -e 'puts Encoding::default_external' +CESU-8 +``` + +### `--help`: Print Help Message + +Option `--help` prints a long help message. + +Arguments and additional options are ignored. + +For a shorter help message, use option `-h`. + +### `--internal-encoding`: \Set Default Internal \Encoding + +Option `--internal-encoding` +sets the default internal encoding for the invoked Ruby program; +for values of +encoding+, +see {Encoding: Names and Aliases}[rdoc-ref:encodings.rdoc@Names+and+Aliases]. + +```sh +$ ruby -e 'puts Encoding::default_internal.nil?' +true +$ ruby --internal-encoding=cesu-8 -e 'puts Encoding::default_internal' +CESU-8 +``` + +### `--verbose`: \Set `$VERBOSE` + +Option `--verbose` sets global variable `$VERBOSE` to `true` +and disables input from `$stdin`. + +### `--version`: Print Ruby Version + +Option `--version` prints the version of the Ruby interpreter, then exits. + +## Experimental Options + +These options are experimental in the current Ruby release, +and may be modified or withdrawn in later releases. + +### `--jit` + +Option `-jit` enables JIT compilation with the default option. + +#### `--jit-debug` + +Option `--jit-debug` enables JIT debugging (very slow); +adds compiler flags if given. + +#### `--jit-max-cache=num` + +Option `--jit-max-cache=num` sets the maximum number of methods +to be JIT-ed in a cache; default: 100). + +#### `--jit-min-calls=num` + +Option `jit-min-calls=num` sets the minimum number of calls to trigger JIT +(for testing); default: 10000). + +#### `--jit-save-temps` + +Option `--jit-save-temps` saves JIT temporary files in $TMP or /tmp (for testing). + +#### `--jit-verbose` + +Option `--jit-verbose` prints JIT logs of level `num` or less +to `$stderr`; default: 0. + +#### `--jit-wait` + +Option `--jit-wait` waits until JIT compilation finishes every time (for testing). + +#### `--jit-warnings` + +Option `--jit-warnings` enables printing of JIT warnings. + diff --git a/doc/security.rdoc b/doc/security.rdoc index ae20ed30fa..e428036cf5 100644 --- a/doc/security.rdoc +++ b/doc/security.rdoc @@ -37,7 +37,7 @@ programs for configuration and database persistence of Ruby object trees. Similar to +Marshal+, it is able to deserialize into arbitrary Ruby classes. For example, the following YAML data will create an +ERB+ object when -deserialized: +deserialized, using the `unsafe_load` method: !ruby/object:ERB src: puts `uname` diff --git a/doc/standard_library.rdoc b/doc/standard_library.rdoc index 1d3580163e..a9fca632f8 100644 --- a/doc/standard_library.rdoc +++ b/doc/standard_library.rdoc @@ -23,41 +23,43 @@ Socket:: Access underlying OS socket implementations = Default gems +* default gems are shipped with Ruby releases and also available as rubygems. +* default gems are not uninstallable from Ruby installation. +* default gems can be updated used by rubygems. + * e.g. `gem update json` +* default gems can be used with bundler environment like `unbundled_env`. +* default gems can be used any version on Gemfile. + * e.g. `gem "json", ">= 2.6"` + == Libraries -Abbrev:: Calculates a set of unique abbreviations for a given set of strings -Base64:: Support for encoding and decoding binary data using a Base64 representation Benchmark:: Provides methods to measure and report the time used to execute code Bundler:: Manage your Ruby application's gem dependencies CGI:: Support for the Common Gateway Interface protocol -CSV:: Provides an interface to read and write CSV files and data -DEBUGGER__:: Debugging functionality for Ruby Delegator:: Provides three abilities to delegate method calls to an object DidYouMean:: "Did you mean?" experience in Ruby -DRb:: Distributed object system for Ruby English:: Provides references to special global variables with less cryptic names ERB:: An easy to use but powerful templating system for Ruby +ErrorHighlight:: Highlight error location in your code FileUtils:: Several file utility methods for copying, moving, removing, etc Find:: This module supports top-down traversal of a set of file paths Forwardable:: Provides delegation of specified methods to a designated object -GetoptLong:: Parse command line options similar to the GNU C getopt_long() IPAddr:: Provides methods to manipulate IPv4 and IPv6 IP addresses IRB:: Interactive Ruby command-line tool for REPL (Read Eval Print Loop) OptionParser:: Ruby-oriented class for command-line option analysis Logger:: Provides a simple logging utility for outputting messages -Mutex_m:: Mixin to extend objects to be handled like a Mutex Net::HTTP:: HTTP client api for Ruby -Observable:: Provides a mechanism for publish/subscribe pattern in Ruby Open3:: Provides access to stdin, stdout and stderr when running other programs OpenStruct:: Class to build custom data structures, similar to a Hash OpenURI:: An easy-to-use wrapper for Net::HTTP, Net::HTTPS and Net::FTP PP:: Provides a PrettyPrinter for Ruby objects PrettyPrinter:: Implements a pretty printing algorithm for readable structure +Prism:: A portable, error-tolerant Ruby parser PStore:: Implements a file based persistence mechanism based on a Hash +Readline:: Wrapper for Readline extencion and Reline +Reline:: GNU Readline and Editline by pure Ruby implementation. Resolv:: Thread-aware DNS resolver library in Ruby -resolv-replace.rb:: Replace Socket DNS with Resolv RDoc:: Produces HTML and command-line documentation for Ruby -Rinda:: The Linda distributed computing paradigm in Ruby SecureRandom:: Interface for secure random number generator Set:: Provides a class to deal with collections of unordered, unique values Shellwords:: Manipulates strings with word parsing rules of UNIX Bourne shell @@ -74,7 +76,6 @@ WeakRef:: Allows a referenced object to be garbage-collected == Extensions -BigDecimal:: Provides arbitrary-precision floating point decimal arithmetic Date:: A subclass of Object includes Comparable module for handling dates DateTime:: Subclass of Date to handling dates, hours, minutes, seconds, offsets Digest:: Provides a framework for message digest libraries @@ -83,20 +84,22 @@ Fcntl:: Loads constants defined in the OS fcntl.h C header file Fiddle:: A libffi wrapper for Ruby IO:: Extensions for Ruby IO class, including #wait, #nonblock and ::console JSON:: Implements Javascript Object Notation for Ruby -NKF:: Ruby extension for Network Kanji Filter OpenSSL:: Provides SSL, TLS and general purpose cryptography for Ruby Pathname:: Representation of the name of a file or directory on the filesystem Psych:: A YAML parser and emitter for Ruby -Racc:: A LALR(1) parser generator written in Ruby. -Readline:: Provides an interface for GNU Readline and Edit Line (libedit) StringIO:: Pseudo I/O on String objects StringScanner:: Provides lexical scanning operations on a String -Syslog:: Ruby interface for the POSIX system logging facility WIN32OLE:: Provides an interface for OLE Automation in Ruby Zlib:: Ruby interface for the zlib compression/decompression library = Bundled gems +* bundled gems are shipped with Ruby releases and also available as rubygems. +* bundled gems are same as normal gems like `rails`, `rack`. + * They are only bundled with Ruby releases. + * They can be uninstallable from Ruby installation. + * They are needed to declare in Gemfile when use with bundler. + == Libraries MiniTest:: A test suite with TDD, BDD, mocking and benchmarking @@ -113,3 +116,17 @@ Matrix:: Represents a mathematical matrix. Prime:: Prime numbers and factorization library RBS:: RBS is a language to describe the structure of Ruby programs TypeProf:: A type analysis tool for Ruby code based on abstract interpretation +DEBUGGER__:: Debugging functionality for Ruby +Racc:: A LALR(1) parser generator written in Ruby. +Mutex_m:: Mixin to extend objects to be handled like a Mutex +GetoptLong:: Parse command line options similar to the GNU C getopt_long() +Base64:: Support for encoding and decoding binary data using a Base64 representation +BigDecimal:: Provides arbitrary-precision floating point decimal arithmetic +Observable:: Provides a mechanism for publish/subscribe pattern in Ruby +Abbrev:: Calculates a set of unique abbreviations for a given set of strings +resolv-replace.rb:: Replace Socket DNS with Resolv +Rinda:: The Linda distributed computing paradigm in Ruby +DRb:: Distributed object system for Ruby +NKF:: Ruby extension for Network Kanji Filter +Syslog:: Ruby interface for the POSIX system logging facility +CSV:: Provides an interface to read and write CSV files and data diff --git a/doc/strftime_formatting.rdoc b/doc/strftime_formatting.rdoc new file mode 100644 index 0000000000..5c7b33155d --- /dev/null +++ b/doc/strftime_formatting.rdoc @@ -0,0 +1,527 @@ += Formats for Dates and Times + +Several Ruby time-related classes have instance method +strftime+, +which returns a formatted string representing all or part of a date or time: + +- Date#strftime. +- DateTime#strftime. +- Time#strftime. + +Each of these methods takes optional argument +format+, +which has zero or more embedded _format_ _specifications_ (see below). + +Each of these methods returns the string resulting from replacing each +format specification embedded in +format+ with a string form +of one or more parts of the date or time. + +A simple example: + + Time.now.strftime('%H:%M:%S') # => "14:02:07" + +A format specification has the form: + + %[flags][width]conversion + +It consists of: + +- A leading percent character. +- Zero or more _flags_ (each is a character). +- An optional _width_ _specifier_ (an integer). +- A _conversion_ _specifier_ (a character). + +Except for the leading percent character, +the only required part is the conversion specifier, so we begin with that. + +== Conversion Specifiers + +=== \Date (Year, Month, Day) + +- <tt>%Y</tt> - Year including century, zero-padded: + + Time.now.strftime('%Y') # => "2022" + Time.new(-1000).strftime('%Y') # => "-1000" # Before common era. + Time.new(10000).strftime('%Y') # => "10000" # Far future. + Time.new(10).strftime('%Y') # => "0010" # Zero-padded by default. + +- <tt>%y</tt> - Year without century, in range (0.99), zero-padded: + + Time.now.strftime('%y') # => "22" + Time.new(1).strftime('%y') # => "01" # Zero-padded by default. + +- <tt>%C</tt> - Century, zero-padded: + + Time.now.strftime('%C') # => "20" + Time.new(-1000).strftime('%C') # => "-10" # Before common era. + Time.new(10000).strftime('%C') # => "100" # Far future. + Time.new(100).strftime('%C') # => "01" # Zero-padded by default. + +- <tt>%m</tt> - Month of the year, in range (1..12), zero-padded: + + Time.new(2022, 1).strftime('%m') # => "01" # Zero-padded by default. + Time.new(2022, 12).strftime('%m') # => "12" + +- <tt>%B</tt> - Full month name, capitalized: + + Time.new(2022, 1).strftime('%B') # => "January" + Time.new(2022, 12).strftime('%B') # => "December" + +- <tt>%b</tt> - Abbreviated month name, capitalized: + + Time.new(2022, 1).strftime('%b') # => "Jan" + Time.new(2022, 12).strftime('%h') # => "Dec" + +- <tt>%h</tt> - Same as <tt>%b</tt>. + +- <tt>%d</tt> - Day of the month, in range (1..31), zero-padded: + + Time.new(2002, 1, 1).strftime('%d') # => "01" + Time.new(2002, 1, 31).strftime('%d') # => "31" + +- <tt>%e</tt> - Day of the month, in range (1..31), blank-padded: + + Time.new(2002, 1, 1).strftime('%e') # => " 1" + Time.new(2002, 1, 31).strftime('%e') # => "31" + +- <tt>%j</tt> - Day of the year, in range (1..366), zero-padded: + + Time.new(2002, 1, 1).strftime('%j') # => "001" + Time.new(2002, 12, 31).strftime('%j') # => "365" + +=== \Time (Hour, Minute, Second, Subsecond) + +- <tt>%H</tt> - Hour of the day, in range (0..23), zero-padded: + + Time.new(2022, 1, 1, 1).strftime('%H') # => "01" + Time.new(2022, 1, 1, 13).strftime('%H') # => "13" + +- <tt>%k</tt> - Hour of the day, in range (0..23), blank-padded: + + Time.new(2022, 1, 1, 1).strftime('%k') # => " 1" + Time.new(2022, 1, 1, 13).strftime('%k') # => "13" + +- <tt>%I</tt> - Hour of the day, in range (1..12), zero-padded: + + Time.new(2022, 1, 1, 1).strftime('%I') # => "01" + Time.new(2022, 1, 1, 13).strftime('%I') # => "01" + +- <tt>%l</tt> - Hour of the day, in range (1..12), blank-padded: + + Time.new(2022, 1, 1, 1).strftime('%l') # => " 1" + Time.new(2022, 1, 1, 13).strftime('%l') # => " 1" + +- <tt>%P</tt> - Meridian indicator, lowercase: + + Time.new(2022, 1, 1, 1).strftime('%P') # => "am" + Time.new(2022, 1, 1, 13).strftime('%P') # => "pm" + +- <tt>%p</tt> - Meridian indicator, uppercase: + + Time.new(2022, 1, 1, 1).strftime('%p') # => "AM" + Time.new(2022, 1, 1, 13).strftime('%p') # => "PM" + +- <tt>%M</tt> - Minute of the hour, in range (0..59), zero-padded: + + Time.new(2022, 1, 1, 1, 0, 0).strftime('%M') # => "00" + +- <tt>%S</tt> - Second of the minute in range (0..59), zero-padded: + + Time.new(2022, 1, 1, 1, 0, 0, 0).strftime('%S') # => "00" + +- <tt>%L</tt> - Millisecond of the second, in range (0..999), zero-padded: + + Time.new(2022, 1, 1, 1, 0, 0, 0).strftime('%L') # => "000" + +- <tt>%N</tt> - Fractional seconds, default width is 9 digits (nanoseconds): + + t = Time.now # => 2022-06-29 07:10:20.3230914 -0500 + t.strftime('%N') # => "323091400" # Default. + + Use {width specifiers}[rdoc-ref:strftime_formatting.rdoc@Width+Specifiers] + to adjust units: + + t.strftime('%3N') # => "323" # Milliseconds. + t.strftime('%6N') # => "323091" # Microseconds. + t.strftime('%9N') # => "323091400" # Nanoseconds. + t.strftime('%12N') # => "323091400000" # Picoseconds. + t.strftime('%15N') # => "323091400000000" # Femptoseconds. + t.strftime('%18N') # => "323091400000000000" # Attoseconds. + t.strftime('%21N') # => "323091400000000000000" # Zeptoseconds. + t.strftime('%24N') # => "323091400000000000000000" # Yoctoseconds. + +- <tt>%s</tt> - Number of seconds since the epoch: + + Time.now.strftime('%s') # => "1656505136" + +=== Timezone + +- <tt>%z</tt> - Timezone as hour and minute offset from UTC: + + Time.now.strftime('%z') # => "-0500" + +- <tt>%Z</tt> - Timezone name (platform-dependent): + + Time.now.strftime('%Z') # => "Central Daylight Time" + +=== Weekday + +- <tt>%A</tt> - Full weekday name: + + Time.now.strftime('%A') # => "Wednesday" + +- <tt>%a</tt> - Abbreviated weekday name: + + Time.now.strftime('%a') # => "Wed" + +- <tt>%u</tt> - Day of the week, in range (1..7), Monday is 1: + + t = Time.new(2022, 6, 26) # => 2022-06-26 00:00:00 -0500 + t.strftime('%a') # => "Sun" + t.strftime('%u') # => "7" + +- <tt>%w</tt> - Day of the week, in range (0..6), Sunday is 0: + + t = Time.new(2022, 6, 26) # => 2022-06-26 00:00:00 -0500 + t.strftime('%a') # => "Sun" + t.strftime('%w') # => "0" + +=== Week Number + +- <tt>%U</tt> - Week number of the year, in range (0..53), zero-padded, + where each week begins on a Sunday: + + t = Time.new(2022, 6, 26) # => 2022-06-26 00:00:00 -0500 + t.strftime('%a') # => "Sun" + t.strftime('%U') # => "26" + +- <tt>%W</tt> - Week number of the year, in range (0..53), zero-padded, + where each week begins on a Monday: + + t = Time.new(2022, 6, 26) # => 2022-06-26 00:00:00 -0500 + t.strftime('%a') # => "Sun" + t.strftime('%W') # => "25" + +=== Week Dates + +See {ISO 8601 week dates}[https://en.wikipedia.org/wiki/ISO_8601#Week_dates]. + + t0 = Time.new(2023, 1, 1) # => 2023-01-01 00:00:00 -0600 + t1 = Time.new(2024, 1, 1) # => 2024-01-01 00:00:00 -0600 + +- <tt>%G</tt> - Week-based year: + + t0.strftime('%G') # => "2022" + t1.strftime('%G') # => "2024" + +- <tt>%g</tt> - Week-based year without century, in range (0..99), zero-padded: + + t0.strftime('%g') # => "22" + t1.strftime('%g') # => "24" + +- <tt>%V</tt> - Week number of the week-based year, in range (1..53), + zero-padded: + + t0.strftime('%V') # => "52" + t1.strftime('%V') # => "01" + +=== Literals + +- <tt>%n</tt> - Newline character "\n": + + Time.now.strftime('%n') # => "\n" + +- <tt>%t</tt> - Tab character "\t": + + Time.now.strftime('%t') # => "\t" + +- <tt>%%</tt> - Percent character '%': + + Time.now.strftime('%%') # => "%" + +=== Shorthand Conversion Specifiers + +Each shorthand specifier here is shown with its corresponding +longhand specifier. + +- <tt>%c</tt> - \Date and time: + + Time.now.strftime('%c') # => "Wed Jun 29 08:01:41 2022" + Time.now.strftime('%a %b %e %T %Y') # => "Wed Jun 29 08:02:07 2022" + +- <tt>%D</tt> - \Date: + + Time.now.strftime('%D') # => "06/29/22" + Time.now.strftime('%m/%d/%y') # => "06/29/22" + +- <tt>%F</tt> - ISO 8601 date: + + Time.now.strftime('%F') # => "2022-06-29" + Time.now.strftime('%Y-%m-%d') # => "2022-06-29" + +- <tt>%v</tt> - VMS date: + + Time.now.strftime('%v') # => "29-JUN-2022" + Time.now.strftime('%e-%^b-%4Y') # => "29-JUN-2022" + +- <tt>%x</tt> - Same as <tt>%D</tt>. + +- <tt>%X</tt> - Same as <tt>%T</tt>. + +- <tt>%r</tt> - 12-hour time: + + Time.new(2022, 1, 1, 1).strftime('%r') # => "01:00:00 AM" + Time.new(2022, 1, 1, 1).strftime('%I:%M:%S %p') # => "01:00:00 AM" + Time.new(2022, 1, 1, 13).strftime('%r') # => "01:00:00 PM" + Time.new(2022, 1, 1, 13).strftime('%I:%M:%S %p') # => "01:00:00 PM" + +- <tt>%R</tt> - 24-hour time: + + Time.new(2022, 1, 1, 1).strftime('%R') # => "01:00" + Time.new(2022, 1, 1, 1).strftime('%H:%M') # => "01:00" + Time.new(2022, 1, 1, 13).strftime('%R') # => "13:00" + Time.new(2022, 1, 1, 13).strftime('%H:%M') # => "13:00" + +- <tt>%T</tt> - 24-hour time: + + Time.new(2022, 1, 1, 1).strftime('%T') # => "01:00:00" + Time.new(2022, 1, 1, 1).strftime('%H:%M:%S') # => "01:00:00" + Time.new(2022, 1, 1, 13).strftime('%T') # => "13:00:00" + Time.new(2022, 1, 1, 13).strftime('%H:%M:%S') # => "13:00:00" + +- <tt>%+</tt> (not supported in Time#strftime) - \Date and time: + + DateTime.now.strftime('%+') + # => "Wed Jun 29 08:31:53 -05:00 2022" + DateTime.now.strftime('%a %b %e %H:%M:%S %Z %Y') + # => "Wed Jun 29 08:32:18 -05:00 2022" + +== Flags + +Flags may affect certain formatting specifications. + +Multiple flags may be given with a single conversion specified; +order does not matter. + +=== Padding Flags + +- <tt>0</tt> - Pad with zeroes: + + Time.new(10).strftime('%0Y') # => "0010" + +- <tt>_</tt> - Pad with blanks: + + Time.new(10).strftime('%_Y') # => " 10" + +- <tt>-</tt> - Don't pad: + + Time.new(10).strftime('%-Y') # => "10" + +=== Casing Flags + +- <tt>^</tt> - Upcase result: + + Time.new(2022, 1).strftime('%B') # => "January" # No casing flag. + Time.new(2022, 1).strftime('%^B') # => "JANUARY" + +- <tt>#</tt> - Swapcase result: + + Time.now.strftime('%p') # => "AM" + Time.now.strftime('%^p') # => "AM" + Time.now.strftime('%#p') # => "am" + +=== Timezone Flags + +- <tt>:</tt> - Put timezone as colon-separated hours and minutes: + + Time.now.strftime('%:z') # => "-05:00" + +- <tt>::</tt> - Put timezone as colon-separated hours, minutes, and seconds: + + Time.now.strftime('%::z') # => "-05:00:00" + +== Width Specifiers + +The integer width specifier gives a minimum width for the returned string: + + Time.new(2002).strftime('%Y') # => "2002" # No width specifier. + Time.new(2002).strftime('%10Y') # => "0000002002" + Time.new(2002, 12).strftime('%B') # => "December" # No width specifier. + Time.new(2002, 12).strftime('%10B') # => " December" + Time.new(2002, 12).strftime('%3B') # => "December" # Ignored if too small. + += Specialized Format Strings + +Here are a few specialized format strings, +each based on an external standard. + +== HTTP Format + +The HTTP date format is based on +{RFC 2616}[https://www.rfc-editor.org/rfc/rfc2616], +and treats dates in the format <tt>'%a, %d %b %Y %T GMT'</tt>: + + d = Date.new(2001, 2, 3) # => #<Date: 2001-02-03> + # Return HTTP-formatted string. + httpdate = d.httpdate # => "Sat, 03 Feb 2001 00:00:00 GMT" + # Return new date parsed from HTTP-formatted string. + Date.httpdate(httpdate) # => #<Date: 2001-02-03> + # Return hash parsed from HTTP-formatted string. + Date._httpdate(httpdate) + # => {:wday=>6, :mday=>3, :mon=>2, :year=>2001, :hour=>0, :min=>0, :sec=>0, :zone=>"GMT", :offset=>0} + +== RFC 3339 Format + +The RFC 3339 date format is based on +{RFC 3339}[https://www.rfc-editor.org/rfc/rfc3339]: + + d = Date.new(2001, 2, 3) # => #<Date: 2001-02-03> + # Return 3339-formatted string. + rfc3339 = d.rfc3339 # => "2001-02-03T00:00:00+00:00" + # Return new date parsed from 3339-formatted string. + Date.rfc3339(rfc3339) # => #<Date: 2001-02-03> + # Return hash parsed from 3339-formatted string. + Date._rfc3339(rfc3339) + # => {:year=>2001, :mon=>2, :mday=>3, :hour=>0, :min=>0, :sec=>0, :zone=>"+00:00", :offset=>0} + +== RFC 2822 Format + +The RFC 2822 date format is based on +{RFC 2822}[https://www.rfc-editor.org/rfc/rfc2822], +and treats dates in the format <tt>'%a, %-d %b %Y %T %z'</tt>]: + + d = Date.new(2001, 2, 3) # => #<Date: 2001-02-03> + # Return 2822-formatted string. + rfc2822 = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" + # Return new date parsed from 2822-formatted string. + Date.rfc2822(rfc2822) # => #<Date: 2001-02-03> + # Return hash parsed from 2822-formatted string. + Date._rfc2822(rfc2822) + # => {:wday=>6, :mday=>3, :mon=>2, :year=>2001, :hour=>0, :min=>0, :sec=>0, :zone=>"+0000", :offset=>0} + +== JIS X 0301 Format + +The JIS X 0301 format includes the +{Japanese era name}[https://en.wikipedia.org/wiki/Japanese_era_name], +and treats dates in the format <tt>'%Y-%m-%d'</tt> +with the first letter of the romanized era name prefixed: + + d = Date.new(2001, 2, 3) # => #<Date: 2001-02-03> + # Return 0301-formatted string. + jisx0301 = d.jisx0301 # => "H13.02.03" + # Return new date parsed from 0301-formatted string. + Date.jisx0301(jisx0301) # => #<Date: 2001-02-03> + # Return hash parsed from 0301-formatted string. + Date._jisx0301(jisx0301) # => {:year=>2001, :mon=>2, :mday=>3} + +== ISO 8601 Format Specifications + +This section shows format specifications that are compatible with +{ISO 8601}[https://en.wikipedia.org/wiki/ISO_8601]. +Details for various formats may be seen at the links. + +Examples in this section assume: + + t = Time.now # => 2022-06-29 16:49:25.465246 -0500 + +=== Dates + +See {ISO 8601 dates}[https://en.wikipedia.org/wiki/ISO_8601#Dates]. + +- {Years}[https://en.wikipedia.org/wiki/ISO_8601#Years]: + + - Basic year (+YYYY+): + + t.strftime('%Y') # => "2022" + + - Expanded year (<tt>±YYYYY</tt>): + + t.strftime('+%5Y') # => "+02022" + t.strftime('-%5Y') # => "-02022" + +- {Calendar dates}[https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates]: + + - Basic date (+YYYYMMDD+): + + t.strftime('%Y%m%d') # => "20220629" + + - Extended date (<tt>YYYY-MM-DD</tt>): + + t.strftime('%Y-%m-%d') # => "2022-06-29" + + - Reduced extended date (<tt>YYYY-MM</tt>): + + t.strftime('%Y-%m') # => "2022-06" + +- {Week dates}[https://en.wikipedia.org/wiki/ISO_8601#Week_dates]: + + - Basic date (+YYYYWww+ or +YYYYWwwD+): + + t.strftime('%Y%Ww') # => "202226w" + t.strftime('%Y%Ww%u') # => "202226w3" + + - Extended date (<tt>YYYY-Www</tt> or <tt>YYYY-Www-D<tt>): + + t.strftime('%Y-%Ww') # => "2022-26w" + t.strftime('%Y-%Ww-%u') # => "2022-26w-3" + +- {Ordinal dates}[https://en.wikipedia.org/wiki/ISO_8601#Ordinal_dates]: + + - Basic date (+YYYYDDD+): + + t.strftime('%Y%j') # => "2022180" + + - Extended date (<tt>YYYY-DDD</tt>): + + t.strftime('%Y-%j') # => "2022-180" + +=== Times + +See {ISO 8601 times}[https://en.wikipedia.org/wiki/ISO_8601#Times]. + +- Times: + + - Basic time (+Thhmmss.sss+, +Thhmmss+, +Thhmm+, or +Thh+): + + t.strftime('T%H%M%S.%L') # => "T164925.465" + t.strftime('T%H%M%S') # => "T164925" + t.strftime('T%H%M') # => "T1649" + t.strftime('T%H') # => "T16" + + - Extended time (+Thh:mm:ss.sss+, +Thh:mm:ss+, or +Thh:mm+): + + t.strftime('T%H:%M:%S.%L') # => "T16:49:25.465" + t.strftime('T%H:%M:%S') # => "T16:49:25" + t.strftime('T%H:%M') # => "T16:49" + +- {Time zone designators}[https://en.wikipedia.org/wiki/ISO_8601#Time_zone_designators]: + + - Timezone (+time+ represents a valid time, + +hh+ represents a valid 2-digit hour, + and +mm+ represents a valid 2-digit minute): + + - Basic timezone (<tt>time±hhmm</tt>, <tt>time±hh</tt>, or +timeZ+): + + t.strftime('T%H%M%S%z') # => "T164925-0500" + t.strftime('T%H%M%S%z').slice(0..-3) # => "T164925-05" + t.strftime('T%H%M%SZ') # => "T164925Z" + + - Extended timezone (<tt>time±hh:mm</tt>): + + t.strftime('T%H:%M:%S%z') # => "T16:49:25-0500" + + - See also: + + - {Local time (unqualified)}[https://en.wikipedia.org/wiki/ISO_8601#Local_time_(unqualified)]. + - {Coordinated Universal Time (UTC)}[https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_(UTC)]. + - {Time offsets from UTC}[https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC]. + +=== Combined \Date and \Time + +See {ISO 8601 Combined date and time representations}[https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations]. + +An ISO 8601 combined date and time representation may be any +ISO 8601 date and any ISO 8601 time, +separated by the letter +T+. + +For the relevant +strftime+ formats, see +{Dates}[rdoc-ref:strftime_formatting.rdoc@Dates] +and {Times}[rdoc-ref:strftime_formatting.rdoc@Times] above. diff --git a/doc/string/b.rdoc b/doc/string/b.rdoc new file mode 100644 index 0000000000..f8ad2910b4 --- /dev/null +++ b/doc/string/b.rdoc @@ -0,0 +1,14 @@ +Returns a copy of +self+ that has ASCII-8BIT encoding; +the underlying bytes are not modified: + + s = "\x99" + s.encoding # => #<Encoding:UTF-8> + t = s.b # => "\x99" + t.encoding # => #<Encoding:ASCII-8BIT> + + s = "\u4095" # => "䂕" + s.encoding # => #<Encoding:UTF-8> + s.bytes # => [228, 130, 149] + t = s.b # => "\xE4\x82\x95" + t.encoding # => #<Encoding:ASCII-8BIT> + t.bytes # => [228, 130, 149] diff --git a/doc/string/bytes.rdoc b/doc/string/bytes.rdoc new file mode 100644 index 0000000000..a9e89f1cd1 --- /dev/null +++ b/doc/string/bytes.rdoc @@ -0,0 +1,6 @@ +Returns an array of the bytes in +self+: + + 'hello'.bytes # => [104, 101, 108, 108, 111] + 'тест'.bytes # => [209, 130, 208, 181, 209, 129, 209, 130] + 'こんにちは'.bytes + # => [227, 129, 147, 227, 130, 147, 227, 129, 171, 227, 129, 161, 227, 129, 175] diff --git a/doc/string/bytesize.rdoc b/doc/string/bytesize.rdoc new file mode 100644 index 0000000000..b0567ff67b --- /dev/null +++ b/doc/string/bytesize.rdoc @@ -0,0 +1,11 @@ +Returns the count of bytes (not characters) in +self+: + + 'foo'.bytesize # => 3 + 'тест'.bytesize # => 8 + 'こんにちは'.bytesize # => 15 + +Contrast with String#length: + + 'foo'.length # => 3 + 'тест'.length # => 4 + 'こんにちは'.length # => 5 diff --git a/doc/string/center.rdoc b/doc/string/center.rdoc new file mode 100644 index 0000000000..d53d921ad5 --- /dev/null +++ b/doc/string/center.rdoc @@ -0,0 +1,16 @@ +Returns a centered copy of +self+. + +If integer argument +size+ is greater than the size (in characters) of +self+, +returns a new string of length +size+ that is a copy of +self+, +centered and padded on both ends with +pad_string+: + + 'hello'.center(10) # => " hello " + ' hello'.center(10) # => " hello " + 'hello'.center(10, 'ab') # => "abhelloaba" + 'тест'.center(10) # => " тест " + 'こんにちは'.center(10) # => " こんにちは " + +If +size+ is not greater than the size of +self+, returns a copy of +self+: + + 'hello'.center(5) # => "hello" + 'hello'.center(1) # => "hello" diff --git a/doc/string/chars.rdoc b/doc/string/chars.rdoc new file mode 100644 index 0000000000..d24a1cc3a9 --- /dev/null +++ b/doc/string/chars.rdoc @@ -0,0 +1,5 @@ +Returns an array of the characters in +self+: + + 'hello'.chars # => ["h", "e", "l", "l", "o"] + 'тест'.chars # => ["т", "е", "с", "т"] + 'こんにちは'.chars # => ["こ", "ん", "に", "ち", "は"] diff --git a/doc/string/chomp.rdoc b/doc/string/chomp.rdoc new file mode 100644 index 0000000000..b6fb9ff38c --- /dev/null +++ b/doc/string/chomp.rdoc @@ -0,0 +1,29 @@ +Returns a new string copied from +self+, with trailing characters possibly removed: + +When +line_sep+ is <tt>"\n"</tt>, removes the last one or two characters +if they are <tt>"\r"</tt>, <tt>"\n"</tt>, or <tt>"\r\n"</tt> +(but not <tt>"\n\r"</tt>): + + $/ # => "\n" + "abc\r".chomp # => "abc" + "abc\n".chomp # => "abc" + "abc\r\n".chomp # => "abc" + "abc\n\r".chomp # => "abc\n" + "тест\r\n".chomp # => "тест" + "こんにちは\r\n".chomp # => "こんにちは" + +When +line_sep+ is <tt>''</tt> (an empty string), +removes multiple trailing occurrences of <tt>"\n"</tt> or <tt>"\r\n"</tt> +(but not <tt>"\r"</tt> or <tt>"\n\r"</tt>): + + "abc\n\n\n".chomp('') # => "abc" + "abc\r\n\r\n\r\n".chomp('') # => "abc" + "abc\n\n\r\n\r\n\n\n".chomp('') # => "abc" + "abc\n\r\n\r\n\r".chomp('') # => "abc\n\r\n\r\n\r" + "abc\r\r\r".chomp('') # => "abc\r\r\r" + +When +line_sep+ is neither <tt>"\n"</tt> nor <tt>''</tt>, +removes a single trailing line separator if there is one: + + 'abcd'.chomp('d') # => "abc" + 'abcdd'.chomp('d') # => "abcd" diff --git a/doc/string/chop.rdoc b/doc/string/chop.rdoc new file mode 100644 index 0000000000..8ef82f8a49 --- /dev/null +++ b/doc/string/chop.rdoc @@ -0,0 +1,16 @@ +Returns a new string copied from +self+, with trailing characters possibly removed. + +Removes <tt>"\r\n"</tt> if those are the last two characters. + + "abc\r\n".chop # => "abc" + "тест\r\n".chop # => "тест" + "こんにちは\r\n".chop # => "こんにちは" + +Otherwise removes the last character if it exists. + + 'abcd'.chop # => "abc" + 'тест'.chop # => "тес" + 'こんにちは'.chop # => "こんにち" + ''.chop # => "" + +If you only need to remove the newline separator at the end of the string, String#chomp is a better alternative. diff --git a/doc/string/codepoints.rdoc b/doc/string/codepoints.rdoc new file mode 100644 index 0000000000..0c55d3f4b9 --- /dev/null +++ b/doc/string/codepoints.rdoc @@ -0,0 +1,6 @@ +Returns an array of the codepoints in +self+; +each codepoint is the integer value for a character: + + 'hello'.codepoints # => [104, 101, 108, 108, 111] + 'тест'.codepoints # => [1090, 1077, 1089, 1090] + 'こんにちは'.codepoints # => [12371, 12435, 12395, 12385, 12399] diff --git a/doc/string/delete_prefix.rdoc b/doc/string/delete_prefix.rdoc new file mode 100644 index 0000000000..fa9d8abd38 --- /dev/null +++ b/doc/string/delete_prefix.rdoc @@ -0,0 +1,8 @@ +Returns a copy of +self+ with leading substring <tt>prefix</tt> removed: + + 'hello'.delete_prefix('hel') # => "lo" + 'hello'.delete_prefix('llo') # => "hello" + 'тест'.delete_prefix('те') # => "ст" + 'こんにちは'.delete_prefix('こん') # => "にちは" + +Related: String#delete_prefix!, String#delete_suffix. diff --git a/doc/string/delete_suffix.rdoc b/doc/string/delete_suffix.rdoc new file mode 100644 index 0000000000..4862b725cf --- /dev/null +++ b/doc/string/delete_suffix.rdoc @@ -0,0 +1,8 @@ +Returns a copy of +self+ with trailing substring <tt>suffix</tt> removed: + + 'hello'.delete_suffix('llo') # => "he" + 'hello'.delete_suffix('hel') # => "hello" + 'тест'.delete_suffix('ст') # => "те" + 'こんにちは'.delete_suffix('ちは') # => "こんに" + +Related: String#delete_suffix!, String#delete_prefix. diff --git a/doc/string/each_byte.rdoc b/doc/string/each_byte.rdoc new file mode 100644 index 0000000000..643118fea3 --- /dev/null +++ b/doc/string/each_byte.rdoc @@ -0,0 +1,17 @@ +Calls the given block with each successive byte from +self+; +returns +self+: + + 'hello'.each_byte {|byte| print byte, ' ' } + print "\n" + 'тест'.each_byte {|byte| print byte, ' ' } + print "\n" + 'こんにちは'.each_byte {|byte| print byte, ' ' } + print "\n" + +Output: + + 104 101 108 108 111 + 209 130 208 181 209 129 209 130 + 227 129 147 227 130 147 227 129 171 227 129 161 227 129 175 + +Returns an enumerator if no block is given. diff --git a/doc/string/each_char.rdoc b/doc/string/each_char.rdoc new file mode 100644 index 0000000000..e5ae5a1812 --- /dev/null +++ b/doc/string/each_char.rdoc @@ -0,0 +1,17 @@ +Calls the given block with each successive character from +self+; +returns +self+: + + 'hello'.each_char {|char| print char, ' ' } + print "\n" + 'тест'.each_char {|char| print char, ' ' } + print "\n" + 'こんにちは'.each_char {|char| print char, ' ' } + print "\n" + +Output: + + h e l l o + т е с т + こ ん に ち は + +Returns an enumerator if no block is given. diff --git a/doc/string/each_codepoint.rdoc b/doc/string/each_codepoint.rdoc new file mode 100644 index 0000000000..88bfcbd1c0 --- /dev/null +++ b/doc/string/each_codepoint.rdoc @@ -0,0 +1,18 @@ +Calls the given block with each successive codepoint from +self+; +each codepoint is the integer value for a character; +returns +self+: + + 'hello'.each_codepoint {|codepoint| print codepoint, ' ' } + print "\n" + 'тест'.each_codepoint {|codepoint| print codepoint, ' ' } + print "\n" + 'こんにちは'.each_codepoint {|codepoint| print codepoint, ' ' } + print "\n" + +Output: + + 104 101 108 108 111 + 1090 1077 1089 1090 + 12371 12435 12395 12385 12399 + +Returns an enumerator if no block is given. diff --git a/doc/string/each_grapheme_cluster.rdoc b/doc/string/each_grapheme_cluster.rdoc new file mode 100644 index 0000000000..40be95fcac --- /dev/null +++ b/doc/string/each_grapheme_cluster.rdoc @@ -0,0 +1,12 @@ +Calls the given block with each successive grapheme cluster from +self+ +(see {Unicode Grapheme Cluster Boundaries}[https://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries]); +returns +self+: + + s = "\u0061\u0308-pqr-\u0062\u0308-xyz-\u0063\u0308" # => "ä-pqr-b̈-xyz-c̈" + s.each_grapheme_cluster {|gc| print gc, ' ' } + +Output: + + ä - p q r - b̈ - x y z - c̈ + +Returns an enumerator if no block is given. diff --git a/doc/string/each_line.rdoc b/doc/string/each_line.rdoc new file mode 100644 index 0000000000..e254c22d40 --- /dev/null +++ b/doc/string/each_line.rdoc @@ -0,0 +1,60 @@ +With a block given, forms the substrings ("lines") +that are the result of splitting +self+ +at each occurrence of the given line separator +line_sep+; +passes each line to the block; +returns +self+: + + s = <<~EOT + This is the first line. + This is line two. + + This is line four. + This is line five. + EOT + + s.each_line {|line| p line } + +Output: + + "This is the first line.\n" + "This is line two.\n" + "\n" + "This is line four.\n" + "This is line five.\n" + +With a different +line_sep+: + + s.each_line(' is ') {|line| p line } + +Output: + + "This is " + "the first line.\nThis is " + "line two.\n\nThis is " + "line four.\nThis is " + "line five.\n" + +With +chomp+ as +true+, removes the trailing +line_sep+ from each line: + + s.each_line(chomp: true) {|line| p line } + +Output: + + "This is the first line." + "This is line two." + "" + "This is line four." + "This is line five." + +With an empty string as +line_sep+, +forms and passes "paragraphs" by splitting at each occurrence +of two or more newlines: + + s.each_line('') {|line| p line } + +Output: + + "This is the first line.\nThis is line two.\n\n" + "This is line four.\nThis is line five.\n" + +With no block given, returns an enumerator. diff --git a/doc/string/encode.rdoc b/doc/string/encode.rdoc new file mode 100644 index 0000000000..65872fdfd4 --- /dev/null +++ b/doc/string/encode.rdoc @@ -0,0 +1,47 @@ +Returns a copy of +self+ transcoded as determined by +dst_encoding+. +By default, raises an exception if +self+ +contains an invalid byte or a character not defined in +dst_encoding+; +that behavior may be modified by encoding options; see below. + +With no arguments: + +- Uses the same encoding if <tt>Encoding.default_internal</tt> is +nil+ + (the default): + + Encoding.default_internal # => nil + s = "Ruby\x99".force_encoding('Windows-1252') + s.encoding # => #<Encoding:Windows-1252> + s.bytes # => [82, 117, 98, 121, 153] + t = s.encode # => "Ruby\x99" + t.encoding # => #<Encoding:Windows-1252> + t.bytes # => [82, 117, 98, 121, 226, 132, 162] + +- Otherwise, uses the encoding <tt>Encoding.default_internal</tt>: + + Encoding.default_internal = 'UTF-8' + t = s.encode # => "Ruby™" + t.encoding # => #<Encoding:UTF-8> + +With only argument +dst_encoding+ given, uses that encoding: + + s = "Ruby\x99".force_encoding('Windows-1252') + s.encoding # => #<Encoding:Windows-1252> + t = s.encode('UTF-8') # => "Ruby™" + t.encoding # => #<Encoding:UTF-8> + +With arguments +dst_encoding+ and +src_encoding+ given, +interprets +self+ using +src_encoding+, encodes the new string using +dst_encoding+: + + s = "Ruby\x99" + t = s.encode('UTF-8', 'Windows-1252') # => "Ruby™" + t.encoding # => #<Encoding:UTF-8> + +Optional keyword arguments +enc_opts+ specify encoding options; +see {Encoding Options}[rdoc-ref:encodings.rdoc@Encoding+Options]. + +Please note that, unless <code>invalid: :replace</code> option is +given, conversion from an encoding +enc+ to the same encoding +enc+ +(independent of whether +enc+ is given explicitly or implicitly) is a +no-op, i.e. the string is simply copied without any changes, and no +exceptions are raised, even if there are invalid bytes. + diff --git a/doc/string/end_with_p.rdoc b/doc/string/end_with_p.rdoc new file mode 100644 index 0000000000..f959cf7aaa --- /dev/null +++ b/doc/string/end_with_p.rdoc @@ -0,0 +1,11 @@ +Returns whether +self+ ends with any of the given +strings+. + +Returns +true+ if any given string matches the end, +false+ otherwise: + + 'hello'.end_with?('ello') #=> true + 'hello'.end_with?('heaven', 'ello') #=> true + 'hello'.end_with?('heaven', 'paradise') #=> false + 'тест'.end_with?('т') # => true + 'こんにちは'.end_with?('は') # => true + +Related: String#start_with?. diff --git a/doc/string/force_encoding.rdoc b/doc/string/force_encoding.rdoc new file mode 100644 index 0000000000..fd9615caaa --- /dev/null +++ b/doc/string/force_encoding.rdoc @@ -0,0 +1,20 @@ +Changes the encoding of +self+ to +encoding+, +which may be a string encoding name or an Encoding object; +returns self: + + s = 'łał' + s.bytes # => [197, 130, 97, 197, 130] + s.encoding # => #<Encoding:UTF-8> + s.force_encoding('ascii') # => "\xC5\x82a\xC5\x82" + s.encoding # => #<Encoding:US-ASCII> + +Does not change the underlying bytes: + + s.bytes # => [197, 130, 97, 197, 130] + +Makes the change even if the given +encoding+ is invalid +for +self+ (as is the change above): + + s.valid_encoding? # => false + s.force_encoding(Encoding::UTF_8) # => "łał" + s.valid_encoding? # => true diff --git a/doc/string/grapheme_clusters.rdoc b/doc/string/grapheme_clusters.rdoc new file mode 100644 index 0000000000..8c7f5a7259 --- /dev/null +++ b/doc/string/grapheme_clusters.rdoc @@ -0,0 +1,6 @@ +Returns an array of the grapheme clusters in +self+ +(see {Unicode Grapheme Cluster Boundaries}[https://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries]): + + s = "\u0061\u0308-pqr-\u0062\u0308-xyz-\u0063\u0308" # => "ä-pqr-b̈-xyz-c̈" + s.grapheme_clusters + # => ["ä", "-", "p", "q", "r", "-", "b̈", "-", "x", "y", "z", "-", "c̈"] diff --git a/doc/string/index.rdoc b/doc/string/index.rdoc new file mode 100644 index 0000000000..ce09a37bdf --- /dev/null +++ b/doc/string/index.rdoc @@ -0,0 +1,38 @@ +Returns the integer index of the first match for the given argument, +or +nil+ if none found; +the search of +self+ is forward, and begins at position +offset+ (in characters). + +With string argument +substring+, +returns the index of the first matching substring in +self+: + + 'foo'.index('f') # => 0 + 'foo'.index('o') # => 1 + 'foo'.index('oo') # => 1 + 'foo'.index('ooo') # => nil + 'тест'.index('с') # => 2 + 'こんにちは'.index('ち') # => 3 + +With Regexp argument +regexp+, returns the index of the first match in +self+: + + 'foo'.index(/o./) # => 1 + 'foo'.index(/.o/) # => 0 + +With positive integer +offset+, begins the search at position +offset+: + + 'foo'.index('o', 1) # => 1 + 'foo'.index('o', 2) # => 2 + 'foo'.index('o', 3) # => nil + 'тест'.index('с', 1) # => 2 + 'こんにちは'.index('ち', 2) # => 3 + +With negative integer +offset+, selects the search position by counting backward +from the end of +self+: + + 'foo'.index('o', -1) # => 2 + 'foo'.index('o', -2) # => 1 + 'foo'.index('o', -3) # => 1 + 'foo'.index('o', -4) # => nil + 'foo'.index(/o./, -2) # => 1 + 'foo'.index(/.o/, -2) # => 1 + +Related: String#rindex. diff --git a/doc/string/length.rdoc b/doc/string/length.rdoc new file mode 100644 index 0000000000..544bca269f --- /dev/null +++ b/doc/string/length.rdoc @@ -0,0 +1,12 @@ +Returns the count of characters (not bytes) in +self+: + + 'foo'.length # => 3 + 'тест'.length # => 4 + 'こんにちは'.length # => 5 + +Contrast with String#bytesize: + + 'foo'.bytesize # => 3 + 'тест'.bytesize # => 8 + 'こんにちは'.bytesize # => 15 + diff --git a/doc/string/ljust.rdoc b/doc/string/ljust.rdoc new file mode 100644 index 0000000000..8e23c1fc8f --- /dev/null +++ b/doc/string/ljust.rdoc @@ -0,0 +1,16 @@ +Returns a left-justified copy of +self+. + +If integer argument +size+ is greater than the size (in characters) of +self+, +returns a new string of length +size+ that is a copy of +self+, +left justified and padded on the right with +pad_string+: + + 'hello'.ljust(10) # => "hello " + ' hello'.ljust(10) # => " hello " + 'hello'.ljust(10, 'ab') # => "helloababa" + 'тест'.ljust(10) # => "тест " + 'こんにちは'.ljust(10) # => "こんにちは " + +If +size+ is not greater than the size of +self+, returns a copy of +self+: + + 'hello'.ljust(5) # => "hello" + 'hello'.ljust(1) # => "hello" diff --git a/doc/string/new.rdoc b/doc/string/new.rdoc new file mode 100644 index 0000000000..d955e61c87 --- /dev/null +++ b/doc/string/new.rdoc @@ -0,0 +1,51 @@ +Returns a new \String that is a copy of +string+. + +With no arguments, returns the empty string with the Encoding <tt>ASCII-8BIT</tt>: + + s = String.new + s # => "" + s.encoding # => #<Encoding:ASCII-8BIT> + +With optional argument +string+ and no keyword arguments, +returns a copy of +string+ with the same encoding: + + String.new('foo') # => "foo" + String.new('тест') # => "тест" + String.new('こんにちは') # => "こんにちは" + +(Unlike \String.new, +a {string literal}[rdoc-ref:syntax/literals.rdoc@String+Literals] like <tt>''</tt> or a +{here document literal}[rdoc-ref:syntax/literals.rdoc@Here+Document+Literals] +always has {script encoding}[rdoc-ref:encodings.rdoc@Script+Encoding].) + +With optional keyword argument +encoding+, returns a copy of +string+ +with the specified encoding; +the +encoding+ may be an Encoding object, an encoding name, +or an encoding name alias: + + String.new('foo', encoding: Encoding::US_ASCII).encoding # => #<Encoding:US-ASCII> + String.new('foo', encoding: 'US-ASCII').encoding # => #<Encoding:US-ASCII> + String.new('foo', encoding: 'ASCII').encoding # => #<Encoding:US-ASCII> + +The given encoding need not be valid for the string's content, +and that validity is not checked: + + s = String.new('こんにちは', encoding: 'ascii') + s.valid_encoding? # => false + +But the given +encoding+ itself is checked: + + String.new('foo', encoding: 'bar') # Raises ArgumentError. + +With optional keyword argument +capacity+, returns a copy of +string+ +(or an empty string, if +string+ is not given); +the given +capacity+ is advisory only, +and may or may not set the size of the internal buffer, +which may in turn affect performance: + + String.new(capacity: 1) + String.new('foo', capacity: 4096) + +The +string+, +encoding+, and +capacity+ arguments may all be used together: + + String.new('hello', encoding: 'UTF-8', capacity: 25) diff --git a/doc/string/ord.rdoc b/doc/string/ord.rdoc new file mode 100644 index 0000000000..d586363d44 --- /dev/null +++ b/doc/string/ord.rdoc @@ -0,0 +1,6 @@ +Returns the integer ordinal of the first character of +self+: + + 'h'.ord # => 104 + 'hello'.ord # => 104 + 'тест'.ord # => 1090 + 'こんにちは'.ord # => 12371 diff --git a/doc/string/partition.rdoc b/doc/string/partition.rdoc new file mode 100644 index 0000000000..ebe575e8eb --- /dev/null +++ b/doc/string/partition.rdoc @@ -0,0 +1,24 @@ +Returns a 3-element array of substrings of +self+. + +Matches a pattern against +self+, scanning from the beginning. +The pattern is: + +- +string_or_regexp+ itself, if it is a Regexp. +- <tt>Regexp.quote(string_or_regexp)</tt>, if +string_or_regexp+ is a string. + +If the pattern is matched, returns pre-match, first-match, post-match: + + 'hello'.partition('l') # => ["he", "l", "lo"] + 'hello'.partition('ll') # => ["he", "ll", "o"] + 'hello'.partition('h') # => ["", "h", "ello"] + 'hello'.partition('o') # => ["hell", "o", ""] + 'hello'.partition(/l+/) #=> ["he", "ll", "o"] + 'hello'.partition('') # => ["", "", "hello"] + 'тест'.partition('т') # => ["", "т", "ест"] + 'こんにちは'.partition('に') # => ["こん", "に", "ちは"] + +If the pattern is not matched, returns a copy of +self+ and two empty strings: + + 'hello'.partition('x') # => ["hello", "", ""] + +Related: String#rpartition, String#split. diff --git a/doc/string/rjust.rdoc b/doc/string/rjust.rdoc new file mode 100644 index 0000000000..24e7bf3159 --- /dev/null +++ b/doc/string/rjust.rdoc @@ -0,0 +1,16 @@ +Returns a right-justified copy of +self+. + +If integer argument +size+ is greater than the size (in characters) of +self+, +returns a new string of length +size+ that is a copy of +self+, +right justified and padded on the left with +pad_string+: + + 'hello'.rjust(10) # => " hello" + 'hello '.rjust(10) # => " hello " + 'hello'.rjust(10, 'ab') # => "ababahello" + 'тест'.rjust(10) # => " тест" + 'こんにちは'.rjust(10) # => " こんにちは" + +If +size+ is not greater than the size of +self+, returns a copy of +self+: + + 'hello'.rjust(5, 'ab') # => "hello" + 'hello'.rjust(1, 'ab') # => "hello" diff --git a/doc/string/rpartition.rdoc b/doc/string/rpartition.rdoc new file mode 100644 index 0000000000..d24106fb9f --- /dev/null +++ b/doc/string/rpartition.rdoc @@ -0,0 +1,24 @@ +Returns a 3-element array of substrings of +self+. + +Matches a pattern against +self+, scanning backwards from the end. +The pattern is: + +- +string_or_regexp+ itself, if it is a Regexp. +- <tt>Regexp.quote(string_or_regexp)</tt>, if +string_or_regexp+ is a string. + +If the pattern is matched, returns pre-match, last-match, post-match: + + 'hello'.rpartition('l') # => ["hel", "l", "o"] + 'hello'.rpartition('ll') # => ["he", "ll", "o"] + 'hello'.rpartition('h') # => ["", "h", "ello"] + 'hello'.rpartition('o') # => ["hell", "o", ""] + 'hello'.rpartition(/l+/) # => ["hel", "l", "o"] + 'hello'.rpartition('') # => ["hello", "", ""] + 'тест'.rpartition('т') # => ["тес", "т", ""] + 'こんにちは'.rpartition('に') # => ["こん", "に", "ちは"] + +If the pattern is not matched, returns two empty strings and a copy of +self+: + + 'hello'.rpartition('x') # => ["", "", "hello"] + +Related: String#partition, String#split. diff --git a/doc/string/scrub.rdoc b/doc/string/scrub.rdoc new file mode 100644 index 0000000000..1a5b1c79d0 --- /dev/null +++ b/doc/string/scrub.rdoc @@ -0,0 +1,25 @@ +Returns a copy of +self+ with each invalid byte sequence replaced +by the given +replacement_string+. + +With no block given and no argument, replaces each invalid sequence +with the default replacement string +(<tt>"�"</tt> for a Unicode encoding, <tt>'?'</tt> otherwise): + + s = "foo\x81\x81bar" + s.scrub # => "foo��bar" + +With no block given and argument +replacement_string+ given, +replaces each invalid sequence with that string: + + "foo\x81\x81bar".scrub('xyzzy') # => "fooxyzzyxyzzybar" + +With a block given, replaces each invalid sequence with the value +of the block: + + "foo\x81\x81bar".scrub {|bytes| p bytes; 'XYZZY' } + # => "fooXYZZYXYZZYbar" + +Output: + + "\x81" + "\x81" diff --git a/doc/string/split.rdoc b/doc/string/split.rdoc new file mode 100644 index 0000000000..5ab065093b --- /dev/null +++ b/doc/string/split.rdoc @@ -0,0 +1,86 @@ +Returns an array of substrings of +self+ +that are the result of splitting +self+ +at each occurrence of the given field separator +field_sep+. + +When +field_sep+ is <tt>$;</tt>: + +- If <tt>$;</tt> is +nil+ (its default value), + the split occurs just as if +field_sep+ were given as a space character + (see below). + +- If <tt>$;</tt> is a string, + the split occurs just as if +field_sep+ were given as that string + (see below). + +When +field_sep+ is <tt>' '</tt> and +limit+ is +nil+, +the split occurs at each sequence of whitespace: + + 'abc def ghi'.split(' ') => ["abc", "def", "ghi"] + "abc \n\tdef\t\n ghi".split(' ') # => ["abc", "def", "ghi"] + 'abc def ghi'.split(' ') => ["abc", "def", "ghi"] + ''.split(' ') => [] + +When +field_sep+ is a string different from <tt>' '</tt> +and +limit+ is +nil+, +the split occurs at each occurrence of +field_sep+; +trailing empty substrings are not returned: + + 'abracadabra'.split('ab') => ["", "racad", "ra"] + 'aaabcdaaa'.split('a') => ["", "", "", "bcd"] + ''.split('a') => [] + '3.14159'.split('1') => ["3.", "4", "59"] + '!@#$%^$&*($)_+'.split('$') # => ["!@#", "%^", "&*(", ")_+"] + 'тест'.split('т') => ["", "ес"] + 'こんにちは'.split('に') => ["こん", "ちは"] + +When +field_sep+ is a Regexp and +limit+ is +nil+, +the split occurs at each occurrence of a match; +trailing empty substrings are not returned: + + 'abracadabra'.split(/ab/) # => ["", "racad", "ra"] + 'aaabcdaaa'.split(/a/) => ["", "", "", "bcd"] + 'aaabcdaaa'.split(//) => ["a", "a", "a", "b", "c", "d", "a", "a", "a"] + '1 + 1 == 2'.split(/\W+/) # => ["1", "1", "2"] + +If the \Regexp contains groups, their matches are also included +in the returned array: + + '1:2:3'.split(/(:)()()/, 2) # => ["1", ":", "", "", "2:3"] + +As seen above, if +limit+ is +nil+, +trailing empty substrings are not returned; +the same is true if +limit+ is zero: + + 'aaabcdaaa'.split('a') => ["", "", "", "bcd"] + 'aaabcdaaa'.split('a', 0) # => ["", "", "", "bcd"] + +If +limit+ is positive integer +n+, no more than <tt>n - 1-</tt> +splits occur, so that at most +n+ substrings are returned, +and trailing empty substrings are included: + + 'aaabcdaaa'.split('a', 1) # => ["aaabcdaaa"] + 'aaabcdaaa'.split('a', 2) # => ["", "aabcdaaa"] + 'aaabcdaaa'.split('a', 5) # => ["", "", "", "bcd", "aa"] + 'aaabcdaaa'.split('a', 7) # => ["", "", "", "bcd", "", "", ""] + 'aaabcdaaa'.split('a', 8) # => ["", "", "", "bcd", "", "", ""] + +Note that if +field_sep+ is a \Regexp containing groups, +their matches are in the returned array, but do not count toward the limit. + +If +limit+ is negative, it behaves the same as if +limit+ was +nil+, +meaning that there is no limit, +and trailing empty substrings are included: + + 'aaabcdaaa'.split('a', -1) # => ["", "", "", "bcd", "", "", ""] + +If a block is given, it is called with each substring: + + 'abc def ghi'.split(' ') {|substring| p substring } + +Output: + + "abc" + "def" + "ghi" + +Related: String#partition, String#rpartition. diff --git a/doc/string/start_with_p.rdoc b/doc/string/start_with_p.rdoc new file mode 100644 index 0000000000..5d1f9f9543 --- /dev/null +++ b/doc/string/start_with_p.rdoc @@ -0,0 +1,18 @@ +Returns whether +self+ starts with any of the given +string_or_regexp+. + +Matches patterns against the beginning of +self+. +For each given +string_or_regexp+, the pattern is: + +- +string_or_regexp+ itself, if it is a Regexp. +- <tt>Regexp.quote(string_or_regexp)</tt>, if +string_or_regexp+ is a string. + +Returns +true+ if any pattern matches the beginning, +false+ otherwise: + + 'hello'.start_with?('hell') # => true + 'hello'.start_with?(/H/i) # => true + 'hello'.start_with?('heaven', 'hell') # => true + 'hello'.start_with?('heaven', 'paradise') # => false + 'тест'.start_with?('т') # => true + 'こんにちは'.start_with?('こ') # => true + +Related: String#end_with?. diff --git a/doc/string/sum.rdoc b/doc/string/sum.rdoc new file mode 100644 index 0000000000..5de24e6402 --- /dev/null +++ b/doc/string/sum.rdoc @@ -0,0 +1,11 @@ +Returns a basic +n+-bit checksum of the characters in +self+; +the checksum is the sum of the binary value of each byte in +self+, +modulo <tt>2**n - 1</tt>: + + 'hello'.sum # => 532 + 'hello'.sum(4) # => 4 + 'hello'.sum(64) # => 532 + 'тест'.sum # => 1405 + 'こんにちは'.sum # => 2582 + +This is not a particularly strong checksum. diff --git a/doc/symbol/casecmp.rdoc b/doc/symbol/casecmp.rdoc new file mode 100644 index 0000000000..9c286070b7 --- /dev/null +++ b/doc/symbol/casecmp.rdoc @@ -0,0 +1,27 @@ +Like Symbol#<=>, but case-insensitive; +equivalent to <tt>self.to_s.casecmp(object.to_s)</tt>: + + lower = :abc + upper = :ABC + upper.casecmp(lower) # => 0 + lower.casecmp(lower) # => 0 + lower.casecmp(upper) # => 0 + +Returns nil if +self+ and +object+ have incompatible encodings, +or if +object+ is not a symbol: + + sym = 'äöü'.encode("ISO-8859-1").to_sym + other_sym = 'ÄÖÜ' + sym.casecmp(other_sym) # => nil + :foo.casecmp(2) # => nil + +Unlike Symbol#casecmp?, +case-insensitivity does not work for characters outside of 'A'..'Z' and 'a'..'z': + + lower = :äöü + upper = :ÄÖÜ + upper.casecmp(lower) # => -1 + lower.casecmp(lower) # => 0 + lower.casecmp(upper) # => 1 + +Related: Symbol#casecmp?, String#casecmp. diff --git a/doc/symbol/casecmp_p.rdoc b/doc/symbol/casecmp_p.rdoc new file mode 100644 index 0000000000..7102b54289 --- /dev/null +++ b/doc/symbol/casecmp_p.rdoc @@ -0,0 +1,26 @@ +Returns +true+ if +self+ and +object+ are equal after Unicode case folding, +otherwise +false+: + + lower = :abc + upper = :ABC + upper.casecmp?(lower) # => true + lower.casecmp?(lower) # => true + lower.casecmp?(upper) # => true + +Returns nil if +self+ and +object+ have incompatible encodings, +or if +object+ is not a symbol: + + sym = 'äöü'.encode("ISO-8859-1").to_sym + other_sym = 'ÄÖÜ' + sym.casecmp?(other_sym) # => nil + :foo.casecmp?(2) # => nil + +Unlike Symbol#casecmp, works for characters outside of 'A'..'Z' and 'a'..'z': + + lower = :äöü + upper = :ÄÖÜ + upper.casecmp?(lower) # => true + lower.casecmp?(lower) # => true + lower.casecmp?(upper) # => true + +Related: Symbol#casecmp, String#casecmp?. diff --git a/doc/syntax.rdoc b/doc/syntax.rdoc index 5895673f36..6ca5843512 100644 --- a/doc/syntax.rdoc +++ b/doc/syntax.rdoc @@ -37,3 +37,6 @@ Miscellaneous[rdoc-ref:syntax/miscellaneous.rdoc] :: Comments[rdoc-ref:syntax/comments.rdoc] :: Line and block code comments + +Operators[rdoc-ref:syntax/operators.rdoc] :: + Operator method behaviors diff --git a/doc/syntax/assignment.rdoc b/doc/syntax/assignment.rdoc index a1806e4c48..f45f5bc0ea 100644 --- a/doc/syntax/assignment.rdoc +++ b/doc/syntax/assignment.rdoc @@ -8,6 +8,9 @@ example assigns the number five to the local variable +v+: Assignment creates a local variable if the variable was not previously referenced. +An assignment expression result is always the assigned value, including +{assignment methods}[rdoc-ref:syntax/assignment.rdoc@Assignment+Methods]. + == Local Variable Names A local variable name must start with a lowercase US-ASCII letter or a @@ -104,7 +107,7 @@ Rather than printing "true" you receive a NameError, "undefined local variable or method `a'". Since ruby parses the bare +a+ left of the +if+ first and has not yet seen an assignment to +a+ it assumes you wish to call a method. Ruby then sees the assignment to +a+ and will assume you are referencing a local -method. +variable. The confusion comes from the out-of-order execution of the expression. First the local variable is assigned-to then you attempt to call a nonexistent @@ -159,9 +162,7 @@ Here is an example of instance variable usage: p object1.value # prints "some value" p object2.value # prints "other value" -An uninitialized instance variable has a value of +nil+. If you run Ruby with -warnings enabled, you will get a warning when accessing an uninitialized -instance variable. +An uninitialized instance variable has a value of +nil+. The +value+ method has access to the value set by the +initialize+ method, but only for the same object. @@ -342,6 +343,9 @@ This prints: local_variables: @value: 42 +Note that the value returned by an assignment method is ignored whatever, +since an assignment expression result is always the assignment value. + == Abbreviated Assignment You can mix several of the operators and assignment. To add 1 to an object @@ -397,6 +401,10 @@ assigning. This is similar to multiple assignment: p a # prints [1, 2, 3] + b = *1 + + p b # prints [1] + You can splat anywhere in the right-hand side of the assignment: a = 1, *[2, 3] diff --git a/doc/syntax/calling_methods.rdoc b/doc/syntax/calling_methods.rdoc index fc806d5c31..c2c6c61a10 100644 --- a/doc/syntax/calling_methods.rdoc +++ b/doc/syntax/calling_methods.rdoc @@ -210,6 +210,24 @@ definition. If a keyword argument is given that the method did not list, and the method definition does not accept arbitrary keyword arguments, an ArgumentError will be raised. +Keyword argument value can be omitted, meaning the value will be fetched +from the context by the name of the key + + keyword1 = 'some value' + my_method(positional1, keyword1:) + # ...is the same as + my_method(positional1, keyword1: keyword1) + +Be aware that when method parenthesis are omitted, too, the parsing order might +be unexpected: + + my_method positional1, keyword1: + + some_other_expression + + # ...is actually parsed as + my_method(positional1, keyword1: some_other_expression) + === Block Argument The block argument sends a closure from the calling scope to the method. @@ -304,18 +322,6 @@ Both are equivalent to: my_method(1, 2, 3) -If the method accepts keyword arguments, the splat operator will convert a -hash at the end of the array into keyword arguments: - - def my_method(a, b, c: 3) - end - - arguments = [1, 2, { c: 4 }] - my_method(*arguments) - -Note that this behavior is currently deprecated and will emit a warning. -This behavior will be removed in Ruby 3.0. - You may also use the <code>**</code> (described next) to convert a Hash into keyword arguments. diff --git a/doc/syntax/comments.rdoc b/doc/syntax/comments.rdoc index dbc7816984..00d19d588a 100644 --- a/doc/syntax/comments.rdoc +++ b/doc/syntax/comments.rdoc @@ -196,7 +196,7 @@ The method Module#const_set is not affected. In this mode, all values assigned to constants are deeply copied and made shareable. It is safer mode than +experimental_everything+. - # shareable_constant_value: experimental_everything + # shareable_constant_value: experimental_copy var = [{foo: []}] var.frozen? # => false (assignment was made to local variable) X = var # => calls `Ractor.make_shareable(var, copy: true)` diff --git a/doc/syntax/control_expressions.rdoc b/doc/syntax/control_expressions.rdoc index e91b03e72d..9126289389 100644 --- a/doc/syntax/control_expressions.rdoc +++ b/doc/syntax/control_expressions.rdoc @@ -189,7 +189,7 @@ The same is true for +unless+. The +case+ expression can be used in two ways. The most common way is to compare an object against multiple patterns. The -patterns are matched using the +===+ method which is aliased to +==+ on +patterns are matched using the <tt>===</tt> method which is aliased to <tt>==</tt> on Object. Other classes must override it to give meaningful behavior. See Module#=== and Regexp#=== for examples. @@ -513,9 +513,9 @@ and modifier +if+ has lower precedence than <code>=</code>. == Flip-Flop -The flip-flop is a rarely seen conditional expression. It's primary use is -for processing text from ruby one-line programs used with <code>ruby -n</code> -or <code>ruby -p</code>. +The flip-flop is a slightly special conditional expression. One of its +typical uses is processing text from ruby one-line programs used with +<code>ruby -n</code> or <code>ruby -p</code>. The form of the flip-flop is an expression that indicates when the flip-flop turns on, <code>..</code> (or <code>...</code>), then an expression @@ -524,7 +524,6 @@ will continue to evaluate to +true+, and +false+ when off. Here is an example: - selected = [] 0.upto 10 do |value| @@ -533,15 +532,16 @@ Here is an example: p selected # prints [2, 3, 4, 5, 6, 7, 8] -In the above example, the on condition is <code>n==2</code>. The flip-flop -is initially off (false) for 0 and 1, but becomes on (true) for 2 and remains -on through 8. After 8 it turns off and remains off for 9 and 10. +In the above example, the `on' condition is <code>n==2</code>. The flip-flop +is initially `off' (false) for 0 and 1, but becomes `on' (true) for 2 and +remains `on' through 8. After 8 it turns off and remains `off' for 9 and 10. -The flip-flop must be used inside a conditional such as +if+, +while+, -+unless+, +until+ etc. including the modifier forms. +The flip-flop must be used inside a conditional such as <code>!</code>, +<code>? :</code>, +not+, +if+, +while+, +unless+, +until+ etc. including the +modifier forms. -When you use an inclusive range (<code>..</code>), the off condition is -evaluated when the on condition changes: +When you use an inclusive range (<code>..</code>), the `off' condition is +evaluated when the `on' condition changes: selected = [] @@ -555,7 +555,7 @@ Here, both sides of the flip-flop are evaluated so the flip-flop turns on and off only when +value+ equals 2. Since the flip-flop turned on in the iteration it returns true. -When you use an exclusive range (<code>...</code>), the off condition is +When you use an exclusive range (<code>...</code>), the `off' condition is evaluated on the following iteration: selected = [] @@ -567,5 +567,73 @@ evaluated on the following iteration: p selected # prints [2, 3, 4, 5] Here, the flip-flop turns on when +value+ equals 2, but doesn't turn off on the -same iteration. The off condition isn't evaluated until the following +same iteration. The `off' condition isn't evaluated until the following iteration and +value+ will never be two again. + +== throw/catch + ++throw+ and +catch+ are used to implement non-local control flow in Ruby. They +operate similarly to exceptions, allowing control to pass directly from the +place where +throw+ is called to the place where the matching +catch+ is +called. The main difference between +throw+/+catch+ and the use of exceptions +is that +throw+/+catch+ are designed for expected non-local control flow, +while exceptions are designed for exceptional control flow situations, such +as handling unexpected errors. + +When using +throw+, you provide 1-2 arguments. The first argument is the +value for the matching +catch+. The second argument is optional (defaults to ++nil+), and will be the value that +catch+ returns if there is a matching ++throw+ inside the +catch+ block. If no matching +throw+ method is called +inside a +catch+ block, the +catch+ method returns the return value of the +block passed to it. + + def a(n) + throw :d, :a if n == 0 + b(n) + end + + def b(n) + throw :d, :b if n == 1 + c(n) + end + + def c(n) + throw :d if n == 2 + end + + 4.times.map do |i| + catch(:d) do + a(i) + :default + end + end + # => [:a, :b, nil, :default] + +If the first argument you pass to +throw+ is not handled by a matching ++catch+, an UncaughtThrowError exception will be raised. This is because ++throw+/+catch+ should only be used for expected control flow changes, so +using a value that is not already expected is an error. + ++throw+/+catch+ are implemented as Kernel methods (Kernel#throw and +Kernel#catch), not as keywords. So they are not usable directly if you are +in a BasicObject context. You can use Kernel.throw and Kernel.catch in +this case: + + BasicObject.new.instance_exec do + def a + b + end + + def b + c + end + + def c + ::Kernel.throw :d, :e + end + + result = ::Kernel.catch(:d) do + a + end + result # => :e + end diff --git a/doc/syntax/exceptions.rdoc b/doc/syntax/exceptions.rdoc index 31e2f0175c..ac5ff78a95 100644 --- a/doc/syntax/exceptions.rdoc +++ b/doc/syntax/exceptions.rdoc @@ -86,7 +86,7 @@ To always run some code whether an exception was raised or not, use +ensure+: rescue # ... ensure - # this always runs + # this always runs BUT does not implicitly return the last evaluated statement. end You may also run some code when an exception is not raised: @@ -96,7 +96,11 @@ You may also run some code when an exception is not raised: rescue # ... else - # this runs only when no exception was raised + # this runs only when no exception was raised AND return the last evaluated statement ensure - # ... + # this always runs. + # It is evaluated after the evaluation of either the `rescue` or the `else` block. + # It will not return implicitly. end + +NB : Without explicit +return+ in the +ensure+ block, +begin+/+end+ block will return the last evaluated statement before entering in the `ensure` block. diff --git a/doc/syntax/literals.rdoc b/doc/syntax/literals.rdoc index 45d3d90c58..0c1e4a434b 100644 --- a/doc/syntax/literals.rdoc +++ b/doc/syntax/literals.rdoc @@ -2,15 +2,31 @@ Literals create objects you can use in your program. Literals include: -* Booleans and nil -* Numbers -* Strings -* Symbols -* Arrays -* Hashes -* Ranges -* Regexps -* Lambda Procs +* {Boolean and Nil Literals}[#label-Boolean+and+Nil+Literals] +* {Number Literals}[#label-Number+Literals] + + * {Integer Literals}[#label-Integer+Literals] + * {Float Literals}[#label-Float+Literals] + * {Rational Literals}[#label-Rational+Literals] + * {Complex Literals}[#label-Complex+Literals] + +* {String Literals}[#label-String+Literals] +* {Here Document Literals}[#label-Here+Document+Literals] +* {Symbol Literals}[#label-Symbol+Literals] +* {Array Literals}[#label-Array+Literals] +* {Hash Literals}[#label-Hash+Literals] +* {Range Literals}[#label-Range+Literals] +* {Regexp Literals}[#label-Regexp+Literals] +* {Lambda Proc Literals}[#label-Lambda+Proc+Literals] +* {Percent Literals}[#label-Percent+Literals] + + * {%q: Non-Interpolable String Literals}[#label-25q-3A+Non-Interpolable+String+Literals] + * {% and %Q: Interpolable String Literals}[#label-25+and+-25Q-3A+Interpolable+String+Literals] + * {%w and %W: String-Array Literals}[#label-25w+and+-25W-3A+String-Array+Literals] + * {%i and %I: Symbol-Array Literals}[#label-25i+and+-25I-3A+Symbol-Array+Literals] + * {%r: Regexp Literals}[#label-25r-3A+Regexp+Literals] + * {%s: Symbol Literals}[#label-25s-3A+Symbol+Literals] + * {%x: Backtick Literals}[#label-25x-3A+Backtick+Literals] == Boolean and Nil Literals @@ -20,7 +36,7 @@ Literals create objects you can use in your program. Literals include: +true+ is a true value. All objects except +nil+ and +false+ evaluate to a true value in conditional expressions. -== Numbers +== Number Literals === \Integer Literals @@ -74,15 +90,36 @@ point numbers as well. === \Rational Literals -You can write a Rational number as follows (suffixed +r+): +You can write a Rational literal using a special suffix, <tt>'r'</tt>. - 12r #=> (12/1) - 12.3r #=> (123/10) - -A \Rational number is exact, whereas a \Float number may be inexact. +Examples: - 0.1r + 0.2r #=> (3/10) - 0.1 + 0.2 #=> 0.30000000000000004 + 1r # => (1/1) + 2/3r # => (2/3) # With denominator. + -1r # => (-1/1) # With signs. + -2/3r # => (-2/3) + 2/-3r # => (-2/3) + -2/-3r # => (2/3) + +1/+3r # => (1/3) + 1.2r # => (6/5) # With fractional part. + 1_1/2_1r # => (11/21) # With embedded underscores. + 2/4r # => (1/2) # Automatically reduced. + +Syntax: + + <rational-literal> = <numerator> [ '/' <denominator> ] 'r' + <numerator> = [ <sign> ] <digits> [ <fractional-part> ] + <fractional-part> = '.' <digits> + <denominator> = [ sign ] <digits> + <sign> = '-' | '+' + <digits> = <digit> { <digit> | '_' <digit> } + <digit> = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' + +Note this, which is parsed as \Float numerator <tt>1.2</tt> +divided by \Rational denominator <tt>3r</tt>, +resulting in a \Float: + + 1.2/3r # => 0.39999999999999997 === \Complex Literals @@ -162,15 +199,6 @@ In addition to disabling interpolation, single-quoted strings also disable all escape sequences except for the single-quote (<tt>\'</tt>) and backslash (<tt>\\\\</tt>). -You may also create strings using <tt>%</tt>: - - %(1 + 1 is #{1 + 1}) #=> "1 + 1 is 2" - -There are two different types of <tt>%</tt> strings <tt>%q(...)</tt> behaves -like a single-quote string (no interpolation or character escaping), while -<tt>%Q</tt> behaves as a double-quote string. See Percent Strings below for -more discussion of the syntax of percent strings. - Adjacent string literals are automatically concatenated by the interpreter: "con" "cat" "en" "at" "ion" #=> "concatenation" @@ -200,6 +228,11 @@ a single codepoint in the script encoding: ?\C-\M-a #=> "\x81", same as above ?あ #=> "あ" +See also: + +* {%q: Non-Interpolable String Literals}[#label-25q-3A+Non-Interpolable+String+Literals] +* {% and %Q: Interpolable String Literals}[#label-25+and+-25Q-3A+Interpolable+String+Literals] + === Here Document Literals If you are writing a large block of text you may use a "here document" or @@ -244,6 +277,12 @@ the content. Note that empty lines and lines consisting solely of literal tabs and spaces will be ignored for the purposes of determining indentation, but escaped tabs and spaces are considered non-indentation characters. +For the purpose of measuring an indentation, a horizontal tab is regarded as a +sequence of one to eight spaces such that the column position corresponding to +its end is a multiple of eight. The amount to be removed is counted in terms +of the number of spaces. If the boundary appears in the middle of a tab, that +tab is not removed. + A heredoc allows interpolation and escaped characters. You may disable interpolation and escaping by surrounding the opening identifier with single quotes: @@ -299,6 +338,11 @@ Like strings, a single-quote may be used to disable interpolation: When creating a Hash, there is a special syntax for referencing a Symbol as well. +See also: + +* {%s: Symbol Literals}[#label-25s-3A+Symbol+Literals] + + == \Array Literals An array is created using the objects between <tt>[</tt> and <tt>]</tt>: @@ -310,6 +354,11 @@ You may place expressions inside the array: [1, 1 + 1, 1 + 2] [1, [1 + 1, [1 + 2]]] +See also: + +* {%w and %W: String-Array Literals}[#label-25w+and+-25W-3A+String-Array+Literals] +* {%i and %I: Symbol-Array Literals}[#label-25i+and+-25I-3A+Symbol-Array+Literals] + See Array for the methods you may use with an array. == \Hash Literals @@ -334,6 +383,14 @@ is equal to { :"a 1" => 1, :"b 2" => 2 } +Hash values can be omitted, meaning that value will be fetched from the context +by the name of the key: + + x = 100 + y = 200 + h = { x:, y: } + #=> {:x=>100, :y=>200} + See Hash for the methods you may use with a hash. == \Range Literals @@ -351,20 +408,24 @@ on the methods you need to implement. == \Regexp Literals -A regular expression is created using "/": +A regular expression may be created using leading and trailing +slash (<tt>'/'</tt>) characters: - /my regular expression/ + re = /foo/ # => /foo/ + re.class # => Regexp -The regular expression may be followed by flags which adjust the matching -behavior of the regular expression. The "i" flag makes the regular expression -case-insensitive: - - /my regular expression/i +The trailing slash may be followed by one or more modifiers characters +that set modes for the regexp. +See {Regexp modes}[rdoc-ref:Regexp@Modes] for details. Interpolation may be used inside regular expressions along with escaped characters. Note that a regular expression may require additional escaped characters than a string. +See also: + +* {%r: Regexp Literals}[#label-25r-3A+Regexp+Literals] + See Regexp for a description of the syntax of regular expressions. == Lambda Proc Literals @@ -383,25 +444,91 @@ This proc will add one to its argument. == Percent Literals -Besides <tt>%(...)</tt> which creates a String, the <tt>%</tt> may create -other types of object. As with strings, an uppercase letter allows -interpolation and escaped characters while a lowercase letter disables them. +Each of the literals in described in this section +may use these paired delimiters: + +* <tt>[</tt> and <tt>]</tt>. +* <tt>(</tt> and <tt>)</tt>. +* <tt>{</tt> and <tt>}</tt>. +* <tt><</tt> and <tt>></tt>. +* Any other character, as both beginning and ending delimiters. + +These are demonstrated in the next section. + +=== <tt>%q</tt>: Non-Interpolable String Literals + +You can write a non-interpolable string with <tt>%q</tt>. +The created string is the same as if you created it with single quotes: + + %[foo bar baz] # => "foo bar baz" # Using []. + %(foo bar baz) # => "foo bar baz" # Using (). + %{foo bar baz} # => "foo bar baz" # Using {}. + %<foo bar baz> # => "foo bar baz" # Using <>. + %|foo bar baz| # => "foo bar baz" # Using two |. + %:foo bar baz: # => "foo bar baz" # Using two :. + %q(1 + 1 is #{1 + 1}) # => "1 + 1 is \#{1 + 1}" # No interpolation. + +=== <tt>% and %Q</tt>: Interpolable String Literals + +You can write an interpolable string with <tt>%Q</tt> +or with its alias <tt>%</tt>: + + %[foo bar baz] # => "foo bar baz" + %(1 + 1 is #{1 + 1}) # => "1 + 1 is 2" # Interpolation. + +=== <tt>%w and %W</tt>: String-Array Literals + +You can write an array of strings with <tt>%w</tt> (non-interpolable) +or <tt>%W</tt> (interpolable): + + %w[foo bar baz] # => ["foo", "bar", "baz"] + %w[1 % *] # => ["1", "%", "*"] + # Use backslash to embed spaces in the strings. + %w[foo\ bar baz\ bat] # => ["foo bar", "baz bat"] + %w(#{1 + 1}) # => ["\#{1", "+", "1}"] + %W(#{1 + 1}) # => ["2"] + +=== <tt>%i and %I</tt>: Symbol-Array Literals + +You can write an array of symbols with <tt>%i</tt> (non-interpolable) +or <tt>%I</tt> (interpolable): + + %i[foo bar baz] # => [:foo, :bar, :baz] + %i[1 % *] # => [:"1", :%, :*] + # Use backslash to embed spaces in the symbols. + %i[foo\ bar baz\ bat] # => [:"foo bar", :"baz bat"] + %i(#{1 + 1}) # => [:"\#{1", :+, :"1}"] + %I(#{1 + 1}) # => [:"2"] + +=== <tt>%s</tt>: Symbol Literals + +You can write a symbol with <tt>%s</tt>: + + %s[foo] # => :foo + %s[foo bar] # => :"foo bar" + +=== <tt>%r</tt>: Regexp Literals + +You can write a regular expression with <tt>%r</tt>; +the character used as the leading and trailing delimiter +may be (almost) any character: + + %r/foo/ # => /foo/ + %r:name/value pair: # => /name\/value pair/ + +A few "symmetrical" character pairs may be used as delimiters: -These are the types of percent literals: + %r[foo] # => /foo/ + %r{foo} # => /foo/ + %r(foo) # => /foo/ + %r<foo> # => /foo/ -<tt>%i</tt> :: Array of Symbols -<tt>%q</tt> :: String -<tt>%r</tt> :: Regular Expression -<tt>%s</tt> :: Symbol -<tt>%w</tt> :: Array of Strings -<tt>%x</tt> :: Backtick (capture subshell result) +The trailing delimiter may be followed by one or more modifier characters +that set modes for the regexp. +See {Regexp modes}[rdoc-ref:Regexp@Modes] for details. -For the two array forms of percent string, if you wish to include a space in -one of the array entries you must escape it with a "\\" character: +=== <tt>%x</tt>: Backtick Literals - %w[one one-hundred\ one] - #=> ["one", "one-hundred one"] +You can write and execute a shell command with <tt>%x</tt>: -If you are using "(", "[", "{", "<" you must close it with ")", "]", "}", ">" -respectively. You may use most other non-alphanumeric characters for percent -string delimiters such as "%", "|", "^", etc. + %x(echo 1) # => "1\n" diff --git a/doc/syntax/methods.rdoc b/doc/syntax/methods.rdoc index 2bb350def1..8dafa6bb0c 100644 --- a/doc/syntax/methods.rdoc +++ b/doc/syntax/methods.rdoc @@ -441,6 +441,13 @@ Also, note that a bare <code>*</code> can be used to ignore arguments: def ignore_arguments(*) end +You can also use a bare <code>*</code> when calling a method to pass the +arguments directly to another method: + + def delegate_arguments(*) + other_method(*) + end + === Keyword Arguments Keyword arguments are similar to positional arguments with default values: @@ -481,6 +488,13 @@ Also, note that <code>**</code> can be used to ignore keyword arguments: def ignore_keywords(**) end +You can also use <code>**</code> when calling a method to delegate +keyword arguments to another method: + + def delegate_keywords(**) + other_method(**) + end + To mark a method as accepting keywords, but not actually accepting keywords, you can use the <code>**nil</code>: diff --git a/doc/syntax/modules_and_classes.rdoc b/doc/syntax/modules_and_classes.rdoc index 6122f6e08e..9e05c5c774 100644 --- a/doc/syntax/modules_and_classes.rdoc +++ b/doc/syntax/modules_and_classes.rdoc @@ -40,9 +40,9 @@ functionality: remove_method :my_method end -Reopening classes is a very powerful feature of Ruby, but it is best to only -reopen classes you own. Reopening classes you do not own may lead to naming -conflicts or difficult to diagnose bugs. +Reopening modules (or classes) is a very powerful feature of Ruby, but it is +best to only reopen modules you own. Reopening modules you do not own may lead +to naming conflicts or difficult to diagnose bugs. == Nesting @@ -155,8 +155,8 @@ Ruby has three types of visibility. The default is +public+. A public method may be called from any other object. The second visibility is +protected+. When calling a protected method the -sender must be a subclass of the receiver or the receiver must be a subclass of -the sender. Otherwise a NoMethodError will be raised. +sender must inherit the Class or Module which defines the method. Otherwise a +NoMethodError will be raised. Protected visibility is most frequently used to define <code>==</code> and other comparison methods where the author does not wish to expose an object's @@ -259,6 +259,28 @@ includes a minimum of built-in methods. You can use BasicObject to create an independent inheritance structure. See the BasicObject documentation for further details. +Just like modules, classes can also be reopened. You can omit its superclass +when you reopen a class. Specifying a different superclass than the previous +definition will raise an error. + + class C + end + + class D < C + end + + # OK + class D < C + end + + # OK + class D + end + + # TypeError: superclass mismatch for class D + class D < String + end + == Inheritance Any method defined on a class is callable from its subclass: diff --git a/doc/syntax/operators.rdoc b/doc/syntax/operators.rdoc new file mode 100644 index 0000000000..d3045ac99e --- /dev/null +++ b/doc/syntax/operators.rdoc @@ -0,0 +1,75 @@ += Operators + +In Ruby, operators such as <code>+</code>, are defined as methods on the class. +Literals[rdoc-ref:syntax/literals.rdoc] define their methods within the lower +level, C language. String class, for example. + +Ruby objects can define or overload their own implementation for most operators. + +Here is an example: + + class Foo < String + def +(str) + self.concat(str).concat("another string") + end + end + + foobar = Foo.new("test ") + puts foobar + "baz " + +This prints: + + test baz another string + +What operators are available is dependent on the implementing class. + +== Operator Behavior + +How a class behaves to a given operator is specific to that class, since +operators are method implementations. + +When using an operator, it's the expression on the left-hand side of the +operation that specifies the behavior. + + 'a' * 3 #=> "aaa" + 3 * 'a' # TypeError: String can't be coerced into Integer + +== Logical Operators + +Logical operators are not methods, and therefore cannot be +redefined/overloaded. They are tokenized at a lower level. + +Short-circuit logical operators (<code>&&</code>, <code>||</code>, +<code>and</code>, and <code>or</code>) do not always result in a boolean value. +Similar to blocks, it's the last evaluated expression that defines the result +of the operation. + +=== <code>&&</code>, <code>and</code> + +Both <code>&&</code>/<code>and</code> operators provide short-circuiting by executing each +side of the operator, left to right, and stopping at the first occurrence of a +falsey expression. The expression that defines the result is the last one +executed, whether it be the final expression, or the first occurrence of a falsey +expression. + +Some examples: + + true && 9 && "string" #=> "string" + (1 + 2) && nil && "string" #=> nil + (a = 1) && (b = false) && (c = "string") #=> false + + puts a #=> 1 + puts b #=> false + puts c #=> nil + +In this last example, <code>c</code> was initialized, but not defined. + +=== <code>||</code>, <code>or</code> + +The means by which <code>||</code>/<code>or</code> short-circuits, is to return the result of +the first expression that is truthy. + +Some examples: + + (1 + 2) || true || "string" #=> 3 + false || nil || "string" #=> "string" diff --git a/doc/syntax/pattern_matching.rdoc b/doc/syntax/pattern_matching.rdoc index b7d614770c..e49c09a1f8 100644 --- a/doc/syntax/pattern_matching.rdoc +++ b/doc/syntax/pattern_matching.rdoc @@ -415,6 +415,11 @@ Additionally, when matching custom classes, the expected class can be specified end #=> "matched: 1" +These core and library classes implement deconstruction: + +* MatchData#deconstruct and MatchData#deconstruct_keys; +* Time#deconstruct_keys, Date#deconstruct_keys, DateTime#deconstruct_keys. + == Guard clauses +if+ can be used to attach an additional condition (guard clause) when the pattern matches. This condition may use bound variables: @@ -445,29 +450,6 @@ Additionally, when matching custom classes, the expected class can be specified end #=> "matched" -== Current feature status - -As of Ruby 3.1, find patterns are considered _experimental_: its syntax can change in the future. Every time you use these features in code, a warning will be printed: - - [0] => [*, 0, *] - # warning: Find pattern is experimental, and the behavior may change in future versions of Ruby! - # warning: One-line pattern matching is experimental, and the behavior may change in future versions of Ruby! - -To suppress this warning, one may use the Warning::[]= method: - - Warning[:experimental] = false - eval('[0] => [*, 0, *]') - # ...no warning printed... - -Note that pattern-matching warnings are raised at compile time, so this will not suppress the warning: - - Warning[:experimental] = false # At the time this line is evaluated, the parsing happened and warning emitted - [0] => [*, 0, *] - -So, only subsequently loaded files or `eval`-ed code is affected by switching the flag. - -Alternatively, the command line option <code>-W:no-experimental</code> can be used to turn off "experimental" feature warnings. - == Appendix A. Pattern syntax Approximate syntax is: diff --git a/doc/syntax/precedence.rdoc b/doc/syntax/precedence.rdoc index f64691ab1f..f0ca92b571 100644 --- a/doc/syntax/precedence.rdoc +++ b/doc/syntax/precedence.rdoc @@ -55,7 +55,7 @@ keywords. For example, this is a modifier-unless statement: Note that <code>(a if b rescue c)</code> is parsed as <code>((a if b) rescue c)</code> due to reasons not related to precedence. See {modifier -statements}[control_expressions_rdoc.html#label-Modifier+Statements]. +statements}[control_expressions.rdoc#label-Modifier+Statements]. <code>{ ... }</code> blocks have priority below all listed operations, but <code>do ... end</code> blocks have lower priority. diff --git a/doc/syntax/refinements.rdoc b/doc/syntax/refinements.rdoc index c900ab1bdc..17d5e67c21 100644 --- a/doc/syntax/refinements.rdoc +++ b/doc/syntax/refinements.rdoc @@ -279,6 +279,6 @@ Refinements in descendants have higher precedence than those of ancestors. == Further Reading -See https://bugs.ruby-lang.org/projects/ruby-master/wiki/RefinementsSpec for the +See https://github.com/ruby/ruby/wiki/Refinements-Spec for the current specification for implementing refinements. The specification also contains more details. diff --git a/doc/time/in.rdoc b/doc/time/in.rdoc deleted file mode 100644 index f47db76a35..0000000000 --- a/doc/time/in.rdoc +++ /dev/null @@ -1,7 +0,0 @@ -- <tt>in: zone</tt>: a timezone _zone_, which may be: - - A string offset from UTC. - - A single letter offset from UTC, in the range <tt>'A'..'Z'</tt>, - <tt>'J'</tt> (the so-called military timezone) excluded. - - An integer number of seconds. - - A timezone object; - see {Timezone Argument}[#class-Time-label-Timezone+Argument] for details. diff --git a/doc/time/mon-min.rdoc b/doc/time/mon-min.rdoc deleted file mode 100644 index 5bd430c74a..0000000000 --- a/doc/time/mon-min.rdoc +++ /dev/null @@ -1,8 +0,0 @@ -- +month+: a month value, which may be: - - An integer month in the range <tt>1..12</tt>. - - A 3-character string that matches regular expression - <tt>/jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec/i</tt>. -- +day+: an integer day in the range <tt>1..31</tt> - (less than 31 for some months). -- +hour+: an integer hour in the range <tt>0..23</tt>. -- +min+: an integer minute in the range <tt>0..59</tt>. diff --git a/doc/time/msec.rdoc b/doc/time/msec.rdoc deleted file mode 100644 index ce5d1e6145..0000000000 --- a/doc/time/msec.rdoc +++ /dev/null @@ -1,2 +0,0 @@ -- +msec+ is the number of milliseconds (Integer, Float, or Rational) - in the range <tt>0..1000</tt>. diff --git a/doc/time/nsec.rdoc b/doc/time/nsec.rdoc deleted file mode 100644 index a2dfe2d608..0000000000 --- a/doc/time/nsec.rdoc +++ /dev/null @@ -1,2 +0,0 @@ -- +nsec+ is the number of nanoseconds (Integer, Float, or Rational) - in the range <tt>0..1000000000</tt>. diff --git a/doc/time/sec.rdoc b/doc/time/sec.rdoc deleted file mode 100644 index 049c712110..0000000000 --- a/doc/time/sec.rdoc +++ /dev/null @@ -1,2 +0,0 @@ -- +sec+ is the number of seconds (Integer, Float, or Rational) - in the range <tt>0..60</tt>. diff --git a/doc/time/sec_i.rdoc b/doc/time/sec_i.rdoc deleted file mode 100644 index 99c8eddc65..0000000000 --- a/doc/time/sec_i.rdoc +++ /dev/null @@ -1 +0,0 @@ -- +isec_i+ is the integer number of seconds in the range <tt>0..60</tt>. diff --git a/doc/time/usec.rdoc b/doc/time/usec.rdoc deleted file mode 100644 index bb5a46419a..0000000000 --- a/doc/time/usec.rdoc +++ /dev/null @@ -1,2 +0,0 @@ -- +usec+ is the number of microseconds (Integer, Float, or Rational) - in the range <tt>0..1000000</tt>. diff --git a/doc/time/year.rdoc b/doc/time/year.rdoc deleted file mode 100644 index 2222b830d7..0000000000 --- a/doc/time/year.rdoc +++ /dev/null @@ -1 +0,0 @@ -- +year+: an integer year. diff --git a/doc/time/zone_and_in.rdoc b/doc/time/zone_and_in.rdoc deleted file mode 100644 index e09e22874b..0000000000 --- a/doc/time/zone_and_in.rdoc +++ /dev/null @@ -1,8 +0,0 @@ -- +zone+: a timezone, which may be: - - A string offset from UTC. - - A single letter offset from UTC, in the range <tt>'A'..'Z'</tt>, - <tt>'J'</tt> (the so-called military timezone) excluded. - - An integer number of seconds. - - A timezone object; - see {Timezone Argument}[#class-Time-label-Timezone+Argument] for details. -- <tt>in: zone</tt>: a timezone _zone_, which may be as above. diff --git a/doc/windows.md b/doc/windows.md new file mode 100644 index 0000000000..2020eec9cf --- /dev/null +++ b/doc/windows.md @@ -0,0 +1,234 @@ +# Windows + +Ruby supports a few native build platforms for Windows. + +* mswin: Build using Microsoft Visual C++ compiler with vcruntimeXXX.dll +* mingw-msvcrt: Build using compiler for Mingw with msvcrtXX.dll +* mingw-ucrt: Build using compiler for Mingw with Windows Universal CRT + +## Building Ruby using Mingw with UCRT + +The easiest build environment is just a standard [RubyInstaller-Devkit] +installation and [git-for-windows]. You might like to use [VSCode] as an +editor. + +### Build examples + +Ruby core development can be done either in Windows `cmd` like: + +``` +ridk enable ucrt64 + +pacman -S --needed %MINGW_PACKAGE_PREFIX%-openssl %MINGW_PACKAGE_PREFIX%-libyaml %MINGW_PACKAGE_PREFIX%-libffi + +cd c:\ +mkdir work +cd work +git clone https://github.com/ruby/ruby + +cd c:\work\ruby +sh autogen.sh +sh configure -C --disable-install-doc +make +``` + +or in MSYS2 `bash` like: + +``` +ridk enable ucrt64 +bash + +pacman -S --needed $MINGW_PACKAGE_PREFIX-openssl $MINGW_PACKAGE_PREFIX-libyaml $MINGW_PACKAGE_PREFIX-libffi + +cd /c/ +mkdir work +cd work +git clone https://github.com/ruby/ruby +cd ruby + +./autogen.sh +./configure -C --disable-install-doc +make +``` + +[RubyInstaller-Devkit]: https://rubyinstaller.org/ +[git-for-windows]: https://gitforwindows.org/ +[VSCode]: https://code.visualstudio.com/ + +## Building Ruby using Visual C++ + +### Requirement + +1. Windows 10/Windows Server 2016 or later. + +2. Visual C++ 14.0 (2015) or later. + + **Note** if you want to build x64 version, use native compiler for + x64. + +3. Please set environment variable `INCLUDE`, `LIB`, `PATH` + to run required commands properly from the command line. + + **Note** building ruby requires following commands. + + * nmake + * cl + * ml + * lib + * dumpbin + +4. If you want to build from GIT source, following commands are required. + * patch + * sed + * ruby 3.0 or later + + You can use [scoop](https://scoop.sh/) to install them like: + + ``` + scoop install git ruby sed patch + ``` + +5. You need to install required libraries using [vcpkg](https://vcpkg.io/) on + directory of ruby repository like: + + ``` + vcpkg --triplet x64-windows install + ``` + +6. Enable Command Extension of your command line. It's the default behavior + of `cmd.exe`. If you want to enable it explicitly, run `cmd.exe` with + `/E:ON` option. + +### How to compile and install + +1. Execute `win32\configure.bat` on your build directory. + You can specify the target platform as an argument. + For example, run `configure --target=i686-mswin32` + You can also specify the install directory. + For example, run `configure --prefix=<install_directory>` + Default of the install directory is `/usr` . + The default _PLATFORM_ is `i386-mswin32_`_MSRTVERSION_ on 32-bit + platforms, or `x64-mswin64_`_MSRTVERSION_ on x64 platforms. + _MSRTVERSION_ is the 2- or 3-digits version of the Microsoft + Runtime Library. + +2. Change _RUBY_INSTALL_NAME_ and _RUBY_SO_NAME_ in `Makefile` + if you want to change the name of the executable files. + And add _RUBYW_INSTALL_NAME_ to change the name of the + executable without console window if also you want. + +3. You need specify vcpkg directory to use `--with-opt-dir` + option like `win32\configure.bat --with-opt-dir=vcpkg_installed\x64-windows` + +4. Run `nmake up` if you are building from GIT source. + +5. Run `nmake` + +6. Run `nmake check` + +7. Run `nmake install` + +### Build examples + +* Build on the ruby source directory. + + ``` + ruby source directory: C:\ruby + build directory: C:\ruby + install directory: C:\usr\local + ``` + + ``` + C: + cd \ruby + win32\configure --prefix=/usr/local + nmake + nmake check + nmake install + ``` + +* Build on the relative directory from the ruby source directory. + + ``` + ruby source directory: C:\ruby + build directory: C:\ruby\mswin32 + install directory: C:\usr\local + ``` + + ``` + C: + cd \ruby + mkdir mswin32 + cd mswin32 + ..\win32\configure --prefix=/usr/local + nmake + nmake check + nmake install + ``` + +* Build on the different drive. + + ``` + ruby source directory: C:\src\ruby + build directory: D:\build\ruby + install directory: C:\usr\local + ``` + + ``` + D: + cd D:\build\ruby + C:\src\ruby\win32\configure --prefix=/usr/local + nmake + nmake check + nmake install DESTDIR=C: + ``` + +* Build x64 version (requires native x64 VC++ compiler) + + ``` + ruby source directory: C:\ruby + build directory: C:\ruby + install directory: C:\usr\local + ``` + + ``` + C: + cd \ruby + win32\configure --prefix=/usr/local --target=x64-mswin64 + nmake + nmake check + nmake install + ``` + +### Bugs + +You can **NOT** use a path name that contains any white space characters +as the ruby source directory, this restriction comes from the behavior +of `!INCLUDE` directives of `NMAKE`. + +You can build ruby in any directory including the source directory, +except `win32` directory in the source directory. +This is restriction originating in the path search method of `NMAKE`. + +## Icons + +Any icon files(`*.ico`) in the build directory, directories specified with +_icondirs_ make variable and `win32` directory under the ruby +source directory will be included in DLL or executable files, according +to their base names. + $(RUBY_INSTALL_NAME).ico or ruby.ico --> $(RUBY_INSTALL_NAME).exe + $(RUBYW_INSTALL_NAME).ico or rubyw.ico --> $(RUBYW_INSTALL_NAME).exe + the others --> $(RUBY_SO_NAME).dll + +Although no icons are distributed with the ruby source, you can use +anything you like. You will be able to find many images by search engines. +For example, followings are made from [Ruby logo kit]: + +* Small [favicon] in the official site + +* [vit-ruby.ico] or [icon itself] + +[Ruby logo kit]: https://cache.ruby-lang.org/pub/misc/logo/ruby-logo-kit.zip +[favicon]: https://www.ruby-lang.org/favicon.ico +[vit-ruby.ico]: http://ruby.morphball.net/vit-ruby-ico_en.html +[icon itself]: http://ruby.morphball.net/icon/vit-ruby.ico diff --git a/doc/yjit/yjit.md b/doc/yjit/yjit.md index a56aec652a..8ea3409e48 100644 --- a/doc/yjit/yjit.md +++ b/doc/yjit/yjit.md @@ -4,103 +4,140 @@ </a> </p> - YJIT - Yet Another Ruby JIT =========================== -**DISCLAIMER: Please note that this project is experimental. It is very much a work in progress, it may cause your software to crash, and current performance results will vary widely, especially on larger applications.** - YJIT is a lightweight, minimalistic Ruby JIT built inside CRuby. -It lazily compiles code using a Basic Block Versioning (BBV) architecture. The target use case is that of servers running -Ruby on Rails, an area where MJIT has not yet managed to deliver speedups. -To simplify development, we currently support only macOS and Linux on x86-64, but an ARM64 backend -is part of future plans. +It lazily compiles code using a Basic Block Versioning (BBV) architecture. +YJIT is currently supported for macOS, Linux and BSD on x86-64 and arm64/aarch64 CPUs. This project is open source and falls under the same license as CRuby. +<p align="center"><b> + If you're using YJIT in production, please + <a href="mailto:maxime.chevalierboisvert@shopify.com">share your success stories with us!</a> +</b></p> + If you wish to learn more about the approach taken, here are some conference talks and publications: +- RubyKaigi 2023 keynote: [Optimizing YJIT’s Performance, from Inception to Production](https://www.youtube.com/watch?v=X0JRhh8w_4I) +- RubyKaigi 2023 keynote: [Fitting Rust YJIT into CRuby](https://www.youtube.com/watch?v=GI7vvAgP_Qs) +- RubyKaigi 2022 keynote: [Stories from developing YJIT](https://www.youtube.com/watch?v=EMchdR9C8XM) +- RubyKaigi 2022 talk: [Building a Lightweight IR and Backend for YJIT](https://www.youtube.com/watch?v=BbLGqTxTRp0) - RubyKaigi 2021 talk: [YJIT: Building a New JIT Compiler Inside CRuby](https://www.youtube.com/watch?v=PBVLf3yfMs8) - Blog post: [YJIT: Building a New JIT Compiler Inside CRuby](https://pointersgonewild.com/2021/06/02/yjit-building-a-new-jit-compiler-inside-cruby/) +- MPLR 2023 paper: [Evaluating YJIT’s Performance in a Production Context: A Pragmatic Approach](https://dl.acm.org/doi/10.1145/3617651.3622982) +- VMIL 2021 paper: [YJIT: A Basic Block Versioning JIT Compiler for CRuby](https://dl.acm.org/doi/10.1145/3486606.3486781) - MoreVMs 2021 talk: [YJIT: Building a New JIT Compiler Inside CRuby](https://www.youtube.com/watch?v=vucLAqv7qpc) - ECOOP 2016 talk: [Interprocedural Type Specialization of JavaScript Programs Without Type Analysis](https://www.youtube.com/watch?v=sRNBY7Ss97A) - ECOOP 2016 paper: [Interprocedural Type Specialization of JavaScript Programs Without Type Analysis](https://drops.dagstuhl.de/opus/volltexte/2016/6101/pdf/LIPIcs-ECOOP-2016-7.pdf) - ECOOP 2015 talk: [Simple and Effective Type Check Removal through Lazy Basic Block Versioning](https://www.youtube.com/watch?v=S-aHBuoiYE0) - ECOOP 2015 paper: [Simple and Effective Type Check Removal through Lazy Basic Block Versioning](https://arxiv.org/pdf/1411.0352.pdf) -To cite this repository in your publications, please use this bibtex snippet: +To cite YJIT in your publications, please cite the MPLR 2023 paper: ``` -@misc{yjit_ruby_jit, - author = {Chevalier-Boisvert, Maxime and Wu, Alan and Patterson, Aaron}, - title = {YJIT - Yet Another Ruby JIT}, - year = {2021}, - publisher = {GitHub}, - journal = {GitHub repository}, - howpublished = {\url{https://github.com/Shopify/yjit}}, +@inproceedings{yjit_mplr_2023, +author = {Chevalier-Boisvert, Maxime and Kokubun, Takashi and Gibbs, Noah and Wu, Si Xing (Alan) and Patterson, Aaron and Issroff, Jemma}, +title = {Evaluating YJIT’s Performance in a Production Context: A Pragmatic Approach}, +year = {2023}, +isbn = {9798400703805}, +publisher = {Association for Computing Machinery}, +address = {New York, NY, USA}, +url = {https://doi.org/10.1145/3617651.3622982}, +doi = {10.1145/3617651.3622982}, +booktitle = {Proceedings of the 20th ACM SIGPLAN International Conference on Managed Programming Languages and Runtimes}, +pages = {20–33}, +numpages = {14}, +keywords = {dynamically typed, optimization, just-in-time, virtual machine, ruby, compiler, bytecode}, +location = {Cascais, Portugal}, +series = {MPLR 2023} } ``` ## Current Limitations -YJIT is a work in progress and as such may not yet be mature enough for mission-critical software. Below is a list of known limitations, all of which we plan to eventually address: - -- No garbage collection for generated code. -- Currently supports only macOS and Linux. -- Currently supports only x86-64 CPUs. - -Because there is no GC for generated code yet, your software could run out of executable memory if it is large enough. You can change how much executable memory is allocated using [YJIT's command-line options](https://github.com/Shopify/yjit#command-line-options). +YJIT may not be suitable for certain applications. It currently only supports macOS, Linux and BSD on x86-64 and arm64/aarch64 CPUs. YJIT will use more memory than the Ruby interpreter because the JIT compiler needs to generate machine code in memory and maintain additional state information. +You can change how much executable memory is allocated using [YJIT's command-line options](#command-line-options). ## Installation -Current YJIT versions are installed by default with CRuby. Make sure to specify the "--yjit" command line option to enable it at runtime. +### Requirements -Experimental YJIT patches that have not yet been merged with CRuby can be found in ruby-build: +You will need to install: +- A C compiler such as GCC or Clang +- GNU Make and Autoconf +- The Rust compiler `rustc` and Cargo (if you want to build in dev/debug mode) + - The Rust version must be [>= 1.58.0](../../yjit/Cargo.toml). -``` -ruby-build yjit-dev ~/.rubies/ruby-yjit-dev -``` +To install the Rust build toolchain, we suggest following the [recommended installation method][rust-install]. Rust also provides first class [support][editor-tools] for many source code editors. -They can also be found in the Shopify/yjit repository, which is cloned and build like CRuby. +[rust-install]: https://www.rust-lang.org/tools/install +[editor-tools]: https://www.rust-lang.org/tools -Start by cloning the `Shopify/yjit` repository: +### Building YJIT -``` -git clone https://github.com/Shopify/yjit +Start by cloning the `ruby/ruby` repository: + +```sh +git clone https://github.com/ruby/ruby yjit cd yjit ``` -The YJIT `ruby` binary can be built with either GCC or Clang. For development, we recommend enabling debug symbols so that assertions are enabled as this makes debugging easier. Enabling debug mode will also make it possible for you to disassemble code generated by YJIT. However, this causes a performance hit. For maximum performance, compile with GCC, without the `DRUBY_DEBUG` or `YJIT_STATS` build options. More detailed build instructions are provided in the [Ruby README](https://github.com/ruby/ruby#how-to-compile-and-install). -To support disassembly of the generated code, `libcapstone` is also required (`brew install capstone` on MacOS, `sudo apt-get install -y libcapstone-dev` on Ubuntu/Debian and `sudo dnf -y install capstone-devel` on Fedora). +The YJIT `ruby` binary can be built with either GCC or Clang. It can be built either in dev (debug) mode or in release mode. For maximum performance, compile YJIT in release mode with GCC. More detailed build instructions are provided in the [Ruby README](https://github.com/ruby/ruby#how-to-build). -``` -# Configure with debugging/stats options for development, build and install +```sh +# Configure in release mode for maximum performance, build and install ./autogen.sh -./configure cppflags="-DRUBY_DEBUG -DYJIT_STATS" --prefix=$HOME/.rubies/ruby-yjit --disable-install-doc --disable--install-rdoc -make -j16 install +./configure --enable-yjit --prefix=$HOME/.rubies/ruby-yjit --disable-install-doc +make -j && make install ``` -On macOS, you may need to specify where to find openssl, libyaml and gdbm: +or +```sh +# Configure in lower-performance dev (debug) mode for development, build and install +./autogen.sh +./configure --enable-yjit=dev --prefix=$HOME/.rubies/ruby-yjit --disable-install-doc +make -j && make install ``` -# Configure with debugging/stats options for development, build and install -./configure cppflags="-DRUBY_DEBUG -DYJIT_STATS" --prefix=$HOME/.rubies/ruby-yjit --disable-install-doc --disable--install-rdoc --with-opt-dir=$(brew --prefix openssl):$(brew --prefix readline):$(brew --prefix libyaml):$(brew --prefix gdbm) -make -j16 install + +Dev mode includes extended YJIT statistics, but can be slow. For only statistics you can configure in stats mode: + +```sh +# Configure in extended-stats mode without slow runtime checks, build and install +./autogen.sh +./configure --enable-yjit=stats --prefix=$HOME/.rubies/ruby-yjit --disable-install-doc +make -j && make install ``` -Typically configure will choose default C compiler. To specify the C compiler, use +On macOS, you may need to specify where to find some libraries: + +```sh +# Install dependencies +brew install openssl libyaml + +# Configure in dev (debug) mode for development, build and install +./autogen.sh +./configure --enable-yjit=dev --prefix=$HOME/.rubies/ruby-yjit --disable-install-doc --with-opt-dir="$(brew --prefix openssl):$(brew --prefix readline):$(brew --prefix libyaml)" +make -j && make install ``` + +Typically configure will choose the default C compiler. To specify the C compiler, use + +```sh # Choosing a specific c compiler -export CC=/path/to/my/choosen/c/compiler +export CC=/path/to/my/chosen/c/compiler ``` + before running `./configure`. You can test that YJIT works correctly by running: -``` +```sh # Quick tests found in /bootstraptest make btest # Complete set of tests -make -j16 test-all +make -j test-all ``` ## Usage @@ -110,124 +147,371 @@ make -j16 test-all Once YJIT is built, you can either use `./miniruby` from within your build directory, or switch to the YJIT version of `ruby` by using the `chruby` tool: -``` +```sh chruby ruby-yjit ruby myscript.rb ``` You can dump statistics about compilation and execution by running YJIT with the `--yjit-stats` command-line option: -``` +```sh ./miniruby --yjit-stats myscript.rb ``` The machine code generated for a given method can be printed by adding `puts RubyVM::YJIT.disasm(method(:method_name))` to a Ruby script. Note that no code will be generated if the method is not compiled. - ### Command-Line Options YJIT supports all command-line options supported by upstream CRuby, but also adds a few YJIT-specific options: -- `--disable-yjit`: turn off YJIT (enabled by default) -- `--yjit-stats`: produce statistics after the execution of a program (must compile with `cppflags=-DRUBY_DEBUG` to use this) -- `--yjit-exec-mem-size=N`: size of the executable memory block to allocate (default 256 MiB) -- `--yjit-call-threshold=N`: number of calls after which YJIT begins to compile a function (default 2) -- `--yjit-max-versions=N`: maximum number of versions to generate per basic block (default 4) -- `--yjit-greedy-versioning`: greedy versioning mode (disabled by default, may increase code size) +- `--yjit`: enable YJIT (disabled by default) +- `--yjit-exec-mem-size=N`: size of the executable memory block to allocate, in MiB (default 48 MiB) +- `--yjit-call-threshold=N`: number of calls after which YJIT begins to compile a function. + It defaults to 30, and it's then increased to 120 when the number of ISEQs in the process reaches 40,000. +- `--yjit-cold-threshold=N`: number of global calls after which an ISEQ is considered cold and not + compiled, lower values mean less code is compiled (default 200K) +- `--yjit-stats`: print statistics after the execution of a program (incurs a run-time cost) +- `--yjit-stats=quiet`: gather statistics while running a program but don't print them. Stats are accessible through `RubyVM::YJIT.runtime_stats`. (incurs a run-time cost) +- `--yjit-disable`: disable YJIT despite other `--yjit*` flags for lazily enabling it with `RubyVM::YJIT.enable` +- `--yjit-code-gc`: enable code GC (disabled by default as of Ruby 3.3). + It will cause all machine code to be discarded when the executable memory size limit is hit, meaning JIT compilation will then start over. + This can allow you to use a lower executable memory size limit, but may cause a slight drop in performance when the limit is hit. +- `--yjit-perf`: enable frame pointers and profiling with the `perf` tool +- `--yjit-trace-exits`: produce a Marshal dump of backtraces from all exits. Automatically enables `--yjit-stats` +- `--yjit-trace-exits=COUNTER`: produce a Marshal dump of backtraces from specified exits. Automatically enables `--yjit-stats` +- `--yjit-trace-exits-sample-rate=N`: trace exit locations only every Nth occurrence. Automatically enables `--yjit-trace-exits` + +Note that there is also an environment variable `RUBY_YJIT_ENABLE` which can be used to enable YJIT. +This can be useful for some deployment scripts where specifying an extra command-line option to Ruby is not practical. + +You can also enable YJIT at run-time using `RubyVM::YJIT.enable`. This can allow you to enable YJIT after your application is done +booting, which makes it possible to avoid compiling any initialization code. + +You can verify that YJIT is enabled using `RubyVM::YJIT.enabled?` or by checking that `ruby --yjit -v` includes the string `+YJIT`: + +```sh +ruby --yjit -v +ruby 3.3.0dev (2023-01-31T15:11:10Z master 2a0bf269c9) +YJIT dev [x86_64-darwin22] + +ruby --yjit -e "p RubyVM::YJIT.enabled?" +true + +ruby -e "RubyVM::YJIT.enable; p RubyVM::YJIT.enabled?" +true +``` ### Benchmarking -We have collected a set of benchmarks and implemented a simple benchmarking harness in the [yjit-bench](https://github.com/Shopify/yjit-bench) repository. This benchmarking harness is designed to disable CPU frequency scaling, set process affinity and disable address space randomization so that the variance between benchmarking runs will be as small as possible. Please kindly note that we are at an early stage in this project. +We have collected a set of benchmarks and implemented a simple benchmarking harness in the [yjit-bench](https://github.com/Shopify/yjit-bench) repository. This benchmarking harness is designed to disable CPU frequency scaling, set process affinity and disable address space randomization so that the variance between benchmarking runs will be as small as possible. + +## Performance Tips for Production Deployments + +While YJIT options default to what we think would work well for most workloads, +they might not necessarily be the best configuration for your application. +This section covers tips on improving YJIT performance in case YJIT does not +speed up your application in production. + +### Increasing --yjit-exec-mem-size + +When JIT code size (`RubyVM::YJIT.runtime_stats[:code_region_size]`) reaches this value, +YJIT stops compiling new code. Increasing the executable memory size means more code +can be optimized by YJIT, at the cost of more memory usage. + +If you start Ruby with `--yjit-stats`, e.g. using an environment variable `RUBYOPT=--yjit-stats`, +`RubyVM::YJIT.runtime_stats[:ratio_in_yjit]` shows the ratio of YJIT-executed instructions in %. +Ideally, `ratio_in_yjit` should be as large as 99%, and increasing `--yjit-exec-mem-size` often +helps improving `ratio_in_yjit`. + +### Running workers as long as possible + +It's helpful to call the same code as many times as possible before a process restarts. +If a process is killed too frequently, the time taken for compiling methods may outweigh +the speedup obtained by compiling them. + +You should monitor the number of requests each process has served. +If you're periodically killing worker processes, e.g. with `unicorn-worker-killer` or `puma_worker_killer`, +you may want to reduce the killing frequency or increase the limit. + +## Reducing YJIT Memory Usage + +YJIT allocates memory for JIT code and metadata. Enabling YJIT generally results in more memory usage. +This section goes over tips on minimizing YJIT memory usage in case it uses more than your capacity. + +### Decreasing --yjit-exec-mem-size -### Performance Tips +The `--yjit-exec-mem-size` option specifies the JIT code size, but YJIT also uses memory for its metadata, +which often consumes more memory than JIT code. Generally, YJIT adds memory overhead by roughly +3-4x of `--yjit-exec-mem-size` in production as of Ruby 3.3. You should multiply that by the number +of worker processes to estimate the worst case memory overhead. -This section contains tips on writing Ruby code that will run as fast as possible on YJIT. Some of this advice is based on current limitations of YJIT, while other advice is broadly applicable. It probably won't be practical to apply these tips everywhere in your codebase, but you can profile your code using a tool such as [stackprof](https://github.com/tmm1/stackprof) and refactor the specific methods that make up the largest fractions of the execution time. +`--yjit-exec-mem-size=48` is the default since Ruby 3.3.1, +but smaller values like 32 MiB might make sense for your application. +While doing so, you may want to monitor `RubyVM::YJIT.runtime_stats[:ratio_in_yjit]` as explained above. -- Use exceptions for error recovery only, not as part of normal control-flow +### Enabling YJIT lazily + +If you enable YJIT by `--yjit` options or `RUBY_YJIT_ENABLE=1`, YJIT may compile code that is +used only during the application boot. `RubyVM::YJIT.enable` allows you to enable YJIT from Ruby code, +and you can call this after your application is initialized, e.g. on Unicorn's `after_fork` hook. +If you use any YJIT options (`--yjit-*`), YJIT will start at boot by default, but `--yjit-disable` +allows you to start Ruby with the YJIT-disabled mode while passing YJIT tuning options. + +## Code Optimization Tips + +This section contains tips on writing Ruby code that will run as fast as possible on YJIT. Some of this advice is based on current limitations of YJIT, while other advice is broadly applicable. It probably won't be practical to apply these tips everywhere in your codebase. You should ideally start by profiling your application using a tool such as [stackprof](https://github.com/tmm1/stackprof) so that you can determine which methods make up most of the execution time. You can then refactor the specific methods that make up the largest fractions of the execution time. We do not recommend modifying your entire codebase based on the current limitations of YJIT. + +- Avoid using `OpenStruct` - Avoid redefining basic integer operations (i.e. +, -, <, >, etc.) - Avoid redefining the meaning of `nil`, equality, etc. - Avoid allocating objects in the hot parts of your code -- Use while loops if you can, instead of `integer.times` - Minimize layers of indirection - - Avoid classes that wrap objects if you can - - Avoid methods that just call another method, trivial one liner methods -- CRuby method calls are costly. Favor larger methods over smaller methods. -- Try to write code so that the same variables always have the same type + - Avoid writing wrapper classes if you can (e.g. a class that only wraps a Ruby hash) + - Avoid methods that just call another method +- Ruby method calls are costly. Avoid things such as methods that only return a value from a hash +- Try to write code so that the same variables and method arguments always have the same type +- Avoid using `TracePoint` as it can cause YJIT to deoptimize code +- Avoid using `Binding` as it can cause YJIT to deoptimize code + +You can also use the `--yjit-stats` command-line option to see which bytecodes cause YJIT to exit, and refactor your code to avoid using these instructions in the hottest methods of your code. + +### Other Statistics + +If you run `ruby` with `--yjit-stats`, YJIT will track and return performance statistics in `RubyVM::YJIT.runtime_stats`. + +```rb +$ RUBYOPT="--yjit-stats" irb +irb(main):001:0> RubyVM::YJIT.runtime_stats +=> +{:inline_code_size=>340745, + :outlined_code_size=>297664, + :all_stats=>true, + :yjit_insns_count=>1547816, + :send_callsite_not_simple=>7267, + :send_kw_splat=>7, + :send_ivar_set_method=>72, +... +``` + +Some of the counters include: -You can also compile YJIT in debug mode and use the `--yjit-stats` command-line option to see which bytecodes cause YJIT to exit, and refactor your code to avoid using these instructions in the hottest methods of your code. +* :yjit_insns_count - how many Ruby bytecode instructions have been executed +* :binding_allocations - number of bindings allocated +* :binding_set - number of variables set via a binding +* :code_gc_count - number of garbage collections of compiled code since process start +* :vm_insns_count - number of instructions executed by the Ruby interpreter +* :compiled_iseq_count - number of bytecode sequences compiled +* :inline_code_size - size in bytes of compiled YJIT blocks +* :outline_code_size - size in bytes of YJIT error-handling compiled code +* :side_exit_count - number of side exits taken at runtime +* :total_exit_count - number of exits, including side exits, taken at runtime +* :avg_len_in_yjit - avg. number of instructions in compiled blocks before exiting to interpreter + +Counters starting with "exit_" show reasons for YJIT code taking a side exit (return to the interpreter.) + +Performance counter names are not guaranteed to remain the same between Ruby versions. If you're curious what each counter means, +it's usually best to search the source code for it — but it may change in a later Ruby version. + +The printed text after a `--yjit-stats` run includes other information that may be named differently than the information in `RubyVM::YJIT.runtime_stats`. ## Contributing -We welcome open source contributors. You should feel free to open new issues to report bugs or just to ask questions. +We welcome open source contributions. You should feel free to open new issues to report bugs or just to ask questions. Suggestions on how to make this readme file more helpful for new contributors are most welcome. Bug fixes and bug reports are very valuable to us. If you find a bug in YJIT, it's very possible be that nobody has reported it before, or that we don't have a good reproduction for it, so please open an issue and provide as much information as you can about your configuration and a description of how you encountered the problem. List the commands you used to run YJIT so that we can easily reproduce the issue on our end and investigate it. If you are able to produce a small program reproducing the error to help us track it down, that is very much appreciated as well. -If you would like to contribute a large patch to YJIT, we suggest opening an issue or a discussion on this repository so that +If you would like to contribute a large patch to YJIT, we suggest opening an issue or a discussion on the [Shopify/ruby repository](https://github.com/Shopify/ruby/issues) so that we can have an active discussion. A common problem is that sometimes people submit large pull requests to open source projects without prior communication, and we have to reject them because the work they implemented does not fit within the design of the -project. We want to save you time and frustration, so please reach out and we can have a productive discussion as to how -you can contribute things we will want to merge into YJIT. +project. We want to save you time and frustration, so please reach out so we can have a productive discussion as to how +you can contribute patches we will want to merge into YJIT. ### Source Code Organization The YJIT source code is divided between: -- `yjit_asm.c`: x86 in-memory assembler we use to generate machine code -- `yjit_codegen.c`: logic for translating Ruby bytecode to machine code -- `yjit_core.c`: basic block versioning logic, core structure of YJIT -- `yjit_iface.c`: code YJIT uses to interface with the rest of CRuby +- `yjit.c`: code YJIT uses to interface with the rest of CRuby - `yjit.h`: C definitions YJIT exposes to the rest of the CRuby - `yjit.rb`: `YJIT` Ruby module that is exposed to Ruby -- `misc/test_yjit_asm.sh`: script to compile and run the in-memory assembler tests -- `misc/yjit_asm_tests.c`: tests for the in-memory assembler +- `yjit/src/asm/*`: in-memory assembler we use to generate machine code +- `yjit/src/codegen.rs`: logic for translating Ruby bytecode to machine code +- `yjit/src/core.rb`: basic block versioning logic, core structure of YJIT +- `yjit/src/stats.rs`: gathering of run-time statistics +- `yjit/src/options.rs`: handling of command-line options +- `yjit/src/cruby.rs`: C bindings manually exposed to the Rust codebase +- `yjit/bindgen/src/main.rs`: C bindings exposed to the Rust codebase through bindgen The core of CRuby's interpreter logic is found in: - `insns.def`: defines Ruby's bytecode instructions (gets compiled into `vm.inc`) - `vm_insnshelper.c`: logic used by Ruby's bytecode instructions - `vm_exec.c`: Ruby interpreter loop +### Generating C bindings with bindgen + +In order to expose C functions to the Rust codebase, you will need to generate C bindings: + +```sh +CC=clang ./configure --enable-yjit=dev +make -j yjit-bindgen +``` + +This uses the bindgen tools to generate/update `yjit/src/cruby_bindings.inc.rs` based on the +bindings listed in `yjit/bindgen/src/main.rs`. Avoid manually editing this file +as it could be automatically regenerated at a later time. If you need to manually add C bindings, +add them to `yjit/cruby.rs` instead. + ### Coding & Debugging Protips -There are 3 test suites: +There are multiple test suites: - `make btest` (see `/bootstraptest`) - `make test-all` - `make test-spec` - `make check` runs all of the above +- `make yjit-smoke-test` runs quick checks to see that YJIT is working correctly The tests can be run in parallel like this: -``` -make -j16 test-all RUN_OPTS="--yjit-call-threshold=1" +```sh +make -j test-all RUN_OPTS="--yjit-call-threshold=1" ``` Or single-threaded like this, to more easily identify which specific test is failing: -``` +```sh make test-all TESTOPTS=--verbose RUN_OPTS="--yjit-call-threshold=1" ``` To debug a single test in `test-all`: -``` +```sh make test-all TESTS='test/-ext-/marshal/test_usrmarshal.rb' RUNRUBYOPT=--debugger=lldb RUN_OPTS="--yjit-call-threshold=1" ``` You can also run one specific test in `btest`: -``` +```sh make btest BTESTS=bootstraptest/test_ractor.rb RUN_OPTS="--yjit-call-threshold=1" ``` There are shortcuts to run/debug your own test/repro in `test.rb`: -``` +```sh make run # runs ./miniruby test.rb make lldb # launches ./miniruby test.rb in lldb ``` You can use the Intel syntax for disassembly in LLDB, keeping it consistent with YJIT's disassembly: -``` +```sh echo "settings set target.x86-disassembly-flavor intel" >> ~/.lldbinit ``` + +## Running x86 YJIT on Apple's Rosetta + +For development purposes, it is possible to run x86 YJIT on an Apple M1 via Rosetta. You can find basic +instructions below, but there are a few caveats listed further down. + +First, install Rosetta: + +```sh +$ softwareupdate --install-rosetta +``` + +Now any command can be run with Rosetta via the `arch` command line tool. + +Then you can start your shell in an x86 environment: + +```sh +$ arch -x86_64 zsh +``` + +You can double check your current architecture via the `arch` command: + +```sh +$ arch -x86_64 zsh +$ arch +i386 +``` + +You may need to set the default target for `rustc` to x86-64, e.g. + +```sh +$ rustup default stable-x86_64-apple-darwin +``` + +While in your i386 shell, install Cargo and Homebrew, then hack away! + +### Rosetta Caveats + +1. You must install a version of Homebrew for each architecture +2. Cargo will install in $HOME/.cargo by default, and I don't know a good way to change architectures after install + +If you use Fish shell you can [read this link](https://tenderlovemaking.com/2022/01/07/homebrew-rosetta-and-ruby.html) for information on making the dev environment easier. + +## Profiling with Linux perf + +`--yjit-perf` allows you to profile JIT-ed methods along with other native functions using Linux perf. +When you run Ruby with `perf record`, perf looks up `/tmp/perf-{pid}.map` to resolve symbols in JIT code, +and this option lets YJIT write method symbols into that file as well as enabling frame pointers. + +### Call graph + +Here's an example way to use this option with [Firefox Profiler](https://profiler.firefox.com) +(See also: [Profiling with Linux perf](https://profiler.firefox.com/docs/#/./guide-perf-profiling)): + +```bash +# Compile the interpreter with frame pointers enabled +./configure --enable-yjit --prefix=$HOME/.rubies/ruby-yjit --disable-install-doc cflags=-fno-omit-frame-pointer +make -j && make install + +# [Optional] Allow running perf without sudo +echo 0 | sudo tee /proc/sys/kernel/kptr_restrict +echo -1 | sudo tee /proc/sys/kernel/perf_event_paranoid + +# Profile Ruby with --yjit-perf +cd ../yjit-bench +PERF="record --call-graph fp" ruby --yjit-perf -Iharness-perf benchmarks/liquid-render/benchmark.rb + +# View results on Firefox Profiler https://profiler.firefox.com. +# Create /tmp/test.perf as below and upload it using "Load a profile from file". +perf script --fields +pid > /tmp/test.perf +``` + +### YJIT codegen + +You can also profile the number of cycles consumed by code generated by each YJIT function. + +```bash +# Install perf +apt-get install linux-tools-common linux-tools-generic linux-tools-`uname -r` + +# [Optional] Allow running perf without sudo +echo 0 | sudo tee /proc/sys/kernel/kptr_restrict +echo -1 | sudo tee /proc/sys/kernel/perf_event_paranoid + +# Profile Ruby with --yjit-perf=codegen +cd ../yjit-bench +PERF=record ruby --yjit-perf=codegen -Iharness-perf benchmarks/lobsters/benchmark.rb + +# Aggregate results +perf script > /tmp/perf.txt +../ruby/misc/yjit_perf.py /tmp/perf.txt +``` + +#### Building perf with Python support + +The above instructions work fine for most people, but you could also use +a handy `perf script -s` interface if you build perf from source. + +```bash +# Build perf from source for Python support +sudo apt-get install libpython3-dev python3-pip flex libtraceevent-dev \ + libelf-dev libunwind-dev libaudit-dev libslang2-dev libdw-dev +git clone --depth=1 https://github.com/torvalds/linux +cd linux/tools/perf +make +make install + +# Aggregate results +perf script -s ../ruby/misc/yjit_perf.py +``` |