magic-lookup 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 165ed4c613f3808aa064d20eecc5137a20b74ffca108e4b4edaab39e1de5c710
-  data.tar.gz: 8c57c00e753425063568765d62f4879a3848de727431663b4199c1e2cc119cd2
+  metadata.gz: 6c703f8d45523eb9fe156018f415b24d1eef923ae8abe72b549a8f66944b3d02
+  data.tar.gz: 7f473974c2a805aa8bfe766fb1fb0a58692098338a99f09dffbde0b2a6617899
 SHA512:
-  metadata.gz: a42291c47d5e2c2d4545f0c7cbb842c03c39ae4f683b177c339832864c1a33fc98b1cc2deadb15e16e87b069cf557fce80e5f8b70ee6bb479921b658704ae208
-  data.tar.gz: 04b6aaf11baa0644333869e36a0045503b996f13bb1854cc8670d2510220865310e8f01a8b406b56d424328dde9e0690d3d5d5b81cf58cd9c59079fa9eda56fa
+  metadata.gz: 68be2c2fb418fe82891c30e8fbc5e8a8b84bcdc3eed3eee8b696ce2cbbf8f538f92b950af599fd3710d977f15c8c0f8f9816784e55454b0995e333b8fa9d63cc
+  data.tar.gz: b00b16af1e3aedc9a5c900ef9144f3e669fae21d862b0d856819dfb7eac90320597c496a2ff56f1e117f265cb58ec9b337c1c173cc985868e47b87a812b6f433

data/.rubocop.yml

@@ -1,5 +1,7 @@
-inherit_from: https://github.com/Alexander-Senko/Alexander-Senko/raw/refs/heads/main/.rubocop.yml
+inherit_from:
+  - https://github.com/Alexander-Senko/Alexander-Senko/raw/refs/heads/main/.rubocop.yml
+  - https://github.com/Alexander-Senko/Alexander-Senko/raw/refs/heads/main/.rubocop-rspec.yml
 
-require:
+plugins:
   - rubocop-rspec
   - rubocop-rake

data/CHANGELOG.md

@@ -1,5 +1,22 @@
-## [Unreleased]
+## [0.3.0] — 2025-05-20
 
-## [0.1.0] - 2024-10-07
+### Added
 
-- Initial release
+- `Magic::Lookup#for` to consider `self` a part of a lookup scope.
+
+
+## [0.2.0] — 2024-10-19
+
+### Added
+
+- Optional `namespace` parameter to `Magic::Lookup#for` for class lookups within a namespace.
+- `Magic::Lookup#namespaces` to set default lookup namespaces.
+
+
+## [0.1.0] — 2024-10-10
+
+### Added
+
+- `Magic::Lookup#for` for name-based class lookups.
+- `Magic::Lookup::Error` to be used when lookup fails.
+- `Magic::Lookup::Error.for` factory helper.

data/README.md

@@ -1,3 +1,6 @@
+![GitHub Actions Workflow Status](
+	https://img.shields.io/github/actions/workflow/status/Alexander-Senko/magic-lookup/ci.yml
+)
 ![Code Climate maintainability](
 	https://img.shields.io/codeclimate/maintainability-percentage/Alexander-Senko/magic-lookup
 )
@@ -17,21 +20,19 @@ Moreover, inconsistencies across these implementations lead to misunderstanding
 
 So, meet
 
-# 🔮 Magic Lookup
+# 🔮 Magic Lookup
 
-It's meant to be The One to Rule Them All — the library to provide a generic name-based lookup for a plenty of cases.
+It’s meant to be _The One to Rule Them All_ — the library to provide a generic name-based lookup for a plenty of cases.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+    $ bundle add magic-lookup
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+    $ gem install magic-lookup
 
 ## Usage
 
