u-attributes 2.0.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac1586077d89b91d2e851ce3f59819d0c474bc809fe9d64eff5d5627bd78a967
-  data.tar.gz: 7246180e49313f3b9038e3bfdd858356dce65a80c7c94aa6173a15afbea9ab90
+  metadata.gz: 2f90839cb67a0501e1ef44a5f06a324103063c87e929549377f885504bda5d8a
+  data.tar.gz: fd77058f7e514644a8363d460ad33ad76885648e32b5d9b02e22e592ffbf3ffe
 SHA512:
-  metadata.gz: 1ce2864d28e95139a1fc3e3a08ca08ea2c771eec936b5ff21567fb3f0bae792bd406a4b905c7c5346b7f53de3972a6f01ce4629e50e786935186ae6f93614956
-  data.tar.gz: 28076be013bc9038497297186994d23df2b39b16fb46b2a6c82d59520f3f5de84a3c1f1f89196a6dc073677f0fa339a707e1a2cb10591e9aabfc19dab80036b6
+  metadata.gz: 27401e952c4f5611ec5443df546d4c2c67f0af7aa40606a8e0f128ae37dc167747d0ba4c94008d993d65c886d4e1d66c6ef3472556ecfa353903779f51b4fe23
+  data.tar.gz: d05025bd7442681e14fa8f970fb166898ec9af4a344b8912e10c57f559830833bebe05ccacea85332ef9c88437adabc60152967f8b0b38d01f38f1cc6a7c1257

data/.travis.yml

@@ -1,7 +1,5 @@
 language: ruby
 
-sudo: false
-
 rvm:
 - 2.2.2
 - 2.3.0
@@ -9,6 +7,7 @@ rvm:
 - 2.5.0
 - 2.6.0
 - 2.7.0
+- truffleruby-head
 
 cache: bundler
 

data/Gemfile

@@ -1,5 +1,7 @@
 source 'https://rubygems.org'
 
+gem 'u-case', '~> 4.0'
+
 activemodel_version = ENV.fetch('ACTIVEMODEL_VERSION', '6.1')
 
 activemodel = case activemodel_version
@@ -18,9 +20,16 @@ if activemodel_version < '6.1'
   gem 'activesupport', activemodel, require: false
 end
 
+simplecov_version =
+  case RUBY_VERSION
+  when /\A2.[23]/ then '~> 0.17.1'
+  when /\A2.4/ then '~> 0.18.5'
+  else '~> 0.19'
+  end
+
 group :test do
   gem 'minitest', activemodel_version < '4.1' ? '~> 4.2' : '~> 5.0'
-  gem 'simplecov', require: false
+  gem 'simplecov', simplecov_version, require: false
 end
 
 # Specify your gem's dependencies in u-attributes.gemspec

data/README.md

