troupe 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 36d3441bf24fea4d1712b7694245912ac0ad6af2
+  data.tar.gz: ff3ba18a37d8bb618855bbbfaf23d51c1a4780f0
+SHA512:
+  metadata.gz: 21449aca99de6d0123a18c9a7697052ba359f28231adf4137126591a804afd83ccc0fb29d3194b475579cadbf4a71cbce471fc3396da15cfdbf38ef51e53addd
+  data.tar.gz: 87cfeb509d80f21b6445b59c4e0c0d7c78da1579e485b5b7428ca5491c04abca7f09085f8333b5acdd282d19ac73dd2a4eb205636abf2efad1ba5bcf35869283

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.2.2

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.com'
+
+# Specify your gem's dependencies in troupe.gemspec
+gemspec
+
+group :test do
+  gem "rspec", "~> 3.1"
+end

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Jon Stokes
+
+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/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Jon Stokes
+
+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,160 @@
+# troupe
+Troupe is a contract DSL for the [interactor gem](https://github.com/collectiveidea/interactor). It's backwards-compatible with
+interactor 3.1.0 and higher, so you can introduce it into your codebase gradually.
+
+# Getting Started
+
+Add troupe to your Gemfile and bundle install.
+```ruby
+gem "troupe"
+```
+Use it just like you would Interactor, by doing `include Troupe` in your class instead of `include Interactor`. Including the former will also include the latter by default, and monkey patch it so that it works with contracts as described below.
+
+# Requirements
+Ruby 2.0 or higher
+
+# DSL
+
+Here's the normal way to write an interactor:
+```ruby
+class PlaceOrder
+  include Interactor
+
+  before do
+    context.user ||= User.find(context.user_id)
+  end
+
+  def call
+    context.order = context.user.orders.create(context.attributes)
+
+    context.fail! unless context.order.persisted?
+  end
+end
+```
+
+Here's the same interactor using the DSL
+```ruby
+class PlaceOrder
+  include Troupe
+
+  expects :attributes
+  permits :user_id
+
+  permits(:user) do
+    User.find(user_id)
+  end
+
+  provides(:order) do
+    user.orders.create(attributes)
+  end
+
+  before { context.fail! unless order.persisted? }
+end
+```
+Here's a quick description of all the main verbs in the DSL:
+
+### expects
+E.g. `expects :property1, :property2`
+
+Any properties listed here must be part of the context, or else the interactor will raise a `ContractViolation` error.
+
+### permits
+E.g. `permits :property1, :property2, default: :get_property_default`
+
+Any attributes listed here can be part of the context and can be accessed inside the interactor as if they were local variables declared with `attr_accessor`, e.g. `puts "#{attr}"` and `self.foo = :bar`. If an attribute is part  of the context and isn't listed under `expects` or `permits`, then it has no such getter or setter.
+
+Defaults can be set either as above, with a symbolized method name, or with a block as below:
+```ruby
+permits(:property1, :property2) do
+   'default value'
+end
+```
+If either `property` or `property` are when the interactor is called, then the above code will set the nil property (or properties) to 'default value'. The default applies to every listed property. If you want to set individual defaults, use separate `permits` clauses for each property.
+
+### provides
+E.g. `provides :property1, :property2, default: :get_property_default`
+
+The `provides` verb is basically an alias for `permits`, and is offered for the sake of documentation and ease of reading.
+
+The one nice thing about `provides` is that all post-`call` evaluations* happen in the following order: expected properties, permitted properties, provided properties. So anything declared with `provides` can expect to have anything that's expected or permitted already defined.
+
+(* See below for what I mean by the phrase "post-`call` evaluations".)
+
+### A word about order
+
+The TL;DR version of this section can be expressed in two simple rules:
+ 1. All property defaults are lazy evaluated at the time that they're first called in the hooks or in the `call` method.
+ 2. Any property defaults that have not been so evaluated once the interactor is completely done will be evaluated in the order that they were declared, subject to the constraint that expected defaults go first, then permitted ones, then provided ones.
+
+No for the longer explanation:
+
+The default values given for the verbs above are lazy evaluated within your interactor's hooks and `call` method. So in the example above, the code `User.find(user_id)` would not be evaluated until you actually reference `user` from within `call` or one of the hooks, and then it would be evaluated only if the interactor had been called without the `:user` key in the context object.
+
+If the `call` method ends and all the hooks are run and `user` the getter for `user` has still not been called and there still is no `user` key in the context, then an `ensure_contract_defaults` method will run and will call its getter just to ensure that it gets referenced at least once and therefore added to the context with any default that may have been set.
+
+In other words, after the `call` and all of the hooks are run, the interactor essentially does the following:
+
+```ruby
+(expected_properties + permitted_properties + provided_properties).each do |property|
+  send(property)
+end
+```
+That call to `send(property)` just returns `context[property]` if that propert is a key in the context, otherwise it checks for a default block and tries to set the key with that.
+
+What all of this means is that the following code is just not a problem and behaves predictably every time, provided that you call `MyInteractor` with either `property1` or `property2` set:
+```ruby
+class MyInteractor
+  permits :property1 do
+    property2
+  end
+
+  permits :property2 do
+    property1
+  end
+  
+  def call
+    property1
+  end
+end
+```
+Of course, if you do `MyInteractor.call` without either property key, then you'll have a stack overflow.
+
+And again, just to be clear, you can use `expects` and `permits` and `provides` in whatever order -- it generally doesn't matter, and everything will work as you expect.
+
+## Hooks
+
+A contract violation will raise a `Troupe::ContractViolation` error, but it doesn't have to. You can handle violations yourself with the following hooks.
+
+### on_violation
+Example:
+```ruby
+class MyInteractor
+  include Troupe
+
+  expects :property1, :property2
+
+  on_violation do |violation|
+    if violation.property == :property1
+      puts "Property1 violated the contract!"
+    else
+      context.fail!(error: violation.message)
+    end
+  end
+end
+```
+The above should be self-explanatory. One thing to note: a `ContractViolation` object has a `property` method that returns the name of the property that raised the violation, and a `message` method that returns the error message that would otherwise be raised.
+
+### on_violation_for
+Example:
+```ruby
+class MyInteractor
+  include Troupe
+
+  expects :property1
+
+  on_violation_for(:property1) do |violation|
+    context.fail!(error: violation.message)
+  end
+end
+```
+Yep, it's technically redundant to `on_violation`, but can make the hooks a little cleaner if you're only handling one or two properties.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "troupe"
+
+# 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

data/bin/setup

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

data/lib/troupe.rb

@@ -0,0 +1,36 @@
+require "interactor"
+require "troupe/version"
+require "troupe/contract_violation"
+require "troupe/contract"
+require "troupe/contract/property"
+require "troupe/contract/property_table"
+
+module Troupe
+  def self.included(base)
+
+    Interactor::Context.class_eval do
+      def members
+        @table.keys
+      end
+    end
+
+    Interactor.class_eval do
+      def run!
+        validate_contract_expectations
+        with_hooks do
+          call
+          context.called!(self)
+        end
+        ensure_contract_defaults
+      rescue
+        context.rollback!
+        raise
+      end
+    end
+
+    base.class_eval do
+      include Interactor
+      include Contract
+    end
+  end
+end

data/lib/troupe/contract.rb

@@ -0,0 +1,145 @@
+module Troupe
+  module Contract
+    VALID_TYPES = %i(open closed)
+
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+      end
+
+      private
+
+      def violation_table
+        @violation_table ||= {}
+      end
+
+      def validate_contract_expectations
+        populate_violation_table
+        check_each_violation
+      end
+
+      def missing_properties
+        @missing_properties ||= self.class.missing_properties(context)
+      end
+
+      def ensure_contract_defaults
+        self.class.all_properties.each do |attr|
+          send(attr)
+        end
+      end
+
+      def populate_violation_table
+        missing_properties.each do |property_name|
+          violation_table[property_name] = ContractViolation.new(
+            self,
+            property: property_name,
+            message: "Expected context to include property '#{property_name}'."
+          )
+        end
+      end
+
+      def check_each_violation
+        return if violation_table.empty?
+        violation_table.each do |property_name, violation|
+          if block = violation_block_for(property_name)
+            instance_exec(violation, &block)
+          else
+            raise violation
+          end
+        end
+      end
+
+      def violation_block_for(property_name)
+        self.class.violation_block_for(property_name) ||
+          self.class.on_violation_block
+      end
+    end
+
+    module ClassMethods
+      # Core DSL
+      #
+      def property(attr, opts={}, &block)
+        opts.merge!(default: block) if block
+        property_table.set(attr, opts)
+
+        delegate_properties
+      end
+
+      def on_violation_for(*args, &block)
+        args.each do |arg|
+          next unless property = property_table.get(arg)
+          property.on_violation = block
+        end
+      end
+
+      def on_violation(&block)
+        @on_violation_block = block
+      end
+
+      # Sugar for core DSL
+      #
+      def expects(*args, &block)
+        presence_is(:expected, args, block)
+      end
+
+      def permits(*args, &block)
+        presence_is(:permitted, args, block)
+      end
+
+      def provides(*args, &block)
+        presence_is(:provided, args, block)
+      end
+
+      def on_violation_block
+        @on_violation_block
+      end
+
+      def expected_properties;  property_table.expected_properties; end
+      def permitted_properties; property_table.permitted_properties; end
+      def provided_properties;  property_table.provided_properties; end
+      def all_properties;       property_table.all_properties; end
+      def default_for(attr);    property_table.default_for(attr); end
+      def violation_block_for(attr);     property_table.get(attr).on_violation; end
+      def missing_properties(context);   property_table.missing_properties(context); end
+
+      def expected_and_permitted_properties
+        property_table.expected_and_permitted_properties
+      end
+
+      private
+
+      def property_table
+        @property_table ||= PropertyTable.new
+      end
+
+
+      def delegate_properties
+        all_properties.each do |attr|
+          define_method attr do
+            next context[attr] if context.members.include?(attr)
+            default = self.class.default_for(attr)
+            context[attr] = if default.is_a?(Proc)
+                              instance_exec(&default)
+                            elsif default.is_a?(Symbol)
+                              send(default)
+                            end
+          end
+
+          define_method "#{attr}=" do |value|
+            context[attr] = value
+          end
+        end
+      end
+
+      def presence_is(presence, args, block)
+        opts = args.detect { |arg| arg.is_a?(Hash) } || {}
+        opts.merge!(presence: presence)
+        args.reject! { |arg| arg.is_a?(Hash) }
+
+        args.each do |arg|
+          property(arg, opts, &block)
+        end
+      end
+    end
+  end
+end

data/lib/troupe/contract/property.rb

@@ -0,0 +1,36 @@
+module Troupe
+  module Contract
+    class Property
+      DEFAULTS = { presence: :provided }
+
+      VALID_OPTIONS = {
+        presence: [:expected, :permitted, :provided]
+      }
+
+      attr_accessor :default, :on_violation, :presence
+
+      def initialize(opts={})
+        validate_options(opts)
+        opts = DEFAULTS.merge(opts)
+        @default      = opts[:default]
+        @on_violation = opts[:on_violation]
+        @presence     = opts[:presence]
+      end
+
+      def merge!(hash)
+        hash.each do |k, v|
+          send("#{k}=", v)
+        end
+      end
+
+      private
+
+      def validate_options(opts)
+        opts.each do |k, v|
+          next unless values = VALID_OPTIONS[k]
+          raise "Invalid value '#{v}' for option #{k}" unless values.include?(v)
+        end
+      end
+    end
+  end
+end

data/lib/troupe/contract/property_table.rb

@@ -0,0 +1,66 @@
+module Troupe
+  module Contract
+    class PropertyTable
+      def initialize
+        @table ||= {}
+      end
+
+      def get(property_name)
+        @table[property_name]
+      end
+
+      def set(property_name, opts={})
+        @table[property_name] ||= Property.new(opts)
+        @table[property_name].merge!(opts)
+      end
+
+      def each_property
+        @table.each do |property_name, property|
+          yield property_name, property
+        end
+      end
+
+      def select(args)
+        @table.select do |_, property|
+          args == args.select do |k, v|
+            property.send(k) == v
+          end
+        end
+      end
+
+      def expected;  select(presence: :expected); end
+      def permitted; select(presence: :permitted); end
+      def provided;  select(presence: :provided); end
+
+      def all_properties
+        expected_properties +
+          permitted_properties +
+          provided_properties
+      end
+
+      def expected_properties; expected.keys; end
+      def permitted_properties; permitted.keys; end
+      def provided_properties; provided.keys; end
+
+      def expected_and_permitted_properties
+        expected_properties + permitted_properties
+      end
+
+      def undeclared_properties(context)
+        context.members.select do |attr|
+          !expected_and_permitted_properties.include?(attr)
+        end
+      end
+
+      def missing_properties(context)
+        expected_properties.select do |attr|
+          !context.members.include?(attr)
+        end
+      end
+
+      def default_for(property_name)
+        @table[property_name].default
+      end
+    end
+  end
+end

data/lib/troupe/contract_violation.rb

@@ -0,0 +1,16 @@
+module Troupe
+  class ContractViolation < StandardError
+    attr_reader :context, :property
+
+    def initialize(context=nil, opts={})
+      @context = context
+      @property = opts[:property]
+      @message = opts[:message]
+      super()
+    end
+
+    def message
+      @message || "Property '#{property}' violated the interactor's contract."
+    end
+  end
+end

data/lib/troupe/version.rb

@@ -0,0 +1,3 @@
+module Troupe
+  VERSION = "0.1.0"
+end

data/troupe.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'troupe/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "troupe"
+  spec.version       = Troupe::VERSION
+  spec.authors       = ["Jon Stokes"]
+  spec.email         = ["jon@jonstokes.com"]
+
+  spec.summary       = %q{These (inter)actors have contracts.}
+  spec.description   = %q{This gem layers a contract DSL onto the interactor gem.}
+  spec.homepage      = "http://github.com/jonstokes/troupe"
+  spec.license       = "MIT"
+  
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'interactor', '~> 3.1'
+
+  spec.add_development_dependency "bundler", "~> 1.9"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: troupe
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jon Stokes
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-04-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: interactor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: This gem layers a contract DSL onto the interactor gem.
+email:
+- jon@jonstokes.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/troupe.rb
+- lib/troupe/contract.rb
+- lib/troupe/contract/property.rb
+- lib/troupe/contract/property_table.rb
+- lib/troupe/contract_violation.rb
+- lib/troupe/version.rb
+- troupe.gemspec
+homepage: http://github.com/jonstokes/troupe
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: These (inter)actors have contracts.
+test_files: []