u-attributes 2.2.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31b9f3d0195fc8b0f865279a79a54bd9beb8b0644d3f1b4371b6aa4163264024
-  data.tar.gz: '048e8c549d655980eee398e8ae445a7eb6900143f98c8e04449d5e2c82f0c9e6'
+  metadata.gz: c330847c820a244e35afcd702510d791a72822677ad97a4050b37dc0a9653a00
+  data.tar.gz: 66f7e86e1c1579f64d39e77c54eac7fab03551dbbc8fd6ce02438fab817c0939
 SHA512:
-  metadata.gz: 3a776e02b0708d566156ce8adc7d0ad5813a7c752f8f19615eeea734b46ee34995d69a8cab263ed1e1ffbba64140eee4a630ff18fdcb6cf54cd5fb0a404d6fe8
-  data.tar.gz: 4e7869905c50b2f0ea288f404900c3c2b645ca3c8cad6404c2d8aa8913a0ad87874b43288c8f408e1a23252d9ab114fa8664a6a21914f71c2ffbf4ee04bb3d68
+  metadata.gz: d06af39a1601f4ba9496e5daec023cb13d1944f0ab2b986320a365788df2208fecf1122c73d023c669647fb3f826eca15d0f4bf132872c6b84459bd13c8037ce
+  data.tar.gz: 16bd3897ce372901db54506761dffbc3ba42a72e6700fabc0db83fedad6ab8eaf9bb69f1d98c26e4c0eee809311d51926431807fde187af3b80a6cdba2d73f78

data/.travis.sh

@@ -1,31 +1,45 @@
 #!/bin/bash
 
-bundle exec rake test
+RUBY_V=$(ruby -v)
 
-ACTIVEMODEL_VERSION='3.2' bundle update
-ACTIVEMODEL_VERSION='3.2' bundle exec rake test
+function run_with_bundler {
+  rm Gemfile.lock
 
-ACTIVEMODEL_VERSION='4.0' bundle update
-ACTIVEMODEL_VERSION='4.0' bundle exec rake test
+  if [ ! -z "$1" ]; then
+    bundle_cmd="bundle _$1_"
+  else
+    bundle_cmd="bundle"
+  fi
 
-ACTIVEMODEL_VERSION='4.1' bundle update
-ACTIVEMODEL_VERSION='4.1' bundle exec rake test
+  eval "$2 $bundle_cmd update"
+  eval "$2 $bundle_cmd exec rake test"
+}
 
-ACTIVEMODEL_VERSION='4.2' bundle update
-ACTIVEMODEL_VERSION='4.2' bundle exec rake test
+function run_with_am_version_and_bundler {
+  run_with_bundler "$2" "ACTIVEMODEL_VERSION=$1"
+}
 
-ACTIVEMODEL_VERSION='5.0' bundle update
-ACTIVEMODEL_VERSION='5.0' bundle exec rake test
+RUBY_2_2345="ruby 2.[2345]."
 
-ACTIVEMODEL_VERSION='5.1' bundle update
-ACTIVEMODEL_VERSION='5.1' bundle exec rake test
+if [[ $RUBY_V =~ $RUBY_2_2345 ]]; then
+  run_with_bundler "$BUNDLER_V1"
 
-if [[ ! $ruby_v =~ '2.2.0' ]]; then
-  ACTIVEMODEL_VERSION='5.2' bundle update
-  ACTIVEMODEL_VERSION='5.2' bundle exec rake test
+  run_with_am_version_and_bundler "3.2" "$BUNDLER_V1"
+  run_with_am_version_and_bundler "4.0" "$BUNDLER_V1"
+  run_with_am_version_and_bundler "4.1" "$BUNDLER_V1"
+  run_with_am_version_and_bundler "4.2" "$BUNDLER_V1"
+  run_with_am_version_and_bundler "5.0" "$BUNDLER_V1"
+  run_with_am_version_and_bundler "5.1" "$BUNDLER_V1"
+  run_with_am_version_and_bundler "5.2" "$BUNDLER_V1"
 fi
 