@@ -1,21 +1,41 @@
-![Ruby](https://img.shields.io/badge/ruby-2.2+-ruby.svg?colorA=99004d&colorB=cc0066)
-[![Gem](https://img.shields.io/gem/v/u-attributes.svg?style=flat-square)](https://rubygems.org/gems/u-attributes)
-[![Build Status](https://travis-ci.com/serradura/u-attributes.svg?branch=master)](https://travis-ci.com/serradura/u-attributes)
-[![Maintainability](https://api.codeclimate.com/v1/badges/b562e6b877a9edf4dbf6/maintainability)](https://codeclimate.com/github/serradura/u-attributes/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/b562e6b877a9edf4dbf6/test_coverage)](https://codeclimate.com/github/serradura/u-attributes/test_coverage)
+<p align="center">
+  <img src="./assets/u-attributes_logo_v1.png" alt='Create "immutable" objects. No setters, just getters!'>
 
-μ-attributes (Micro::Attributes) <!-- omit in toc -->
-================================
+  <p align="center"><i>Create "immutable" objects. No setters, just getters!</i></p>
+  <br>
+</p>
 
-This gem allows defining read-only attributes, that is, your objects will have only getters to access their attributes data.
+<p align="center">
+  <img src="https://img.shields.io/badge/ruby-2.2+-ruby.svg?colorA=99004d&colorB=cc0066" alt="Ruby">
 
-## Table of contents <!-- omit in toc -->
-- [Required Ruby version](#required-ruby-version)
+  <a href="https://rubygems.org/gems/u-attributes">
+    <img alt="Gem" src="https://img.shields.io/gem/v/u-attributes.svg?style=flat-square">
+  </a>
+
+  <a href="https://travis-ci.com/serradura/u-attributes">
+    <img alt="Build Status" src="https://travis-ci.com/serradura/u-attributes.svg?branch=main">
+  </a>
+
+  <a href="https://codeclimate.com/github/serradura/u-attributes/maintainability">
+    <img alt="Maintainability" src="https://api.codeclimate.com/v1/badges/b562e6b877a9edf4dbf6/maintainability">
+  </a>
+
+  <a href="https://codeclimate.com/github/serradura/u-attributes/test_coverage">
+    <img alt="Test Coverage" src="https://api.codeclimate.com/v1/badges/b562e6b877a9edf4dbf6/test_coverage">
+  </a>
+</p>
+
+This gem allows you to define "immutable" objects, and your objects will have only getters and no setters.
+So, if you change [[1](#with_attribute)] [[2](#with_attributes)] some object attribute, you will have a new object instance. That is, you transform the object instead of modifying it.
+
+# Table of contents <!-- omit in toc -->
 - [Installation](#installation)
 - [Compatibility](#compatibility)
 - [Usage](#usage)
   - [How to define attributes?](#how-to-define-attributes)
     - [`Micro::Attributes#attributes=`](#microattributesattributes)
+      - [How to extract attributes from an object or hash?](#how-to-extract-attributes-from-an-object-or-hash)
+      - [Is it possible to define an attribute as required?](#is-it-possible-to-define-an-attribute-as-required)
     - [`Micro::Attributes#attribute`](#microattributesattribute)
     - [`Micro::Attributes#attribute!`](#microattributesattribute-1)
   - [How to define multiple attributes?](#how-to-define-multiple-attributes)
@@ -23,26 +43,36 @@ This gem allows defining read-only attributes, that is, your objects will have o
     - [`#with_attribute()`](#with_attribute)
     - [`#with_attributes()`](#with_attributes)
   - [Defining default values to the attributes](#defining-default-values-to-the-attributes)
-  - [Strict initializer](#strict-initializer)
+  - [The strict initializer](#the-strict-initializer)
   - [Is it possible to inherit the attributes?](#is-it-possible-to-inherit-the-attributes)
-    - [.attribute!()](#attribute)
+    - [`.attribute!()`](#attribute)
   - [How to query the attributes?](#how-to-query-the-attributes)
+    - [`.attributes`](#attributes)
+    - [`.attribute?()`](#attribute-1)
+    - [`#attribute?()`](#attribute-2)
+    - [`#attributes()`](#attributes-1)
+      - [`#attributes(keys_as:)`](#attributeskeys_as)
+      - [`#attributes(*names)`](#attributesnames)
+      - [`#attributes([names])`](#attributesnames-1)
+      - [`#attributes(with:, without)`](#attributeswith-without)
+    - [`#defined_attributes`](#defined_attributes)
 - [Built-in extensions](#built-in-extensions)
-  - [ActiveModel::Validations extension](#activemodelvalidations-extension)
-    - [Attribute options](#attribute-options)
-  - [Diff extension](#diff-extension)
-  - [Initialize extension](#initialize-extension)
-  - [Strict initialize mode](#strict-initialize-mode)
+  - [Picking specific features](#picking-specific-features)
+    - [`Micro::Attributes.with`](#microattributeswith)
+    - [`Micro::Attributes.without`](#microattributeswithout)
+  - [Picking all the features](#picking-all-the-features)
+  - [Extensions](#extensions)
+    - [`ActiveModel::Validation` extension](#activemodelvalidation-extension)
+      - [`.attribute()` options](#attribute-options)
+    - [Diff extension](#diff-extension)
+    - [Initialize extension](#initialize-extension)
+      - [Strict mode](#strict-mode)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
 - [Code of Conduct](#code-of-conduct)
 
-## Required Ruby version
-
-> \>= 2.2.0
-
-## Installation
+# Installation
 
 Add this line to your application's Gemfile and `bundle install`:
 
@@ -50,25 +80,29 @@ Add this line to your application's Gemfile and `bundle install`:
 gem 'u-attributes'
 ```
 
-## Compatibility
+# Compatibility
 
 | u-attributes   | branch  | ruby     |  activemodel  |
 | -------------- | ------- | -------- | ------------- |
-| 2.0.0          | master  | >= 2.2.0 | >= 3.2, < 6.1 |
+| 2.3.0          | main    | >= 2.2.0 | >= 3.2, < 6.1 |
 | 1.2.0          | v1.x    | >= 2.2.0 | >= 3.2, < 6.1 |
 
-## Usage
+> **Note**: The activemodel is an optional dependency, this module [can be enabled](#activemodelvalidation-extension) to validate the attributes.
 
-### How to define attributes?
+[⬆️ Back to Top](#table-of-contents-)
 
-```ruby
-# By default you must to define the class constructor.
+# Usage
+
+## How to define attributes?
 
+By default, you must define the class constructor.
+
+```ruby
 class Person
   include Micro::Attributes
 
-  attribute :name
   attribute :age
+  attribute :name
 
   def initialize(name: 'John Doe', age:)
     @name, @age = name, age
@@ -77,8 +111,8 @@ end
 
 person = Person.new(age: 21)
 
-person.name # John Doe
 person.age  # 21
+person.name # John Doe
 
 # By design the attributes are always exposed as reader methods (getters).
 # If you try to call a setter you will see a NoMethodError.
@@ -87,7 +121,9 @@ person.age  # 21
 # NoMethodError (undefined method `name=' for #<Person:0x0000... @name='John Doe', @age=21>)
 ```
 
-#### `Micro::Attributes#attributes=`
+[⬆️ Back to Top](#table-of-contents-)
+
+### `Micro::Attributes#attributes=`
 
 This is a protected method to make easier the assignment in a constructor. e.g.
 
@@ -95,8 +131,8 @@ This is a protected method to make easier the assignment in a constructor. e.g.
 class Person
   include Micro::Attributes
 
-  attribute :name, default: 'John Doe'
   attribute :age
+  attribute :name, default: 'John Doe'
 
   def initialize(options)
     self.attributes = options
@@ -105,19 +141,81 @@ end
 
 person = Person.new(age: 20)
 
+person.age  # 20
 person.name # John Doe
+```
+
+#### How to extract attributes from an object or hash?
+
+You can extract attributes using the `extract_attributes_from` method, it will try to fetch attributes from the
+object using either the `object[attribute_key]` accessor or the reader method `object.attribute_key`.
+
+```ruby
+class Person
+  include Micro::Attributes
+
+  attribute :age
+  attribute :name, default: 'John Doe'
+
+  def initialize(user:)
+    self.attributes = extract_attributes_from(user)
+  end
+end
+
+# extracting from an object
+
+class User
+  attr_accessor :age, :name
+end
+
+user = User.new
+user.age = 20
+
+person = Person.new(user: user)
+
 person.age  # 20
+person.name # John Doe
+
+# extracting from a hash
+
+another_person = Person.new(user: { age: 55, name: 'Julia Not Roberts' })
+
+another_person.age  # 55
+another_person.name # Julia Not Roberts
+```
+
+#### Is it possible to define an attribute as required?
+
+You only need to use the `required: true` option.
+
+But to this work, you need to assign the attributes using the [`#attributes=`](#microattributesattributes) method or the extensions: [initialize](#initialize-extension), [activemodel_validations](#activemodelvalidation-extension).
+
+```ruby
+class Person
+  include Micro::Attributes
+
+  attribute :age
+  attribute :name, required: true
+
+  def initialize(attributes)
+    self.attributes = attributes
+  end
+end
+
+Person.new(age: 32) # ArgumentError (missing keyword: :name)
 ```
 
-#### `Micro::Attributes#attribute`
+[⬆️ Back to Top](#table-of-contents-)
+
+### `Micro::Attributes#attribute`
 
 Use this method with a valid attribute name to get its value.
 
 ```ruby
 person = Person.new(age: 20)
 
-person.attribute(:name) # John Doe
 person.attribute('age') # 20
+person.attribute(:name) # John Doe
 person.attribute('foo') # nil
 ```
 
@@ -129,17 +227,21 @@ person.attribute('age') { |value| puts value } # 20
 person.attribute('foo') { |value| puts value } # !! Nothing happened, because of the attribute doesn't exist.
 ```
 
-#### `Micro::Attributes#attribute!`
+[⬆️ Back to Top](#table-of-contents-)
+
+### `Micro::Attributes#attribute!`
 
 Works like the `#attribute` method, but it will raise an exception when the attribute doesn't exist.
 
 ```ruby
-person.attribute!('foo')                        # NameError (undefined attribute `foo)
+person.attribute!('foo')                   # NameError (undefined attribute `foo)
 
 person.attribute!('foo') { |value| value } # NameError (undefined attribute `foo)
 ```
 
-### How to define multiple attributes?
+[⬆️ Back to Top](#table-of-contents-)
+
+## How to define multiple attributes?
 
 Use `.attributes` with a list of attribute names.
 
@@ -162,7 +264,9 @@ person.age  # 32
 
 > **Note:** This method can't define default values. To do this, use the `#attribute()` method.
 
-### `Micro::Attributes.with(:initialize)`
+[⬆️ Back to Top](#table-of-contents-)
+
+## `Micro::Attributes.with(:initialize)`
 
 Use `Micro::Attributes.with(:initialize)` to define a constructor to assign the attributes. e.g.
 
@@ -170,47 +274,49 @@ Use `Micro::Attributes.with(:initialize)` to define a constructor to assign the
 class Person
   include Micro::Attributes.with(:initialize)
 
-  attribute :age
+  attribute :age, required: true
   attribute :name, default: 'John Doe'
 end
 
 person = Person.new(age: 18)
 
-person.name # John Doe
 person.age  # 18
+person.name # John Doe
 ```
 
 This extension enables two methods for your objects.
 The `#with_attribute()` and `#with_attributes()`.
 
-#### `#with_attribute()`
+### `#with_attribute()`
 
 ```ruby
 another_person = person.with_attribute(:age, 21)
 
-another_person.name           # John Doe
 another_person.age            # 21
+another_person.name           # John Doe
 another_person.equal?(person) # false
 ```
 
-#### `#with_attributes()`
+### `#with_attributes()`
 
 Use it to assign multiple attributes
 ```ruby
 other_person = person.with_attributes(name: 'Serradura', age: 32)
 
-other_person.name           # Serradura
 other_person.age            # 32
+other_person.name           # Serradura
 other_person.equal?(person) # false
 ```
 
 If you pass a value different of a Hash, a Kind::Error will be raised.
 
 ```ruby
-Person.new(1) # Kind::Error (1 must be a Hash)
+Person.new(1) # Kind::Error (1 expected to be a kind of Hash)
 ```
 
-### Defining default values to the attributes
+[⬆️ Back to Top](#table-of-contents-)
+
+## Defining default values to the attributes
 
 To do this, you only need make use of the `default:` keyword. e.g.
 
@@ -223,10 +329,9 @@ class Person
 end
 ```
 
-There are 3 different strategies to define default values.
+There are two different strategies to define default values.
 1. Pass a regular object, like in the previous example.
 2. Pass a `proc`/`lambda`, and if it has an argument you will receive the attribute value to do something before assign it.
-3. Pass a **callable**, that is, a `class`, `module` or `instance` which responds to the `call` method. The behavior will be like the previous item (`proc`/`lambda`).
 
 ```ruby
 class Person
@@ -237,9 +342,13 @@ class Person
 end
 ```
 
-### Strict initializer
+[⬆️ Back to Top](#table-of-contents-)
+
+## The strict initializer
+
+Use `.with(initialize: :strict)` to forbids an instantiation without all the attribute keywords.
 
-Use `.with(initialize: :strict)` to forbids an instantiation without all the attribute keywords. e.g.
+In other words, it is equivalent to you define all the attributes using the [`required: true` option](#is-it-possible-to-define-an-attribute-as-required).
 
 ```ruby
 class StrictPerson
@@ -257,13 +366,15 @@ An attribute with a default value can be omitted.
 ``` ruby
 person_without_age = StrictPerson.new(age: nil)
 
-person_without_age.name # 'John Doe'
 person_without_age.age  # nil
+person_without_age.name # 'John Doe'
 ```
 
 > **Note:** Except for this validation the `.with(initialize: :strict)` method will works in the same ways of `.with(:initialize)`.
 
-### Is it possible to inherit the attributes?
+[⬆️ Back to Top](#table-of-contents-)
+
+## Is it possible to inherit the attributes?
 
 Yes. e.g.
 
@@ -286,7 +397,9 @@ instance.respond_to?(:age) # true
 instance.respond_to?(:foo) # true
 ```
 
-#### .attribute!()
+[⬆️ Back to Top](#table-of-contents-)
+
+### `.attribute!()`
 
 This method allows us to redefine the attributes default data that was defined in the parent class. e.g.
 
@@ -311,137 +424,217 @@ beta_person.name # 'Beta'
 beta_person.age  # 0
 ```
 
-### How to query the attributes?
+[⬆️ Back to Top](#table-of-contents-)
+
+## How to query the attributes?
+
+All of the methods that will be explained can be used with any of the built-in extensions.
+
+**PS:** We will use the class below for all of the next examples.
 
 ```ruby
 class Person
   include Micro::Attributes
 
   attribute :age
-  attribute :name, default: 'John Doe'
+  attribute :first_name, default: 'John'
+  attribute :last_name, default: 'Doe'
 
   def initialize(options)
     self.attributes = options
   end
+
+  def name
+    "#{first_name} #{last_name}"
+  end
 end
+```
+
+### `.attributes`
+
+Listing all the class attributes.
+
+```ruby
+Person.attributes # ["age", "first_name", "last_name"]
+```
 
-#---------------#
-# .attributes() #
-#---------------#
+### `.attribute?()`
 
-Person.attributes # ['name', 'age']
+Checking the existence of some attribute.
 
-#---------------#
-# .attribute?() #
-#---------------#
+```ruby
+Person.attribute?(:first_name)  # true
+Person.attribute?('first_name') # true
 
-Person.attribute?(:name)  # true
-Person.attribute?('name') # true
 Person.attribute?('foo') # false
 Person.attribute?(:foo)  # false
+```
 
-# ---
+### `#attribute?()`
 
-person = Person.new(age: 20)
+Checking the existence of some attribute in an instance.
 
-#---------------#
-# #attribute?() #
-#---------------#
+```ruby
+person = Person.new(age: 20)
 
 person.attribute?(:name)  # true
 person.attribute?('name') # true
+
 person.attribute?('foo') # false
 person.attribute?(:foo)  # false
+```
+
+### `#attributes()`
+
+Fetching all the attributes with their values.
+
+```ruby
+person1 = Person.new(age: 20)
+person1.attributes # {"age"=>20, "first_name"=>"John", "last_name"=>"Doe"}
+
+person2 = Person.new(first_name: 'Rodrigo', last_name: 'Rodrigues')
+person2.attributes # {"age"=>nil, "first_name"=>"Rodrigo", "last_name"=>"Rodrigues"}
+```
+
+#### `#attributes(keys_as:)`
+
+Use the `keys_as:` option with `Symbol` or `String` to transform the attributes hash keys.
+
+```ruby
+person1 = Person.new(age: 20)
+person1.attributes(keys_as: Symbol) # {:age=>20, :first_name=>"John", :last_name=>"Doe"}
+
+person2 = Person.new(first_name: 'Rodrigo', last_name: 'Rodrigues')
+person2.attributes(keys_as: String) # {"age"=>nil, "first_name"=>"Rodrigo", "last_name"=>"Rodrigues"}
+```
+
+#### `#attributes(*names)`
+
+Slices the attributes to include only the given keys (in their types).
+
+```ruby
+person = Person.new(age: 20)
+
+person.attributes(:age)               # {:age => 20}
+person.attributes(:age, :first_name)  # {:age => 20, :first_name => "John"}
+person.attributes('age', 'last_name') # {"age" => 20, "last_name" => "Doe"}
+
+person.attributes(:age, 'last_name') # {:age => 20, "last_name" => "Doe"}
+
+# You could also use the keys_as: option to ensure the same type for all of the hash keys.
+
+person.attributes(:age, 'last_name', keys_as: Symbol) # {:age=>20, :last_name=>"Doe"}
+```
+
+#### `#attributes([names])`
+
+As the previous example, this methods accepts a list of keys to slice the attributes.
+
+```ruby
+person = Person.new(age: 20)
+
+person.attributes([:age])               # {:age => 20}
+person.attributes([:age, :first_name])  # {:age => 20, :first_name => "John"}
+person.attributes(['age', 'last_name']) # {"age" => 20, "last_name" => "Doe"}
+
+person.attributes([:age, 'last_name']) # {:age => 20, "last_name" => "Doe"}
+
+# You could also use the keys_as: option to ensure the same type for all of the hash keys.
+
+person.attributes([:age, 'last_name'], keys_as: Symbol) # {:age=>20, :last_name=>"Doe"}
+```
+
+#### `#attributes(with:, without)`
+
+Use the `with:` option to include any method value of the instance inside of the hash, and,
+you can use the `without:` option to exclude one or more attribute keys from the final hash.
+
+```ruby
+person = Person.new(age: 20)
 
-#---------------#
-# #attributes() #
-#---------------#
+person.attributes(without: :age)               # {"first_name"=>"John", "last_name"=>"Doe"}
+person.attributes(without: [:age, :last_name]) # {"first_name"=>"John"}
 
-person.attributes                   # {'age'=>20, 'name'=>'John Doe'}
-Person.new(name: 'John').attributes # {'age'=>nil, 'name'=>'John'}
+person.attributes(with: [:name], without: [:first_name, :last_name]) # {"age"=>20, "name"=>"John Doe"}
 
-#---------------------#
-# #attributes(*names) #
-#---------------------#
+# To achieves the same output of the previous example, use the attribute names to slice only them.
 
-# Slices the attributes to include only the given keys.
-# Returns a hash containing the given keys (in their types).
+person.attributes(:age, with: [:name]) # {:age=>20, "name"=>"John Doe"}
 
-person.attributes(:age)             # {age: 20}
-person.attributes(:age, :name)      # {age: 20, name: 'John Doe'}
-person.attributes('age', 'name')    # {'age'=>20, 'name'=>'John Doe'}
+# You could also use the keys_as: option to ensure the same type for all of the hash keys.
+
+person.attributes(:age, with: [:name], keys_as: Symbol) # {:age=>20, :name=>"John Doe"}
 ```
 
-## Built-in extensions
+### `#defined_attributes`
+
+Listing all the available attributes.
+
+```ruby
+person = Person.new(age: 20)
+
+person.defined_attributes # ["age", "first_name", "last_name"]
+```
+
+[⬆️ Back to Top](#table-of-contents-)
+
+# Built-in extensions
 
 You can use the method `Micro::Attributes.with()` to combine and require only the features that better fit your needs.
 
 But, if you desire except one or more features, use the `Micro::Attributes.without()` method.
 
+## Picking specific features
+
+### `Micro::Attributes.with`
+
 ```ruby
-#===========================#
-# Loading specific features #
-#===========================#
+Micro::Attributes.with(:initialize)
 
-class Job
-  include Micro::Attributes.with(:diff)
+Micro::Attributes.with(initialize: :strict)
 
-  attribute :id
-  attribute :state, default: 'sleeping'
+Micro::Attributes.with(:diff, :initialize)
 
-  def initialize(options)
-    self.attributes = options
-  end
-end
+Micro::Attributes.with(:diff, initialize: :strict)
 
-#======================#
-# Loading all features #
-#         ---          #
-#======================#
+Micro::Attributes.with(:activemodel_validations)
 
-class Job
-  include Micro::Attributes.with_all_features
+Micro::Attributes.with(:activemodel_validations, :diff)
 
-  attribute :id
-  attribute :state, default: 'sleeping'
-end
+Micro::Attributes.with(:activemodel_validations, :diff, initialize: :strict)
+```
 
-#----------------------------------------------------------------------------#
-# Using the .with() method alias and adding the strict initialize extension. #
-#----------------------------------------------------------------------------#
-class Job
-  include Micro::Attributes.with(:diff, initialize: :strict)
+The method `Micro::Attributes.with()` will raise an exception if no arguments/features were declared.
 
-  attribute :id
-  attribute :state, default: 'sleeping'
+```ruby
+class Job
+  include Micro::Attributes.with() # ArgumentError (Invalid feature name! Available options: :activemodel_validations, :diff, :initialize)
 end
+```
 
-# Note:
-# The method `Micro::Attributes.with()` will raise an exception if no arguments/features were declared.
-#
-# class Job
-#   include Micro::Attributes.with() # ArgumentError (Invalid feature name! Available options: diff, initialize, activemodel_validations)
-# end
+### `Micro::Attributes.without`
 
-#=====================================#
-# Loading except one or more features #
-#         -----                       #
-#=====================================#
+Picking *except* one or more features
 
-class Job
-  include Micro::Attributes.without(:diff)
+```ruby
+Micro::Attributes.without(:diff) # will load :activemodel_validations and initialize: :strict
 
-  attribute :id
-  attribute :state, default: 'sleeping'
-end
+Micro::Attributes.without(initialize: :strict) # will load :activemodel_validations and :diff
+```
 
-# Note:
-# The method `Micro::Attributes.without()` returns `Micro::Attributes` if all features extensions were used.
+## Picking all the features
+
+```ruby
+Micro::Attributes.with_all_features
 ```
 
-### ActiveModel::Validations extension
+[⬆️ Back to Top](#table-of-contents-)
+
+## Extensions
 
-If your application uses ActiveModel as a dependency (like a regular Rails app). You will be enabled to use the `actimodel_validations` extension.
+### `ActiveModel::Validation` extension
+
+If your application uses ActiveModel as a dependency (like a regular Rails app). You will be enabled to use the `activemodel_validations` extension.
 
 ```ruby
 class Job
@@ -461,7 +654,7 @@ job.id    # 1
 job.state # 'sleeping'
 ```
 
-#### Attribute options
+#### `.attribute()` options
 
 You can use the `validate` or `validates` options to define your attributes. e.g.
 
@@ -472,7 +665,7 @@ class Job
   attribute :id, validates: { presence: true }
   attribute :state, validate: :must_be_a_filled_string
 
-  def must_be_a_string
+  def must_be_a_filled_string
     return if state.is_a?(String) && state.present?
 
     errors.add(:state, 'must be a filled string')
@@ -480,6 +673,8 @@ class Job
 end
 ```
 
+[⬆️ Back to Top](#table-of-contents-)
+
 ### Diff extension
 
 Provides a way to track changes in your object attributes.
@@ -529,6 +724,8 @@ job_changes.changed?(:state, from: 'sleeping', to: 'running') # true
 job_changes.differences # {'state'=> {'from' => 'sleeping', 'to' => 'running'}}
 ```
 
+[⬆️ Back to Top](#table-of-contents-)
+
 ### Initialize extension
 
 1. Creates a constructor to assign the attributes.
@@ -578,7 +775,9 @@ other_job.state       # killed
 other_job.equal?(job) # false
 ```
 
-### Strict initialize mode
+[⬆️ Back to Top](#table-of-contents-)
+
+#### Strict mode
 
 1. Creates a constructor to assign the attributes.
 2. Adds methods to build new instances when some data was assigned.
@@ -616,20 +815,22 @@ job.state # 'sleeping'
 
 > **Note**: This extension works like the `initialize` extension. So, look at its section to understand all of the other features.
 
-## Development
+[⬆️ Back to Top](#table-of-contents-)
+
+# Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-## Contributing
+# Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/serradura/u-attributes. 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
+# License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-## Code of Conduct
+# Code of Conduct
 
-Everyone interacting in the Micro::Attributes project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/serradura/u-attributes/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Micro::Attributes project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/serradura/u-attributes/blob/main/CODE_OF_CONDUCT.md).

data/lib/micro/attributes.rb

@@ -14,7 +14,8 @@ module Micro
       base.extend(::Micro::Attributes.const_get(:Macros))
 
       base.class_eval do
-        private_class_method :__attributes, :__attribute_set, :__attribute_reader
+        private_class_method :__attributes, :__attribute_reader
+        private_class_method :__attribute_assign, :__attributes_data_to_assign
       end
 
       def base.inherited(subclass)
@@ -54,48 +55,92 @@ module Micro
       raise NameError, "undefined attribute `#{name}"
     end
 
+    def defined_attributes
+      @defined_attributes ||= self.class.attributes
+    end
+
     def attributes(*names)
       return __attributes if names.empty?
 
-      names.each_with_object({}) do |name, memo|
-        memo[name] = attribute(name) if attribute?(name)
+      options = names.last.is_a?(Hash) ? names.pop : Kind::Empty::HASH
+
+      names.flatten!
+
+      without_option = Array(options.fetch(:without, Kind::Empty::ARRAY))
+
+      keys = names.empty? ? defined_attributes - without_option.map(&:to_s) : names - without_option
+
+      data = keys.each_with_object({}) { |key, memo| memo[key] = attribute(key) if attribute?(key) }
+
+      with_option = Array(options.fetch(:with, Kind::Empty::ARRAY))
+
+      unless with_option.empty?
+        extra = with_option.each_with_object({}) { |key, memo| memo[key.to_s] = public_send(key) }
+
+        data.merge!(extra)
       end
+
+      Utils::Hashes.keys_as(options[:keys_as], data)
     end
 
     protected
 
       def attributes=(arg)
-        hash = Utils.stringify_hash_keys(arg)
+        hash = Utils::Hashes.stringify_keys(arg)
+
+        __attributes_missing!(hash)
 
-        __attributes_set(hash, self.class.__attributes_data__)
+        __attributes_assign(hash)
       end
 
     private
 
+      def extract_attributes_from(other)
+        Utils::ExtractAttribute.from(other, keys: defined_attributes)
+      end
+
       def __attributes
         @__attributes ||= {}
       end
 
-      def __attribute_set(name, value)
-        __attributes[name] = instance_variable_set("@#{name}", value) if attribute?(name)
+      FetchValueToAssign = -> (value, default) do
+        if default.is_a?(Proc)
+          default.arity > 0 ? default.call(value) : default.call
+        else
+          value.nil? ? default : value
+        end
       end
 
-      def __attributes_set(hash, att_data)
-        att_data.each do |key, default|
-          value = hash[key]
-
-          final_value =
-            if default.respond_to?(:call)
-              callable = default.is_a?(Proc) ? default : default.method(:call)
-              callable.arity > 0 ? callable.call(value) : callable.call
-            else
-              value || default
-            end
-
-          __attribute_set(key, final_value)
+      def __attributes_assign(hash)
+        self.class.__attributes_data__.each do |name, default|
+          __attribute_assign(name, FetchValueToAssign.(hash[name], default)) if attribute?(name)
         end
 
         __attributes.freeze
       end
+
+      def __attribute_assign(name, value)
+        __attributes[name] = instance_variable_set("@#{name}", value)
+      end
+
+      MISSING_KEYWORD = 'missing keyword'.freeze
+      MISSING_KEYWORDS = 'missing keywords'.freeze
+
+      def __attributes_missing!(hash)
+        required_keys = self.class.__attributes_required__
+
+        return if required_keys.empty?
+
+        missing_keys = required_keys.map { |name| ":#{name}" if !hash.key?(name) }
+        missing_keys.compact!
+
+        return if missing_keys.empty?
+
+        label = missing_keys.size == 1 ? MISSING_KEYWORD : MISSING_KEYWORDS
+
+        raise ArgumentError, "#{label}: #{missing_keys.join(', ')}"
+      end
+
+      private_constant :FetchValueToAssign, :MISSING_KEYWORD, :MISSING_KEYWORDS
   end
 end

data/lib/micro/attributes/features/activemodel_validations.rb

@@ -14,11 +14,11 @@ module Micro::Attributes
       end
 
       module ClassMethods
-        def __call_after_attribute_set__(attr_name, options)
+        def __call_after_attribute_assign__(attr_name, options)
           validate, validates = options.values_at(:validate, :validates)
 
           self.validate(validate) if validate
-          self.validates(attr_name, validates) if validates
+          self.validates(attr_name, validates.dup) if validates
         end
       end
 

data/lib/micro/attributes/features/initialize/strict.rb

@@ -4,35 +4,15 @@ module Micro::Attributes
   module Features
     module Initialize
       module Strict
-        MISSING_KEYWORD = 'missing keyword'.freeze
-        MISSING_KEYWORDS = 'missing keywords'.freeze
-
-        protected def attributes=(arg)
-          arg_hash = Utils.stringify_hash_keys(arg)
-          att_data = self.class.__attributes_data__
-
-          attributes_missing!(ref: att_data, arg: arg_hash)
-
-          __attributes_set(arg_hash, att_data)
-        end
-
-        private def attributes_missing!(ref:, arg:)
-          missing_keys = attributes_missing(ref, arg)
-
-          return if missing_keys.empty?
-
-          label = missing_keys.size == 1 ? MISSING_KEYWORD : MISSING_KEYWORDS
-
-          raise ArgumentError, "#{label}: #{missing_keys.join(', ')}"
-        end
-
-        private def attributes_missing(ref, arg)
-          ref.each_with_object([]) do |(key, val), memo|
-            memo << ":#{key}" if val.nil? && !arg.has_key?(key)
+        module ClassMethods
+          def attributes_are_all_required?
+            true
           end
         end
 
-        private_constant :MISSING_KEYWORD, :MISSING_KEYWORDS
+        def self.included(base)
+          base.send(:extend, ClassMethods)
+        end
       end
     end
   end

data/lib/micro/attributes/macros.rb

@@ -3,10 +3,33 @@
 module Micro
   module Attributes
     module Macros
+      def attributes_are_all_required?
+        false
+      end
+
+      # NOTE: can't be renamed! It is used by u-case v4.
       def __attributes_data__
         @__attributes_data__ ||= {}
       end
 
+      def __attributes_required__
+        @__attributes_required__ ||= Set.new
+      end
+
+      def __attributes_required_add(name, is_required, hasnt_default)
+        if is_required || (attributes_are_all_required? && hasnt_default)
+          __attributes_required__.add(name)
+        end
+
+        nil
+      end
+
+      def __attributes_data_to_assign(name, options)
+        hasnt_default = !options.key?(:default)
+
+        hasnt_default ? __attributes_required_add(name, options[:required], hasnt_default) : options[:default]
+      end
+
       def __attributes
         @__attributes ||= Set.new
       end
@@ -17,20 +40,24 @@ module Micro
         attr_reader(name)
       end
 
-      def __attribute_set(key, can_overwrite, options)
+      def __attribute_assign(key, can_overwrite, options)
         name = key.to_s
         has_attribute = attribute?(name)
 
         __attribute_reader(name) unless has_attribute
-        __attributes_data__[name] = options[:default] if can_overwrite || !has_attribute
 
-        __call_after_attribute_set__(name, options)
+        __attributes_data__[name] = __attributes_data_to_assign(name, options) if can_overwrite || !has_attribute
+
+        __call_after_attribute_assign__(name, options)
       end
 
-      def __call_after_attribute_set__(attr_name, options); end
+      def __call_after_attribute_assign__(attr_name, options); end
 
+      # NOTE: can't be renamed! It is used by u-case v4.
       def __attributes_set_after_inherit__(arg)
-        arg.each { |key, val| __attribute_set(key, true, default: val) }
+        arg.each do |key, val|
+          __attribute_assign(key, true, val ? { default: val } : {})
+        end
       end
 
       def attribute?(name)
@@ -38,27 +65,32 @@ module Micro
       end
 
       def attribute(name, options = Kind::Empty::HASH)
-        __attribute_set(name, false, options)
+        __attribute_assign(name, false, options)
       end
 
       def attributes(*args)
         return __attributes.to_a if args.empty?
 
         args.flatten!
+
+        options =
+          args.size > 1 && args.last.is_a?(::Hash) ? args.pop : Kind::Empty::HASH
+
         args.each do |arg|
           if arg.is_a?(String) || arg.is_a?(Symbol)
-            __attribute_set(arg, false, Kind::Empty::HASH)
+            __attribute_assign(arg, false, options)
           else
             raise Kind::Error.new('String/Symbol'.freeze, arg)
           end
         end
       end
 
+      # NOTE: can't be renamed! It is used by u-case v4.
       module ForSubclasses
         WRONG_NUMBER_OF_ARGS = 'wrong number of arguments (given 0, expected 1 or more)'.freeze
 
         def attribute!(name, options = Kind::Empty::HASH)
-          __attribute_set(name, true, options)
+          __attribute_assign(name, true, options)
         end
 
         private_constant :WRONG_NUMBER_OF_ARGS

data/lib/micro/attributes/utils.rb

@@ -1,17 +1,52 @@
 # frozen_string_literal: true
 
-module Micro
-  module Attributes
-    module Utils
-      def self.stringify_hash_keys(arg)
+module Micro::Attributes
+  module Utils
+    module Hashes
+      def self.stringify_keys(arg)
         hash = Kind::Of.(::Hash, arg)
 
         return hash if hash.empty?
+        return hash.transform_keys(&:to_s) if hash.respond_to?(:transform_keys)
 
-        if hash.respond_to?(:transform_keys)
-          hash.transform_keys { |key| key.to_s }
-        else
-          hash.each_with_object({}) { |(key, val), memo| memo[key.to_s] = val }
+        hash.each_with_object({}) { |(key, val), memo| memo[key.to_s] = val }
+      end
+
+      def self.symbolize_keys(arg)
+        hash = Kind::Of.(::Hash, arg)
+
+        return hash if hash.empty?
+        return hash.transform_keys(&:to_sym) if hash.respond_to?(:transform_keys)
+
+        hash.each_with_object({}) { |(key, val), memo| memo[key.to_sym] = val }
+      end
+
+      def self.keys_as(type, hash)
+        return Kind::Of.(::Hash, hash) unless type
+
+        return symbolize_keys(hash) if type == Symbol
+        return stringify_keys(hash) if type == String
+
+        raise ArgumentError, 'first argument must be the class String or Symbol'.freeze
+      end
+
+      def self.get(hash, key)
+        value = hash[key.to_s]
+
+        value.nil? ? hash[key.to_sym] : value
+      end
+    end
+
+    module ExtractAttribute
+      def self.call(object, key:)
+        return object.public_send(key) if object.respond_to?(key)
+
+        Hashes.get(object, key) if object.respond_to?(:[])
+      end
+
+      def self.from(object, keys:)
+        Kind::Of.(::Array, keys).each_with_object({}) do |key, memo|
+          memo[key] = call(object, key: key)
         end
       end
     end

data/lib/micro/attributes/version.rb

@@ -2,6 +2,6 @@
 
 module Micro
   module Attributes
-    VERSION = '2.0.0'.freeze
+    VERSION = '2.3.0'.freeze
   end
 end

data/lib/micro/attributes/with.rb

@@ -27,7 +27,7 @@ module Micro
 
       module ActiveModelValidations
         def self.included(base)
-          base.send(:include, ::Micro::Attributes)
+          base.send(:include, Initialize)
           base.send(:include, ::Micro::Attributes::Features::ActiveModelValidations)
         end
       end

data/u-attributes.gemspec

@@ -9,8 +9,11 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Rodrigo Serradura']
   spec.email         = ['rodrigo.serradura@gmail.com']
 
-  spec.summary       = %q{Define read-only attributes}
-  spec.description   = %q{This gem allows defining read-only attributes, that is, your objects will have only getters to access their attributes data.}
+  spec.summary       = %q{Create "immutable" objects. No setters, just getters!}
+  spec.description   =
+    "This gem allows you to define \"immutable\" objects, and your objects will have only getters and no setters. "\
+    "So, if you change some object attribute, you will have a new object instance. " \
+    "That is, you transform the object instead of modifying it."
   spec.homepage      = 'https://github.com/serradura/u-attributes'
   spec.license       = 'MIT'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: u-attributes
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Rodrigo Serradura
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-08-20 00:00:00.000000000 Z
+date: 2020-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: kind
@@ -58,8 +58,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: This gem allows defining read-only attributes, that is, your objects
-  will have only getters to access their attributes data.
+description: This gem allows you to define "immutable" objects, and your objects will
+  have only getters and no setters. So, if you change some object attribute, you will
+  have a new object instance. That is, you transform the object instead of modifying
+  it.
 email:
 - rodrigo.serradura@gmail.com
 executables: []
@@ -74,6 +76,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- assets/u-attributes_logo_v1.png
 - bin/console
 - bin/setup
 - lib/micro/attributes.rb
@@ -112,5 +115,5 @@ requirements: []
 rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
-summary: Define read-only attributes
+summary: Create "immutable" objects. No setters, just getters!
 test_files: []