V2 (#20)

* beginning refactor

* more v2 rewrite, removing need for inheritance

* v2 tweaks to rewrite logic

* refactors base run() method, and early prop setting

* rips out old shitty tests, stubs out new ones for logic built so far:

* v2 clean up.  Moves core logic changes to lib/.  Refactors and fixes base rspec implementation and tests

* refactors spec tests in output spec

* resolves #14 updates readme for V2

* readme updated, again

* v2, refactors all helper classes in spec to mutant_spec_helpers.rb'

* adds tests and logic for running all the mutations's instance validation functions?

* tweaks spec fixtures

* defines required_attr method for mutation classes to define which properties the mutaiton should enforce are present.

* Adds specs for handling required field setting, in both raise_or_error is true and false

* resolves #27 by updating gemsepc

* removes old v1 errors that are not needed

* adds YARD documentation to output.rb

* Adds more YARD documentation

* Delete .byebug_history

* removes byebug from depdencies

Author: coreyjs

.gitignore

@@ -6,6 +6,8 @@
 /pkg/
 /spec/reports/
 /tmp/
+/.idea
 
 # rspec failure tracking
 .rspec_status
+.byebug_history

.rakeTasks

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Settings><!--This file was automatically generated by Ruby plugin.
+You are allowed to: 
+1. Remove rake task
+2. Add existing rake tasks
+To add existing rake tasks automatically delete this file and reload the project.
+--><RakeGroup description="" fullCmd="" taksId="rake" /></Settings>

Gemfile.lock

@@ -32,4 +32,4 @@ DEPENDENCIES
   ruby-mutant!
 
 BUNDLED WITH
-   1.16.6
+   1.17.3

README.md

@@ -15,46 +15,66 @@ gem 'ruby-mutant'
 
 Ruby Mutant is a lightweight mutations library to help you encapsulate your business logic.  With Ruby Mutant you can easily add executable code with validation, helping you decouple important logic from your application.
 
-To create a mutation, subclass `MutatantBase`  
+To create a mutation from a ruby object, include the module `include Mutatant`  
+
 
 ```ruby
 require "mutant"
 
-class ProductCreatedMutation < MutantBase
-
-    #Define required attributes for this mutation to execute
-    required do
-        {
-            name: String, 
-            address: String, 
-            product: Product,
-            name: String
-        }
-    end
-    
-    validate do 
-        [:validate_name?]
-    end
+class RecipeCreatedMutation
+  include Mutant
 
     #Define custom validators for our attributes
     def validate_name?
         true
     end
 
-    # Requried, this will execute our new mutation.
-    def self.run(*args)
-        super
-        input = args[0].to_h
-        
-        # Put all our mutation logic here!
-        input[:product].on_sale = true
-        
-        # Output is generated by the Mutator, contains our errors and success? of validation.
-        @output
+    # Required, this will execute our new mutation.
+    def execute(args)
+        # here, recipe is passe into out Class.run(recipe=Recipe.new) method
+        if recipe.difficulty == 'godlike'
+          recipe_service.send_alert_new_super_recipe_confirmation()
+        end 
     end
 end
 ```
 
+---
+To run a mutation definition:
+```ruby
+# run() excepts any number of parameters that you want to pass into your mutation
+output = RecipeCreatedMutation.run(obj: obj1, obj2: obj2, ....)
+```
+
+Every mutation execution will return an `output` object.  This object contains information on the
+mutation execution, and errors occurred or any metadata that's needed to be returned from the mutation, 
+in the form of a hash.
+
+Any meta data that needs to be returned can be added to the output object using the
+helper method inside your mutation:
+
+```ruby
+class RecipeCreatedMutation
+  include Mutant
+...
+    def execute(args)
+      output.add_meta(:test, 'value')
+    end
+
+...
+
+output = RecipeCreatedMutation.run()
+output.meta[:test] # >> 'value'
+
+```
+
+```ruby
+output = RecipeCreatedMutation.run(obj: obj1)
+output.success?
+output.errors
+output.meta
+```
+
 
 
 ## Contributing

lib/mutant.rb

@@ -1,5 +1,5 @@
 require "ruby-mutant/version"
-require "ruby-mutant/mutant_base"
+require "ruby-mutant/base"
 
 module Mutant
 end

lib/ruby-mutant/base.rb

@@ -0,0 +1,156 @@
+require 'ruby-mutant/exceptions/mutation_validation_exception'
+require 'ruby-mutant/exceptions/mutation_setup_exception'
+require 'ruby-mutant/exceptions/mutation_missing_required_var_exception'
+require 'ruby-mutant/output'
+require "bundler/setup"
+
+
+module Mutant
+    attr_accessor :output
+
+    def self.included(klass)
+        klass.extend(ClassMethods)
+    end
+
+    module ClassMethods
+        def required_attr(*attrs)
+            puts 'Mutant::required_attr'
+            # This defines a method called required_attr that will
+            # return an array of symbols for all the properties of the
+            # mutation that we should have defined.
+            define_method(:required_attr) { attrs ||= [] }
+        end
+
+        # The entry point, main method that will be execute any mutation logic
+        #
+        # == Parameters:
+        # args::
+        #   A hash of inputs suppplied when the user runs the mutation.
+        #   i.e. MyMutation.run(name: 'jon', house: 'stark')
+        #
+        # == Returns:
+        #   An instance of `Mutant::Output`.  This object defines all
+        #   errors, metadata and success definition of the mutation
+        def run(args = {})
+            unless args.has_key?(:raise_on_error)
+                args[:raise_on_error] = true
+            end
+            args[:raise_on_error].freeze
+
+            puts 'Mutant::self.run(*args) '
+            obj = new(args)
+
+            # Ensure the mutation has the correct method
+            unless obj.respond_to?(:execute)
+                raise MutationSetupException.new(msg='Missing execute method')
+            end
+
+            # 1. We want to run the validators first, then determine if we should continue
+            errs = obj.send(:validate)
+            obj.output.errors = obj.output.errors + errs
+            if errs.length > 0
+                if args[:raise_on_error]
+                    raise MutationSetupException.new(msg='Validation failed')
+                end
+            end
+
+            # 2. Check to see the mutation has the corresponding inst vars
+            args.each do |k, val|
+                puts "Mutant::var check '#{k}', responds? #{obj.respond_to? k.to_sym}"
+
+                # First make sure this mutation obj has the correct vars,
+                # if not, then proceeed to create them
+                unless obj.respond_to? k.to_sym
+                    # create the attr_accessor for the missing vars
+                    obj.class.send(:define_method, "#{k}=".to_sym) do |value|
+                        instance_variable_set("@" + k.to_s, value)
+                    end
+                    obj.class.send(:define_method, k.to_sym) do
+                        instance_variable_get("@" + k.to_s)
+                    end
+                end
+
+                # 3. Propagate the values from the mutation props to the class
+                obj.send("#{k}=".to_sym, val)
+            end
+
+            # 3 If this instance defines :required_attr
+            if obj.respond_to? :required_attr
+                required_attr_errors = obj.send(:check_required_attrs)
+                unless required_attr_errors.length == 0
+                    # We need to handle any errors we get back from our
+                    # required_attr validator
+                    obj.output.errors += required_attr_errors
+                    if args[:raise_on_error]
+                        raise required_attr_errors[0]
+                    end
+                end
+            end
+
+            # 4. Run execute method to run mutation logic
+            obj.execute(args)
+            # Return out Output obj, with all meta data regarding the ran mutation
+            obj.output
+        end
+    end
+
+    def initialize(*args)
+        @output = Output.new
+    end
+
+    private
+
+    # This will run all ou validation functions on our mutation class.
+    # This will return an array of MutationValidationException, to the class method, run()
+    #
+    # == Parameters:
+    #
+    # == Returns:
+    #  errors.  An array of errors representing all validation methods that have failed.
+    # (defaults to `[]`)
+    def validate
+        errors = []
+        self.public_methods.each do |m|
+            if m.to_s.start_with?('validate_') && m.to_s.end_with?('?')
+                # execute validation method
+                res = self.send(m)
+
+                # unless the response is truthy
+                unless res
+                    errors << MutationValidationException.new(msg='Validator has returned false', validator=m)
+                end
+            end
+        end
+        errors
+    end
+
+    # Checks to see if any `required_attr` has been set, if so check to see if each one
+    # is defined in either the .run() definition or the mutation's `attr_accesor`.
+    # TODO need to also check that these required attributes have values
+    #
+    # == Parameters:
+    #
+    # == Returns:
+    # An array of errors, of type `MutationMissingRequiredVarException`, for each
+    # missing required attribute.
+    def check_required_attrs
+        # In this we need to compare what we define in
+        # required_attr(*attrs) against what we have defined in
+        # the mutation vs what we pass into the run() definition
+        errors = []
+        puts 'Mutant::check_required_attrs'
+        self.required_attr.each do |attr|
+            if !self.respond_to?(attr)
+                # Our attribute is not defined on our mutation class
+                # So we will build the error to return to the run()
+                # method, which can determine how we proceed
+                err = MutationMissingRequiredVarException.new(
+                                    msg="A property that is marked as required is not defined on the mutation: #{attr}",
+                                    prop=attr)
+                errors << err
+            end
+        end
+        errors
+    end
+
+end

lib/ruby-mutant/exceptions/mutation_duplicate_attr_exception.rb

@@ -0,0 +1,7 @@
+class MutationMissingRequiredVarException < StandardError
+  attr_reader :prop
+  def initialize(msg='MutationMissingRequiredVarException', prop=nil)
+    @prop = prop
+    super("#{msg} - #{prop}")
+  end
+end

lib/ruby-mutant/exceptions/mutation_missing_required_var_exception.rb

@@ -0,0 +1,5 @@
+class MutationSetupException < StandardError
+  def initialize(msg='MutationSetupException')
+    super(msg)
+  end
+end