magic-decorator 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7cf3d435ee5af817990bfe657305a0112a012786540a89628a78d1bd6649dda
-  data.tar.gz: 61a1f7a7a3f1a8734ecb7ab5b8e414bd4055181d11a8ef2ef164868ecf27bbfa
+  metadata.gz: d922af068afa4289fc270fe9b007de813cff5b8855fc12ff925cfcbe0831d018
+  data.tar.gz: 0d95e22503c504847815bad194faf699614840be21fb2aadc231d47c107823a0
 SHA512:
-  metadata.gz: 8146547bc999da507600a3af86de3aaf174e27f66cd3e1b866e2e8e4703f92ef3a6c48f5a2ca217decc7950e645cc03af35a1e6a8f94db5849ef0663470bfe6c
-  data.tar.gz: d33c6fd8584763e694870b2047093964ecdf7ee770649fc0f7d3c89c3711c26108ee9f9dd7b7dfb6c76b3d9e7a3f08e5e902bfa9e5eb8241a366601993be0799
+  metadata.gz: 8a3c8d64bbf55a1a9aac586f3489b9ccead69dfb734d1352d44f908e5a8c6973de230d1a498615cef92ac59c4f0727f30c38ded0ed61072dcaf1ce78d0612485
+  data.tar.gz: ef85e806210c58a398d43f0bf558482ee62e94632757cb7de3e0e9c5c96ff1c56ff81ef069f88ddaef4c1b2154b1932f753d180f8b709ebddcd9659f346025a3

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [1.2.0] — 2026-10-28
+
+### Added
+
+- `Module#decorated_method`
+	to decorate method return values.
+
+
 ## [1.1.1] — 2026-10-27
 
 ### Fixed
@@ -46,7 +54,7 @@ This release marks the gem to be stable enough.
 
 - Improved extendability: one may override `Magic::Decoratable#decorator_base` to be used for lookups.
 - `Magic::Decoratable.classes`
-  for all the decoratables.
+	for all the decoratables.
 
 ### Fixed
 
@@ -58,7 +66,7 @@ This release marks the gem to be stable enough.
 ### 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:
+	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 `_`.
@@ -66,12 +74,12 @@ This release marks the gem to be stable enough.
 ### Added
 
 - `Magic::Decorator::Base.undecorated`
-  to exclude methods from being decorated automagically.
+	to exclude methods from being decorated automagically.
 
 #### Default decorators
 
 - `EnumerableDecorator`
-  to decorate `Enumerable`s.
+	to decorate `Enumerable`s.
 	- enables _splat_ operator: `*decorated` ,
 	- enables _double-splat_ operator: `**decorated`,
 	- enumerating methods yield decorated items.
@@ -82,9 +90,9 @@ This release marks the gem to be stable enough.
 ### Added
 
 - `Magic::Decorator::Base`
-  — a basic decorator class.
+	— a basic decorator class.
 - `Magic::Decoratable`
-  to be included in decoratable classes.
+	to be included in decoratable classes.
 	- `#decorate`,
 	- `#decorate!`,
 	- `#decorated`,

data/README.md

@@ -93,6 +93,38 @@ end
 Special::Model.new.decorate # looks for Special::Decorator descendants
 ```
 
+### Decorating methods
+
+`Module#decorated_method` decorates the return value of one or more existing instance methods by calling `#decorated` on it.
+It accepts method names as symbols or strings, either separately or in one array, and returns those names as `Module#private` does:
+
+```ruby
+class Account
+  decorated_method attr_reader :owner
+  decorated_method def address = owner.address
+  decorated_method :method_missing
+end
+```
+
+Calling it without arguments decorates instance methods defined afterward:
+
+```ruby
+class Account
+  decorated_method
+
+  attr_reader :owner
+  def address = owner.address
+end
+```
+
+Method arguments, keyword arguments, blocks, and visibility are preserved.
+
+> [!IMPORTANT]
+> This core class extension is not loaded by default and should be required explicitly if needed:
+> ```ruby
+> require 'magic/decorator/core_ext/module'
+> ```
+
 ## 🪄 Magic
 
 ### Decoratable scope

data/lib/enumerable_decorator.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# = Enumerable Decorator
+#
+# As the name suggests, it’s used automatically to decorate any
+# `Enumerable` collection. The collection itself doesn’t get decorated,
+# while its items do.
 class EnumerableDecorator < Magic::Decorator::Base
 	def to_a(...)   = super.map &:decorated
 	def to_ary(...) = super.map &:decorated

