Advent of Changelog: Day 11

Author: zverok

_src/3.3.md

@@ -63,7 +63,13 @@ Two methods to accept an integer file descriptor as an argument: `for_fd` create
   # Same logic works for .fchdir
   Dir.fchdir(fileno) #=> 0
   Dir.pwd
-  # "/home/zverok/projects/ruby/doc" -- the current path have changed successfully
+  #=> "/home/zverok/projects/ruby/doc" -- the current path have changed successfully
+
+  # A block form of fchdir is available, like for a regular .chdir:
+  Dir.fchdir(Dir.new('NEWS').fileno) do
+    p Dir.pwd #=> "/home/zverok/projects/ruby/doc/NEWS"
+  end
+  Dir.pwd #=> "/home/zverok/projects/ruby/doc" -- back to the path before the block
   ```
 * **Notes:**
   * The functionality is only supported on POSIX platforms;
@@ -81,8 +87,13 @@ An instance method version of [Dir.chdir](https://docs.ruby-lang.org/en/master/D
   dir = Dir.new('doc')
   dir.chdir #=> nil
   Dir.pwd #=> "/home/zverok/projects/ruby/doc"
+
+  # The block form works, too:
+  Dir.new('NEWS').chdir do
+    Dir.pwd #=> "/home/zverok/projects/ruby/doc/NEWS"
+  end
+  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
 
@@ -301,37 +312,92 @@ Specialized `Range#reverse_each` method is implemented.
   ```
 * **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`
+### `Refinement#refined_class` is renamed to `Refinement#target`
+
+Just a renaming of the unfortunately named new method that [emerged in Ruby 3.2](/rubychanges/3.2.html#refinementrefined_class).
 
-* **Reason:**
 * **Discussion:** [Feature #19714]
 * **Documentation:** [Refinement#target](https://docs.ruby-lang.org/en/master/Refinement.html#method-i-target)
-* **Code:**
-* **Notes:**
 
 ### `String#bytesplice`: new arguments to select a portion of the replacement string
 
-* **Reason:**
+The low-level string manipulation method now allows to provide a coordinates of the part of the replacement string to be used.
+
+* **Reason:** The new "byte-oriented" methods [were introduced](https://rubyreferences.github.io/rubychanges/3.2.html#byte-oriented-methods) in Ruby 3.2 to support low-level programming like text editors or network protocol implementations. In those use cases, the necessity of copying of a small part of one string into the middle of another is frequent, and producing intermediate strings (by first slicing the necessary part) is costly.
 * **Discussion:** [Feature #19314]
 * **Documentation:** [String#bytesplice](https://docs.ruby-lang.org/en/master/String.html#method-i-bytesplice)
 * **Code:**
-* **Notes:**
+  ```ruby
+  # Base usage
+  'foo'.byteplice(1..2, 'bar', 0..1)
+  # The receiver is modified
 
-### `TracePoint` supports `rescue` event
+  # Or, alternatively:
+  'foo'.byteplice(1, 2, 'bar', 0, 1)
+
+  # Two forms can't be mixed:
+  'foo'.byteplice(1..2, 'bar', 0, 1)
+  # Semi-open ranges work:
+  'foo'.byteplice(1..2, 'bar', 1..)
+  'foo'.byteplice(1..2, 'bar', ..1)
+
+  ```
+
+### `TracePoint` supports `:rescue` event
+
+Allows to trace when some exception was `rescue`'d in the code of interest.
 
-* **Reason:**
 * **Discussion:** [Feature #19572]
 * **Documentation:** [TracePoint#Events](https://docs.ruby-lang.org/en/master/TracePoint.html#class-TracePoint-label-Events)
 * **Code:**
-* **Notes:**
+  ```ruby
+  TracePoint.trace(:rescue) do |tp|
+    puts "Exception rescued: #{tp.raised_exception.inspect} at #{tp.path}:#{tp.lineno}"
+  end
 
-### `Kernel#lambda` behavior change with non-lambda blocks
+  begin
+    raise "foo"
+  rescue => e
+  end
+  # Prints: "Exception rescued: #<RuntimeError: foo> at example.rb:7
+  ```
+* **Notes:** The event-specific attribute for the event is the same as for `:raise`: [#raised_exception](https://docs.ruby-lang.org/en/master/TracePoint.html#method-i-raised_exception).
 
-* **Reason:**
+### `Kernel#lambda` raises when passed `Proc` instance
+
+* **Reason:** `lambda`'s goal is to create a lambda from provided literal block; in Ruby, it is impossible to change the "lambdiness" of the block once it is created. But `lambda(&proc_instance)` never notified users of that, which was confusing.
 * **Discussion:** [Feature #19777]
-* **Documentation:**
+* **Documentation:** [Kernel#lambda](https://docs.ruby-lang.org/en/master/Kernel.html#method-i-lambda) _(no specific details are provided, though)_
 * **Code:**
+  ```ruby
+  # Intended usage:
+  l = lambda { |a, b| a + b }
+  l.lambda? #=> true
+  l.parameters #=> [[:req, :a], [:req, :b]]
+
+  # Unintended usage:
+  p = proc { |a, b| a + b }
+
+  # In Ruby 3.2 and below, it worked, but the produced value wasn't lambda:
+  l = lambda(&p)
+  l.parameters #=> [[:opt, :a], [:opt, :b]]
+  l.lambda? #=> false
+  l.object_id == p.object_id #=> true, it is just the same proc
+
+  # Ruby 3.3:
+  l = lambda(&p)
+  # in `lambda': the lambda method requires a literal block (ArgumentError)
+
+  # Despite the message about a "literal block," the method
+  # works (though has no meaningful effect) with lambda-like Proc objects
+  other_lambda = lambda { |a, b| a + b }
+  lambda(&other_lambda) #=> works
+  lambda(&:to_s) #=> works
+  lambda(&method(:puts)) #=> works
+  ```
 * **Notes:**
+  * The discussion was once [started](https://bugs.ruby-lang.org/issues/15973) from the proposal to make `lambda` change "lambiness" of a passed block, but it raises multiple issues (changing the block semantics mid-program is just one of them). In general, `lambda` as a _method_ is considered legacy, inferior to the `-> { }` lambda literal syntax, exactly due to problems like this: it looks like a regular method that receives a block, and therefore should be able accept _any_ block, but in fact it is "special" method. So in 3.0, there was a warning about `lambda(&proc_instance)`, and since 3.3, the warning finally turned into an error.
+  * There is exactly one occurrence in Ruby where block semantics _changes_ mid-flight:
 
 ### Deprecate subprocess creation with method dedicated to files