magic-decorator 0.1.0.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b2496bbc27395a1c313aaa44e0c993037437a485595de2ef59f269835238409
-  data.tar.gz: 6cace80885c21da63511ac98e4a231ed03ffc67ac9567af4d192ad411b0b7149
+  metadata.gz: 673fe3ecf73066b97e1076dfb9a41e7fb31732396e9c39a5f97561d1ec2e616f
+  data.tar.gz: 44c33204523d4022f8b2b1c1eb28dd51f5a3499d5001cdfae97fff59568d89d1
 SHA512:
-  metadata.gz: 51300c4ae7274695352d0c4eab403f378646c3afb966eee38119000080a525b6637e838a57fce9897484f36de6917ebad630f94e25806399ea72e683789616f4
-  data.tar.gz: 81c9ee0f416defadebe38efb6e944a643b54f4d08d5aadf04062093141f229bc0a1aa26fa5ff293f219873c7e6927aae7cac163d2c66ba520214d9159a77ccc5
+  metadata.gz: 309f3a70d8ce2ae726375e59e152a77d044b7ffe52d8f7064e4baefe964aecc90c4a835dbf3e5474a56e0c7de08e0cb0e975e3e65bc3872a2cc2a18f2a401885
+  data.tar.gz: 595d311692d8db65bb29e0adc44222a48abea98b7b869a62d6b823cb436801be1317cddfc9c4caacf9a6514ec8cc0a1182a1b26c005f9efe2c52fa0d48cca2fc

data/CHANGELOG.md

@@ -1,10 +1,44 @@
+## [0.3.0] — 2024-10-27
+
+### Added
+
+- Improved extendability: one may override `Magic::Decoratable#decorator_base` to be used for lookups.
+- `Magic::Decoratable.classes` for all the decoratables.
+
+### Fixed
+
+- Failures on double decoration attempts.
+
+
+## [0.2.0] — 2024-10-17
+
+### Changed
+
+- For almost any method called on a decorated object, both its result and `yield`ed arguments get decorated.
+  Some methods aren’t meant to be decorated though:
+	- `deconstruct` & `deconstruct_keys` for _pattern matching_,
+	- _converting_ methods: those starting with `to_`,
+	- _system_ methods: those starting with `_`.
+
+### Added
+
+- `Magic::Decorator::Base.undecorated` to exclude methods from being decorated automagically.
+
+#### Default decorators
+
+- `EnumerableDecorator` to decorate `Enumerable`s.
+	- enables _splat_ operator: `*decorated` ,
+	- enables _double-splat_ operator: `**decorated`,
+	- enumerating methods yield decorated items.
+
+
 ## [0.1.0] — 2024-10-13
 
 ### Added
 
 - `Magic::Decorator::Base` — a basic decorator class.
 - `Magic::Decoratable` to be included in decoratable classes.
-  - `#decorate`,
-  - `#decorate!`,
-  - `#decorated`,
-  - `#decorated?`.
+	- `#decorate`,
+	- `#decorate!`,
+	- `#decorated`,
+	- `#decorated?`.

data/README.md

@@ -1,5 +1,8 @@
 # 🪄 Magic Decorator
 
+![GitHub Actions Workflow Status](
+	https://img.shields.io/github/actions/workflow/status/Alexander-Senko/magic-decorator/ci.yml
+)
 ![Code Climate maintainability](
 	https://img.shields.io/codeclimate/maintainability-percentage/Alexander-Senko/magic-decorator
 )
@@ -47,20 +50,83 @@ person.name # => "John Smith"
 This module adds three methods to decorate an object.
 Decorator class is being inferred automatically.
 When no decorator is found,
-* `#decorate`  returns `nil`,
-* `#decorate!` raises `Magic::Lookup::Error`,
-* `#decorated` returns the original object.
+- `#decorate`  returns `nil`,
+- `#decorate!` raises `Magic::Lookup::Error`,
+- `#decorated` returns the original object.
 
 One can test for the object is actually decorated with `#decorated?`.
 
 ```ruby
-'with no decorator for String'.decorated.decorated? # => false
-['with a decorator for Array'].decorated.decorated? # => true
+'with no decorator for String'.decorated
+    .decorated? # => false
+['with a decorator for Array'].decorated
+    .decorated? # => true
+```
+
+### Extending decorator logic
+
+When extending `Magic::Decoratable`, one may override `#decorator_base` to be used for lookup.
+
+```ruby
+class Special::Decorator < Magic::Decorator::Base
+  def self.name_for object_class
+    "Special::#{object_class}Decorator"
+  end
+end
+
+module Special::Decoratable
+  include Magic::Decoratable
+
+  private
+
+  def decorator_base = Special::Decorator
+end
+
+class Special::Model
+  include Special::Decoratable
+end
+
+Special::Model.new.decorate # looks for Special::Decorator descendants
 ```
 
