smart_initializer 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84aa6ce59c1c73432c01015a595c6a20c2e11344d2d6464aa63920c288f3b51f
-  data.tar.gz: '0819287ddbd9cfc21fac709a848205230036dd2b724df4568ed90b36bbd0316e'
+  metadata.gz: e16ae20c546597ce7c44382a790934260b44b1ebff59a51c7c7eb366205d969f
+  data.tar.gz: 14af5a449ae56ecf8b38d22c3ea0957f4896070556fec3c280a4b265e78f63de
 SHA512:
-  metadata.gz: e6b1f6664ae3e519b4fe516e565b959987f459d145d0f5de4a7d26e8b9d32ed103567eb11d7d050ef1b3d7ad2fa05e430223060f7638552dfe24edd3d8999644
-  data.tar.gz: 7ee572ea83d433095f1fd3a27a127543eb22fbbafde515e052e6d1a3360914c828a8dd983f8659501a7fbca08499cec11a34a18e4c43ac9702acd39af5235663
+  metadata.gz: cecc3bc1e93570d2c8cb0cc11c1b409c24d6b401a9a8225de4676a10915c7e08a1bf869315650f9ddf66c7b5dc4602e96d2a0717a83289b6fec79cb795d5dde9
+  data.tar.gz: 6ed53102d9c016fbdad65a3f4ad2b2aec6ad567596ec3e255f33a55f979eab5180138ae496f1ff5eafae3ae71019229ea8840d9fc1608ddcbb821a6f2aeffae5

data/.rubocop.yml

@@ -5,7 +5,7 @@ inherit_gem:
     - lib/rubocop.rspec.yml
 
 AllCops:
-  TargetRubyVersion: 3.0.0
+  TargetRubyVersion: 3.1
   NewCops: enable
   Include:
     - lib/**/*.rb

data/CHANGELOG.md

