active_interface 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 42dde65b9a4587eb6f8523824689d6777401ed5c870b5dc6695a49bd41e68332
+  data.tar.gz: f30a127da41095e8d13808acb4ac339ec9e0efa2a0d7f8da16a975bd29e7bc40
+SHA512:
+  metadata.gz: eaba98da8342d0f3f5b4c3e26079809be1166ff2473a3fb17e1fafa0ffc935d0ea79c8ddb47482b45ffdecd5ab6343029ea562ee7141e339956f57b8f83af529
+  data.tar.gz: 3d9a69a81a23576379b96f25544c2b12d39bcef516e2e35213574049cb523c0d8e385e6c4a5b1b4a3d94ce31d792b778ca2328b83a6ae32c71b90bb990814b61

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,40 @@
+PATH
+  remote: .
+  specs:
+    active_interface (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coderay (1.1.3)
+    diff-lcs (1.5.0)
+    method_source (1.0.0)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    rake (13.0.6)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.1)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
+
+PLATFORMS
+  arm64-darwin-21
+
+DEPENDENCIES
+  active_interface!
+  pry (~> 0.14)
+  rake (~> 13.0)
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   2.3.8

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Russell Jennings
+
+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,122 @@
+# active_interface
+
+ActiveInterface is a Ruby library for defining OOP interfaces in ruby 
+
+## Getting Started
+
+Add to your Gemfile
+
+```
+  gem 'active_interface'
+```
+
+Then Bundle install. Now create a directory like `app/interfaces` and put your first interface there. Any methods defined (or attributes specified in `REQUIRED_ATTRIBUTES`) will be enforced on the class the interface is appended to. 
+
+```
+module ExampleInterface  
+  extend ActiveInterface::Base
+  
+  REQUIRED_ATTRIBUTES = %i[size count count=].freeze
+
+  def example
+    super
+  end
+end
+```
+
+Make sure any methods defined either call `super` or  `interface_contract` (more info below) in order for the underlying method to be executed.
+
+for any class that you want to apply this interface to, append it after the definition. This ensures all the methods are defined by the class, and that when the Interface is appended that it will sit in front of the method calls and act as a pass through.   
+
+```
+class MyClass
+  ...
+end
+MyClass.append ExampleInterface
+```
+
+## What's an OOP interface?
+
+An interfaces allows developers to define an abstract collection of methods and attributes that must be implemented by a class. This allows developers to code against an abstract interface (that many classes could implement) instead of just a specific classes implementation. 
+
+Given the following class
+```
+class User
+
+  attr_accessor :first_name, :last_name
+
+  def full_name(seperator)
+    first_name + seperator + last_name
+  end
+end
+```
+
+if we also want a `Contact` or `Admin` to have the same behavior, we might reach for creating a common `Person` class. But what if each of our Classes already inherit from another class? We could extact everything into a `PersonModule`. But if we also have a `Product` class, or a `Car` class with the same behavior but their own implementations, how can we allow them to be wildly different and yet similar enough to treat the same in certain circumstances? 
+
+Enter Active Interface!
+
+```
+module NameInterface
+  
+  extend ActiveInterface::Base
+
+  REQUIRED_ATTRIBUTES = %i[first_name last_name].freeze
+
+  def full_name(seperator)
+    super 
+  end
+
+end
+
+User.append NameInterface
+```
+
+Once we append `User` with `NameInterface`, we gain the following:
+  - Will raise exception if any of the required attributes are not defined
+  - Will raise exception if the expected methods are not defined or have different method signatures
+  - the interface sits in front of every call to the methods 
+  - we can ask `User.has_interface?(NameInterface) => true` to develop our code against. 
+
+## What's an interface contract?
+
+Once appended, Active Interface will ensure that certain methods/signatures and attributes are present at initialization. However, as a ruby is a dynamically typed language, it can be ambiguious what the expected inputs and outputs are for a method or how flexible they are. As a developer that must rely on an interface created by another team, how can you be sure you'll get the expected return values, or that you know what the expected inputs are? 
+
+Enter Interface Contracts with Active Interface!
+
+```
+module NameInterface
+  
+  include ActiveInterface::Base
+
+  REQUIRED_ATTRIBUTES = %i[first_name last_name].freeze
+
+  def full_name(seperator)
+    interface_contract(binding) do |c|
+      c.enforce_input :seperator, kind_of: String, length: 1..4
+      c.enforce_output kind_of: String
+    end
+  end
+end
+
+User.append NameInterface
+```
+
+With the above Interface, every call to `#full_name` will be enforced to adheres to the interface contract. This carries a number of benefits:
+- Documentation about what the expected parameters and return values are for the Interface
+- method level validations of input and output values abstracted from implementation
+- raises `InterfaceError` for any incorrect parameters per the contract
+- raises `InterfaceError` if the output does not conform to the contract
+- Ensures developers can implement interfaces and code against them reliably
+- the results of `super` are only called once all the inputs have been enforced, or at the end of the block.
+- If there are no exceptions raised, the block returns the result of `super`
+
+## Other Active Interface uses
+Because of the runtime capabilities, Active Interface can be used for more than just API conformity. Some additional uses could include:
+
+- Logging request/response of method calls. 
+- Transforming inputs or outputs (such as always calling `.to_s`)
+- Caching
+- Running history of previous inputs and outputs
+- And more!
+
+

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "active_interface"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/active_interface/base.rb

