magic-decorator 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 910cb75b4dedfce18a494e39779b65821642feb96a24f3cda7228deea96ccd04
-  data.tar.gz: 98603bb63196fa955b4aec3172ff6326f5be10371b0fffb96404a9f5cd84a86b
+  metadata.gz: 84b46e61d09d011e36bfd527b1e99bf9b83a7d3d4844f9afcd11304abd5c7990
+  data.tar.gz: 22f50120c5b4b8b2887d28b3e909f698128c04a37293c9409d93411dddb1f2e3
 SHA512:
-  metadata.gz: 4b4bfb9bbb3838ac81dc35527caddd9d42d86887e1019ad75c7aad5f21af03607a1540523555aa0669baef7705a989af99487d3fa0a925fe8fedca96749070e3
-  data.tar.gz: 9f1cc4b1b608fd9b795b2a296c7919e513ed0a9ea7a9c0d1957fe23e5f5b537edc7ea30985ccc02ce72ca5fac1c7707d8b44769502a4f702e426dd26c2ce1260
+  metadata.gz: 0ad5fc1e9e7cf8fab9a75a792cc31f027e113e95f7968ee2f6502b113c4f8f943bf7f111fa599929896e6bf7a3a77cf7cf13d46c6fe58dd52e770fc109278d42
+  data.tar.gz: 743f50f6835be84d59028240ec9c306df79f8647c90d4b4c34d39eb9e462741cbfc3f0ebde4bea447c0a94b731e61a8e370c497d84821bfe9dfa4272771f3d8b

data/CHANGELOG.md

@@ -1,3 +1,28 @@
+## [1.0.0] — 2024-11-23
+
+This release marks the gem to be stable enough.
+
+> [!NOTE]
+> Nothing notable was changed in the code since the last version.
+
+### Documentation
+
+- Added a section about overriding the defaults.
+- Added a section about testing.
+
+
+## [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
@@ -19,6 +44,7 @@
 	- enables _double-splat_ operator: `**decorated`,
 	- enumerating methods yield decorated items.
 
+
 ## [0.1.0] — 2024-10-13
 
 ### Added

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
 )
@@ -60,12 +63,40 @@ One can test for the object is actually decorated with `#decorated?`.
     .decorated? # => true
 ```
 
-## Magic
+### 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
 
 ### 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.
@@ -134,6 +165,51 @@ It automagically decorates all its decoratable items.
 - enables _double-splat_ operator: `**decorated`,
 - enumerating methods yield decorated items.
 
+## Overriding the magic
+
+When one needs more complicated behavior than the default one or feels like [_explicit is better than implicit_](
+	https://peps.python.org/pep-0020/#the-zen-of-python
+).
+
+### Decorator class inference
+
+One may override `#decorator` for any decoratable class, to be used instead of Magic Lookup.
+
+- That could be as straightforward as a constant:
+
+	```ruby
+	class Guest
+	  private
+	
+	  def decorator = UserDecorator
+	end
+	
+	guest.decorate # => instance of UserDecorator
+	```
+
+- Or, that could be virtually any logic:
+
+	```ruby
+	class User
+	  private
+	
+	  def decorator = admin? ? AdminDecorator : super
+	end
+	
+	user.decorate  # => instance of UserDecorator
+	admin.decorate # => instance of AdminDecorator
+	```
+
+## Testing decorators
+
+Testing a decorator is much like testing any other class.
+
+To test whether an object is decorated one can use `#decorated?` method.
+
+> [!NOTE]
+> A decorated object equals the original one (`object.decorated == object`).
+> Thus, any existing tests shouldn’t break when the objects being tested get decorated.
+
 ## 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/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,7 +5,8 @@ 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"
@@ -33,6 +34,8 @@ module Magic
 					deconstruct_keys
 			]
 
+			private
+
 			def method_missing(method, ...)
 				return super if method.start_with? 'to_' # converter
 				return super if method.start_with? '_'   # system

data/lib/magic/decorator/version.rb

@@ -2,6 +2,6 @@
 
 module Magic
 	module Decorator
-		VERSION = '0.2.0'
+		VERSION = '1.0.0'
 	end
 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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: magic-decorator
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Alexander Senko
 bindir: bin
 cert_chain: []
-date: 2024-10-17 00:00:00.000000000 Z
+date: 2024-11-23 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:
@@ -55,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.2.0/CHANGELOG.md
+  changelog_uri: https://github.com/Alexander-Senko/magic-decorator/blob/v1.0.0/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib