mruby-object-ext: add README.md

The document is written by Google Jules.

mrbgems/mruby-object-ext/README.md

@@ -0,0 +1,144 @@
+# mruby-object-ext
+
+This mrbgem provides several extension methods to core objects in mruby, enhancing their functionality and providing useful utilities for common programming patterns.
+
+## Core Extension Methods
+
+This gem extends core mruby objects with the following methods:
+
+### `Kernel#yield_self` (aliased as `then`)
+
+Yields the receiver (self) to the given block and returns the result of the block. This is useful for chaining operations in a readable way.
+
+**Signature:**
+
+```ruby
+obj.yield_self {|current_obj| ... } > an_object
+obj.then       {|current_obj| ... } -> an_object
+```
+
+**Example:**
+
+```ruby
+result = "hello"
+  .yield_self {|s| s.upcase }
+  .then       {|s| s + " WORLD" }
+
+puts result #=> "HELLO WORLD"
+
+# Another example with a different data type
+(1..5)
+  .yield_self {|range| range.to_a }
+  .then       {|arr| arr.select(&:even?) }
+  .then       {|evens| evens.map {|n| n * n } }
+  .then       {|squares| puts squares.inspect } #=> [4, 16]
+```
+
+### `Kernel#tap`
+
+Yields the receiver (self) to the given block and then returns the receiver itself. This method is primarily used for "tapping into" a method chain to perform operations on intermediate results without affecting the final result of the chain.
+
+**Signature:**
+
+```ruby
+obj.tap {|current_obj| ... } -> obj
+```
+
+**Example:**
+
+```ruby
+(1..10)
+  .to_a
+  .tap {|arr| puts "Array: #{arr.inspect}" }
+  .select(&:even?)
+  .tap {|evens| puts "Evens: #{evens.inspect}" }
+  .map {|n| n * n }
+  .tap {|squares| puts "Squares: #{squares.inspect}" }
+# Output:
+# Array: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+# Evens: [2, 4, 6, 8, 10]
+# Squares: [4, 16, 36, 64, 100]
+```
+
+### `Kernel#itself`
+
+Returns the receiver (self). While simple, it can be useful in certain chaining or meta-programming scenarios.
+
+**Signature:**
+
+```ruby
+obj.itself -> obj
+```
+
+**Example:**
+
+```ruby
+string = "my string"
+puts string.itself.object_id == string.object_id #=> true
+
+# Can be useful with methods expecting a callable
+data = { a: 1, b: 2 }
+transformed_data = data.transform_values(&:itself) # No change if values are already what you want
+puts transformed_data #=> {:a=>1, :b=>2} (in mruby hash output format)
+```
+
+### `BasicObject#instance_exec`
+
+Executes the given block within the context of the receiver (obj). This means that inside the block, `self` is set to `obj`, giving the code access to `obj`'s instance variables and private methods. Arguments passed to `instance_exec` are passed as block parameters.
+
+**Signature:**
+
+```ruby
+obj.instance_exec(arg...) {|var...| block } -> result_of_block
+```
+
+**Example:**
+
+```ruby
+class MyClass
+  def initialize(value)
+    @secret = value
+  end
+
+  def reveal_secret(multiplier, &block)
+    # self here is MyClass instance
+    instance_exec(multiplier, &block)
+  end
+end
+
+instance = MyClass.new(10)
+result = instance.reveal_secret(5) {|m| @secret * m }
+puts result #=> 50
+
+# Example without a class context
+num = 42
+num.instance_exec("Number is: ") {|prefix| puts prefix + self.to_s } #=> Number is: 42
+```
+
+## `NilClass` Extensions
+
+This gem also adds convenient type conversion methods to `NilClass`:
+
+- **`nil.to_a`**: Returns an empty Array (`[]`).
+
+  ```ruby
+  p nil.to_a #=> []
+  ```
+
+- **`nil.to_f`**: Returns `0.0`.
+
+  ```ruby
+  p nil.to_f #=> 0.0
+  ```
+
+- **`nil.to_h`**: Returns an empty Hash (`{}`).
+
+  ```ruby
+  p nil.to_h #=> {}
+  ```
+
+- **`nil.to_i`**: Returns `0`.
+
+  ```ruby
+  p nil.to_i #=> 0
+  ```