magic-decorator 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05eb0d1c9c1f08235269894f1ce906ca355d65239d9a708ad68078d9ebce7159
-  data.tar.gz: 679f113b552348de25243303de4550cda0774dd5e284bd4ec64c94c79471aecf
+  metadata.gz: 910cb75b4dedfce18a494e39779b65821642feb96a24f3cda7228deea96ccd04
+  data.tar.gz: 98603bb63196fa955b4aec3172ff6326f5be10371b0fffb96404a9f5cd84a86b
 SHA512:
-  metadata.gz: fb7bd90db8afc2235cc5a1b7f572b316a5494888a34a07052a7d77a2b20abc8d07444dca8e2e8436bb0a1dd6e8e61f8ddf15c80ed54ac5ee956a99e90bfbac4d
-  data.tar.gz: ddac7d0a18af55a99a561812660847f6935dd849c42287dd397466c520c392742580331526b33b98efe9a64020a9622e6dee92e60e177f08c8c0a5c4851310c3
+  metadata.gz: 4b4bfb9bbb3838ac81dc35527caddd9d42d86887e1019ad75c7aad5f21af03607a1540523555aa0669baef7705a989af99487d3fa0a925fe8fedca96749070e3
+  data.tar.gz: 9f1cc4b1b608fd9b795b2a296c7919e513ed0a9ea7a9c0d1957fe23e5f5b537edc7ea30985ccc02ce72ca5fac1c7707d8b44769502a4f702e426dd26c2ce1260

data/CHANGELOG.md

@@ -1,10 +1,31 @@
+## [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

@@ -47,20 +47,55 @@ 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
 ```
 
-#### 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_.
+
+### 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 +107,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/decorator/base.rb

@@ -9,9 +9,51 @@ module Magic
 
 			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'
+		VERSION = '0.2.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/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
+  version: 0.2.0
 platform: ruby
 authors:
 - Alexander Senko
 bindir: bin
 cert_chain: []
-date: 2024-10-13 00:00:00.000000000 Z
+date: 2024-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: magic-lookup
@@ -38,11 +38,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 +55,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/CHANGELOG.md
+  changelog_uri: https://github.com/Alexander-Senko/magic-decorator/blob/v0.2.0/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -61,7 +63,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - "~>"
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="