@@ -68,9 +69,10 @@ scope_class = Scope.for(object.class) or
     raise Magic::Lookup::Error.for(object, Scope)
 ```
 
-`Magic::Lookup::Error` is never raised internally and is meant to be used in your code that implements the lookup logic.
+> [!NOTE]
+> `Magic::Lookup::Error` is never raised internally and is meant to be used in your code that implements the lookup logic.
 
-## Features
+## 🔮 Magic
 
 ### Inheritance
 
@@ -80,11 +82,33 @@ Lookup is provided not only for the class itself, but to any of its ancestors as
 
 Both of matching classes — the target and its match — may be namespaced independently.
 
+One can specify a namespace to look in:
+
+```ruby
+Scope.for MyModel              # => MyScope
+Scope.for MyModel, MyNamespace # => MyNamespace::MyScope
+```
+
+Multiple default lookup namespaces may be set for the base class:
+
+```ruby
+Scope.namespaces << MyNamespace # => [nil, MyNamespace]
+Scope.for MyModel               # => MyNamespace::MyScope
+```
+
 > [!TIP]
 > Until a comprehensive documentation on all the use cases is released, the spec is recommended as further reading.
 > One can access it by running `rake` in the gem directory.
 > The output is quite descriptive to get familiar with the use cases.
 
+## Known issues
+
+### https://github.com/Alexander-Senko/magic-lookup/issues/1
+
+> [!IMPORTANT]
+> Magic Lookup doesn’t try to autoload any classes, it searches among already loaded ones instead.
+> Thus, one should preload all classes that need to be accessible via the lookup.
+
 ## 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/lookup/authors.rb

@@ -9,8 +9,8 @@ Gem::Author ||= Struct.new(
 end
 
 module Magic
-	module Lookup
-		AUTHORS = [
+	module Lookup # :nodoc:
+		AUTHORS = [ # rubocop:disable Style/MutableConstant
 				Gem::Author.new(
 						name:   'Alexander Senko',
 						email:  'Alexander.Senko@gmail.com',

data/lib/magic/lookup/error.rb

@@ -2,6 +2,17 @@
 
 module Magic
 	module Lookup
+		# = Magic Lookup Error
+		#
+		# When no class is found, `nil` is returned. If you need to raise
+		# an exception in this case, you can use `Magic::Lookup::Error`
+		# like this:
+		#
+		#     scope_class = Scope.for(object.class) or
+		#         raise Magic::Lookup::Error.for(object, Scope)
+		#
+		# `Magic::Lookup::Error` is never raised internally and is meant
+		# to be used by a class implementing the lookup logic.
 		class Error < NameError
 			def self.for object, lookup_class
 				default_name = lookup_class.name_for object.class

data/lib/magic/lookup/namespaces.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Magic
+	module Lookup
+		module Namespaces # :nodoc:
+			attr_writer :namespaces
+
+			def namespaces = @namespaces ||= [ nil ]
+
+			def for object_class, *namespaces
+				return super unless namespaces.empty?
+
+				self.namespaces
+						.reverse # recently added first
+						.lazy    # optimization
+						.filter_map { super object_class, _1 }
+						.first
+			end
+		end
+	end
+end

data/lib/magic/lookup/version.rb

@@ -2,6 +2,6 @@
 
 module Magic
 	module Lookup
-		VERSION = '0.1.0'
+		VERSION = '0.3.0'
 	end
 end

data/lib/magic/lookup.rb

@@ -5,25 +5,56 @@ require_relative 'lookup/version'
 require 'memery'
 
 module Magic
+	# = Magic Lookup
+	#
+	# These are the steps to set up an automatic class inference:
+	#
+	# 1. Define a base class extending `Magic::Lookup`.
+	# 2. Define `.name_for` method for that class implementing your
+	#    lookup logic.
+	# 3. From the base class, inherit classes to be looked up.
+	#
+	# Example:
+	#
+	#     class Scope
+	#       extend Magic::Lookup
+	#
+	#       def self.name_for object_class
+	#         object_class.name
+	#             .delete_suffix('Model')
+	#             .concat('Scope')
+	#       end
+	#     end
+	#
+	#     class MyScope < Scope
+	#     end
+	#
+	#     Scope.for MyModel    # => MyScope
+	#     Scope.for OtherModel # => nil
 	module Lookup
-		autoload :Error, 'magic/lookup/error'
+		autoload :Error,      'magic/lookup/error'
+		autoload :Namespaces, 'magic/lookup/namespaces'
 
 		include Memery
 
-		memoize def for object_class
+		memoize def for object_class, namespace = nil
 			descendants = self.descendants # cache
+					.union([ self ]) # including self
 					.reverse # most specific first
 
 			object_class.ancestors
 					.lazy # optimization
 					.filter(&:name)
 					.map { name_for _1 }
+					.map { [ *namespace, _1 ] * '::' }
 					.filter_map do |class_name|
 						descendants.find { _1.name == class_name }
 					end
 					.first
 		end
 
+		prepend Namespaces
+
 		def name_for(object_class) = raise NotImplementedError
 
 		def descendants

data/sig/magic/lookup.rbs

@@ -3,7 +3,7 @@ module Magic
 		VERSION: String
 		AUTHORS: Array[Gem::Author]
 
-		def for: (Class) -> Class?
+		def for: (Class, ?(Module | interned) namespace) -> Class?
 
 		def name_for: (Module) -> String
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: magic-lookup
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Alexander Senko
 bindir: bin
 cert_chain: []
-date: 2024-10-10 00:00:00.000000000 Z
+date: 2025-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: memery
@@ -41,6 +41,7 @@ files:
 - lib/magic/lookup.rb
 - lib/magic/lookup/authors.rb
 - lib/magic/lookup/error.rb
+- lib/magic/lookup/namespaces.rb
 - lib/magic/lookup/version.rb
 - sig/gem.rbs
 - sig/magic/lookup.rbs
@@ -51,7 +52,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/Alexander-Senko/magic-lookup
   source_code_uri: https://github.com/Alexander-Senko/magic-lookup
-  changelog_uri: https://github.com/Alexander-Senko/magic-lookup/blob/v0.1.0/CHANGELOG.md
+  changelog_uri: https://github.com/Alexander-Senko/magic-lookup/blob/v0.3.0/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -66,7 +67,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.0.dev
+rubygems_version: 3.6.5
 specification_version: 4
 summary: Related class inference with some magic involved
 test_files: []