data/lib/magic/decoratable.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 module Magic
+	# = Decoratable object
+	#
+	# This module allows a descendant to be decorated. Decorator class is
+	# being inferred automatically via Magic Lookup.
 	module Decoratable
 		include Lookup::Scope
 

data/lib/magic/decorator/base.rb

@@ -4,6 +4,18 @@ require 'delegate'
 
 module Magic
 	module Decorator
+		# = Magic Decorator
+		#
+		# Any decorator should inherit `Magic::Decorator::Base`.
+		# It further inherits from `SimpleDelegator` and behaves like that.
+		#
+		# == Decorator class inference
+		#
+		# Decorators provide automatic class inference for any class based
+		# on its name powered by Magic Lookup.
+		# For example, `MyObject.new` looks for `MyObjectDecorator` first.
+		# If not found, it looks for decorators of its ancestor classes,
+		# up to `ObjectDecorator`.
 		class Base < SimpleDelegator
 			extend  Lookup
 			include Decoratable

data/lib/magic/decorator/core_ext/module.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# rubocop:disable Lint/EmptyInPattern
+
+require 'active_support/core_ext/module/redefine_method'
+
+# Extends Module with method return-value decoration.
+class Module
+	# Prepend it to decorate all subsequently defined instance methods.
+	module DecorateAllMethods
+		def method_added name
+			super
+
+			decorated_method name
+		end
+	end
+
+	# Decorates the return values of named instance methods.
+	#
+	# Like Module#private, names can be passed individually or as a single array.
+	# With no arguments, subsequently defined instance methods are decorated.
+	def decorated_method *methods
+		case methods
+		in []
+			singleton_class.prepend DecorateAllMethods
+
+			return
+		in [ Symbol | String => method ]
+		in [ (Symbol | String), * ]
+		in [ [ (Symbol | String), * ] | [] => methods ]
+		end
+
+		location = caller_locations(1, 1).first
+
+		methods.map do |method|
+			decorated_methods_module.module_eval <<~RUBY.strip, location.path, location.lineno
+				#{method_visibility method} def #{method}(...) = super.decorated
+			RUBY
+		end
+
+		method || methods
+	end
+
+	private
+
+	def decorated_methods_module
+		if const_defined? :DecoratedMethods, false
+			const_get :DecoratedMethods
+		else
+			const_set :DecoratedMethods, Module.new
+					.tap { it.include const_get :DecoratedMethods if const_defined? :DecoratedMethods } # inheritance
+					.tap { prepend it }
+		end
+	end
+end

data/lib/magic/decorator/version.rb

@@ -2,6 +2,6 @@
 
 module Magic
 	module Decorator
-		VERSION = '1.1.1'
+		VERSION = '1.2.0'
 	end
 end

data/lib/magic/decorator.rb

@@ -4,11 +4,15 @@ require 'magic/lookup'
 
 require_relative 'decorator/version'
 
-module Magic
+module Magic # :nodoc:
 	autoload :Decoratable, 'magic/decoratable'
 
 	Object.include Decoratable
 
+	# = Magic Decorator
+	#
+	# It implements a general decorator logic. It is not meant to be a
+	# presenter.
 	module Decorator
 		autoload :Base, 'magic/decorator/base'
 

data/sig/module.rbs

@@ -0,0 +1,10 @@
+class Module
+	def decorated_method: (interned) -> interned
+			| (interned, interned, *interned) -> Array[interned]
+			| (Array[interned])               -> Array[interned]
+			| -> nil
+
+	private
+
+	def decorated_methods_module: -> Module
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: magic-decorator
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
   - Alexander Senko
@@ -42,18 +42,20 @@ files:
   - lib/magic/decorator.rb
   - lib/magic/decorator/authors.rb
   - lib/magic/decorator/base.rb
+  - lib/magic/decorator/core_ext/module.rb
   - lib/magic/decorator/version.rb
   - sig/enumerable_decorator.rbs
   - sig/magic/decoratable.rbs
   - sig/magic/decorator.rbs
   - sig/magic/decorator/base.rbs
+  - sig/module.rbs
 homepage: "https://github.com/Alexander-Senko/magic-decorator"
 licenses:
   - MIT
 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/v1.1.1/CHANGELOG.md"
+  changelog_uri: "https://github.com/Alexander-Senko/magic-decorator/blob/v1.2.0/CHANGELOG.md"
 rdoc_options: []
 require_paths:
   - lib