attr_magic 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c5c17464091f895e95a549137979f6be96d48eae
+  data.tar.gz: f17e82aad2ebf8d6e28937c46b71e373038f488f
+SHA512:
+  metadata.gz: 4c689dbcef43970967cfb0db1c2fb4ce98cfdb132ed7cea4da80a6acb8f0ed447bd47680cc496d0db0c0ad9eb36f1a2eaf9f7164c2a685eeb563bd96e813bbd4
+  data.tar.gz: b4772ada55e0fb12de57f589b06b1d9418b1e20717a3ca7326980d4bd2aa86931e773a924fc1814629b14e172ee2b61f362469bbbd0b28d4bc190fbf9ea1bcbf

data/.gitignore

@@ -0,0 +1,26 @@
+
+# General Ruby, sorted by first letter.
+/.bundle/
+/coverage/
+/doc/
+/vendor/bundle/
+/.yardoc/
+
+# Project-specific.
+/*.gem
+
+# Old etc.
+*.old*
+*.orig
+/*.patch
+*.ref*
+
+# Nonpersistent stuff.
+TODO.md
+
+# Shared VS Code settings.
+/.vscode/*
+!/.vscode/*.json
+
+# Custom VS Code settings.
+/*.code-workspace

data/.rspec

@@ -0,0 +1,3 @@
+
+-fd
+--require spec_helper

data/.yardopts

@@ -0,0 +1,6 @@
+
+--default-return void
+
+{lib}/**/*.rb
+-
+README-ru.md

data/Gemfile

@@ -0,0 +1,9 @@
+
+source "https://rubygems.org"
+
+group :development do
+  gem "its"
+  gem "rspec"
+  gem "simplecov", require: false
+  gem "yard"
+end

data/Gemfile.lock