-#### Magic
+## 🪄 Magic
 
-`Decoratable` is mixed into `Object` by default. That means that effectively any object is `Decoratable`.
+### Decoratable scope
+
+`Magic::Decoratable` is mixed into `Object` by default. It means that effectively any object is _magically decoratable_.
+
+One can use `Magic::Decoratable.classes` to see all the decoratable classes.
+
+### Decoration expansion
+
+For almost any method called on a decorated object, both its result and `yield`ed arguments get decorated.
+
+```ruby
+'with no decorator for String'.decorated.chars
+    .decorated? # => false
+['with a decorator for Array'].decorated.map(&:chars).first.grep(/\S/).group_by(&:upcase).transform_values(&:size).sort_by(&:last).reverse.first(5).map(&:first)
+    .decorated? # => true
+```
+
+#### Undecorated methods
+
+Some methods aren’t meant to be decorated though:
+
+- `deconstruct` & `deconstruct_keys` for _pattern matching_,
+- _converting_ methods: those starting with `to_`,
+- _system_ methods: those starting with `_`.
+
+#### `undecorated` modifier
+
+`Magic::Decorator::Base.undecorated` can be used to exclude methods from being decorated automagically.
+
+```ruby
+class MyDecorator < Magic::Decorator::Base
+  undecorated %i[to_s inspect]
+  undecorated :raw_method
+  undecorated :m1, :m2
+end
+```
 
 ### Decorator class inference
 
