From: "zverok (Victor Shepelev)" <noreply@...>
Date: 2022-09-10T12:35:05+00:00
Subject: [ruby-core:109872] [Ruby master Feature#16122] Data: simple immutable value object
Issue #16122 has been updated by zverok (Victor Shepelev).
Pull request: https://github.com/ruby/ruby/pull/6353
Copying from its description:
Example docs rendering: [Data](https://zverok.space/ruby-rdoc/Data.html)
Design and implementation decisions made:
**1. The "define data object method is called `Data.define`**. As per [Matz](https://bugs.ruby-lang.org/issues/16122#note-51):
> `define` might be a candidate. But I still prefer shorter one (e.g. `def`), but you can try to persuade me.
There were a few quite reasonable arguments towards `define` in that ticket. To add to them, my PoV:
* I believe that nowadays (adding new APIs to the mature language), it is better to use full English words to remove confusion and increase readability;
* `def` is strongly associated in Ruby with "defining a method" and became a separate word in Rubyist's dictionary, not a "generic shortcut for 'define'"
* I believe that the "definition of the new type" (unlike the definition of a new method) is a situation where clarity is more important than saving 3 chars; and somewhat rarer.
**2. `define` accepts keyword and positional ars; they are converted to keyword args there, and checked in `initialize`**
```ruby
Measure = Data.define(:amount, :unit)
Measure.new(1, 'km') # => OK
Measure.new(amount: 1, unit: 'km') # => OK
Measure.new(1) # ArgumentError
Measure.new(amount: 1) # ArgumentError
Measure.new(1, 'km', 'h') # ArgumentError
Measure.new(amount: 1, unit: 'km', comment: 'slow') #=> ArgumentError
```
The fact that `initialize` accepts only keyword args and checks them makes it easy to define custom `initialize` with defaults, for example (it is all explicitly documented, see link above):
```ruby
Measure = Data.define(:amount, :unit) do
def initialize(amount:, unit: '-none-') = super
end
Measure[1] #=> #<data Measure amount=1, unit="-none-">
```
(This might be enough for not to invent a separate API for default values, but this discussion can be postponed.)
**3. I didn't introduce any additional APIs yet (e.g. something like `with` which was discussed).** So, the full API of the `Data` as rendered by RDoc is:
I believe it is enough for the introduction, and then the feedback might be accepted for how to make it more convenient.
**4. I wrote custom docs for `Data` class** instead of copy-pasting/editing docs for `Struct`. I have a strong belief that the approach to docs used is more appropriate:
1. For separate methods, instead of detailed documenting of every behavior quirk by spelling it in many phrases, I provided the explanation of _what_ it does logically and examples of _how_ it can/should be used.
2. For the entire class, I don't see a point in the recently introduced formal structure of "What's here" with many nested sections, at least for small classes. It sacrifices the lightweight-yet-enough explanations that can be consumed almost instantly, towards the feeling of "there is a book-worth of information to read," making the documentation user's experience more laborious.
Probably it is not a good place to discuss those approaches in general, but at least for the Data class, I believe the chosen approach is superior. If the core team believes it is not true, I think my changes can be merged and then formal docs provided by team members who consider them valuable.
----------------------------------------
Feature #16122: Data: simple immutable value object
https://bugs.ruby-lang.org/issues/16122#change-99112
* Author: zverok (Victor Shepelev)
* Status: Assigned
* Priority: Normal
* Assignee: zverok (Victor Shepelev)
----------------------------------------
**Value Object** is a useful concept, introduced by Martin Fowler ([his post](https://martinfowler.com/bliki/ValueObject.html), [Wikipedia Entry](https://en.wikipedia.org/wiki/Value_object)) with the following properties (simplifying the idea):
* representing some relatively simple data;
* immutable;
* compared by type & value;
* nicely represented.
Value objects are super-useful especially for defining APIs, their input/return values. Recently, there were some movement towards using more immutability-friendly approach in Ruby programming, leading to creating several discussions/libraries with value objects. For example, [Tom Dalling's gem](https://github.com/tomdalling/value_semantics), [Good Ruby Value object convention](https://github.com/zverok/good-value-object) (disclaimer: the latter is maintained by yours truly).
I propose to introduce **native value objects** to Ruby as a core class.
**Why not a gem?**
* I believe that concept is that simple, that nobody *will even try* to use a gem for representing it with, unless the framework/library used already provides one.
* Potentially, a lot of standard library (and probably even core) APIs could benefit from the concept.
**Why `Struct` is not enough**
Core `Struct` class is "somewhat alike" value-object, and frequently used instead of one: it is compared by value and consists of simple attributes. On the other hand, `Struct` is:
* mutable;
* collection-alike (defines `to_a` and is `Enumerable`);
* dictionary-alike (has `[]` and `.values` methods).
The above traits somehow erodes the semantics, making code less clear, especially when duck-typing is used.
For example, this code snippet shows why `to_a` is problematic:
```ruby
Result = Struct.new(:success, :content)
# Now, imagine that other code assumes `data` could be either Result, or [Result, Result, Result]
# So, ...
data = Result.new(true, 'it is awesome')
Array(data) # => expected [Result(true, 'it is awesome')], got [true, 'it is awesome']
# or...
def foo(arg1, arg2 = nil)
p arg1, arg2
end
foo(*data) # => expected [Result(true, 'it is awesome'), nil], got [true, 'it is awesome']
```
Having `[]` and `each` defined on something that is thought as "just value" can also lead to subtle bugs, when some method checks "if the received argument is collection-alike", and value object's author doesn't thought of it as a collection.
**Concrete proposal**
* Class name: `Struct::Value`: lot of Rubyists are used to have `Struct` as a quick "something-like-value" drop-in, so alternative, more strict implementation, being part of `Struct` API, will be quite discoverable; *alternative: just `Value`*
* Class API is copying `Struct`s one (most of the time -- even reuses the implementation), with the following exceptions *(note: the immutability is **not** the only difference)*:
* Not `Enumerable`;
* Immutable;
* Doesn't think of itself as "almost hash" (doesn't have `to_a`, `values` and `[]` methods);
* Can have empty members list (fun fact: `Struct.new('Foo')` creating member-less `Struct::Foo`, is allowed, but `Struct.new()` is not) to allow usage patterns like:
```ruby
class MyService
Success = Struct::Value.new(:results)
NotFound = Struct::Value.new
end
```
`NotFound` here, unlike, say, `Object.new.freeze` (another pattern for creating "empty typed value object"), has nice inspect `#<value NotFound>`, and created consistently with the `Success`, making the code more readable. And if it will evolve to have some attributes, the code change would be easy.
**Patch is provided**
[Sample rendered RDoc documentation](https://zverok.github.io/ruby-rdoc/Struct-Value.html)
---Files--------------------------------
struct_value.patch (18.6 KB)
--
https://bugs.ruby-lang.org/
Unsubscribe: <mailto:ruby-core-request@ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>