@@ -0,0 +1,52 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (5.2.8.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    concurrent-ruby (1.2.2)
+    diff-lcs (1.5.0)
+    docile (1.3.5)
+    i18n (1.14.1)
+      concurrent-ruby (~> 1.0)
+    its (0.2.0)
+      rspec-core
+    json (2.6.3)
+    minitest (5.15.0)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.6)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.1)
+    simplecov (0.17.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    thread_safe (0.3.6)
+    tzinfo (1.2.11)
+      thread_safe (~> 0.1)
+    yard (0.9.34)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport
+  its
+  rspec
+  simplecov
+  yard
+
+BUNDLED WITH
+   1.17.3

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2017-2023 Alex Fortuna
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README-ru.md

@@ -0,0 +1,212 @@
+
+# Инструменты для реализации атрибутов-вычислителей
+
+<!-- @import "[TOC]" {cmd="toc" depthFrom=2 depthTo=6 orderedList=false} -->
+
+<!-- code_chunk_output -->
+
+- [Введение](#введение)
+  - [Что даёт AttrMagic?](#что-даёт-attrmagic)
+- [Установка](#установка)
+- [Пример использования](#пример-использования)
+  - [`#igetset`](#igetset)
+  - [`#require_attr`](#require_attr)
+  - [`#igetwrite`](#igetwrite)
+- [Copyright](#copyright)
+
+<!-- /code_chunk_output -->
+
+## Введение
+
+*An English version of this text is also available: [README.md](README.md).*
+
+Атрибут-вычислитель (lazy attribute) — это метод-accessor, который производит некое вычисление при первом вызове,
+мемоизирует результат в instance-переменную и возвращает результат. Например:
+
+```ruby
+class Person
+  # @return [String]
+  attr_accessor :first_name, :last_name
+
+  attr_writer :full_name, :is_admin
+
+  def initialize(attrs = {})
+    attrs.each { |k, v| public_send("#{k}=", v) }
+  end
+
+  # @return [String]
+  def full_name
+    @full_name ||= begin
+      [first_name, last_name].compact.join(" ").strip
+    end
+  end
+
+  # @return [Boolean]
+  def is_admin
+    return @is_admin if defined? @is_admin
+    @is_admin = !!full_name.match(/admin/i)
+  end
+end
+```
+
+В примере выше `#full_name` и `#is_admin` — атрибуты-вычислители.
+
+### Что даёт AttrMagic?
+
+Классам, содержащим атрибуты-вычислители, AttrMagic даёт:
+
+1. `#igetset` и `#igetwrite` для простой мемоизации любых значений, включая `false` и `nil`.
+2. `#require_attr` для валидации атрибутов, от которых зависит результат данного вычисления.
+
+## Установка
+
+Добавляем в `Gemfile` нашего проекта:
+
+```ruby
+gem "attr_magic"
+#gem "attr_magic", git: "https://github.com/dadooda/attr_magic"
+```
+
+## Пример использования
+
+Чтобы использовать фичу, загружаем её в класс:
+
+```ruby
+class Person
+  AttrMagic.load(self)
+  …
+end
+```
+
+Методы AttrMagic теперь доступны в классе `Person`.
+Теперь рассмотрим, какие инструменты стали нам доступны.
+
+### `#igetset`
+
+В примере выше метод `#full_name` мемоизирует результат оператором `||=`.
+Это вполне приемлемо, ведь результат вычисления — строка.
+
+А вот реализация `#is_admin` гораздо более громоздка, ведь результат
+может быть вычислен как `false`, стало быть `||=` не подойдёт.
+
+Оба метода можно переписать с использованием `#igetset`:
+
+```ruby
+class Person
+  …
+  def full_name
+    igetset(__method__) { [first_name, last_name].compact.join(" ").strip }
+  end
+
+  def is_admin
+    igetset(__method__) { !!full_name.match(/admin/i) }
+  end
+end
+```
+
+Методы приобрели короткий, единообразный, легко читаемый вид.
+Теперь вычисление в `#is_admin` отчётливо видно, тогда как ранее оно тонуло в повторах
+*is_admin* внутри метода, который и так назван этим словом.
+
+### `#require_attr`
+
+В примере выше метод `#first_name` возвращает пустую строку, даже если атрибуты
+`first_name` и `last_name` не присвоены или пусты.
+
+С точки зрения внятности это поведение «на грани фола».
+Ведь, скорее всего, результат `#full_name` будет выводиться в блоке информации о персоне или при обращении к персоне.
+Пустая строка, даже правомерно вычисленная, вызовет в этой ситуации, как минимум, непонимание.
+
+Конечно, экземпляр `Person` не виноват, что перед вызовом `#full_name` в нём не присвоили `first_name` и `last_name`.
+Как говорится, garbage in — garbage out.
+
+Однако, чем тупо «вредничать», возвращая невнятную пустоту, `#full_name` мог бы
+помочь разработчику выявить эту ситуацию, чётко о ней просигналив.
+
+Предположим, мы решили, что для корректного вычисления `#full_name` нам необходим,
+как минимум, непустой `first_name`. Реализация может выглядеть так:
+
+```ruby
+class Person
+  …
+  def full_name
+    igetset(__method__) do
+      require_attr :first_name
+      [first_name, last_name].compact.join(" ").strip
+    end
+  end
+end
+```
+
+Теперь посмотрим, как это работает:
+
+```ruby
+Person.new.full_name
+# RuntimeError: Attribute `first_name` must not be nil: nil
+```
+
+Вроде неплохо. Вместо пустоты мы получили исключение с указанием на причину отказа:
+не присвоен `first_name`. Смущают, однако, слова про `nil`, хотя речь идёт о строковом атрибуте.
+А вдруг в `first_name` пустая строка, что тогда? Пробуем:
+
+```ruby
+Person.new(first_name: "").full_name
+# => ""
+
+Person.new(first_name: " ").full_name
+# => ""
+```
+
+На пустую строку наш `require_attr` пока не реагирует, хотя суть требования была в том,
+чтобы `first_name` был именно *не пустой.* Чуть-чуть доработаем код:
+
+```ruby
+# Нужно для `Object#present?`.
+require "active_support/core_ext/object/blank"
+
+class Person
+  …
+  def full_name
+    igetset(__method__) do
+      require_attr :first_name, :present?
+      #require_attr :first_name, :not_blank?   # Можно так.
+      [first_name, last_name].compact.join(" ").strip
+    end
+  end
+end
+```
+
+Снова пробуем вызвать:
+
+```ruby
+Person.new.full_name
+# RuntimeError: Attribute `first_name` must be present: nil
+
+Person.new(first_name: " ").full_name
+# RuntimeError: Attribute `first_name` must be present: " "
+
+Person.new(first_name: "Joe").full_name
+# => "Joe"
+```
+
+Теперь и сообщение чётче, и требование выполнено.
+
+Мы узнали, что `#require_attr` даёт возможность выполнить тривиальную валидацию
+соседнего атрибута, значение которого нужно в данном вычислении.
+
+### `#igetwrite`
+
+Описанный в примере выше, метод `#igetset` взаимодействует с instance-переменными напрямую:
+проверяет наличие, читает, записывает. В большинстве случаев этого достаточно.
+
+Бывает, однако, что мы добавляем наш метод-вычислитель в класс, требующий записи в свои атрибуты
+строго через write-аксессоры вроде `#name=`.
+
+В таких случаях помогает `#igetwrite`.
+Выполнив вычисление, он записывает значение в объект через write accessor.
+
+## Copyright
+
+Продукт распространяется свободно на условиях лицензии MIT.
+
+— © 2017-2023 Алексей Фортуна

data/README.md

@@ -0,0 +1,216 @@
+
+# The tools to ease lazy attribute implementation
+
+<!-- @import "[TOC]" {cmd="toc" depthFrom=2 depthTo=6 orderedList=false} -->
+
+<!-- code_chunk_output -->
+
+- [Overview](#overview)
+  - [What does AttrMagic provide?](#what-does-attrmagic-provide)
+- [Setup](#setup)
+- [Usage example](#usage-example)
+  - [`#igetset`](#igetset)
+  - [`#require_attr`](#require_attr)
+  - [`#igetwrite`](#igetwrite)
+- [Copyright](#copyright)
+
+<!-- /code_chunk_output -->
+
+## Overview
+
+*Этот текст можно прочитать на русском языке: [README-ru.md](README-ru.md).*
+
+A lazy attribute is an accessor method that performs some computation the first time it is called,
+memoizes the result into an instance variable, and returns the result. Example:
+
+```ruby
+class Person
+  # @return [String]
+  attr_accessor :first_name, :last_name
+
+  attr_writer :full_name, :is_admin
+
+  def initialize(attrs = {})
+    attrs.each { |k, v| public_send("#{k}=", v) }
+  end
+
+  # @return [String]
+  def full_name
+    @full_name ||= begin
+      [first_name, last_name].compact.join(" ").strip
+    end
+  end
+
+  # @return [Boolean]
+  def is_admin
+    return @is_admin if defined? @is_admin
+    @is_admin = !!full_name.match(/admin/i)
+  end
+end
+```
+
+Methods `#full_name` и `#is_admin` are lazy attributes.
+
+### What does AttrMagic provide?
+
+For classes that have lazy attributes, AttrMagic provides:
+
+1. `#igetset` and `#igetwrite` for simple memoization of any values, including `false` and `nil`.
+2. `#require_attr` to validate attributes which are required by the given computation.
+
+## Setup
+
+Add to your project's `Gemfile`:
+
+```ruby
+gem "attr_magic"
+#gem "attr_magic", git: "https://github.com/dadooda/attr_magic"
+```
+
+## Usage example
+
+To use feature, let's load it into a class:
+
+```ruby
+class Person
+   AttrMagic.load(self)
+   …
+end
+```
+
+AttrMagic methods are now available in the `Person` class.
+Let's see how we can use them.
+
+### `#igetset`
+
+In the example above, method `#full_name` memoizes the result with the `||=` operator.
+This suits us, because the result of the computation is a string.
+
+As to `#is_admin`, its much more verbose: the result can be `false`,
+thus operator `||=` won't work.
+
+Both methods can be written using `#igetset`:
+
+```ruby
+class Person
+  …
+  def full_name
+    igetset(__method__) { [first_name, last_name].compact.join(" ").strip }
+  end
+
+  def is_admin
+    igetset(__method__) { !!full_name.match(/admin/i) }
+  end
+end
+```
+
+Now our methods are short, uniform, and easy to read.
+
+Also, the computation in `#is_admin` is clearly visible, whereas previously it was obscured
+by repetitions of *is_admin* inside the method already named by this word.
+
+### `#require_attr`
+
+In the example above, method `#first_name` returns an empty string even if attributes
+`first_name` and `last_name` are unassigned or blank.
+
+Such behavior cannot be considered completely sane.
+Most likely, the result of `#full_name` will be displayed in the info block about a person
+or be used when addressing a person.
+An empty string, even “legitimately” computed, may cause confusion.
+
+Of course, it's not the `Person` instance's fault that neither `first_name` nor `last_name`
+were assigned values prior to calling `#full_name`. Garbage in — garbage out.
+
+However, rather than behaving deliberately “harmful” by returning inarticulate blankness,
+`#full_name` could be *helpful* by signalling about this situation and helping us tackle it promptly.
+
+Suppose we decided, that in order to compute `#full_name` properly,
+we at least need a non-blank `first_name`. An implementation could look like this:
+
+```ruby
+class Person
+  …
+  def full_name
+    igetset(__method__) do
+      require_attr :first_name
+      [first_name, last_name].compact.join(" ").strip
+    end
+  end
+end
+```
+
+Let's see how it works:
+
+```ruby
+Person.new.full_name
+# RuntimeError: Attribute `first_name` must not be nil: nil
+```
+
+Not bad! Instead of getting dumb blankness, we've got an exception pointing straight at the reason:
+unassigned `first_name`. However, the `nil` phrasing might sound a bit confusing
+when talking about string values.
+Also, what if `first_name` is assigned, but is empty or blank? Let's see:
+
+```ruby
+Person.new(first_name: "").full_name
+# => ""
+
+Person.new(first_name: " ").full_name
+# => ""
+```
+
+Our `require_attr` doesn't react to an empty/blank string yet,
+despite our decision to ensure that `first_name` is *non-blank*.
+Let's tune the code a bit:
+
+```ruby
+# We need this for `Object#present?`.
+require "active_support/core_ext/object/blank"
+
+class Person
+  …
+  def full_name
+    igetset(__method__) do
+      require_attr :first_name, :present?
+      #require_attr :first_name, :not_blank?   # Also possible.
+      [first_name, last_name].compact.join(" ").strip
+    end
+  end
+end
+```
+
+Let's try it again:
+
+```ruby
+Person.new.full_name
+# RuntimeError: Attribute `first_name` must be present: nil
+
+Person.new(first_name: " ").full_name
+# RuntimeError: Attribute `first_name` must be present: " "
+
+Person.new(first_name: "Joe").full_name
+# => "Joe"
+```
+
+Now the message is more meaningful and the requirement is met.
+
+We've learned that `#require_attr` makes it possible to perform a trivial validation
+of another attribute, needed for a given computation to succeed.
+
+### `#igetwrite`
+
+Method `#igetset`, described above, operates instance variables directly:
+checks for being defined, gets and sets. This is sufficient in most cases.
+
+Sometimes, however, proper setting of an attribute demands calling its write accessor,
+such as `#name=`.
+
+In such cases, `#igetwrite` comes in handy.
+After performing the computation, it saves the value to the object by calling a write accessor.
+
+## Copyright
+
+The product is free software distributed under the terms of the MIT license.
+
+— © 2017-2023 Alex Fortuna

data/Rakefile

@@ -0,0 +1,15 @@
+
+desc "Build the gem"
+task :build do
+  system "gem build attr_magic.gemspec"
+end
+
+desc "Build YARD docs"
+task :doc do
+  system "bundle exec yard"
+end
+
+desc "Run tests"
+task :test do
+  system "bundle exec rspec"
+end

data/attr_magic.gemspec

@@ -0,0 +1,17 @@
+
+require_relative "lib/attr_magic/version"
+
+Gem::Specification.new do |s|
+  s.name = "attr_magic"
+  s.summary = "The tools to ease lazy attribute implementation"
+  s.version = AttrMagic::VERSION
+
+  s.authors = ["Alex Fortuna"]
+  s.email = ["fortunadze@gmail.com"]
+  s.homepage = "https://github.com/dadooda/attr_magic"
+  s.license = "MIT"
+
+  s.files = `git ls-files`.split("\n")
+  s.require_paths = ["lib"]
+  s.test_files = `git ls-files -- {spec}/*`.split("\n")
+end

data/lib/attr_magic/instance_methods.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module AttrMagic
+  module InstanceMethods
+    # Memoize a lazy attribute, given its computation block.
+    #
+    #   def full_name
+    #     igetset(__method__) { [first_name, last_name].compact.join(" ").strip }
+    #   end
+    #
+    # @param [Symbol | String] name
+    # @return [mixed] The result of +compute+.
+    # @see #igetwrite
+    def igetset(name, &compute)
+      if instance_variable_defined?(k = "@#{name}")
+        instance_variable_get(k)
+      else
+        raise ArgumentError, "Code block must be given" unless compute
+        instance_variable_set(k, compute.call)
+      end
+    end
+
+    # Same as {#igetset}, but this one calls an attribute writer to store the computed
+    # value into the object.
+    # @param [Symbol | String] name
+    # @return [mixed] The result of +compute+.
+    # @see #igetset
+    def igetwrite(name, &compute)
+      if instance_variable_defined?(k = "@#{name}")
+        instance_variable_get(k)
+      else
+        raise ArgumentError, "Code block must be given" unless compute
+        send("#{name}=", compute.call)
+      end
+    end
+
+    # Require an attribute to be set, present, valid or not invalid.
+    #
+    #   require_attr(:name)                 # Require not to be `.nil?`.
+    #   require_attr(:obj, :valid)          # Require to be `.valid`.
+    #   require_attr(:items, :present?)     # Require to be `.present?`.
+    #   require_attr(:items, :not_empty?)   # Require not to be `.empty?`.
+    #
+    # @param name [Symbol | String]
+    # @param predicate [Symbol | String]
+    # @return [mixed] Attribute value.
+    # @raise [RuntimeError]
+    def require_attr(name, predicate = :not_nil?)
+      # Declare in the scope.
+      m = nil
+
+      # `check` is a function returning `true` if the value is good.
+      m, verb, check = if ((sp = predicate.to_s).start_with? "not_")
+        [
+          sp[4..-1],
+          "must not",
+          -> (v) { !v.public_send(m) },
+        ]
+      else
+        [
+          sp,
+          "must",
+          -> (v) { v.public_send(m) },
+        ]
+      end
+
+      raise ArgumentError, "Invalid predicate: #{predicate.inspect}" if m.empty?
+
+      # NOTE: Shorten the error backtrace to the minimum.
+
+      # Get and check the value.
+      v = send(name)
+      check.(v) or raise "Attribute `#{name}` #{verb} be #{m.chomp('?')}: #{v.inspect}"
+
+      v
+    end
+  end # InstanceMethods
+end

data/lib/attr_magic/version.rb

@@ -0,0 +1,4 @@
+
+module AttrMagic
+  VERSION = "0.1.2"
+end

data/lib/attr_magic.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+"LODoc"
+
+# Ease lazy attribute implementation to the owner class.
+#
+# = Usage
+#
+#   class Klass
+#     AttrMagic.load(self)
+#   end
+#
+# = Features
+#
+# == Implement a lazy attribute reader
+#
+#   class Person
+#     …
+#     attr_writer :full_name
+#
+#     def full_name
+#       igetset(__method__) { [first_name, last_name].compact.join(" ").strip }
+#     end
+#   end
+#
+# See {InstanceMethods#igetset}, {InstanceMethods#igetwrite}.
+#
+# == Validate an attribute
+#
+#   class Person
+#     …
+#     def full_name
+#       igetset(__method__) do
+#         #require_attr :first_name                 # Will check for `nil` only.
+#         require_attr :first_name, :present?
+#         #require_attr :first_name, :not_blank?    # Also possible.
+#         [first_name, last_name].compact.join(" ").strip
+#       end
+#     end
+#   end
+#
+# See {InstanceMethods#require_attr}.
+module AttrMagic
+  # Load the feature into +owner+.
+  # @param owner [Class]
+  def self.load(owner)
+    return if owner < InstanceMethods
+    owner.send(:include, InstanceMethods)
+    owner.class_eval { private :igetset, :igetwrite, :require_attr }
+  end
+end
+
+# Load all.
+Dir[File.expand_path("attr_magic/**/*.rb", __dir__)].each { |fn| require fn }

data/libx/README.md

@@ -0,0 +1,4 @@
+
+# Inline portions of RSpecMagic
+
+See [dadooda/rspec_magic](https://github.com/dadooda/rspec_magic).

data/libx/rspec_magic/config.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+"LODoc"
+
+module RSpecMagic
+  # Shared configuration.
+  module Config
+    class << self
+      attr_writer :spec_path
+
+      # @return [String]
+      def spec_path
+        @spec_path || raise("`#{__method__}` must be configured")
+      end
+    end
+  end
+end

data/libx/rspec_magic/stable/alias_method.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+"LODoc"
+
+module RSpecMagic; module Stable
+  # Method alias matcher.
+  # Originally from https://gist.github.com/1950961, but heavily reworked consistency-wise.
+  #
+  # = Usage
+  #
+  #   describe User do
+  #     it { is_expected.to alias_method(:admin?, :is_admin) }
+  #   end
+  module AliasMethod
+  end
+
+  # Activate.
+  defined?(RSpec) and RSpec::Matchers.define(:alias_method) do |new_name, old_name|
+    match do |subject|
+      expect(subject.method(new_name)).to eq subject.method(old_name)
+    end
+
+    description do
+      "have #{new_name.inspect} aliased to #{old_name.inspect}"
+    end
+  end
+end; end

data/libx/rspec_magic/stable/context_when.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+"LODoc"
+
+module RSpecMagic; module Stable
+  # Create a self-descriptive "when …" context with one or more +let+ variables defined.
+  #
+  # = Usage
+  #
+  # The following:
+  #
+  #   context_when name: "Joe", age: 25 do
+  #     …
+  #   end
+  #
+  # is identical to:
+  #
+  #   context "when { name: \"Joe\", age: 25 }" do
+  #     let(:name) { "Joe" }
+  #     let(:age) { 25 }
+  #     …
+  #   end
+  #
+  # = Features
+  #
+  # Prepend +x+ to +context_when+ to exclude it:
+  #
+  #   xcontext_when … do
+  #     …
+  #   end
+  #
+  # ----
+  #
+  # Define a custom formatter via +_context_when_formatter+:
+  #
+  #   context "…" do
+  #     def self._context_when_formatter(h)
+  #       "when #{h.to_json}"
+  #     end
+  #
+  #     …
+  #   end
+  module ContextWhen
+    # Default formatter for {#context_when}. Redefine at the context level if needed.
+    #
+    #   describe "…" do
+    #     def self._context_when_formatter(h)
+    #       # Your custom formatter here.
+    #       h.to_json
+    #     end
+    #
+    #     context_when … do
+    #       …
+    #     end
+    #   end
+    # @param [Hash] h
+    # @return [String]
+    def _context_when_formatter(h)
+      # Extract labels for Proc arguments, if any.
+      labels = {}
+      h.each do |k, v|
+        if v.is_a? Proc
+          begin
+            labels[k] = h.fetch(lk = "#{k}_label".to_sym)
+            h.delete(lk)
+          rescue KeyError
+            raise ArgumentError, "`#{k}` is a `Proc`, `#{k}_label` must be given"
+          end
+        end
+      end
+
+      pcs = h.map do |k, v|
+        [
+          k.is_a?(Symbol) ? "#{k}:" : "#{k.inspect} =>",
+          v.is_a?(Proc) ? labels[k] : v.inspect,
+        ].join(" ")
+      end
+
+      "when { " + pcs.join(", ") + " }"
+    end
+
+    # Create a context.
+    # @param [Hash] h
+    def context_when(h, &block)
+      context _context_when_formatter(h) do
+        h.each do |k, v|
+          if v.is_a? Proc
+            let(k, &v)
+          else
+            # Generic scalar value.
+            let(k) { v }
+          end
+        end
+        class_eval(&block)
+      end
+    end
+
+    # Create a temporarily excluded context.
+    def xcontext_when(h, &block)
+      xcontext _context_when_formatter(h) { class_eval(&block) }
+    end
+  end
+
+  # Activate.
+  defined?(RSpec) and RSpec.configure do |config|
+    config.extend ContextWhen
+  end
+end; end

data/libx/rspec_magic/stable/use_letset.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+"LODoc"
+
+module RSpecMagic; module Stable
+  # Define methods to manage a set of custom +let+ variables which act as a distinct collection.
+  #
+  #   RSpec.describe SomeKlass do
+  #     use_letset :let_a, :attrs       # (1)
+  #     use_letset :let_p, :params      # (2)
+  #     ...
+  #
+  # In above examples, (1) provides our suite with:
+  #
+  #   def self.let_a(let, &block)
+  #   def attrs(include: [])
+  #
+  # , thus this now becomes possible:
+  #
+  #   describe "attrs" do
+  #     let_a(:name) { "Joe" }
+  #     let_a(:age) { 25 }
+  #     let(:gender) { :male }
+  #     it do
+  #       expect(name).to eq "Joe"
+  #       expect(age).to eq 25
+  #       expect(attrs).to eq(name: "Joe", age: 25)
+  #       expect(attrs(include: [:gender])).to eq(name: "Joe", age: 25, gender: :male)
+  #     end
+  #   end
+  #
+  # By not providing a block it's possible to <b>declare</b> a custom <tt>let</tt> variable
+  # and be able to redefine it later via regular <tt>let</tt>. This will work:
+  #
+  #   describe "declarative (no block) usage" do
+  #     let_a(:name)
+  #
+  #     subject { attrs }
+  #
+  #     context "when no other `let` value" do
+  #       it { is_expected.to eq({}) }
+  #     end
+  #
+  #     context "when `let`" do
+  #       let(:name) { "Joe" }
+  #       it { is_expected.to eq(name: "Joe") }
+  #     end
+  #   end
+  #
+  module UseLetset
+    # Define the collection.
+    # @param let_method [Symbol]
+    # @param collection_let [Symbol]
+    # @return [void]
+    def use_letset(let_method, collection_let)
+      keys_m = "_#{collection_let}_keys".to_sym
+
+      # See "Implementation notes" on failed implementation of "collection only" mode.
+
+      # E.g. "_data_keys" or something.
+      define_singleton_method(keys_m) do
+        if instance_variable_defined?(k = "@#{keys_m}")
+          instance_variable_get(k)
+        else
+          # Start by copying superclass's known vars or default to `[]`.
+          instance_variable_set(k, (superclass.send(keys_m).dup rescue []))
+        end
+      end
+
+      define_singleton_method let_method, ->(k, &block) do
+        (send(keys_m) << k).uniq!
+        # Create a `let` variable unless it's a declaration call (`let_a(:name)`).
+        let(k, &block) if block
+      end
+
+      define_method(collection_let) do
+        {}.tap do |h|
+          self.class.send(keys_m).each do |k|
+            h[k] = public_send(k) if respond_to?(k)
+          end
+        end
+      end
+    end
+  end
+
+  # Activate.
+  defined?(RSpec) and RSpec.configure do |config|
+    config.extend UseLetset
+  end
+end; end
+
+#
+# Implementation notes:
+#
+# * There was once an idea to support `use_letset` in "collection only" mode. Say, `let_a` appends
+#   to `attrs`, but doesn't publish a let variable. This change IS COMPLETELY NOT IN LINE with
+#   RSpec design. Let variables are methods and the collection is built by probing for those
+#   methods. "Collection only" would require a complete redesign. It's easier to implement another
+#   helper method for that, or, even better, do it with straight Ruby right in the test where
+#   needed. The need for "collection only" mode is incredibly rare, say, specific serializer
+#   tests.

data/libx/rspec_magic/stable/use_method_discovery.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+"LODoc"
+
+module RSpecMagic; module Stable
+  # Provide an automatic <tt>let</tt> variable which contains a method name discovered from
+  # its string representation.
+  #
+  #   describe "instance methods" do
+  #     use_method_discovery :m
+  #
+  #     describe "#name" do
+  #       it { expect(m).to eq :name }
+  #     end
+  #
+  #     describe "#surname" do
+  #       it { expect(m).to eq :surname }
+  #     end
+  #   end
+  #
+  module UseMethodDiscovery
+    # Enable the discovery mechanics.
+    # @param [Symbol] method_let
+    def use_method_discovery(method_let)
+      # This context and all sub-contexts will respond to A and return B. "Signature" is based on
+      # invocation arguments which can vary as we use the feature more intensively. Signature method
+      # is the same, thus it shadows higher level definitions completely.
+      signature = { method_let: method_let }
+      define_singleton_method(:_umd_signature) { signature }
+
+      let(method_let) do
+        # NOTE: `self.class` responds to signature method, no need to probe and rescue.
+        if (sig = (klass = self.class)._umd_signature) != signature
+          raise "`#{method_let}` is shadowed by `#{sig.fetch(:method_let)}` in this context"
+        end
+
+        # NOTE: Better not `return` from the loop to keep it debuggable in case logic changes.
+        found = nil
+        while (klass._umd_signature rescue nil) == signature
+          found = self.class.send(:_use_method_discovery_parser, klass.description.to_s) and break
+          klass = klass.superclass
+        end
+
+        found or raise "No method-like descriptions found to use as `#{method_let}`"
+      end
+    end
+
+    private
+
+    # The parser used by {.use_method_discovery}.
+    # @param [String] input
+    # @return [Symbol] Method name, if parsed okay.
+    # @return [nil] If input isn't method-like.
+    def _use_method_discovery_parser(input)
+      if (mat = input.match(/^(?:(?:#|\.|::)(\w+(?:\?|!|=|)|\[\])|(?:DELETE|GET|PUT|POST) (\w+))$/))
+        (mat[1] || mat[2]).to_sym
+      end
+    end
+  end # module
+
+  # Activate.
+  defined?(RSpec) and RSpec.configure do |config|
+    config.extend UseMethodDiscovery
+  end
+end; end

data/libx/rspec_magic/stable.rb

@@ -0,0 +1,2 @@
+
+Dir[File.expand_path("../stable/**/*.rb", __FILE__)].each { |fn| require fn }

data/libx/rspec_magic.rb

@@ -0,0 +1,9 @@
+
+# Load public features.
+require_relative "rspec_magic/config"
+
+# # Load a full set of stable features.
+# require_relative "rspec_magic/alias_method"
+# require_relative "rspec_magic/context_when"
+# require_relative "rspec_magic/use_letset"
+# require_relative "rspec_magic/use_method_discovery"

data/spec/lib/attr_magic_spec.rb

@@ -0,0 +1,140 @@
+
+RSpec.describe AttrMagic do
+  use_method_discovery :m
+
+  describe "#iget*" do
+    let(:klass) do
+      feature = described_class
+      Class.new do
+        feature.load(self)
+
+        attr_writer :c
+
+        def a
+          igetset(:a) do
+            calls << :a_block
+            false
+          end
+        end
+
+        def b
+          igetset(:b) do
+            calls << :b_block
+            nil
+          end
+        end
+
+        def c
+          igetwrite(:c) do
+            calls << :c_block
+            "c"
+          end
+        end
+
+        def c=(value)
+          calls << :c_writer
+          @c = value + "!"      # Custom modification by the writer.
+        end
+
+        def calls
+          @log ||= []
+        end
+      end
+    end
+
+    describe "#igetset" do
+      it "generally works" do
+        obj = klass.new
+        expect(obj.calls).to eq []
+        expect(obj.a).to be false
+        expect(obj.a).to be false
+        expect(obj.calls).to eq [:a_block]
+
+        obj = klass.new
+        expect(obj.calls).to eq []
+        expect(obj.b).to be nil
+        expect(obj.b).to be nil
+        expect(obj.calls).to eq [:b_block]
+      end
+    end # describe "#igetset"
+
+    describe "#igetwrite" do
+      it "generally works" do
+        obj = klass.new
+        expect(obj.calls).to eq []
+        expect(obj.c).to eq "c!"
+        expect(obj.c).to eq "c!"
+        expect(obj.c).to eq "c!"
+        expect(obj.calls).to eq [:c_block, :c_writer]
+      end
+    end # describe "#igetwrite"
+  end # describe "iget*"
+
+  describe "#require_attr" do
+    let(:klass) do
+      feature = described_class
+      Class.new do
+        feature.load(self)
+
+        attr_accessor :a
+
+        def initialize(attrs = {})
+          attrs.each { |k, v| public_send("#{k}=", v) }
+        end
+      end
+    end
+
+    let(:obj) { klass.new(a: value) }
+
+    subject { obj.send(m, :a, predicate) }
+
+    context "when valid arguments" do
+      # NOTE: We don't nest contexts and provide a linear sequence of [value, predicate] for
+      #       smarter reporting.
+      context_when value: nil do
+        subject { obj.send(m, :a) }
+        it { expect { subject }.to raise_error(RuntimeError, /attribute.+`a`.+not.+nil: nil/i) }
+      end
+
+      context_when value: nil, predicate: "not_nil?" do
+        it { expect { subject }.to raise_error(RuntimeError, /attribute.+`a`.+not.+nil: nil/i) }
+      end
+
+      context_when value: [], predicate: :not_empty? do
+        it { expect { subject }.to raise_error(RuntimeError, /attribute.+`a`.+not.+empty: \[\]/i) }
+      end
+
+      context_when value: 1, predicate: :odd? do
+        it { is_expected.to eq 1 }
+      end
+
+      context_when value: 1, predicate: :even? do
+        it { expect { subject }.to raise_error(RuntimeError, /attribute.+`a`.+even: 1/i) }
+      end
+
+      context_when value: [], predicate: :valid do
+        let(:a) { double "a" }
+        it do
+          expect(obj).to receive(:a).and_return(a)
+          expect(a).to receive(:valid).and_return(false)
+          expect { subject }.to raise_error(RuntimeError, /must be valid/i)
+        end
+      end
+
+      # NOTE: This is a valid case in a duck-typed language which Ruby is.
+      context_when value: [], predicate: "joyful?" do
+        it { expect { subject }.to raise_error(NoMethodError, /joyful\?/) }
+      end
+    end # context "when valid arguments"
+
+    context "when invalid arguments" do
+      context_when value: [], predicate: "" do
+        it { expect { subject }.to raise_error(ArgumentError, /invalid predicate/i) }
+      end
+
+      context_when value: [], predicate: "not_" do
+        it { expect { subject }.to raise_error(ArgumentError, /invalid predicate/i) }
+      end
+    end
+  end # describe "#require_attr"
+end # describe

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+
+# Must go before all.
+require_relative "support/simplecov"
+
+# Load support files.
+Dir[File.expand_path("support/**/*.rb", __dir__)].each { |fn| require fn }

data/spec/support/its.rb

@@ -0,0 +1,2 @@
+
+require "its"

data/spec/support/rspec_magic.rb

@@ -0,0 +1,2 @@
+
+require_relative "../../libx/rspec_magic/stable"

data/spec/support/self.rb

@@ -0,0 +1,2 @@
+
+require "attr_magic"

data/spec/support/simplecov.rb

@@ -0,0 +1,11 @@
+
+#
+# See https://github.com/simplecov-ruby/simplecov#getting-started.
+#
+
+require "simplecov"
+
+SimpleCov.start do
+  add_filter "libx/"
+  add_filter "spec/"
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: attr_magic
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Alex Fortuna
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-01-28 00:00:00.000000000 Z
+dependencies: []
+description: 
+email:
+- fortunadze@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".yardopts"
+- Gemfile
+- Gemfile.lock
+- MIT-LICENSE
+- README-ru.md
+- README.md
+- Rakefile
+- attr_magic.gemspec
+- lib/attr_magic.rb
+- lib/attr_magic/instance_methods.rb
+- lib/attr_magic/version.rb
+- libx/README.md
+- libx/rspec_magic.rb
+- libx/rspec_magic/config.rb
+- libx/rspec_magic/stable.rb
+- libx/rspec_magic/stable/alias_method.rb
+- libx/rspec_magic/stable/context_when.rb
+- libx/rspec_magic/stable/use_letset.rb
+- libx/rspec_magic/stable/use_method_discovery.rb
+- spec/lib/attr_magic_spec.rb
+- spec/spec_helper.rb
+- spec/support/its.rb
+- spec/support/rspec_magic.rb
+- spec/support/self.rb
+- spec/support/simplecov.rb
+homepage: https://github.com/dadooda/attr_magic
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2
+signing_key: 
+specification_version: 4
+summary: The tools to ease lazy attribute implementation
+test_files: []