-if [[ $ruby_v =~ '2.5.' ]] || [[ $ruby_v =~ '2.6.' ]] || [[ $ruby_v =~ '2.7.' ]]; then
-  ACTIVEMODEL_VERSION='6.0' bundle update
-  ACTIVEMODEL_VERSION='6.0' bundle exec rake test
+RUBY_2_567="ruby 2.[567]."
+RUBY_3_x_x="ruby 3.0."
+
+if [[ $RUBY_V =~ $RUBY_2_567 ]] || [[ $RUBY_V =~ $RUBY_3_x_x ]]; then
+  gem install bundler -v ">= 2" --no-doc
+
+  run_with_bundler
+  run_with_am_version_and_bundler "6.0"
+  run_with_am_version_and_bundler "6.1"
 fi

data/.travis.yml

@@ -1,5 +1,10 @@
 language: ruby
 
+cache:
+  bundler: true
+  directories:
+    - /home/travis/.rvm/
+
 rvm:
 - 2.2.2
 - 2.3.0
@@ -7,22 +12,22 @@ rvm:
 - 2.5.0
 - 2.6.0
 - 2.7.0
-- truffleruby-head
+- 3.0.0
 
-cache: bundler
+env:
+  - BUNDLER_V1="1.17.3"
 
 before_install:
-  - gem uninstall -v '>= 2' -i $(rvm gemdir)@global -ax bundler || true
-  - gem install bundler -v '< 2'
+  - gem install bundler -v "$BUNDLER_V1"
 
 install: bundle install --jobs=3 --retry=3
 
 before_script:
   - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
   - chmod +x ./cc-test-reporter
-  - './cc-test-reporter before-build'
+  - "./cc-test-reporter before-build"
 
-script: './.travis.sh'
+script: "./.travis.sh"
 
 after_success:
-  - './cc-test-reporter after-build -t simplecov'
+  - "./cc-test-reporter after-build -t simplecov"

data/Gemfile

@@ -2,7 +2,7 @@ source 'https://rubygems.org'
 
 gem 'u-case', '~> 4.0'
 
-activemodel_version = ENV.fetch('ACTIVEMODEL_VERSION', '6.1')
+activemodel_version = ENV['ACTIVEMODEL_VERSION']
 
 activemodel = case activemodel_version
               when '3.2' then '3.2.22'
@@ -11,26 +11,31 @@ activemodel = case activemodel_version
               when '4.2' then '4.2.11'
               when '5.0' then '5.0.7'
               when '5.1' then '5.1.7'
-              when '5.2' then '5.2.3'
-              when '6.0' then '6.0.0'
+              when '5.2' then '5.2.4'
+              when '6.0' then '6.0.3.4'
+              when '6.1' then '6.1.2'
               end
 
-if activemodel_version < '6.1'
-  gem 'activemodel', activemodel, require: false
-  gem 'activesupport', activemodel, require: false
-end
-
 simplecov_version =
   case RUBY_VERSION
-  when /\A2.[23]/ then '~> 0.17.1'
+  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'
+  if activemodel_version
+    gem 'activesupport', activemodel, require: false
+    gem 'activemodel', activemodel, require: false
+    gem 'minitest', activemodel_version < '4.1' ? '~> 4.2' : '~> 5.0'
+  else
+    gem 'minitest', '~> 5.0'
+  end
+
   gem 'simplecov', simplecov_version, require: false
 end
 
+gem 'rake', '~> 13.0'
+
 # Specify your gem's dependencies in u-attributes.gemspec
 gemspec

data/README.md

@@ -1,12 +1,12 @@
 <p align="center">
   <img src="./assets/u-attributes_logo_v1.png" alt='Create "immutable" objects. No setters, just getters!'>
 
-  <p align="center"><i>Create "immutable" objects. No setters, just getters!</i></p>
+  <p align="center"><i>Create "immutable" objects with no setters, just getters.</i></p>
   <br>
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/ruby-2.2+-ruby.svg?colorA=99004d&colorB=cc0066" alt="Ruby">
+  <img src="https://img.shields.io/badge/ruby->%3D%202.2.0-ruby.svg?colorA=99004d&colorB=cc0066" alt="Ruby">
 
   <a href="https://rubygems.org/gems/u-attributes">
     <img alt="Gem" src="https://img.shields.io/gem/v/u-attributes.svg?style=flat-square">