@@ -72,6 +138,33 @@ powered by [Magic Lookup](
 For example, `MyNamespace::MyModel.new.decorate` looks for `MyNamespace::MyModelDecorator` first.
 When missing, it further looks for decorators for its ancestor classes, up to `ObjectDecorator`.
 
+### Default decorators
+
+#### `EnumerableDecorator`
+
+It automagically decorates all its decoratable items.
+
+```ruby
+[1, [2], { 3 => 4 }, '5'].decorated
+    .map &:decorated? # => [false, true, true, false]
+
+{ 1 => 2, [3] => [4] }.decorated.keys
+    .map &:decorated? # => [false, true]
+{ 1 => 2, [3] => [4] }.decorated.values
+    .map &:decorated? # => [false, true]
+
+{ 1 => 2, [3] => [4] }.decorated[1]
+    .decorated? # => false
+{ 1 => 2, [3] => [4] }.decorated[[3]]
+    .decorated? # => true
+```
+
+##### Side effects for decorated collections
+
+- enables _splat_ operator: `*decorated` ,
+- enables _double-splat_ operator: `**decorated`,
+- enumerating methods yield decorated items.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/enumerable_decorator.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class EnumerableDecorator < Magic::Decorator::Base
+	def to_a(...)   = super.map &:decorated
+	def to_ary(...) = super.map &:decorated
+
+	def to_h(...)    = super.to_h { |*h| h.map! &:decorated }
+	def to_hash(...) = super.to_h { |*h| h.map! &:decorated }
+end

data/lib/magic/decoratable.rb

@@ -1,14 +1,28 @@
 # frozen_string_literal: true
 
+require 'active_support/concern'
+
 module Magic
 	module Decoratable
+		extend ActiveSupport::Concern
+
+		class_methods do
+			def classes
+				ObjectSpace.each_object(Class)
+						.select { _1 < self }
+			end
+		end
+
+		extend ClassMethods
+
 		def decorate   = decorator&.new self
-		def decorate!  = decorate || raise(Lookup::Error.for self, Decorator)
+		def decorate!  = decorate || raise(Lookup::Error.for self, decorator_base)
 		def decorated  = decorate || self
 		def decorated? = false
 
 		private
 
-		def decorator = Decorator.for self.class
+		def decorator      = decorator_base.for self.class
+		def decorator_base = Decorator
 	end
 end

data/lib/magic/decorator/base.rb

@@ -5,13 +5,56 @@ require 'delegate'
 module Magic
 	module Decorator
 		class Base < SimpleDelegator
-			extend Lookup
+			extend  Lookup
+			include Decoratable
 
 			class << self
 				def name_for(object_class) = "#{object_class}Decorator"
+
+				private
+
+				def undecorated method, *methods
+					return [ method, *methods ].map { undecorated _1 } if
+							methods.any?
+					return undecorated *method if
+							method.is_a? Array
+					raise TypeError, "#{method} is not a symbol nor a string" unless
+							method in Symbol | String
+
+					class_eval <<~RUBY, __FILE__, __LINE__ + 1
+						def #{method}(...) = __getobj__.#{method}(...)
+					RUBY
+				end
 			end
 
 			def decorated? = true
+
+			undecorated %i[
+					deconstruct
+					deconstruct_keys
+			]
+
+			def method_missing(method, ...)
+				return super if method.start_with? 'to_' # converter
+				return super if method.start_with? '_'   # system
+
+				if block_given?
+					super { |*args| yield *args.map(&:decorated) }
+				else
+					super
+				end.decorated
+			rescue NoMethodError => error
+				__raise__ error.class.new(
+						error.message.sub(self.class.name, __getobj__.class.name),
+						error.name,
+						error.args,
+				#		error.private_call?, # FIXME: not implemented in TruffleRuby
+
+						receiver: __getobj__
+				).tap {
+					_1.set_backtrace error.backtrace[2..] # FIXME: use `backtrace_locations` with Ruby 3.4+
+				}
+			end
 		end
 	end
 end

data/lib/magic/decorator/version.rb

@@ -2,6 +2,6 @@
 
 module Magic
 	module Decorator
-		VERSION = '0.1.0.1'
+		VERSION = '0.3.0'
 	end
 end

data/lib/magic/decorator.rb

@@ -18,3 +18,5 @@ module Magic
 		def name_for(...) = Base.name_for(...)
 	end
 end
+
+require 'enumerable_decorator'

data/sig/enumerable_decorator.rbs

@@ -0,0 +1,9 @@
+class EnumerableDecorator[unchecked out Element]
+	include _Each[Element, void]
+	include Enumerable[Element]
+
+	def to_ary: () -> ::Array[Element]
+
+	def to_hash: () -> ::Hash[untyped, untyped]
+			| [T, U] () { (Element) -> [T, U] } -> ::Hash[T, U]
+end

data/sig/magic/decoratable.rbs

@@ -1,13 +1,16 @@
 module Magic
 	module Decoratable
-		def decorate:  ->  Decorator?
-		def decorate!: ->  Decorator
-		def decorated: -> (Decorator | self)
+		def self.classes: () -> Array[Class]
 
-		def decorated?: -> bool
+		def decorate:  () ->  Decorator?
+		def decorate!: () ->  Decorator
+		def decorated: () -> (Decorator | self)
+
+		def decorated?: () -> bool
 
 		private
 
-		def decorator: -> Class?
+		def decorator:      () -> Class?
+		def decorator_base: () -> Module
 	end
 end

data/sig/magic/decorator/base.rbs

@@ -4,6 +4,12 @@ module Magic
 			extend Lookup
 
 			def decorated?: -> bool
+
+			private
+
+			def self.undecorated:      (interned)  -> Symbol
+					| (interned, interned, *interned)  -> Array[Symbol]
+					|                (Array[interned]) -> Array[Symbol]
 		end
 	end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: magic-decorator
 version: !ruby/object:Gem::Version
-  version: 0.1.0.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Alexander Senko
 bindir: bin
 cert_chain: []
-date: 2024-10-13 00:00:00.000000000 Z
+date: 2024-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: magic-lookup
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 'SimpleDelegator on steroids: automatic delegation, decorator class inference,
   etc.'
 email:
@@ -38,11 +52,13 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- lib/enumerable_decorator.rb
 - lib/magic/decoratable.rb
 - lib/magic/decorator.rb
 - lib/magic/decorator/authors.rb
 - lib/magic/decorator/base.rb
 - lib/magic/decorator/version.rb
+- sig/enumerable_decorator.rbs
 - sig/gem.rbs
 - sig/magic/decoratable.rbs
 - sig/magic/decorator.rbs
@@ -53,7 +69,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/Alexander-Senko/magic-decorator
   source_code_uri: https://github.com/Alexander-Senko/magic-decorator
-  changelog_uri: https://github.com/Alexander-Senko/magic-decorator/blob/v0.1.0.1/CHANGELOG.md
+  changelog_uri: https://github.com/Alexander-Senko/magic-decorator/blob/v0.3.0/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib