aspectual 0.1.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 6f66580a8019b4635fd8323ea0c6a15307d5ff56
-  data.tar.gz: 379cbabcd70d9e26ab8dec1128450f3638c963a2
+SHA256:
+  metadata.gz: 817c7afcb4818012c3ff63a90b9cd1d98b5c485fc9fe9970cb6b2e44a24328cd
+  data.tar.gz: 9bb74cc472397a9c2dbc7c9360bd5e63801ced7f54cc46b241e6911239f924ec
 SHA512:
-  metadata.gz: 81e877cabfbcdfec9b810cbb4c1682212cd98e1c5db5a9747cdbae25f36dceed8834a68cc502318e7c71113b51d68eb642b8fdb4b8b4cd4446a762031486f982
-  data.tar.gz: 5c8384f1dda770edced49d1eb1b8b85aeb7e19b61e178295cc8e68cd4a67673561fe61558a209da206a8ffabe39fe579653b97b3d840e0f78e2bf3410d33938b
+  metadata.gz: 601bf77bb2417fd3c2592c1f8774050ed233c35840ba44fcfd763f86446cbb1e9c1dc3e0808debacd505410fc19d10b57b49c81df9a42f6ed1ffec1321dbd38d
+  data.tar.gz: 77d715ff59e1b2773d085e5cefee6e5496521414f4a19ae70371dad02f2ba60fc69d7d43bdc4a9009a184cfca8be9f3570578d3e90f84c16fac776eb59f33199

data/.github/workflows/rubocop.yml

@@ -0,0 +1,37 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Rubocop verification
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.1', '3.2', '3.3', '3.4', '4.0']
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@8e41b362d2589a22a44c1cfa214b3c83052c195b # v1.318.0
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run rubocop
+      run: bundle exec rubocop

data/.github/workflows/ruby.yml

@@ -0,0 +1,37 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby version compatibility
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.1', '3.2', '3.3', '3.4', '4.0']
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@8e41b362d2589a22a44c1cfa214b3c83052c195b # v1.318.0
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rspec

data/.rubocop.yml

@@ -0,0 +1,39 @@
+plugins:
+  - rubocop-rspec
+AllCops:
+  NewCops: enable
+Metrics/BlockLength:
+  Exclude:
+    # rspec blocks can get very long
+    - 'spec/**/*'
+Metrics/ClassLength:
+  Exclude:
+    # our spec Classes can get very long
+    - 'spec/**/*'
+Metrics/ModuleLength:
+  CountAsOne:
+    - array
+    - hash
+    - method_call
+Metrics/MethodLength:
+  CountAsOne:
+    - array
+    - hash
+    - method_call
+Naming/VariableNumber:
+  EnforcedStyle: snake_case
+RSpec/ExampleLength:
+  CountAsOne:
+    - array
+    - hash
+    - method_call
+RSpec/NestedGroups:
+  Max: 4
+RSpec/RepeatedExample:
+  Enabled: false
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: consistent_comma
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: consistent_comma

data/Gemfile

@@ -1,4 +1,10 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in overload.gemspec
+gem 'bundler'
+gem 'rspec'
+gem 'rubocop'
+gem 'rubocop-rspec'
+
 gemspec

data/README.md

@@ -12,11 +12,11 @@ Add this line to your application's Gemfile:
 
 And then execute:
 
-    $ bundle
+    bundle install
 
 Or install it yourself as:
 
-    $ gem install aspectual
+    gem install aspectual
 
 ## Usage
 
@@ -24,20 +24,80 @@ Extend the module
 
     extend Aspectual
 
-Create any methods you want as aspects (Aspectual will not add methods you don't have as aspects)
+### Implicit method aspects
 
-Then declare your aspects
+Aspectual supports implicitly defining your aspects directly before a method.
+This method of defining aspects will hook into the next defined method,
+assigning those aspects to that method:
 
-    aspects before: :logging, after: :more_logging
+    aspects before: :logging, around: fancy_logging, after: :more_logging
     def foo
       "foo"
     end
 
-    aspects before: [:notify_user, :notify_admin], after: [:remove_temp_files, :play_sound]
+    aspects before: [:notify_user, :notify_admin], around: [:setup_and_teardown, :play_background_music], after: [:remove_temp_files, :play_sound]
     def bar
       "bar"
     end
 
+### Explicit method aspects
+
+Aspectual supports defining your aspects associated with a specific method,
+which will be added either immediately (if the method is defined) or when that
+method is first defined on the associated class.
+
+    def foo
+      "foo"
+    end
+
+    aspects :foo, before: :logging, around: fancy_logging, after: :more_logging
+
+    aspects :bar, before: [:notify_user, :notify_admin], around: [:setup_and_teardown, :play_background_music], after: [:remove_temp_files, :play_sound]
+
+    def bar
+      "bar"
+    end
+
+### Inheriting aspects
+
+Aspectual supports defining aspects in a parent class, when those methods will
+be defined in a child class. Aspectual will attach the aspects to the next
+definition of the named method, to support child classes inheriting aspected
+behaviors.
+
+    class Foo
+      aspects :foo, before: :logging, around: fancy_logging, after: :more_logging
+    end
+
+    class Bar < Foo
+      def foo
+        "foo"
+      end
+    end
+
+This behavior means that defining an aspect on an interface that is implemented
+will require a call to `super` to invoke those aspects:
+
+    class Foo
+      aspects :foo, before: :logging, around: fancy_logging, after: :more_logging
+      def foo
+        "foo"
+      end
+    end
+
+    class Bar < Foo
+      def foo
+        super + "bar"
+      end
+    end
+
+    class Baz < Foo
+      # Does not call aspects defined in Foo
+      def foo
+        "baz"
+      end
+    end
+
 ## Contributing
 
 1. Fork it

data/aspectual.gemspec

@@ -1,26 +1,27 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+require 'English'
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'aspectual/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "aspectual"
+  spec.name          = 'aspectual'
   spec.version       = Aspectual::VERSION
-  spec.authors       = ["Alex Sunderland"]
-  spec.email         = ["agentantelope+aspectual@gmail.com"]
-  spec.description   = %q{
+  spec.authors       = ['Fell Sunderland']
+  spec.email         = ['agentantelope+aspectual@gmail.com']
+  spec.description   = '
     A simple gem to support minimal Aspect Oriented Programming in ruby.
-  }
-  spec.summary       = %q{A gem to help with AOP.}
-  spec.homepage      = "https://github.com/AgentAntelope/aspectual"
-  spec.license       = "MIT"
+  '
+  spec.summary       = 'A gem to help with AOP.'
+  spec.homepage      = 'https://github.com/AgentAntelope/aspectual'
+  spec.license       = 'MIT'
 
-  spec.files         = `git ls-files`.split($/).reject {|f| f.end_with?('gem')}
+  spec.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR).reject { |f| f.end_with?('gem') }
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 3.1'
 
-  spec.add_development_dependency "bundler"
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "rspec"
+  spec.metadata['rubygems_mfa_required'] = 'true'
 end