@@ -1,16 +1,48 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [0.8.0] - 2021-12-04
+### Added
+- New options for option and param attributes:
+  - Support for attribute **aliasing** (`:as` parameter);
+    - supports: `option`, `param`;
+  - Support for attribute **auto-casting** (`:auto_cast` parameter);
+    - supports: `option`, `param`;
+  - Support for **mutable** attributes (`:mutable` parameter) with type-validation inside;
+    - supports: `option`, `options`, `param`, `params`;
+  - Support for **optional** attributes (`:optional` parameter);
+    - supports: `option`;
+- **SmartCore::Initializer::Configuration**:
+  - Configuration setting `strict_options` now works separately "per-class" in all configs manner
+    (each class shares the global state but has own state too)
+  - Support for per-class/global `:auto_cast` configuration;
+    - provides a global/per-class behavior for `:cast` option (`false` by default);
+- `options` declaration now supports `privacy` option;
+- `params` declaration now supports `privacy` option;
+
+### Changed
+- Drop support of **Ruby@2.4**;
+- `:default` attribute parameter now duplicates the passed value during object instantiation;
+- `:default` attribute parameter only works with `option` attribute (`param` can't have `default` parameter now);
+- Attribute values generated by `:finalize` are type-validated now too;
+- Now lambda-based `:finalize` attributes are being checked for the signature during attribute declaration;
+- Some error messages have become more readable;
+
+## Fixed
+- `send` method overlaping/rewriting: otions and params named as `send` breaks the internal
+  framework-related invocations of the attribute definitioning inside the custom object constructor
+  (this name rewrites internal Ruby's `send` method and brokes some things);
+
 ## [0.7.0] - 2021-06-23
-## Added
+### Added
 - `strict_options` config option for non-strict checking of passed options;
 
 ## [0.6.0] - 2021-06-23
-## Added
+### Added
 - Validation messages for incorrect attribute types;
 
 ## [0.5.0] - 2021-01-18
-## Changed
+### Changed
 - Updated `smart_types` dependency (`~> 0.4.0`) to guarantee **Ruby@3** compatibility;
 - Updated development dependencies;
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    smart_initializer (0.6.1)
+    smart_initializer (0.8.0)
       qonfig (~> 0.24)
       smart_engine (~> 0.11)
       smart_types (~> 0.4)
@@ -9,39 +9,39 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (6.1.2)
+    activesupport (6.1.4.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
       tzinfo (~> 2.0)
       zeitwerk (~> 2.3)
-    armitage-rubocop (1.8.1)
-      rubocop (= 1.8.1)
-      rubocop-performance (= 1.9.2)
-      rubocop-rails (= 2.9.1)
-      rubocop-rake (= 0.5.1)
-      rubocop-rspec (= 2.1.0)
+    armitage-rubocop (1.23.0.1)
+      rubocop (= 1.23.0)
+      rubocop-performance (= 1.12.0)
+      rubocop-rails (= 2.12.4)
+      rubocop-rake (= 0.6.0)
+      rubocop-rspec (= 2.6.0)
     ast (2.4.2)
     coderay (1.1.3)
-    concurrent-ruby (1.1.8)
+    concurrent-ruby (1.1.9)
     diff-lcs (1.4.4)
-    docile (1.3.5)
-    i18n (1.8.8)
+    docile (1.4.0)
+    i18n (1.8.11)
       concurrent-ruby (~> 1.0)
     method_source (1.0.0)
-    minitest (5.14.3)
-    parallel (1.20.1)
-    parser (3.0.0.0)
+    minitest (5.14.4)
+    parallel (1.21.0)
+    parser (3.0.3.1)
       ast (~> 2.4.1)
-    pry (0.14.0)
+    pry (0.14.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    qonfig (0.25.0)
+    qonfig (0.26.0)
     rack (2.2.3)
     rainbow (3.0.0)
-    rake (13.0.3)
-    regexp_parser (2.0.3)
-    rexml (3.2.4)
+    rake (13.0.6)
+    regexp_parser (2.2.0)
+    rexml (3.2.5)
     rspec (3.10.0)
       rspec-core (~> 3.10.0)
       rspec-expectations (~> 3.10.0)
@@ -54,51 +54,51 @@ GEM
     rspec-mocks (3.10.2)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
-    rspec-support (3.10.2)
-    rubocop (1.8.1)
+    rspec-support (3.10.3)
+    rubocop (1.23.0)
       parallel (~> 1.10)
       parser (>= 3.0.0.0)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml
-      rubocop-ast (>= 1.2.0, < 2.0)
+      rubocop-ast (>= 1.12.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.4.1)
-      parser (>= 2.7.1.5)
-    rubocop-performance (1.9.2)
-      rubocop (>= 0.90.0, < 2.0)
+    rubocop-ast (1.14.0)
+      parser (>= 3.0.1.1)
+    rubocop-performance (1.12.0)
+      rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
-    rubocop-rails (2.9.1)
+    rubocop-rails (2.12.4)
       activesupport (>= 4.2.0)
       rack (>= 1.1)
-      rubocop (>= 0.90.0, < 2.0)
-    rubocop-rake (0.5.1)
-      rubocop
-    rubocop-rspec (2.1.0)
+      rubocop (>= 1.7.0, < 2.0)
+    rubocop-rake (0.6.0)
       rubocop (~> 1.0)
-      rubocop-ast (>= 1.1.0)
+    rubocop-rspec (2.6.0)
+      rubocop (~> 1.19)
     ruby-progressbar (1.11.0)
     simplecov (0.21.2)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
-    simplecov_json_formatter (0.1.2)
+    simplecov_json_formatter (0.1.3)
     smart_engine (0.11.0)
-    smart_types (0.4.0)
+    smart_types (0.7.0)
       smart_engine (~> 0.11)
     tzinfo (2.0.4)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (2.0.0)
-    zeitwerk (2.4.2)
+    unicode-display_width (2.1.0)
+    zeitwerk (2.5.1)
 
 PLATFORMS
   x86_64-darwin-19
   x86_64-darwin-20
+  x86_64-darwin-21
 
 DEPENDENCIES
-  armitage-rubocop (~> 1.7)
+  armitage-rubocop (~> 1.23)
   bundler (~> 2.2)
   pry (~> 0.14)
   rake (~> 13.0)
@@ -107,4 +107,4 @@ DEPENDENCIES
   smart_initializer!
 
 BUNDLED WITH
-   2.2.19
+   2.2.31

data/README.md

@@ -1,8 +1,14 @@
-# SmartCore::Initializer · [![Gem Version](https://badge.fury.io/rb/smart_initializer.svg)](https://badge.fury.io/rb/smart_initializer)
+# SmartCore::Initializer &middot; <a target="_blank" href="https://github.com/Cado-Labs"><img src="https://github.com/Cado-Labs/cado-labs-logos/raw/main/cado_labs_badge.svg" alt="Supported by Cado Labs" style="max-width: 100%; height: 20px"></a> &middot; [![Gem Version](https://badge.fury.io/rb/smart_initializer.svg)](https://badge.fury.io/rb/smart_initializer)
 
 A simple and convenient way to declare complex constructors with a support for various commonly used type systems.
  (**in active development**).
 
+---
+
+<img src="https://github.com/Cado-Labs/cado-labs-resources/blob/main/cado_labs_supporting_rounded.svg" alt="Supported by Cado Labs" />
+
+---
+
 ## Installation
 
 ```ruby
@@ -24,9 +30,21 @@ require 'smart_core/initializer'
 ## Table of contents
 
 - [Synopsis](#synopsis)
+  - [Initialization flow](#initialization-flow)
+  - [Attribute value definition flow](#attribute-value-definition-flow-during-object-allocation-and-construction)
+  - [Constructor definition](#constructor-definition)
+    - [param](#param)
+    - [option](#option)
+    - [params](#params)
+    - [options](#options)
+    - [param and params signature](#param-and-params-signature)
+    - [option and options signature](#option-and-options-signature)
+- [Initializer integration](#initializer-integration)
+- [Basic Example](#basic-example)
 - [Access to the instance attributes](#access-to-the-instance-attributes)
 - [Configuration](#configuration)
 - [Type aliasing](#type-aliasing)
+- [Type auto-casting](#type-auto-casting)
 - [Initialization extension](#initialization-extension)
 - [Plugins](#plugins)
   - [thy-types](#plugin-thy-types)
@@ -37,51 +55,69 @@ require 'smart_core/initializer'
 
 ## Synopsis
 
-**Initialization flow**:
+#### Initialization flow
 
-1. Parameter + Option definitioning;
-2. Original #initialize invokation;
+1. Parameter + Option definitioning and initialization;
+2. Original **#initialize** invokation;
 3. Initialization extensions invokation;
 
-**Constructor definition**:
+**NOTE!**: original constructor is called after **SmarteCore::Initializer**'s constructor
+in order to guarantee the validity of the SmartCore::Initializer's functionality
+(such as `attribute overlap chek`, `instant type checking`, `value post-processing by finalize`, etc)
+
+#### Attribute value definition flow (during object allocation and construction):
+
+1. `original value`
+2. *(if defined)*: `default value` (default value is used when `original value` is not defined)
+3. *(if defined)*: `finalize`;
+
+---
+
+### Constructor definition DSL
+
+**NOTE**: last `Hash` argument will be treated as `kwarg`s;
+
+#### param
 
 - `param` - defines name-like attribute:
-  - `cast` - type-cast received value if value has invalid type;
-  - `privacy` - reader incapsulation level;
-  - `finalize` - value post-processing (receives method name or proc);
-  - `type_system` - differently chosen type system for the current attribute;
-  - (limitation) param has no `:default` option;
-- `option` - defined kwarg-like attribute:
-  - `cast` - type-cast received value if value has invalid type;
-  - `privacy` - reader incapsulation level;
-  - `finalize` - value post-processing (receives method name or proc);
-  - `default` - defalut value (if an attribute is not provided);
-  - `type_system` - differently chosen type system for the current attribute;
-- last `Hash` argument will be treated as `kwarg`s;
+  - `cast` (optional) - type-cast received value if value has invalid type;
+  - `privacy` (optional) - reader incapsulation level;
+  - `finalize` (optional) - value post-processing (receives method name or proc) (the result value type is also validate);
+  - `type_system` (optional) - differently chosen type system for the current attribute;
+  - `as`  (optional)- attribute alias (be careful with naming aliases that overlap the names of other attributes);
+  - `mutable` (optional) - generate type-validated attr_writer in addition to attr_reader (`false` by default)
+  - (**limitation**) param has no `:default` option;
 
-#### initializer integration
+#### option
 
-```ruby
-# with pre-configured type system (:smart_types, see Configuration doc)
+- `option` - defined kwarg-like attribute:
+  - `cast` (optional) - type-cast received value if value has invalid type;
+  - `privacy` (optional) - reader incapsulation level;
+  - `as` (optional) - attribute alias (be careful with naming aliases that overlap the names of other attributes);
+  - `mutable` (optional) - generate type-validated attr_writer in addition to attr_reader (`false` by default)
+  - `optional` (optional) - mark attribut as optional (you can may not initialize optional attributes,
+    their values will be initialized with `nil` or by `default:` parameter);
+  - `finalize` (optional) - value post-processing (receives method name or proc) (the result value type is also validate);
+    - expects `Proc` object or `symbol`/`string` isntance method;
+  - `default` (optional) - defalut value (if an attribute is not provided);
+    - expects `Proc` object or a simple value of any type;
+    - non-proc values will be `dup`licate during initialization;
+  - `type_system` (optional) - differently chosen type system for the current attribute;
 
-class MyStructure
-  include SmartCore::Initializer
-end
-```
+#### params
 
-```ruby
-# with manually chosen type system
+- `params` - define a series of parameters;
+  - `:mutable` (optional) - (`false` by default);
+  - `:privacy` (optional) - (`:public` by default);
 
-class MyStructure
-  include SmartCore::Initializer(type_system: :smart_types)
-end
+#### options
 
-class AnotherStructure
-  include SmartCore::Initializer(type_system: :thy_types)
-end
-```
+- `options` - define a series of options;
+  - `:mutable` (optional) - (`false` by default);
+  - `:privacy` (optional) - (`:public` by default);
 
-#### `param` signautre:
+
+#### `param` and `params` signautre:
 
 ```ruby
 param <attribute_name>,
@@ -89,10 +125,19 @@ param <attribute_name>,
       cast: false, # false by default
       privacy: :public, # :public by default
       finalize: proc { |value| value }, # no finalization by default
+      finalize: :some_method, # use this apporiach in order to finalize by `some_method(value)` instance method
+      as: :some_alias, # define attribute alias
+      mutable: true, # (false by default) generate type-validated attr_writer in addition to attr_reader
       type_system: :smart_types # used by default
 ```
 
-#### `option` signature:
+```ruby
+params <atribute_name1>, <attribute_name2>, <attribute_name3>, ...,
+       mutable: true, # generate type-validated attr_writer in addition to attr_reader (false by default);
+       privacy: :private # incapsulate all attributes as private
+```
+
+#### `option` and `options` signature:
 
 ```ruby
 option <attribute_name>,
@@ -100,11 +145,58 @@ option <attribute_name>,
        cast: false, # false by default
        privacy: :public, # :public by default
        finalize: proc { |value| value }, # no finalization by default
+       finalize: :some_method, # use this apporiach in order to finalize by `some_method(value)` instance method
        default: 123, # no default value by default
+       default: proc { 123 }, # use proc/lambda object for dynamic initialization
+       as: :some_alias, # define attribute alias
+       mutable: true, # (false by default) generate type-validated attr_writer in addition to attr_reader
+       optional: true # (false by default) mark attribute as optional (attribute will be defined with `nil` or by `default:` value)
        type_system: :smart_types # used by default
 ```
 
-Example:
+```ruby
+options <attribute_name1>, <attribute_name2>, <attribute_name3>, ...,
+        mutable: true, # generate type-validated attr_writer in addition to attr_reader (false by default);
+        privacy: :private # incapsulate all attributes as private
+```
+
+---
+
+## Initializer integration
+
+- supports per-class configurations;
+- possible configurations:
+  - `:type_system` - chosen type-system (`smart_types` by default);
+  - `:strict_options` - fail extra kwarg-attributes, passed to the constructor (`true` by default);
+  - `:auto_cast` - type-cast all values to the declared attribute type (`false` by default);
+
+```ruby
+# with pre-configured type system (:smart_types, see Configuration doc)
+
+class MyStructure
+  include SmartCore::Initializer
+end
+```
+
+```ruby
+# with manually chosen settings
+
+class MyStructure
+  include SmartCore::Initializer(
+    type_system: :smart_types, # use smart_types
+    auto_cast: true, # type-cast all values by default
+    strict_options: false # ignore extra kwargs passed to the constructor
+  )
+end
+
+class AnotherStructure
+  include SmartCore::Initializer(type_system: :thy_types) # use thy_types and global defaults
+end
+```
+
+---
+
+### Basic Example:
 
 
 ```ruby
@@ -114,13 +206,34 @@ class User
   include SmartCore::Initializer(type_system: :smart_types)
 
   param :user_id, SmartCore::Types::Value::Integer, cast: false, privacy: :public
+  param :login, :string, mutable: true
+
   option :role, default: :user, finalize: -> { |value| Role.find(name: value) }
 
+  # NOTE: for method-based finalizetion use `your_method(value)` isntance method of your class;
+  # NOTE: for dynamic default values use `proc` objects and `lambda` objects;
+
   params :name, :password
   options :metadata, :enabled
 end
 
-User.new(1, 'John', 'test123', role: :admin, metadata: {}, enabled: false)
+# with correct types (incorrect types will raise SmartCore::Initializer::IncorrectTypeError)
+object = User.new(1, 'kek123', 'John', 'test123', role: :admin, metadata: {}, enabled: false)
+
+# attribute accessing:
+object.user_id # => 1
+object.login # => 'kek123'
+object.name # => 'John'
+object.password # => 'test123'
+object.role # => :admin
+object.metadata # => {}
+object.enabled # => false
+
+# attribute mutation (only mutable attributes have a mutator):
+object.login = 123 # => (type vlaidation error) raises SmartCore::Initializer::IncorrectTypeError (expected String, got Integer)
+object.login # => 'kek123'
+object.login = 'pek456'
+object.login # => 'pek456'
 ```
 
 ---
@@ -152,27 +265,65 @@ user.__attributes__ # => { first_name: 'Rustam', second_name: 'Ibragimov', age:
 
 ## Configuration
 
-- based on `Qonfig` gem;
+- **configuration setitngs**:
+  - `:default_type_system` - default type system (`smart_types` by default);
+  - `:strict_options` - fail on extra kwarg-attributes passed to the constructor (`true` by default);
+  - `:auto_cast` - type-cast all values to the declared attribute type (`false` by default);
+- by default, all classes uses and inherits the Global configuration;
 - you can read config values via `[]` or `.config.settings` or `.config[key]`;
-- setitngs:
-  - `default_type_system` - default type system (`smart_types` by default);
-  - `strict_options` - raise an error when got unknown options if true (`true` by default);
+- each class can be configured separately (in `include` invocation);
+- global configuration affects classes used the default global configs in run-time;
+- each class can be re-configured separately in run-time;
+- based on `Qonfig` gem;
 
 ```ruby
-# configure:
+# Global configuration:
+
 SmartCore::Initializer::Configuration.configure do |config|
   config.default_type_system = :smart_types # default setting value
   config.strict_options = true # default setting value
+  config.auto_cast = false # default setting value
 end
 ```
 
 ```ruby
-# read:
+# Read configs:
+
 SmartCore::Initializer::Configuration[:default_type_system]
 SmartCore::Initializer::Configuration.config[:default_type_system]
 SmartCore::Initializer::Configuration.config.settings.default_type_system
 ```
 
+```ruby
+# per-class configuration:
+
+class Parameters
+  include SmartCore::Initializer(auto_cast: true, strict_options: false)
+  # 1. use globally configured `smart_types` (default value)
+  # 2. type-cast all attributes by default (auto_cast: true)
+  # 3. ignore extra kwarg-attributes passed to the constructor (strict_options: false)
+end
+
+class User
+  include SmartCore::Initializer(type_system: :thy_types)
+  # 1. use :thy_types isntead of pre-configured :smart_types
+  # 2. use pre-configured auto_cast (false by default above)
+  # 3. use pre-configured strict_options ()
+end
+```
+
+```ruby
+# debug class-related configurations:
+
+class SomeClass
+  include SmartCore::Initializer(type_system: :thy_types)
+end
+
+SomeClass.__initializer_settings__[:type_system] # => :thy_types
+SomeClass.__initializer_settings__[:auto_cast] # => false
+SomeClass.__initializer_settings__[:strict_options] # => true
+```
+
 ---
 
 ## Type aliasing
@@ -208,6 +359,63 @@ SmartCore::Initializer::TypeSystem::ThyTypes.type_aliases
 
 ---
 
+## Type-casting
+
+- make param/option as type-castable:
+
+```ruby
+class Order
+  include SmartCore::Initializer
+
+  param :manager, 'string' # cast: false is used by default
+  param :amount, 'float', cast: true
+
+  option :status, :symbol # cast: false is used by default
+  option :is_processed, 'boolean', cast: true
+  option :processed_at, 'time', cast: true
+end
+
+order = Order.new(
+  'Daiver',
+  '123.456',
+  status: :pending,
+  is_processed: nil,
+  processed_at: '2021-01-01'
+)
+
+order.manager # => 'Daiver'
+order.amount # => 123.456 (type casted)
+order.status # => :pending
+order.is_processed # => false (type casted)
+order.processed_at # => 2021-01-01 00:00:00 +0300 (type casted)
+```
+
+- configure automatic type casting:
+
+```ruby
+# per class
+
+class User
+  include SmartCore::Initializer(auto_cast: true) # auto type cast every attribute
+
+  param :x, 'string'
+  param :y, 'numeric', cast: false # disable type-casting
+
+  option :b, 'integer', cast: false # disable type-casting
+  option :c, 'boolean'
+end
+```
+
+```ruby
+# globally
+
+SmartCore::Initializer::Configuration.configure do |config|
+  config.auto_cast = true # false by default
+end
+```
+
+---
+
 ## Initialization extension
 
 - `ext_init(&block)`:
@@ -291,9 +499,9 @@ User.new(123, 'test', { admin: true, age: 22 })
 
 ## Roadmap
 
-- (in development) Attribue Definition DSL
-  - Support for specifying the attribute accessor type (`read_only` parameter);
-  - Support for attribute aliasing (`as` parameter);
+- (**thinking** / **discussing**) Finalize should be invoked on `mutable` attributes after mutation too;
+- Support for `RSpec` doubles and instance_doubles inside the type system integration;
+- Specs restructuring;
 - Migrate from `TravisCI` to `GitHub Actions`;
 - Extract `Type Interop` system to `smart_type-system`;
 
@@ -349,6 +557,12 @@ bundle exec rake rubocop -A
 
 Released under MIT License.
 
+## Supporting
+
+<a target="_blank" href="https://github.com/Cado-Labs">
+  <img src="https://github.com/Cado-Labs/cado-labs-logos/raw/main/cado_labs_badge.svg" alt="Supported by Cado Labs" style="max-width: 100%;">
+</a>
+
 ## Authors
 
 [Rustam Ibragimov](https://github.com/0exp)

data/bin/console

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 require 'bundler/setup'
-require 'smart_core'
-
+require 'smart_core/initializer'
 require 'pry'
+
 Pry.start