README.md in alba-3.0.1 vs README.md in alba-3.0.2
- old
+ new
@@ -4,21 +4,24 @@
[](https://github.com/okuramasafumi/alba/actions/workflows/main.yml)
[](https://codecov.io/gh/okuramasafumi/alba)
[](https://codeclimate.com/github/okuramasafumi/alba/maintainability)
+[](code_of_conduct.md)
# Alba
Alba is a JSON serializer for Ruby, JRuby, and TruffleRuby.
## IMPORTANT NOTICE
Both version `3.0.0` and `2.4.2` contain important bug fix.
-However, version `3.0.0` has some bugs (see https://github.com/okuramasafumi/alba/issues/342).
+~~However, version `3.0.0` has some bugs (see https://github.com/okuramasafumi/alba/issues/342).
Until they get fixed, it's highly recommended to upgrade to version `2.4.2`.
-Dependabot and similar tools might create an automated Pull Request to upgrade to `3.0.0`, so it might be required to upgrade to `2.4.2` manually.
+Dependabot and similar tools might create an automated Pull Request to upgrade to `3.0.0`, so it might be required to upgrade to `2.4.2` manually.~~
+Version `3.0.1` has been released so Ruby 3 users should upgrade to `3.0.1`.
+For Ruby 2 users, it's highly recommended to upgrade to `2.4.2`.
Sorry for the inconvenience.
## TL;DR
Alba allows you to do something like below.
@@ -287,75 +290,80 @@
attribute :some_other_name, &:name
end
```
-#### Prefer methods on resource
+#### Methods conflict
-By default, Alba prefers methods on the object to methods on the resource. This means if you have a following situation:
+Consider following code:
```ruby
-class User
- attr_accessor :id, :name, :email
-
- def initialize(id, name, email)
- @id = id
- @name = name
- @email = email
+class Foo
+ def bar
+ 'This is Foo'
end
-
- def name_with_email
- 'dummy!'
- end
end
-class UserResource
+class FooResource
include Alba::Resource
- root_key :user, :users # Later is for plural
+ attributes :bar
- attributes :id, :name, :name_with_email
-
- # Same method exists in `User` class!
- # This is not called
- def name_with_email(user)
- "#{user.name}: #{user.email}"
+ def bar
+ 'This is FooResource'
end
end
-user = User.new(1, 'Masafumi OKURA', 'masafumi@example.com')
-UserResource.new(user).serialize
-# => '{"user":{"id":1,"name":"Masafumi OKURA","name_with_email":"dummy!"}}'
+FooResource.new(Foo.new).serialize
```
-You can see that `name_with_email` is now `dummy!` from `User#name_with_email`. You cna change this behavior by using `prefer_resource_method!` DSL in a resource class:
+By default, Alba create the JSON as `'{"bar":"This is FooResource"}'`. This means Alba calls a method on a Resource class and doesn't call a method on a target object. This rule is applied to methods that are explicitly defined on Resource class, so methods that Resource class inherits from `Object` class such as `format` are ignored.
```ruby
-# With the same `User` class
+class Foo
+ def format
+ 'This is Foo'
+ end
+end
-class UserResource
+class FooResource
include Alba::Resource
- prefer_resource_method! # This line is important
+ attributes :bar
- root_key :user, :users # Later is for plural
+ # Here, `format` method is available
+end
- attributes :id, :name, :name_with_email
+FooResource.new(Foo.new).serialize
+# => '{"bar":"This is Foo"}'
+```
- # Same method exists in `User` class!
- # But now this is called!
- def name_with_email(user)
- "#{user.name}: #{user.email}"
+If you'd like Alba to call methods on a target object, use `prefer_object_method!` like below.
+
+```ruby
+class Foo
+ def bar
+ 'This is Foo'
end
end
-user = User.new(1, 'Masafumi OKURA', 'masafumi@example.com')
-UserResource.new(user).serialize
-# => '{"user":{"id":1,"name":"Masafumi OKURA","name_with_email":"Masafumi OKURA: masafumi@example.com"}}'
-```
+class FooResource
+ include Alba::Resource
-The next major version of Alba will change this default behavior to prefer resource methods. In case you want to preserve current behavior, there's `prefer_object_method!` DSL, which does that.
+ prefer_object_method! # <- important
+ attributes :bar
+
+ # This is not called
+ def bar
+ 'This is FooResource'
+ end
+end
+
+FooResource.new(Foo.new).serialize
+# => '{"bar":"This is Foo"}'
+```
+
#### Params
You can pass a Hash to the resource for internal use. It can be used as "flags" to control attribute content.
```ruby