Advent of Changelog: Day 10

Author: zverok

_src/3.3.md

@@ -22,35 +22,81 @@ description: Ruby 3.3 full and annotated changelog
 
 ### `Array#pack` and `String#unpack`: raise `ArgumentError` for unknown directives
 
-* **Reason:**
 * **Discussion:** [Bug #19150]
 * **Documentation:** [doc/packed_data.rdoc](https://docs.ruby-lang.org/en/master/packed_data_rdoc.html)
 * **Code:**
+  ```ruby
+  [1, 2, 3].pack('r*')
+  # Ruby 3.1: "", no warning
+  # Ruby 3.2: "", warning: unknown pack directive 'r' in 'r*'
+  # Ruby 3.3: in `pack': unknown pack directive 'r' in 'r*' (ArgumentError)
+  ```
 * **Notes:**
 
 ### `Dir.for_fd` and `Dir.fchdir`
 
-* **Reason:**
+Two methods to accept an integer file descriptor as an argument: `for_fd` creates a `Dir` object from it; `fchdir` changes the current directory to one specified by a descriptor.
+
+* **Reason:** New methods allow to use UNIX file descriptors if they are returned from a C-level code or obtained from OS.
 * **Discussion:** [Feature #19347]
 * **Documentation:** [Dir.for_fd](https://docs.ruby-lang.org/en/master/Dir.html#method-c-for_fd), [Dir.fchdir](https://docs.ruby-lang.org/en/master/Dir.html#method-c-fchdir)
 * **Code:**
+  ```ruby
+  fileno = Dir.new('doc/').fileno
+  # In reality, this #fileno might come from other library
+
+  dir = Dir.for_fd(fileno)
+  #=> #<Dir:0x00007f8831b810a8> -- no readable path representation
+  dir.path #=> nil
+  dir.to_a
+  #=> ["forwardable.rd.ja", "packed_data.rdoc", "marshal.rdoc", "format_specifications.rdoc", ....
+  # It was performed in the Ruby's core folder, and lists the doc/ contents
+
+  # Attempt to use a bogus fileno will result in error:
+  Dir.for_fd(0)
+  # `for_fd': Not a directory - fdopendir (Errno::ENOTDIR)
+
+  # Same with fileno that doesn't designate a directory:
+  Dir.for_fd(Dir.new('README.md').fileno)
+  # in `initialize': Not a directory @ dir_initialize - README.md (Errno::ENOTDIR)
+
+  # Same logic works for .fchdir
+  Dir.fchdir(fileno) #=> 0
+  Dir.pwd
+  # "/home/zverok/projects/ruby/doc" -- the current path have changed successfully
+  ```
 * **Notes:**
+  * The functionality is only supported on POSIX platforms;
+  * The initial [ticket](https://bugs.ruby-lang.org/issues/19347) only proposed to find a way to be able to change a current directory to one specified by a descriptor (i.e., what eventually became `.fchdir`), but during the discussion a need were discovered for a generic instantiation of a `Dir` instance from the descriptor (what became `from_fd`), as well as a generic way to change the current directory to one specified by `Dir` instance ([`#chdir`](TODO), which is not related to descriptors but is generically useful).
 
 ### `Dir#chdir`
 
-* **Reason:**
+An instance method version of [Dir.chdir](https://docs.ruby-lang.org/en/master/Dir.html#method-c-chdir): changes the current working directory to one specified by the `Dir` instance.
+
 * **Discussion:** [Feature #19347]
 * **Documentation:** [Dir#chdir](https://docs.ruby-lang.org/en/master/Dir.html#method-i-chdir)
 * **Code:**
-* **Notes:**
+  ```ruby
+  Dir.pwd #=> "/home/zverok/projects/ruby"
+  dir = Dir.new('doc')
+  dir.chdir #=> nil
+  Dir.pwd #=> "/home/zverok/projects/ruby/doc"
+  ```
+* **Notes:** Unlike [Dir.chdir](https://docs.ruby-lang.org/en/master/Dir.html#method-c-chdir), the new method doesn't have a block form (the form that restores previous working directory after the block is finished).
 
 ### `MatchData#named_captures`: `symbolize_names:` argument
 
-* **Reason:**
 * **Discussion:** [Feature #19591]
 * **Documentation:** [MatchData#named_captures](https://docs.ruby-lang.org/en/master/MatchData.html#method-i-named_captures)
 * **Code:**
-* **Notes:**
+  ```ruby
+  m = "2023-12-25".match(/(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/)
+  m.named_captures
+  #=> {"year"=>"2023", "month"=>"12", "day"=>"25"}
+  m.named_captures(symbolize_names: true)
+  #=> {:year=>"2023", :month=>"12", :day=>"25"}
+  ```
+* **Notes:** While `symbolize_names:` might looks somewhat strange (usually we talk about hash _keys_), it is done for consistency with Ruby standard library's [`JSON.parse`](https://docs.ruby-lang.org/en/master/JSON.html#module-JSON-label-Output+Options) signature, which inherited the terminology from the JSON specification.
 
 ### `Module#set_temporary_name`
 
@@ -60,7 +106,80 @@ Allows to assign a string to be rendered as class/module's `#name`, without assi
 * **Discussion:** [Feature #19521]
 * **Documentation:** [Module#set_temporary_name](https://docs.ruby-lang.org/en/master/Module.html#method-i-set_temporary_name)
 * **Code:**
-* **Notes:**
+  ```ruby
+dynamic_class = Class.new do
+  def foo; end
+end
+
+dynamic_class.name #=> nil
+
+# For dynamic classes, representation of related values is frequently unreadable:
+dynamic_class #=> #<Class:0x0...>
+instance = dynamic_class.new #=> #<#<Class:0x0...>:0x0...>
+instance.method(:foo) #=> #<Method: #<Class:0x0...>#foo() ...>
+
+dynamic_class::Nested = Module.new
+dynamic_class::Nested #=> #<Class:0x0...>::Nested
+
+# After assigning the temporary name, representation becomes more convenient:
+dynamic_class.set_temporary_name("MyDSLClass(with description)")
+
+dynamic_class #=> MyDSLClass(with description)
+instance #=> #<MyDSLClass(with description):0x0...>
+instance.method(:foo) #=> #<Method: MyDSLClass(with description)#foo() ...>
+
+# Note that module constant names are assigned at the moment of their creation,
+# and don't change when the temporary name is assigned:
+dynamic_class::OtherNested = Module.new
+
+dynamic_class::Nested #=> #<Class:0x0...>::Nested
+dynamic_class::OtherNested #=> MyDSLClass(with description)::OtherNested
+
+# Assigning names that correspond to constant name rules is prohibited:
+dynamic_class.set_temporary_name("MyClass")
+# `set_temporary_name': the temporary name must not be a constant path to avoid confusion (ArgumentError)
+dynamic_class.set_temporary_name("MyClass::NestedName")
+# `set_temporary_name': the temporary name must not be a constant path to avoid confusion (ArgumentError)
+
+# When the module with a temporary name is put into a constant,
+# it receives a permanent name, which can't be changed anymore
+C = dynamic_class
+
+# It affects all associated values (including modules)
+
+dynamic_class #=> C
+instance #=> #<C:0x0...>
+instance.method(:foo) #=> #<Method: C#foo() ...>
+dynamic_class::Nested #=> C::Nested
+dynamic_class::OtherNested #=> C::OtherNested
+
+dynamic_class.set_temporary_name("Can I have it back?")
+# `set_temporary_name': can't change permanent name (RuntimeError)
+
+# `nil` can be used to cleanup a temporary name:
+other_class = Class.new
+other_class.set_temporary_name("another one")
+other_class #=> another one
+other_class.set_temporary_name(nil)
+other_class #=> #<Class:0x0...>
+  ```
+* **Notes:** Any phrase that used as a temporary name would be used verbatim; this might create very confusing `#inspect` results and error messages; so it is advised to use strings somehow implying that the name belong to a module. Imagine we wrap into classes with temporary names RSpec-style examples, and then there is a typo in such example:
+  ```ruby
+  it "works as a calculator" do
+    expec(2+2).to eq 4
+  end
+  # If we assign just the example description as a temp.name, the
+  # error would look like this:
+  #
+  #   undefined method `expec' for an instance of works as a calculator
+  #                                               ^^^^^^^^^^^^^^^^^^^^^
+  #
+  # ...which is confusing. So it is probably better to construct a
+  # module-like temporary name, to have:
+  #
+  #   undefined method `expec' for an instance of MyFramework::Example("works as a calculator")
+  #                                               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  ```
 
 ### `ObjectSpace::WeakKeyMap`
 
@@ -100,13 +219,37 @@ A new "weak map" concept implementation. Unlike `ObjectSpace::WeakMap`, it compa
   ```
 * **Notes:**
 
-### `Proc#dup` and `#clone` call `#initialize_dup` and `#initialize_clone`
+### `Proc#dup` and `#clone` call `#initialize_dup` and `#initialize_copy`
 
-* **Reason:**
+* **Reason:** A fix for an old inconsistency: `Object`'s `#dup` and `#clone` methods docs
 * **Discussion:** [Feature #19362]
 * **Documentation:** — (Adheres to the behavior described for [Object#dup](https://docs.ruby-lang.org/en/master/Object.html#method-i-dup) and [#clone](https://docs.ruby-lang.org/en/master/Kernel.html#method-i-clone))
 * **Code:**
-* **Notes:**
+  ```ruby
+  # The examples would work the same with
+  # #dup/#initialize_dup and #clone/#initialize_copy
+  class TaggedProc < Proc
+    attr_reader :tag
+
+    def initialize(tag)
+      super()
+      @tag = tag
+    end
+
+    def initialize_dup(other)
+      @tag = other.tag
+      super
+    end
+  end
+
+  proc = TaggedProc.new('admin') { }
+
+  proc.tag #=> 'admin'
+  proc.dup.tag
+  # Ruby 3.2 => nil, the duplication didn't went through initialize_dup
+  # Ruby 3.3 => "admin"
+  ```
+* **Notes:** Inheriting from core classes is an advanced technique, and most of the times there are simple ways to achieve same goals (like wrapper objects containing a `Proc` and an additional info).
 
 ### `Process.warmup`
 
@@ -118,27 +261,45 @@ A new "weak map" concept implementation. Unlike `ObjectSpace::WeakMap`, it compa
 
 ### `Process::Status#&`  and `#>>` are deprecated
 
-* **Reason:**
+* **Reason:** These methods have been treating `Process::Status` as a very thin wrapper around an integer value of the return status of the process; which is unreasonable for supporting Ruby in more varying environments.
 * **Discussion:** [Bug #19868]
 * **Documentation:** [Process::Status#&](https://docs.ruby-lang.org/en/master/Process/Status.html#method-i-26), [#>>](https://docs.ruby-lang.org/en/master/Process/Status.html#method-i-3E-3E)
 * **Code:**
-* **Notes:**
 
 ### `Thread::Queue#freeze` and `SizedQueue#freeze` raise `TypeError`
 
-* **Reason:**
+* **Reason:** The discussion was started with a bug report about `Queue` not respecting `#freeze` in any way (`#push` and `#pop` were still working after `#freeze` call). It was then decided that allowing to freeze a queue like any other collection (leaving it immutable) would have questionable semantics: as `Queue` is meant to be an inter-thread communication utility, freezing a queue while some thread waits for it would either leave this thread hanging, or would require `#freeze`'s functionality to extend for communication with dependent threads. Neither is a good option, so the behavior of the method was changed to communicate that queue freezing doesn't make sense.
 * **Discussion:** [Bug #17146]
 * **Documentation:** [Thread::Queue#freeze](https://docs.ruby-lang.org/en/master/Thread/Queue.html#method-i-freeze) and [Thread::SizedQueue#freeze](https://docs.ruby-lang.org/en/master/Thread/SizedQueue.html#method-i-freeze)
-* **Code:**
-* **Notes:**
 
-### `Range#reverse_each` behavior change with semi-open ranges
+### `Range#reverse_each`
 
-* **Reason:**
-* **Discussion:** [Feature #18515], [Feature #18551]
+Specialized `Range#reverse_each` method is implemented.
+
+* **Reason:** Previously, `Range` didn't have a specialized `#reverse_each` method, so calling it would invoke a generic `Enumerable#reverse_each`. The latter works by  converting the object to array, and then enumerating this array. In case of a `Range` this can be inefficient (producing large arrays) or impossible (when only upper bound of the range is defined)
+* **Discussion:** [Feature #18515]
 * **Documentation:** [Range#reverse_each](https://docs.ruby-lang.org/en/master/Range.html#method-i-reverse_each)
 * **Code:**
-* **Notes:**
+  ```ruby
+  (1..2**100).reverse_each.take(3)
+  # Ruby 3.2: hangs on my machine, trying to produce an array
+  # Ruby 3.3: #=> [1267650600228229401496703205376, 1267650600228229401496703205375, 1267650600228229401496703205374]
+  #  (returns immediately)
+
+  (...5).reverse_each.take(3)
+  # Ruby 3.2: can't iterate from NilClass (TypeError)
+  # Ruby 3.3: #=> [5, 4, 3]
+
+  (1...).reverse_each
+  # Ruby 3.2: hangs forever, trying to produce an array
+  # Ruby 3.3: `reverse_each': can't iterate from NilClass (TypeError)
+
+  # The latter change affects any type of range beginning:
+  ('a'...).reverse_each
+  # Ruby 3.2: hangs forever, trying to produce an array
+  # Ruby 3.3: `reverse_each': can't iterate from NilClass (TypeError)
+  ```
+* **Notes:** Other than raising `TypeError` for endless ranges (which works with any type of range beginning), the specialized behavior is only implemented for `Integer`. A possibility of a generalization was [discussed](https://bugs.ruby-lang.org/issues/18515#note-4) by using object's `#pred` method (opposite to `#succ`, which the range uses to iterate forward), but the scope of this change would be bigger, as currently only `Integer` implements such method. It is possible that the adjustments would be made in the future versions.
 
 ### `Refinement#target` as an alternative of `Refinement#refined_class`