README.md in supa-0.2.3 vs README.md in supa-0.3.0
- old
+ new
@@ -1,13 +1,13 @@
# Supa
Ruby object → JSON serialization.
-[](https://travis-ci.org/dasnotme/supa)
-[](https://codeclimate.com/github/dasnotme/supa)
-[](https://codeclimate.com/github/dasnotme/supa/coverage)
-[](https://codeclimate.com/github/dasnotme/supa)
+[](https://travis-ci.org/distribusion/supa)
+ [](https://codeclimate.com/repos/587387071c36ea7203000e0d/feed)
+ [](https://codeclimate.com/repos/587387071c36ea7203000e0d/coverage)
+ [](https://codeclimate.com/repos/587387071c36ea7203000e0d/feed)
## Introduction
## Installation
@@ -22,11 +22,11 @@
```shell
bundle install
```
Or install it yourself as
-```
+```shell
gem install supa
```
## Usage
@@ -47,79 +47,81 @@
attr_accessor :id, :text
end
```
```ruby
-module Supa
- class ArticleRepresenter
- include Supa::Representable
+class ArticleRepresenter
+ include Supa::Representable
- define do
- namespace :jsonapi do
- virtual :version, 1.1, modifier: :to_s
- end
+ define do
+ namespace :jsonapi do
+ virtual :version, getter: 1.1, modifier: :to_s
+ end
- namespace :meta do
- attribute :locale, :language, exec_context: :representer
- end
+ namespace :meta do
+ attribute :locale, getter: :language, exec_context: :representer
+ attribute :date, exec_context: :representer
+ end
- namespace :data do
- attribute :id
- virtual :type, 'articles'
+ namespace :data do
+ attribute :id
+ virtual :type, getter: 'articles'
- namespace :attributes do
- attribute :title
- attribute :text
- end
+ namespace :attributes do
+ attribute :title
+ attribute :text
+ end
- namespace :relationships do
- object :author do
- namespace :data do
- attribute :id
- virtual :type, 'authors'
- end
+ namespace :relationships do
+ object :author do
+ namespace :data do
+ attribute :id
+ virtual :type, getter: 'authors'
end
+ end
- namespace :comments do
- collection :data, :comments do
- attribute :id
- virtual :type, 'comments'
- end
+ namespace :comments do
+ collection :data, getter: :comments do
+ attribute :id
+ virtual :type, getter: 'comments'
end
end
end
+ end
- collection :included, :author do
- attribute :id
- virtual :type, 'authors'
+ collection :included, getter: :author do
+ attribute :id
+ virtual :type, getter: 'authors'
- namespace :attributes do
- attribute :first_name
- attribute :last_name
- end
+ namespace :attributes do
+ attribute :first_name
+ attribute :last_name
end
+ end
- append :included, :comments do
- attribute :id
- virtual :type, 'comments'
+ append :included, getter: :comments do
+ attribute :id
+ virtual :type, getter: 'comments'
- namespace :attributes do
- attribute :text
- end
+ namespace :attributes do
+ attribute :text
end
end
+ end
- def to_s(value)
- value.to_s
- end
+ def to_s(value)
+ value.to_s
+ end
- def language
- 'en'
- end
+ def language
+ 'en'
end
-end
+ def date
+ Date.today.iso8601
+ end
+end
```
```ruby
ArticleRepresenter.new(Article.new).to_json
```
@@ -128,11 +130,12 @@
{
"jsonapi": {
"version": "1.1"
},
"meta": {
- "locale": "en"
+ "locale": "en",
+ "date": "2050-01-01"
},
"data": {
"id": "7aa15512-1f9d-4a86-98ad-4bb0aae487a2",
"type": "articles",
"attributes": {
@@ -186,13 +189,96 @@
]
}
```
### `attribute`
+Attributes will be retrieved from correspondingly named instance methods unless a getter is defined:
+```ruby
+class ExampleRepresenter
+ include Supa::Representable
+ define do
+ attribute :name
+ end
+end
+
+ExampleRepresenter.new(OpenStruct.new(name: 'Heidi')).to_hash
+
+ #=> {
+ #=> name: 'Heidi'
+ #=> }
+```
+A getter can take several forms:
+
+### 1. Method name
+```ruby
+class ExampleRepresenter
+ include Supa::Representable
+
+ define do
+ attribute :name, getter: :full_name
+ end
+end
+
+class Person
+ attr_accessor :full_name
+end
+
+example = Person.new
+example.full_name = 'Heidi Shepherd'
+
+ExampleRepresenter.new(example).to_hash
+
+ #=> {
+ #=> name: 'Heidi Shepherd'
+ #=> }
+```
+The lookup order is to first check the object instance and then the representer for a matching method.
+
+###2. Hash key
+```ruby
+class ExampleRepresenter
+ include Supa::Representable
+
+ define do
+ attribute :name, getter: 'full_name'
+ end
+end
+
+example = {
+ 'full_name' => 'Heidi Shepherd'
+}
+
+ExampleRepresenter.new(example).to_hash
+
+ #=> {
+ #=> name: 'Heidi Shepherd'
+ #=> }
+
+```
+
### `virtual`
+Virtual is an attribute that doesn't exist in representing object and defind as `string`.
+```ruby
+class ExampleRepresenter
+ include Supa::Representable
+
+ define do
+ attribute :version, getter: 1.0
+ attribute :type, getter: 'documentation'
+ end
+end
+
+ExampleRepresenter.new({}).to_hash
+
+{
+ version: 1.0,
+ type: 'documentation',
+}
+```
+
### `namespace`
### `object`
### `collection`
@@ -221,12 +307,11 @@
bin/console
```
## Contributing
-Bug reports and pull requests are welcome on GitHub at https://github.com/dasnotme/supa. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/distribusion/supa.
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
-
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-