conventional_extensions 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7ae73a75b482203013f89eb32515cd611d1b198b8cedeba8681032185bf5f51a
+  data.tar.gz: 6952f8616ad0e94edab0822888d02fd881468110d0d0546ba5117ab5ec1a6d27
+SHA512:
+  metadata.gz: 9d1afc244d40c11bb184d0bbed288eac9f2f134d64e0a3957b5f7d08b69892914ba32e764c643d89c3612256e90d74888a8b31a00ad6ec48ff62068ed9f5a4c6
+  data.tar.gz: 22b5807a59e13c7a61bc7bebd6b91e7fac3617e2f3dc61d5119435c78a7a47eafc7540f46c00ca0b616f2f0151cce06300112b9df92e489b9481e9b65b874070

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2022-08-27
+
+- Initial release

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in conventional_extensions.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "minitest", "~> 5.0"

data/Gemfile.lock

@@ -0,0 +1,22 @@
+PATH
+  remote: .
+  specs:
+    conventional_extensions (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    minitest (5.16.3)
+    rake (13.0.6)
+
+PLATFORMS
+  arm64-darwin-20
+  x86_64-linux
+
+DEPENDENCIES
+  conventional_extensions!
+  minitest (~> 5.0)
+  rake (~> 13.0)
+
+BUNDLED WITH
+   2.3.21

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Kasper Timm Hansen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,186 @@
+# ConventionalExtensions
+
+ConventionalExtensions autoloads extensions to an object based on a file name convention.
+
+```ruby
+# lib/post.rb
+class Post < SomeSuperclass
+  load_extensions # Will load every Ruby file under `lib/post/extensions`.
+end
+```
+
+### Defining an extension
+
+Since the loading above happens after the `Post` constant has been defined, we can reopen the class in our extension:
+
+```ruby
+# lib/post/extensions/mailroom.rb
+class Post # <- Post is reopened here and so there's no superclass mismatch error
+  def mailroom
+    puts "you've got mail"
+  end
+end
+```
+
+Now, `Post.new.mailroom` works and `Post.instance_method(:mailroom).source_location` still points to the right file and line.
+
+#### Defining a class method in an extension
+
+Since we're reopening the class we can also define class methods directly:
+
+```ruby
+# lib/post/extensions/cool.rb
+class Post
+  def self.cool
+    puts "really cool"
+  end
+end
+```
+
+Now, `Post.cool` works and `Post.method(:cool).source_location` still points to the right file and line.
+
+Note, any class method macro extensions are available within the top-level Post definition too:
+
+```ruby
+# lib/post.rb
+class Post < SomeSuperclass
+  load_extensions # Loads the `cool` extension…
+
+  cool # …and now we can invoke the class method macro.
+end
+```
+
+### Skipping class reopening boilerplate
+
+ConventionalExtensions also supports implicit class reopening so you can skip `class Post`, like so:
+
+```ruby
+# lib/post/extensions/mailroom.rb
+def mailroom
+  puts "you've got mail"
+end
+```
+
+With this, `Post.new.mailroom` still works and `Post.instance_method(:mailroom).source_location` still points to right file and line.
+
+### Resolve dependencies with a manual `load_extensions`
+
+In case you need to have more fine grained control over the loading, you can call `load_extensions` from within an extension:
+
+```ruby
+# lib/post/extensions/mailroom.rb
+load_extension :named
+named :sup # We're depending on the class method macro from the `named` extension, and hoisting the loading.
+
+def mailroom
+  …
+end
+
+# lib/post/extensions/named.rb
+def self.named(key)
+  puts key
+end
+```
+
+### Supports `# frozen_string_literal: true`
+
+Whether extensions use explicit or implicit class reopening, `# frozen_string_literal: true` is supported.
+
+### Providing a base class that expects ConventionalExtensions loading
+
+In case you're planning on setting up a base class, where you're expecting subclasses to use extensions, you can do this:
+
+```ruby
+class BaseClass
+  extend ConventionalExtensions.load_on_inherited # This defines the `inherited` method to auto-call `load_extensions`
+end
+
+class Subclass < BaseClass
+  # No need to write `load_extensions` here
+end
+```
+
+## A less boilerplate heavy alternative to `ActiveSupport::Concern` for Active Records
+
+Typically, when writing an app domain model with `ActiveSupport::Concern` you end defining an object graph like this:
+
+```ruby
+# app/models/post.rb
+class Post < ApplicationRecord
+  include Cool, Mailroom
+end
+
+# app/models/post/cool.rb
+module Post::Cool
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def cool
+      puts "really cool"
+    end
+  end
+end
+
+# app/models/post/mailroom.rb
+module Post::Mailroom
+  extend ActiveSupport::Concern
+
+  included do
+    belongs_to :creator, class_name: "User"
+  end
+
+  def mailroom
+    puts "you've got mail"
+  end
+end
+```
+
+Both the `Post::Cool` and `Post::Mailroom` modules are here immediately loaded (via Zeitwerks file naming conventions) and included. More often than not they're never referred to again, so they're practically implicit modules, yet defined explicitly with a fair bit of DSL on top.
+
+With ConventionalExtensions you'd write this instead:
+
+```ruby
+# app/models/post.rb
+class Post < ApplicationRecord # ConventionalExtensions automatically loads extensions for Active Record models.
+end
+
+# app/models/post/extensions/cool.rb
+class Post
+  def self.cool
+    puts "really cool"
+  end
+end
+
+# app/models/post/extensions/mailroom.rb
+class Post
+  belongs_to :creator, class_name: "User"
+
+  def mailroom
+    puts "you've got mail"
+  end
+end
+```
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add conventional_extensions
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install conventional_extensions
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/kaspth/conventional_extensions.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+task default: :test

data/conventional_extensions.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "lib/conventional_extensions/version"
+
+Gem::Specification.new do |spec|
+  spec.name    = "conventional_extensions"
+  spec.version = ConventionalExtensions::VERSION
+  spec.authors = ["Kasper Timm Hansen"]
+  spec.email   = ["hey@kaspth.com"]
+
+  spec.summary  = "ConventionalExtensions sets up a file naming convention to extend your domain model"
+  spec.homepage = "https://github.com/kaspth/conventional_extensions"
+  spec.license  = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"]   = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+end

data/lib/conventional_extensions/loader.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class ConventionalExtensions::Loader
+  def initialize(klass, path)
+    @klass, @name = klass, klass.name
+    @directory_name = File.join path.match(/(?=\/extensions|\.rb)/).pre_match, "extensions/"
+  end
+
+  def load(*extensions)
+    paths = extensions.empty? ? extension_paths : extensions.map { extension_path_for _1 }
+    paths.each { load_one _1 }
+  end
+
+  private
+    def extension_paths
+      Dir.glob extension_path_for("*")
+    end
+
+    def extension_path_for(extension)
+      @directory_name + "#{extension}.rb"
+    end
+
+    def load_one(extension)
+      contents = File.read extension
+
+      case
+      when contents.match?(/\s*class #{@name}/)
+        require extension
+      when !$LOADED_FEATURES.include?(extension)
+        $LOADED_FEATURES << extension
+        @klass.class_eval contents, extension, 0
+      end
+    end
+end

data/lib/conventional_extensions/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ConventionalExtensions
+  VERSION = "0.1.0"
+end

data/lib/conventional_extensions.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "conventional_extensions/version"
+
+module ConventionalExtensions
+  Object.extend self # We're enriching object itself, so any object can call `load_extensions`.
+
+  def load_extensions(*extensions)
+    Loader.new(self, caller_locations(1, 1).first.path).load(*extensions)
+  end
+  alias load_extension load_extensions
+
+  # extend ConventionalExtensions.load_on_inherited
+  def self.load_on_inherited() = LoadOnInherited
+
+  module LoadOnInherited
+    def inherited(klass)
+      super
+      klass.load_extensions
+    end
+  end
+
+  autoload :Loader, "conventional_extensions/loader"
+end
+
+defined?(ActiveSupport.on_load) and ActiveSupport.on_load(:active_record) { extend ConventionalExtensions.load_on_inherited }

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: conventional_extensions
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kasper Timm Hansen
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-08-28 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- hey@kaspth.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- conventional_extensions.gemspec
+- lib/conventional_extensions.rb
+- lib/conventional_extensions/loader.rb
+- lib/conventional_extensions/version.rb
+homepage: https://github.com/kaspth/conventional_extensions
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kaspth/conventional_extensions
+  source_code_uri: https://github.com/kaspth/conventional_extensions
+  changelog_uri: https://github.com/kaspth/conventional_extensions/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.21
+signing_key:
+specification_version: 4
+summary: ConventionalExtensions sets up a file naming convention to extend your domain
+  model
+test_files: []