@@ -0,0 +1,61 @@
+
+class Module
+  alias_method :has_interface?, :<
+end
+
+
+module ActiveInterface
+  module Base
+
+    module ClassMethods
+      def prepended(klass)
+        messages = []
+        ensure_methods_implemented(klass, messages)
+        ensure_method_signatures(klass, messages)
+        ensure_attributes_defined(klass, messages)
+
+        if messages.size > 0
+          raise "#{messages.size} errors verifying #{klass} conforms to #{self} \n" + messages.join("\n")
+        end
+      end
+
+      private
+
+      def ensure_attributes_defined(klass, messages)
+        missing_attributes = klass::REQUIRED_ATTRIBUTES - klass.public_instance_methods(false)
+        if (missing_attributes.size > 0)
+          messages << "#{klass} is missing attributes #{missing_attributes.join(', ')}"
+        end
+      end
+
+      def ensure_methods_implemented(klass, messages)
+        missing_methods = public_instance_methods(false) - klass.public_instance_methods(false)
+        if (missing_methods.size > 0)
+          messages << "#{klass} is missing implementation(s) for ##{missing_methods.join(', #')}"
+        end
+      end
+
+      def ensure_method_signatures(klass, messages)
+        public_instance_methods(false).each do |method_name|
+          interface_method = instance_method(method_name)
+          class_method = klass.instance_method(method_name).super_method
+          next if class_method.nil?
+          interface_params = interface_method.parameters.map(&:last)
+          class_params = class_method.parameters.map(&:last)
+          
+          unless interface_params == class_params
+            messages << "method signature for #{method_name} should be #{interface_params} but was #{class_params}"
+          end
+        end
+      end
+    end
+
+    def interface_contract(_binding)
+      ActiveInterface::Contract.new(_binding).call
+    end
+
+    def self.included(klass)
+      klass.extend(ClassMethods)
+    end
+  end
+end

data/lib/active_interface/contract.rb

@@ -0,0 +1,36 @@
+class ActiveInterface::Contract
+
+  def initialize(_binding, _output = nil)
+   @_binding = _binding
+   @output = _output
+  end
+
+  def call(&block)
+   result = block.call self
+   output
+  end
+
+  def enforce_input(value_name, options)
+    callee = @_binding.eval("__method__")
+    interface = @_binding.eval("self").method(callee).owner
+    value = @_binding.eval(value_name.to_s)
+    verify(value_name, interface, value, options)
+  end
+
+
+  def enforce_output(options)
+    callee = @_binding.eval("__method__")
+    interface = @_binding.eval("self").method(callee).owner
+    verify(:output, interface, output, options)
+  end
+
+  def output
+    @output ||= @_binding.eval("super")
+  end
+
+  def verify(attribute, interface, value, options = {})
+    Verify.call(attribute, interface, value, options)
+  end
+
+end
+

data/lib/active_interface/interface_error.rb

@@ -0,0 +1,14 @@
+class ActiveInterface::InterfaceError < StandardError
+
+  def initialize(errors, interface, klass, method_name: )
+    @interface = interface
+    @errors = errors
+    @klass = klass
+    @method_name = method_name
+  end
+
+  def message
+    "Violation of #{@interface} in #{@klass}##{@method_name}: #{@errors}"
+  end
+
+end

data/lib/active_interface/verify.rb

@@ -0,0 +1,32 @@
+class Verify
+
+  def call(attribute, interface, value, options = {})
+    errors = []
+    if options[:presence] && value.nil?
+      errors << "#{attribute} can't be blank"
+    end
+
+    if options[:range] && !options[:range].include?(value)
+      errors << "#{attribute} is not within the range #{options[:in]}"
+    end
+
+    if options[:length] && !options[:length].include?(value.length)
+      errors << "#{attribute} must be between #{options[:length]} characters long"
+    end
+
+    if options[:regex] && !(options[:regex] =~ value)
+      errors << "#{attribute} is invalid"
+    end
+
+    if options[:kind_of] && !Array(options[:kind_of]).include?(value.class)
+      errors << "#{attribute} must be a kind of #{options[:kind_of]}"
+    end
+    if errors.empty?
+      nil
+    else
+      klass = @_binding.eval("self").class
+      meth = @_binding.eval("__method__")
+      raise(InterfaceError.new(errors, interface, klass, method_name: meth))
+    end
+  end
+end

data/lib/active_interface/version.rb

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

data/lib/active_interface.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "active_interface/version"
+
+require_relative "active_interface/base"
+require_relative "active_interface/contract"
+require_relative "active_interface/interface_error"
+require_relative "active_interface/verify"
+
+module ActiveInterface
+  class Error < StandardError; end
+  # Your code goes here...
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: active_interface
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Russell Jennings
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-03-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+description: Provide OOP Interfaces for ruby
+email:
+- violentpurr@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/active_interface.rb
+- lib/active_interface/base.rb
+- lib/active_interface/contract.rb
+- lib/active_interface/interface_error.rb
+- lib/active_interface/verify.rb
+- lib/active_interface/version.rb
+homepage: https://github.com/meesterdude/active_interface
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/meesterdude/active_interface
+  source_code_uri: https://github.com/meesterdude/active_interface
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: OOP Interfaces for ruby
+test_files: []