@@ -25,8 +25,16 @@
   </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.
+This gem allows you to define "immutable" objects, when using it your objects will only have getters and no setters.
+So, if you change [[1](#with_attribute)] [[2](#with_attributes)] an attribute of the object, you’ll have a new object instance. That is, you transform the object instead of modifying it.
+
+## Documentation <!-- omit in toc -->
+
+Version    | Documentation
+---------- | -------------
+unreleased | https://github.com/serradura/u-case/blob/main/README.md
+2.7.0      | https://github.com/serradura/u-case/blob/v2.x/README.md
+1.2.0      | https://github.com/serradura/u-case/blob/v1.x/README.md
 
 # Table of contents <!-- omit in toc -->
 - [Installation](#installation)
@@ -47,6 +55,15 @@ So, if you change [[1](#with_attribute)] [[2](#with_attributes)] some object att
   - [Is it possible to inherit the attributes?](#is-it-possible-to-inherit-the-attributes)
     - [`.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)
   - [Picking specific features](#picking-specific-features)
     - [`Micro::Attributes.with`](#microattributeswith)
@@ -58,6 +75,7 @@ So, if you change [[1](#with_attribute)] [[2](#with_attributes)] some object att
     - [Diff extension](#diff-extension)
     - [Initialize extension](#initialize-extension)
       - [Strict mode](#strict-mode)
+    - [Keys as symbol extension](#keys-as-symbol-extension)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -75,7 +93,8 @@ gem 'u-attributes'
 
 | u-attributes   | branch  | ruby     |  activemodel  |
 | -------------- | ------- | -------- | ------------- |
-| 2.2.0          | main    | >= 2.2.0 | >= 3.2, < 6.1 |
+| unreleased     | main    | >= 2.2.0 | >= 3.2, < 7   |
+| 2.7.0          | v2.x    | >= 2.2.0 | >= 3.2, < 7   |
 | 1.2.0          | v1.x    | >= 2.2.0 | >= 3.2, < 6.1 |
 
 > **Note**: The activemodel is an optional dependency, this module [can be enabled](#activemodelvalidation-extension) to validate the attributes.
@@ -419,69 +438,155 @@ beta_person.age  # 0
 
 ## 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() #
-#---------------#
+### `.attributes`
 
-Person.attributes # ['name', 'age']
+Listing all the class attributes.
 
-#---------------#
-# .attribute?() #
-#---------------#
+```ruby
+Person.attributes # ["age", "first_name", "last_name"]
+```
 
-Person.attribute?(:name)  # true
-Person.attribute?('name') # true
-Person.attribute?('foo') # false
-Person.attribute?(:foo)  # false
+### `.attribute?()`
 
-# ---
+Checking the existence of some attribute.
 
-person = Person.new(age: 20)
+```ruby
+Person.attribute?(:first_name)  # true
+Person.attribute?('first_name') # true
+
+Person.attribute?('foo') # false
+Person.attribute?(:foo)  # false
+```
 
-#---------------------#
-# #defined_attributes #
-#---------------------#
+### `#attribute?()`
 
-person.defined_attributes # ['name', 'age']
+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`/`:symbol` or `String`/`:string` to transform the attributes hash keys.
+
+```ruby
+person1 = Person.new(age: 20)
+person2 = Person.new(first_name: 'Rodrigo', last_name: 'Rodrigues')
+
+person1.attributes(keys_as: Symbol) # {:age=>20, :first_name=>"John", :last_name=>"Doe"}
+person2.attributes(keys_as: String) # {"age"=>nil, "first_name"=>"Rodrigo", "last_name"=>"Rodrigues"}
+
+person1.attributes(keys_as: :symbol) # {:age=>20, :first_name=>"John", :last_name=>"Doe"}
+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.
 
-#---------------#
-# #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)
 
-person.attributes                   # {'age'=>20, 'name'=>'John Doe'}
-Person.new(name: 'John').attributes # {'age'=>nil, 'name'=>'John'}
+person.attributes(without: :age)               # {"first_name"=>"John", "last_name"=>"Doe"}
+person.attributes(without: [:age, :last_name]) # {"first_name"=>"John"}
 
-#---------------------#
-# #attributes(*names) #
-#---------------------#
+person.attributes(with: [:name], without: [:first_name, :last_name]) # {"age"=>20, "name"=>"John Doe"}
 
-# Slices the attributes to include only the given keys.
-# Returns a hash containing the given keys (in their types).
+# To achieves the same output of the previous example, use the attribute names to slice only them.
 
-person.attributes(:age)             # {age: 20}
-person.attributes(:age, :name)      # {age: 20, name: 'John Doe'}
-person.attributes('age', 'name')    # {'age'=>20, 'name'=>'John Doe'}
+person.attributes(:age, with: [: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"}
+```
+
+### `#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-)
@@ -499,24 +604,30 @@ But, if you desire except one or more features, use the `Micro::Attributes.witho
 ```ruby
 Micro::Attributes.with(:initialize)
 
-Micro::Attributes.with(initialize: :strict)
+Micro::Attributes.with(:initialize, :keys_as_symbol)
+
+Micro::Attributes.with(:keys_as_symbol, initialize: :strict)
 
 Micro::Attributes.with(:diff, :initialize)
 
 Micro::Attributes.with(:diff, initialize: :strict)
 
+Micro::Attributes.with(:diff, :keys_as_symbol, initialize: :strict)
+
 Micro::Attributes.with(:activemodel_validations)
 
 Micro::Attributes.with(:activemodel_validations, :diff)
 
 Micro::Attributes.with(:activemodel_validations, :diff, initialize: :strict)
+
+Micro::Attributes.with(:activemodel_validations, :diff, :keys_as_symbol, initialize: :strict)
 ```
 
 The method `Micro::Attributes.with()` will raise an exception if no arguments/features were declared.
 
 ```ruby
 class Job
-  include Micro::Attributes.with() # ArgumentError (Invalid feature name! Available options: :activemodel_validations, :diff, :initialize)
+  include Micro::Attributes.with() # ArgumentError (Invalid feature name! Available options: :accept, :activemodel_validations, :diff, :initialize, :keys_as_symbol)
 end
 ```
 
@@ -525,15 +636,19 @@ end
 Picking *except* one or more features
 
 ```ruby
-Micro::Attributes.without(:diff) # will load :activemodel_validations and initialize: :strict
+Micro::Attributes.without(:diff) # will load :activemodel_validations, :keys_as_symbol and initialize: :strict
 
-Micro::Attributes.without(initialize: :strict) # will load :activemodel_validations and :diff
+Micro::Attributes.without(initialize: :strict) # will load :activemodel_validations, :diff and :keys_as_symbol
 ```
 
 ## Picking all the features
 
 ```ruby
 Micro::Attributes.with_all_features
+
+# This method returns the same of:
+
+Micro::Attributes.with(:activemodel_validations, :diff, :keys_as_symbol, initialize: :strict)
 ```
 
 [⬆️ Back to Top](#table-of-contents-)
@@ -725,6 +840,40 @@ job.state # 'sleeping'
 
 [⬆️ Back to Top](#table-of-contents-)
 
+### Keys as symbol extension
+
+Disables the indifferent access requiring the declaration/usage of the attributes as symbols.
+
+The advantage of this extension over the default behavior is because it avoids an unnecessary allocation in memory of strings. All the keys are transformed into strings in the indifferent access mode, but, with this extension, this typecasting will be avoided. So, it has a better performance and reduces the usage of memory/Garbage collector, but gives for you the responsibility to always use symbols to set/access the attributes.
+
+```ruby
+class Job
+  include Micro::Attributes.with(:initialize, :keys_as_symbol)
+
+  attribute :id
+  attribute :state, default: 'sleeping'
+end
+
+job = Job.new(id: 1)
+
+job.attributes # {:id => 1, :state => "sleeping"}
+
+job.attribute?(:id) # true
+job.attribute?('id') # false
+
+job.attribute(:id) # 1
+job.attribute('id') # nil
+
+job.attribute!(:id) # 1
+job.attribute!('id') # NameError (undefined attribute `id)
+```
+
+As you could see in the previous example only symbols will work to do something with the attributes.
+
+This extension also changes the `diff extension` making everything (arguments, outputs) working only with symbols.
+
+[⬆️ 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.