data/lib/aspectual/method_construction.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Aspectual
+  # Used to build up aspect methods to replace the methods Aspectual wraps
+  module MethodConstruction
+    private
+
+    def define_aspect_method(method_name:, position:, aspect:)
+      # This is to prevent us from looping because we're about to define some
+      # methods.
+      @_defining_method = true
+
+      with_method_name = with_aspect_method_name(
+        target: method_name, position:, feature: aspect,
+      )
+
+      with_method_proc = build_with_method_proc(aspect:, position:, method_name:)
+
+      define_method(with_method_name, with_method_proc)
+
+      scope_method_to_parent(
+        scope_method_name: method_name,
+        new_method_name: with_method_name,
+      )
+
+      alias_method_chain(target: method_name, feature: aspect, position:)
+
+      @_defining_method = false
+    end
+
+    def build_with_method_proc(aspect:, position:, method_name:)
+      without_method_name = without_aspect_method_name(
+        target: method_name, position:, feature: aspect,
+      )
+
+      case position
+      when BEFORE_ASPECT
+        before_lambda(aspect:, without_method_name:)
+      when AROUND_ASPECT
+        around_lambda(aspect:, without_method_name:)
+      when AFTER_ASPECT
+        after_lambda(aspect:, without_method_name:)
+      end
+    end
+
+    def before_lambda(aspect:, without_method_name:)
+      lambda do |*args, **kwargs, &blk|
+        # first, call the aspect
+        send(aspect, *args, **kwargs, &blk)
+
+        # then, call the method without the aspect
+        send(without_method_name, *args, **kwargs, &blk)
+      end
+    end
+
+    def around_lambda(aspect:, without_method_name:)
+      lambda do |*args, **kwargs, &blk|
+        send(aspect, *args, **kwargs, &proc do
+          send(without_method_name, *args, **kwargs, &blk)
+        end)
+      end
+    end
+
+    def after_lambda(aspect:, without_method_name:)
+      lambda do |*args, **kwargs, &blk|
+        # first, call the method without the aspect
+        send(without_method_name, *args, **kwargs, &blk)
+
+        # then, call the aspect
+        send(aspect, *args, **kwargs, &blk)
+      end
+    end
+
+    def scope_method_to_parent(scope_method_name:, new_method_name:)
+      if public_method_defined?(scope_method_name)
+        public new_method_name
+      elsif protected_method_defined?(scope_method_name)
+        protected new_method_name
+      elsif private_method_defined?(scope_method_name)
+        private new_method_name
+      end
+    end
+
+    # adapted from ActiveSupport
+    def alias_method_chain(target:, feature:, position:)
+      with_method_name = with_aspect_method_name(target:, position:, feature:)
+      without_method_name = without_aspect_method_name(target:, position:, feature:)
+
+      alias_method(without_method_name, target)
+      alias_method(target, with_method_name)
+
+      scope_method_to_parent(
+        scope_method_name: without_method_name,
+        new_method_name: target,
+      )
+    end
+
+    def with_aspect_method_name(target:, position:, feature:)
+      target, punctuation = *safe_target(target:)
+
+      # Produce something like: :target_with_position_feature (with possible
+      # punctuation on the end)
+      :"#{target}_with_#{position}_#{feature}#{punctuation}"
+    end
+
+    def without_aspect_method_name(target:, position:, feature:)
+      target, punctuation = *safe_target(target:)
+
+      # Produce something like: :target_without_position_feature (with possible
+      # punctuation on the end)
+      :"#{target}_without_#{position}_#{feature}#{punctuation}"
+    end
+
+    def safe_target(target:)
+      # Extract punctuation on methods ending in one of !, ?, or = since e.g.
+      # target?_without_position_feature should properly be
+      # target_without_position_feature?.
+      target.to_s.scan(/(.*)([?!=])?$/).flatten
+    end
+  end
+end

data/lib/aspectual/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Aspectual
-  VERSION = '0.1.1'
+  VERSION = '0.9.0'
 end

data/lib/aspectual.rb

@@ -1,85 +1,125 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
+# Aspectual allows Aspect Oriented Programming in Ruby.
 module Aspectual
-  def aspects(aspects)
-    # The before aspect have to be reversed so that when multiple before
-    # aspects are added to one method, the first declared method will be
-    # added last.
-    @_before_aspects = Array(aspects[:before]).reverse
-    @_around_aspects = Array(aspects[:around]).reverse
-    @_after_aspects  = Array(aspects[:after])
-  end
-
-  def method_added(method_symbol)
-    return unless has_aspects_declared?
-    return if @_defining_method
-    if method_defined?(method_symbol)
-
-      %w{before around after}.each do |position|
-        current_aspects = instance_variable_get("@_#{position}_aspects")
-        if current_aspects
-          current_aspects.each do |aspect|
-            define_aspect_method(method_symbol, position, aspect)
-          end
-        end
-      end
+  require_relative 'aspectual/method_construction'
+
+  include MethodConstruction
+
+  # This order is important to ensure we're assigning aspects in the correct
+  # order: Before comes before around, so needs to be added to the method after
+  VALID_ASPECTS = [
+    AROUND_ASPECT = :around,
+    BEFORE_ASPECT = :before,
+    AFTER_ASPECT  = :after,
+  ].freeze
+
+  BLANK_ASPECT = VALID_ASPECTS.to_h { [_1, [].freeze] }.freeze
+
+  NEXT_METHOD_ADDED_KEY = :_next_method_added
+
+  # Special default value for next method added
+  DEFAULT_ASPECTS = { NEXT_METHOD_ADDED_KEY => BLANK_ASPECT }.freeze
+
+  def aspects(*method_names, before: [], around: [], after: [])
+    method_names = [NEXT_METHOD_ADDED_KEY] if method_names.empty?
+    method_names.each do |method_name|
+      merge_aspects(
+        method_name:,
+        new_aspects: {
+          BEFORE_ASPECT => Array(before),
+          AROUND_ASPECT => Array(around),
+          AFTER_ASPECT => Array(after),
+        },
+      )
+
+      # If we already defined the method we're adding aspects for, we need to
+      # process that straight away.
+      next unless method_defined?(method_name) || private_method_defined?(method_name)
+
+      add_aspects_to_method(method_name:)
     end
   end
 
-  private
+  def method_added(method_name)
+    add_aspects_to_method(method_name:)
 
-  def has_aspects_declared?
-    @_before_aspects || @_after_aspects
+    super
   end
 
-  def define_aspect_method(method_symbol, position, aspect)
-    # This is to prevent us from looping because we're about to define some methods.
-    @_defining_method = true
-
-    with_aspect_method_name = method_symbol.to_s + "_with_#{position}_" + aspect.to_s
-    without_aspect_method_name = method_symbol.to_s + "_without_#{position}_" + aspect.to_s
+  def defined_aspects
+    return @defined_aspects if defined?(@defined_aspects)
 
-    case position
-    when "before"
-      aspect_proc = lambda {|*args| send(aspect, *args); send(without_aspect_method_name, *args)}
-    when "around"
-      aspect_proc = lambda {|*args| send(aspect, *args, &Proc.new{send(without_aspect_method_name, *args)})}
-    when "after"
-      aspect_proc = lambda {|*args| send(without_aspect_method_name, *args); send(aspect, *args)}
+    aspected_ancestor = ancestors[1..].detect do |klass|
+      klass.is_a?(Aspectual)
     end
 
-    define_method(with_aspect_method_name, aspect_proc)
+    @defined_aspects = Marshal.load(
+      Marshal.dump(
+        aspected_ancestor&.defined_aspects || DEFAULT_ASPECTS,
+      ),
+    )
+  end
 
-    scope_method_to_parent(method_symbol, with_aspect_method_name)
+  private
 
-    alias_method_chain(method_symbol, aspect.to_sym, position)
+  attr_writer :defined_aspects
 
-    @_defining_method = false
+  def can_define_aspect?(aspects:, method_name:)
+    # If there are no defined aspects we have nothing to do
+    aspects.values.any?(&:any?) &&
+      # the method we're adding aspects to needs to have been defined
+      (method_defined?(method_name) || private_method_defined?(method_name))
   end
 
-  def scope_method_to_parent(without_method, target)
-    case
-    when public_method_defined?(without_method)
-      public target
-    when protected_method_defined?(without_method)
-      protected target
-    when private_method_defined?(without_method)
-      private target
+  def add_aspects_to_method(method_name:)
+    return if @_defining_method
+
+    aspects = calculate_aspects(method_name:)
+
+    return unless can_define_aspect?(aspects:, method_name:)
+
+    # Remove the aspects for this method, in case we see multiple definitions
+    # of a single method (i.e. inheritance)
+    defined_aspects.delete(method_name)
+
+    aspects.each do |position, positional_aspects|
+      positional_aspects.each do |aspect|
+        define_aspect_method(method_name:, position:, aspect:)
+      end
     end
   end
 
-  # adapted from active support
-  def alias_method_chain(target, feature, position)
-    # Strip out punctuation on predicates or bang methods since
-    # e.g. target?_without_position_feature is not a valid method name.
-    aliased_target, punctuation = target.to_s.sub(/([?!=])$/, ''), $1
+  def calculate_aspects(method_name:)
+    merge_aspects(
+      method_name:,
+      new_aspects: defined_aspects.fetch(NEXT_METHOD_ADDED_KEY, BLANK_ASPECT),
+    )
 
-    with_method = "#{aliased_target}_with_#{position}_#{feature}#{punctuation}"
-    without_method = "#{aliased_target}_without_#{position}_#{feature}#{punctuation}"
+    # Blank out the aspects for the next method added
+    defined_aspects[NEXT_METHOD_ADDED_KEY] = BLANK_ASPECT
 
-    alias_method without_method, target
-    alias_method target, with_method
+    defined_aspects[method_name] || BLANK_ASPECT
+  end
 
-    scope_method_to_parent(without_method, target)
+  def merge_aspects(method_name:, new_aspects:)
+    return defined_aspects if new_aspects == BLANK_ASPECT
+
+    self.defined_aspects = defined_aspects.merge(
+      { method_name => new_aspects },
+    ) do |_aspected_method_name, old_config, new_config|
+      old_config.merge(new_config) do |aspect, old_aspects, new_aspects|
+        case aspect
+        when BEFORE_ASPECT, AROUND_ASPECT
+          # The before and around aspects have to be reversed so that when
+          # multiple aspects are added to one method, the first declared method
+          # will be added last.
+          (new_aspects.reverse + old_aspects).uniq
+        else
+          (old_aspects + new_aspects).uniq
+        end
+      end
+    end
   end
 end

data/spec/lib/aspectual_block_args_spec.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/aspectual'
+
+class BlockArgsTestClass
+  extend Aspectual
+
+  attr_reader :methods_called
+
+  def initialize
+    # This is to ensure that all methods are properly called within the
+    # context of the current instance of this object.
+    @methods_called = []
+  end
+
+  def block_aspect_method(&block)
+    methods_called << "block_aspect_method_block_result_#{block.call}"
+    self
+  end
+
+  def block_around_aspect_method(&block)
+    methods_called << 'before_block_block_around_aspect_method_block'
+    block.call
+    methods_called << 'after_block_block_around_aspect_method_block'
+    self
+  end
+
+  aspects before: :block_aspect_method
+  def before_block_test_method(&block)
+    methods_called << "before_block_test_method_block_result_#{block.call}"
+    self
+  end
+
+  aspects around: :block_around_aspect_method
+  def around_block_test_method(&block)
+    methods_called << "around_block_test_method_block_result_#{block.call}"
+    self
+  end
+
+  aspects after: :block_aspect_method
+  def after_block_test_method(&block)
+    methods_called << "after_block_test_method_block_result_#{block.call}"
+    self
+  end
+end
+
+describe Aspectual do
+  describe 'methods with block arguments' do
+    it 'can handle before aspects' do
+      test_instance = BlockArgsTestClass.new.before_block_test_method { 'called' }
+      expect(test_instance.methods_called).to eq(%w[
+                                                   block_aspect_method_block_result_called
+                                                   before_block_test_method_block_result_called
+                                                 ])
+    end
+
+    it 'can handle around aspects' do
+      test_instance = BlockArgsTestClass.new.around_block_test_method { 'called' }
+      expect(test_instance.methods_called).to eq(%w[
+                                                   before_block_block_around_aspect_method_block
+                                                   around_block_test_method_block_result_called
+                                                   after_block_block_around_aspect_method_block
+                                                 ])
+    end
+
+    it 'can handle after aspects' do
+      test_instance = BlockArgsTestClass.new.after_block_test_method { 'called' }
+      expect(test_instance.methods_called).to eq(%w[
+                                                   after_block_test_method_block_result_called
+                                                   block_aspect_method_block_result_called
+                                                 ])
+    end
+  end
+end